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 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 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;	/* 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, 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) 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. Available 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

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 implementated by Alexander Chernikov <melifaro@FreeBSD.org>. 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