Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
RTNETLINK(4)		    Kernel Interfaces Manual		  RTNETLINK(4)

NAME
       RTNetlink -- Network configuration-specific Netlink family

SYNOPSIS
       #include	<netlink/netlink.h>
       #include	<netlink/netlink_route.h>

       int
       socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE);

DESCRIPTION
       The NETLINK_ROUTE family	aims to	be the primary configuration mechanism
       for  all	 network-related tasks.	 Currently it supports configuring in-
       terfaces, interface addresses, routes, nexthops and arp/ndp neighbors.

ROUTES
       All route configuration messages	share the common header:

       struct rtmsg {
	       unsigned	char   rtm_family;     /* address family */
	       unsigned	char   rtm_dst_len;    /* Prefix length	*/
	       unsigned	char   rtm_src_len;    /* Deprecated, set to 0 */
	       unsigned	char   rtm_tos;	       /* Type of service (not used) */
	       unsigned	char   rtm_table;      /* deprecated, set to 0 */
	       unsigned	char   rtm_protocol;   /* Routing protocol id (RTPROT_)	*/
	       unsigned	char   rtm_scope;      /* Route	distance (RT_SCOPE_) */
	       unsigned	char   rtm_type;       /* Route	type (RTN_) */
	       unsigned	       rtm_flags;      /* Route	flags (not supported) */
       };

       The rtm_family specifies	the route family  to  be  operated  on.	  Cur-
       rently,	AF_INET6  and  AF_INET	are  the only supported	families.  The
       route prefix length is stored in	rtm_dst_len The	caller should set  the
       originator  identity  (one of the RTPROT_ values) in rtm_protocol It is
       useful for users	and for	the  application  itself,  allowing  for  easy
       identification  of  self-originated  routes.  The route scope has to be
       set via rtm_scope field.	 The supported values are:
	     RT_SCOPE_UNIVERSE	     Global scope
	     RT_SCOPE_LINK	     Link scope

       Route type needs	to be set.  The	defined	values are:
	     RTN_UNICAST     Unicast route
	     RTN_MULTICAST   Multicast route
	     RTN_BLACKHOLE   Drops traffic towards destination
	     RTN_PROHIBIT    Drops traffic and sends reject

       The following messages are supported:

   RTM_NEWROUTE
       Adds a new route.  All NL flags are supported.  Extending  a  multipath
       route requires NLM_F_APPEND flag.

   RTM_DELROUTE
       Tries to	delete a route.	 The route is specified	using a	combination of
       RTA_DST TLV and rtm_dst_len.

   RTM_GETROUTE
       Fetches	a single route or all routes in	the current VNET, depending on
       the NLM_F_DUMP flag.  Each route	is reported as	RTM_NEWROUTE  message.
       The following filters are recognised by the kernel:

	     rtm_family	     required family or	AF_UNSPEC
	     RTA_TABLE	     fib number	or RT_TABLE_UNSPEC to return all fibs

   TLVs
       RTA_DST
	       (binary)	IPv4/IPv6 address, depending on	the rtm_family.

       RTA_OIF
	       (uint32_t) transmit interface index.

       RTA_GATEWAY
	       (binary)	  IPv4/IPv6   gateway	address,   depending   on  the
	       rtm_family.

       RTA_METRICS
	       (nested)	Container attribute, listing  route  properties.   The
	       only supported sub-attribute is RTAX_MTU, which stores path MTU
	       as uint32_t.

       RTA_MULTIPATH
	       This  attribute	contains  multipath  route nexthops with their
	       weights.	 These nexthops	 are  represented  as  a  sequence  of
	       rtnexthop  structures,  each followed by	RTA_GATEWAY or RTA_VIA
	       attributes.

	       struct rtnexthop	{
		       unsigned	short	       rtnh_len;
		       unsigned	char	       rtnh_flags;
		       unsigned	char	       rtnh_hops;      /* nexthop weight */
		       int		       rtnh_ifindex;
	       };

	       The rtnh_len field specifies the	total nexthop info length, in-
	       cluding both struct rtnexthop  and  the	following  TLVs.   The
	       rtnh_hops  field	 stores	relative nexthop weight, used for load
	       balancing between group members.	 The rtnh_ifindex  field  con-
	       tains the index of the transmit interface.

	       The following TLVs can follow the structure:
		     RTA_GATEWAY     IPv4/IPv6 nexthop address of the gateway
		     RTA_VIA	     IPv6 nexthop address for IPv4 route
		     RTA_KNH_ID	     Kernel-specific index of the nexthop

       RTA_KNH_ID
	       (uint32_t)  (FreeBSD-specific)  Auto-allocated  kernel index of
	       the nexthop.

       RTA_RTFLAGS
	       (uint32_t) (FreeBSD-specific) rtsock route flags.

       RTA_TABLE
	       (uint32_t) Fib number of	the route.   Default  route  table  is
	       RT_TABLE_MAIN.	To  explicitely	specify	"all tables" one needs
	       to set the value	to RT_TABLE_UNSPEC.

       RTA_EXPIRES
	       (uint32_t) seconds till path expiration.

       RTA_NH_ID
	       (uint32_t) useland nexthop or nexthop group index.

   Groups
       The following groups are	defined:
	     RTNLGRP_IPV4_ROUTE	     Notifies on IPv4 route arrival/removal/change
	     RTNLGRP_IPV6_ROUTE	     Notifies on IPv6 route arrival/removal/change

