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_PREFSRC

(binary) IPv4/IPv6 preferred 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_PRIORITY

(uint32_t) metric of the nexthop.

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
IFLA_EXT_MASK	extended information selection bitmap

Setting the RTEXT_FILTER_VF bit in IFLA_EXT_MASK requests SR-IOV VF status. The query is opt-in because obtaining status can require entering the PF driver. VF status is not included in unsolicited link notifications.

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_NUM_VF

(uint32_t) (readonly) Number of VF records returned. This attribute is returned with a successful RTEXT_FILTER_VF query.

IFLA_FREEBSD

(nested) Local interface attributes. When requested, IFLAF_VF_STATUS contains the following nested attributes:

IFLAF_VFS_ERROR		(uint32_t) errno if the PF query failed
IFLAF_VFS_PF_LINK_STATE	(uint8_t) IFLAF_VF_LINK_*
IFLAF_VFS_PF_LINK_SPEED	(uint64_t) bits per second

If the PF status provider does not implement this query, the status block is omitted. If an implemented PF status query fails, IFLAF_VFS_ERROR contains the errno value and the other status attributes are omitted. An empty status snapshot reports IFLA_NUM_VF as zero and contains no IFLA_FREEBSD_VF attributes.

Invalid or oversized data returned by a provider is reported through IFLAF_VFS_ERROR. Allocation failures while encoding the reply terminate the requested RTM_GETLINK operation with an error. For a multipart dump, valid interface records may precede the terminating error.

IFLA_FREEBSD_VF

(nested) (readonly) One VF record containing IFLAF_VF_* attributes. The attribute is repeated once for every VF in a successful status snapshot. Keeping each VF in an independent attribute permits the complete Netlink message to exceed the 16-bit length limit of an individual attribute. Each IFLA_FREEBSD_VF may contain the following attributes:

IFLAF_VF_INDEX			(uint32_t) PF-local VF index
IFLAF_VF_CONFIGURED		(bool) PF accepted configuration
IFLAF_VF_INITIALIZED		(bool) VF handshake completed
IFLAF_VF_MAC			(binary) PF-known primary MAC address
IFLAF_VF_VLAN_MODE		(uint8_t) IFLAF_VF_VLAN_*
IFLAF_VF_VLAN			(uint16_t) access VLAN identifier
IFLAF_VF_VLAN_PCP		(uint8_t) PF-administered priority code point
IFLAF_VF_VLAN_PROTO		(uint16_t) host-order access VLAN EtherType
IFLAF_VF_VLAN_COUNT		(uint32_t) explicit VLAN filters
IFLAF_VF_VLAN_LIMIT		(uint32_t) explicit VLAN-filter limit
IFLAF_VF_NUM_TX_QUEUES		(uint16_t) allocated transmit queues
IFLAF_VF_NUM_RX_QUEUES		(uint16_t) allocated receive queues
IFLAF_VF_MIN_TX_RATE		(uint64_t) minimum transmit bits per second
IFLAF_VF_MAX_TX_RATE		(uint64_t) maximum transmit bits per second
IFLAF_VF_ALLOW_SET_MAC		(bool) administrative permission
IFLAF_VF_ALLOW_SET_VLAN		(bool) administrative permission
IFLAF_VF_MAC_ANTI_SPOOF		(bool) MAC anti-spoofing enabled
IFLAF_VF_ALLOW_PROMISC		(bool) administrative permission
IFLAF_VF_TRAFFIC_ALLOWED	(bool) PF permits VF data traffic
IFLAF_VF_FAULT_BLOCKED		(bool) fault-containment block active
IFLAF_VF_QUARANTINED		(bool) persistent quarantine active
IFLAF_VF_API_VERSION		(string) negotiated mailbox API
IFLAF_VF_LINK_STATE_POLICY	(uint8_t) IFLAF_VF_LINK_*
IFLAF_VF_DRIVER			(nested) driver namespace; repeated

IFLAF_VF_INDEX is required in every list entry. Other fields are optional and are omitted when the PF driver cannot observe them; omission does not mean false or zero. Boolean attributes contain a native Netlink boolean value. IFLAF_VF_CONFIGURED means that the PF accepted the VF configuration, while IFLAF_VF_INITIALIZED means that the VF completed its driver or mailbox handshake since its last reset.

