FreeBSD manual
download PDF document: rtnetlink.4.pdf
RTNETLINK(4) FreeBSD 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
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
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:
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
constists 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
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
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
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
RTM_NEWNEIGH
Creates new neighbor entry. The mandatory options are NDA_DST,
NDA_LLADDR and NDA_IFINDEX.
RTM_DELNEIGH
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 implementated by Alexander Chernikov
<melifaro@FreeBSD.org>. It was derived from the Google Summer of Code
2021 project by Ng Peng Nam Sean.
FreeBSD 14.0-RELEASE-p6 November 1, 2022 FreeBSD 14.0-RELEASE-p6