NEXTHOPS
       All nexthop/nexthop  group  configuration  messages  share  the	common
       header:

       struct nhmsg {
	       unsigned	char   nh_family;      /* transport family */
	       unsigned	char   nh_scope;       /* ignored on RX, filled	by kernel */
	       unsigned	char   nh_protocol;    /* Routing protocol that	installed nh */
	       unsigned	char   resvd;
	       unsigned	int    nh_flags;       /* RTNH_F_* flags from route.h */
       };
       The  nh_family  specificies the gateway address family.	It can be dif-
       ferent from route address family	for IPv4 routes	 with  IPv6  nexthops.
       The  nh_protocol	 is  similar  to  rtm_protocol field, which designates
       originator application identity.

       The following messages are supported:

   RTM_NEWNEXTHOP
       Creates a new nexthop or	nexthop	group.

   RTM_DELNEXTHOP
       Deletes nexthop or nexthhop group.  The required	object is specified by
       the RTA_NH_ID attribute.

   RTM_GETNEXTHOP
       Fetches a single	nexthop	or all nexthops/nexthop	groups,	 depending  on
       the  NLM_F_DUMP flag.  The following filters are	recognised by the ker-
       nel:

	     RTA_NH_ID	     nexthop or	nexthtop group id
	     NHA_GROUPS	     match only	nexthtop groups

   TLVs
       RTA_NH_ID
	       (uint32_t) Nexthhop index used to identify  particular  nexthop
	       or nexthop group.  Should be provided by	userland at the	nexth-
	       top creation time.

       NHA_GROUP
	       This  attribute	designates the nexthtop	group and contains all
	       of its nexthtops	and their  relative  weights.	The  attribute
	       consists	of a list of nexthop_grp structures:

	       struct nexthop_grp {
		       uint32_t	       id;	       /* nexhop userland index	*/
		       uint8_t	       weight;	       /* weight of this nexthop */
		       uint8_t	       resvd1;
		       uint16_t	       resvd2;
	       };

       NHA_GROUP_TYPE
	       (uint16_t)  Nexthtop  group  type,  set to one of the following
	       types:
		     NEXTHOP_GRP_TYPE_MPATH  default multipath group

       NHA_BLACKHOLE
	       (flag) Marks the	nexthtop as blackhole.

       NHA_OIF
	       (uint32_t) Transmit interface index of the nexthtop.

       NHA_GATEWAY
	       (binary)	IPv4/IPv6 gateway address

       NHA_GROUPS
	       (flag) Matches nexthtop groups during dump.

   Groups
       The following groups are	defined:
	     RTNLGRP_NEXTHOP	     Notifies on nexthop/groups	arrival/removal/change

