Manual Pages  — RTNETLINK

RTNetlink – Network configuration-specific Netlink family

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

#include <netlink/netlink.h>

#include <netlink/netlink_route.h>

int
socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE);

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.

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:

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

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

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

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.

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

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:

Creates a new nexthop or nexthop group.

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

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

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.

The following groups are defined:

RTNLGRP_NEXTHOP         Notifies on nexthop/groups arrival/removal/change

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 */
};

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

Deletes the interface specified by IFLA_IFNAME.

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_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) */ };

The following groups are defined:

RTNLGRP_LINK            Notifies on interface arrival/removal/change

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.

Not supported

Not supported

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

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.

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

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

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

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

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

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.

The following groups are defined:

RTNLGRP_NEIGH   Notifies on ARP/NDP neighbor  arrival/removal/change

The NETLINK_ROUTE protocol family appeared in FreeBSD 13.2 .

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