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 interfaces, 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. Currently, 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, including 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 contains 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 explicitly 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 specifies the gateway address family. It can be different 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 kernel:

    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 nexthtop 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;	/* IFT_* */
    	int		ifi_index;	/* Interface index */
    	unsigned	ifi_flags;	/* IFF_* flags */
    	unsigned	ifi_change;	/* IFF_* change mask */
    };

Note: On FreeBSD the ifi_type field uses IFT_* constants from <net/if_types.h> rather than ARPHRD_* as on Linux.

  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, depending on the NLM_F_DUMP flag. Each interface is reported as a RTM_NEWLINK message. The following filters are recognised by the kernel:

    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 address family. The ifa_index specifies the interface index of the target 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 filters 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 addresses.

IFA_LABEL
    (string) interface name.

IFA_BROADCAST
    (binary) broadcast 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. Available flags:
    NTF_SELF		local station (LLE_IFADDR)
    NTF_PROXY		proxy entry (LLE_PUB)
    NTF_STICKY		permanent 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, depending 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 implemented by -nosplit Alexander Chernikov <melifaro@FreeBSD.org>. It was derived from the Google Summer of Code 2021 project by Ng Peng Nam Sean.