INTERFACES
       All interface configuration messages share the common header:

       struct ifinfomsg	{
	       unsigned	char   ifi_family;     /* not used, set	to 0 */
	       unsigned	char   __ifi_pad;
	       unsigned	short  ifi_type;       /* ARPHRD_* */
	       int	       ifi_index;      /* Inteface index */
	       unsigned	       ifi_flags;      /* IFF_*	flags */
	       unsigned	       ifi_change;     /* IFF_*	change mask */
       };

   RTM_NEWLINK
       Creates a new interface.	 The only mandatory TLV	is  IFLA_IFNAME.   The
       following     attributes	    are	   returned    inside	 the	nested
       NLMSGERR_ATTR_COOKIE:

	     IFLA_NEW_IFINDEX	     (uint32) created interface	index
	     IFLA_IFNAME	     (string) created interface	name

   RTM_DELLINK
       Deletes the interface specified by IFLA_IFNAME.

   RTM_GETLINK
       Fetches a single	interface or all interfaces in the current  VNET,  de-
       pending	on  the	 NLM_F_DUMP  flag.   Each  interface  is reported as a
       RTM_NEWLINK message.  The following filters are recognised by the  ker-
       nel:

	     ifi_index	     interface index
	     IFLA_IFNAME     interface name
	     IFLA_ALT_IFNAME interface name

   TLVs
       IFLA_ADDRESS
	       (binary)	Llink-level interface address (MAC).

       IFLA_BROADCAST
	       (binary)	(readonly) Link-level broadcast	address.

       IFLA_IFNAME
	       (string)	New interface name.

       IFLA_IFALIAS
	       (string)	Interface description.

       IFLA_LINK
	       (uint32_t) (readonly) Interface index.

       IFLA_MASTER
	       (uint32_t) Parent interface index.

       IFLA_LINKINFO
	       (nested)	Interface type-specific	attributes:
		     IFLA_INFO_KIND	     (string) interface	type ("vlan")
		     IFLA_INFO_DATA	     (nested) custom attributes
	       The following types and attributes are supported:

	       vlan
			     IFLA_VLAN_ID	     (uint16_t)	802.1Q vlan id
			     IFLA_VLAN_PROTOCOL	     (uint16_t)	Protocol: ETHERTYPE_VLAN or ETHERTYPE_QINQ

       IFLA_OPERSTATE
	       (uint8_t) Interface operational state per RFC 2863.  Can	be one
	       of the following:
		     IF_OPER_UNKNOWN	     status can	not be determined
		     IF_OPER_NOTPRESENT	     some (hardware) component not present
		     IF_OPER_DOWN	     down
		     IF_OPER_LOWERLAYERDOWN  some lower-level interface	is down
		     IF_OPER_TESTING	     in	some test mode
		     IF_OPER_DORMANT	     "up" but waiting for some condition (802.1X)
		     IF_OPER_UP		     ready to pass packets

       IFLA_STATS64
	       (readonly) Consists of the following 64-bit counters structure:

	       struct rtnl_link_stats64	{
		       uint64_t	rx_packets;    /* total	RX packets (IFCOUNTER_IPACKETS)	*/
		       uint64_t	tx_packets;    /* total	TX packets (IFCOUNTER_OPACKETS)	*/
		       uint64_t	rx_bytes;      /* total	RX bytes (IFCOUNTER_IBYTES) */
		       uint64_t	tx_bytes;      /* total	TX bytes (IFCOUNTER_OBYTES) */
		       uint64_t	rx_errors;     /* RX errors (IFCOUNTER_IERRORS)	*/
		       uint64_t	tx_errors;     /* RX errors (IFCOUNTER_OERRORS)	*/
		       uint64_t	rx_dropped;    /* RX drop (no space in ring/no bufs) (IFCOUNTER_IQDROPS) */
		       uint64_t	tx_dropped;    /* TX drop (IFCOUNTER_OQDROPS) */
		       uint64_t	multicast;     /* RX multicast packets (IFCOUNTER_IMCASTS) */
		       uint64_t	collisions;    /* not supported	*/
		       uint64_t	rx_length_errors;      /* not supported	*/
		       uint64_t	rx_over_errors;	       /* not supported	*/
		       uint64_t	rx_crc_errors;	       /* not supported	*/
		       uint64_t	rx_frame_errors;       /* not supported	*/
		       uint64_t	rx_fifo_errors;	       /* not supported	*/
		       uint64_t	rx_missed_errors;      /* not supported	*/
		       uint64_t	tx_aborted_errors;     /* not supported	*/
		       uint64_t	tx_carrier_errors;     /* not supported	*/
		       uint64_t	tx_fifo_errors;	       /* not supported	*/
		       uint64_t	tx_heartbeat_errors;   /* not supported	*/
		       uint64_t	tx_window_errors;      /* not supported	*/
		       uint64_t	rx_compressed;	       /* not supported	*/
		       uint64_t	tx_compressed;	       /* not supported	*/
		       uint64_t	rx_nohandler;  /* dropped due to no proto handler (IFCOUNTER_NOPROTO) */
	       };

   Groups
       The following groups are	defined:
	     RTNLGRP_LINK	     Notifies on interface arrival/removal/change

