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 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 iden- tity (one of the RTPROT_ values) in rtm_protocol It is useful for users and for the application itself, allowing for easy identification of self-origi- nated routes. The route scope has to be set via rtm_scope field. The sup- ported 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 fol- lowing 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, includ- ing both struct rtnexthop and the following TLVs. The rtnh_hops field stores relative nexthop weight, used for load balancing be- tween 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 cre- ation 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; /* Interface 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 fol- lowing 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 mes- sage. 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 inter- face. 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 Alexander Chernikov <melifaro@FreeBSD.org>. It was derived from the Google Summer of Code 2021 project by Ng Peng Nam Sean. FreeBSD 15.1 November 1, 2022 RTNETLINK(4)
NAME | SYNOPSIS | DESCRIPTION | ROUTES | NEXTHOPS | INTERFACES | INTERFACE ADDRESSES | NEIGHBORS | SEE ALSO | HISTORY | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=rtnetlink&sektion=4&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>