IFLAF_VF_TRAFFIC_ALLOWED means that the PF currently permits the VF to send and receive data traffic. It does not imply that the VF completed initialization, enabled queues, has link, or is actively passing packets. IFLAF_VF_FAULT_BLOCKED means that the PF isolated the VF because of a detected fault or abusive behavior. It does not include ordinary unconfigured, reset, or link-down states. When present, a driver namespace may describe the particular cause and recovery policy. When both fields are present, a fault block implies that traffic is not allowed. IFLAF_VF_QUARANTINED describes a persistent form of containment and, when both fields are present, implies that a fault block is active.

IFLAF_VF_NUM_TX_QUEUES and IFLAF_VF_NUM_RX_QUEUES are the numbers of transmit and receive queues allocated to the VF, not necessarily the numbers currently used by its driver. The transmit-rate attributes describe configured aggregate VF policy. A present zero minimum means no guaranteed allocation; a present zero maximum means no rate limit. When both are present and the maximum is nonzero, the minimum does not exceed the maximum. Access VLAN mode means that the PF imposes a single port VLAN policy. The optional IFLAF_VF_VLAN and IFLAF_VF_VLAN_PROTO attributes describe its VLAN identifier and host-order tag EtherType, respectively, and are present only in access mode. A present zero VLAN identifier can represent a priority-only access tag. Trunk mode means that no access VLAN is imposed and does not promise unlimited filter capacity. IFLAF_VF_VLAN_PCP describes the PF-administered IEEE 802.1p priority code point (0 through 7). It may be present in access or trunk mode, including priority-only tagging with VID 0. A present zero priority is distinct from an omitted priority. These attributes do not describe individual trunk filters or priorities selected by the VF. IFLAF_VF_VLAN_COUNT counts explicit filters recorded by the PF. It excludes untagged or priority-tag membership installed implicitly by the PF. The permission attributes describe requests the VF may make, not requests it has made. The top-level PF link state and speed are values normally advertised to VFs, not evidence that a VF driver is operational.

Link-state values are:

IFLAF_VF_LINK_UNKNOWN	state is unavailable
IFLAF_VF_LINK_DOWN	link is forced or observed down
IFLAF_VF_LINK_UP	link is forced or observed up
IFLAF_VF_LINK_AUTO	VF follows PF link state

VLAN-mode values are:

IFLAF_VF_VLAN_UNKNOWN	mode is unavailable
IFLAF_VF_VLAN_ACCESS	PF imposes an access VLAN
IFLAF_VF_VLAN_TRUNK	no access VLAN is imposed

Driver-specific data is returned under IFLAF_VF_DRIVER, which may be repeated directly in a VF record. Each driver object contains:

IFLAF_VFD_NAME		(string) stable namespace name
IFLAF_VFD_VERSION	(uint32_t) namespace schema version
IFLAF_VFD_FIELD		(nested) namespace field; repeated

Each field contains its namespace-local name in IFLAF_VFDF_NAME and exactly one of IFLAF_VFDF_BOOL, IFLAF_VFDF_NUMBER, IFLAF_VFDF_STRING, or IFLAF_VFDF_BINARY. The namespace defines the types and meanings of its fields. The named, typed form permits generic consumers to carry or display an extension without knowing its driver-specific schema. Consumers that interpret extensions must ignore unknown namespaces and fields. Each attribute, including each containing nested attribute, is limited to 65535 bytes by the Netlink encoding. If an individual VF record, driver extension, or field cannot be encoded within that limit, IFLAF_VFS_ERROR reports EMSGSIZE. The enclosing RTM_NEWLINK message may exceed 65535 bytes.

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

HISTORY

The NETLINK_ROUTE protocol family appeared in FreeBSD 13.2.

AUTHORS

The netlink was implemented by Alexander Chernikov ⟨[email protected]⟩. It was derived from the Google Summer of Code 2021 project by Ng Peng Nam Sean.

NAME

SYNOPSIS

DESCRIPTION

ROUTES

RTM_NEWROUTE

RTM_DELROUTE

RTM_GETROUTE

TLVs

Groups

NEXTHOPS

RTM_NEWNEXTHOP

RTM_DELNEXTHOP

RTM_GETNEXTHOP

TLVs

Groups

INTERFACES

RTM_NEWLINK

RTM_DELLINK

RTM_GETLINK

TLVs

Groups

INTERFACE ADDRESSES

RTM_NEWADDR

RTM_DELADDR

RTM_GETADDR

TLVs

Groups

NEIGHBORS

RTM_NEWNEIGH

RTM_DELNEIGH

RTM_GETNEIGH

TLVs

Groups

SEE ALSO

HISTORY

AUTHORS

History