INTERFACE ADDRESSES
       All interface address configuration messages share the common header:

       struct ifaddrmsg	{
	       uint8_t	       ifa_family;     /* Address family */
	       uint8_t	       ifa_prefixlen;  /* Prefix length	*/
	       uint8_t	       ifa_flags;      /* Address-specific flags */
	       uint8_t	       ifa_scope;      /* Address scope	*/
	       uint32_t	       ifa_index;      /* Link ifindex */
       };

       The  ifa_family	specifies the address family of	the interface address.
       The ifa_prefixlen specifies the prefix length if	applicable for the ad-
       dress family.  The ifa_index specifies the interface index of the  tar-
       get interface.

   RTM_NEWADDR
       Not supported

   RTM_DELADDR
       Not supported

   RTM_GETADDR
       Fetches	interface  addresses  in the current VNET matching conditions.
       Each address is reported	as a RTM_NEWADDR message.  The following  fil-
       ters are	recognised by the kernel:

	     ifa_family	     required family or	AF_UNSPEC
	     ifa_index	     matching interface	index or 0

   TLVs
       IFA_ADDRESS
	       (binary)	 masked	 interface  address or destination address for
	       p2p interfaces.

       IFA_LOCAL
	       (binary)	local interface	address.  Set for  IPv4	 and  p2p  ad-
	       dresses.

       IFA_LABEL
	       (string)	interface name.

       IFA_BROADCAST
	       (binary)	broacast interface address.

   Groups
       The following groups are	defined:
	     RTNLGRP_IPV4_IFADDR     Notifies on IPv4 ifaddr arrival/removal/change
	     RTNLGRP_IPV6_IFADDR     Notifies on IPv6 ifaddr arrival/removal/change

NEIGHBORS
       All neighbor configuration messages share the common header:

       struct ndmsg {
	       uint8_t	       ndm_family;
	       uint8_t	       ndm_pad1;
	       uint16_t	       ndm_pad2;
	       int32_t	       ndm_ifindex;
	       uint16_t	       ndm_state;
	       uint8_t	       ndm_flags;
	       uint8_t	       ndm_type;
       };

       The ndm_family field specifies the address family (IPv4 or IPv6)	of the
       neighbor.   The ndm_ifindex specifies the interface to operate on.  The
       ndm_state represents the	entry state according to the  neighbor	model.
       The state can be	one of the following:
	     NUD_INCOMPLETE	     No	lladdr,	address	resolution in progress
	     NUD_REACHABLE	     reachable & recently resolved
	     NUD_STALE		     has lladdr	but it's stale
	     NUD_DELAY		     has lladdr, is stale, probes delayed
	     NUD_PROBE		     has lladdr, is stale, probes sent
	     NUD_FAILED		     unused

       The  ndm_flags field stores the options specific	to this	entry.	Avail-
       able flags:
	     NTF_SELF		     local station (LLE_IFADDR)
	     NTF_PROXY		     proxy entry (LLE_PUB)
	     NTF_STICKY		     permament entry (LLE_STATIC)
	     NTF_ROUTER		     dst indicated itself as a router

   RTM_NEWNEIGH
       Creates	new  neighbor  entry.	The  mandatory	options	 are  NDA_DST,
       NDA_LLADDR and NDA_IFINDEX.

   RTM_DELNEIGH
       Deletes	the neighbor entry.  The entry is specified by the combination
       of NDA_DST and NDA_IFINDEX.

   RTM_GETNEIGH
       Fetches a single	neighbor or all	neighbors in the current VNET, depend-
       ing on the NLM_F_DUMP flag.  Each entry	is  reported  as  RTM_NEWNEIGH
       message.	 The following filters are recognised by the kernel:

	     ndm_family	     required family or	AF_UNSPEC
	     ndm_ifindex     target ifindex
	     NDA_IFINDEX     target ifindex

   TLVs
       NDA_DST
	       (binary)	neighbor IPv4/IPv6 address.

       NDA_LLADDR
	       (binary)	neighbor link-level address.

       NDA_IFINDEX
	       (uint32_t) interface index.

       NDA_FLAGS_EXT
	       (uint32_t) extended version of ndm_flags.

   Groups
       The following groups are	defined:
	     RTNLGRP_NEIGH   Notifies on ARP/NDP neighbor  arrival/removal/change

SEE ALSO
       netlink(4), route(4)

HISTORY
       The NETLINK_ROUTE protocol family appeared in FreeBSD 13.2.

AUTHORS
       The     netlink	  was	 implementated	  by	Alexander    Chernikov
       <melifaro@FreeBSD.org>.	It was derived from the	Google Summer of  Code
       2021 project by Ng Peng Nam Sean.

FreeBSD	14.3		       November	1, 2022			  RTNETLINK(4)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=rtnetlink&sektion=4&manpath=FreeBSD+14.3-RELEASE+and+Ports>

home | help