1.\" 2.\" Copyright (C) 2022 Alexander Chernikov <melifaro@FreeBSD.org>. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd November 1, 2022 28.Dt RTNETLINK 4 29.Os 30.Sh NAME 31.Nm RTNetlink 32.Nd Network configuration-specific Netlink family 33.Sh SYNOPSIS 34.In netlink/netlink.h 35.In netlink/netlink_route.h 36.Ft int 37.Fn socket AF_NETLINK SOCK_RAW NETLINK_ROUTE 38.Sh DESCRIPTION 39The 40.Dv NETLINK_ROUTE 41family aims to be the primary configuration mechanism for all 42network-related tasks. 43Currently it supports configuring interfaces, interface addresses, routes, 44nexthops and arp/ndp neighbors. 45.Sh ROUTES 46All route configuration messages share the common header: 47.Bd -literal 48struct rtmsg { 49 unsigned char rtm_family; /* address family */ 50 unsigned char rtm_dst_len; /* Prefix length */ 51 unsigned char rtm_src_len; /* Deprecated, set to 0 */ 52 unsigned char rtm_tos; /* Type of service (not used) */ 53 unsigned char rtm_table; /* deprecated, set to 0 */ 54 unsigned char rtm_protocol; /* Routing protocol id (RTPROT_) */ 55 unsigned char rtm_scope; /* Route distance (RT_SCOPE_) */ 56 unsigned char rtm_type; /* Route type (RTN_) */ 57 unsigned rtm_flags; /* Route flags (not supported) */ 58}; 59.Ed 60.Pp 61The 62.Va rtm_family 63specifies the route family to be operated on. 64Currently, 65.Dv AF_INET6 66and 67.Dv AF_INET 68are the only supported families. 69The route prefix length is stored in 70.Va rtm_dst_len 71. 72The caller should set the originator identity (one of the 73.Dv RTPROT_ 74values) in 75.Va rtm_protocol 76. 77It is useful for users and for the application itself, allowing for easy 78identification of self-originated routes. 79The route scope has to be set via 80.Va rtm_scope 81field. 82The supported values are: 83.Bd -literal -offset indent -compact 84RT_SCOPE_UNIVERSE Global scope 85RT_SCOPE_LINK Link scope 86.Ed 87.Pp 88Route type needs to be set. 89The defined values are: 90.Bd -literal -offset indent -compact 91RTN_UNICAST Unicast route 92RTN_MULTICAST Multicast route 93RTN_BLACKHOLE Drops traffic towards destination 94RTN_PROHIBIT Drops traffic and sends reject 95.Ed 96.Pp 97The following messages are supported: 98.Ss RTM_NEWROUTE 99Adds a new route. 100All NL flags are supported. 101Extending a multipath route requires NLM_F_APPEND flag. 102.Ss RTM_DELROUTE 103Tries to delete a route. 104The route is specified using a combination of 105.Dv RTA_DST 106TLV and 107.Va rtm_dst_len . 108.Ss RTM_GETROUTE 109Fetches a single route or all routes in the current VNET, depending on the 110.Dv NLM_F_DUMP 111flag. 112Each route is reported as 113.Dv RTM_NEWROUTE 114message. 115The following filters are recognised by the kernel: 116.Pp 117.Bd -literal -offset indent -compact 118rtm_family required family or AF_UNSPEC 119RTA_TABLE fib number or RT_TABLE_UNSPEC to return all fibs 120.Ed 121.Ss TLVs 122.Bl -tag -width indent 123.It Dv RTA_DST 124(binary) IPv4/IPv6 address, depending on the 125.Va rtm_family . 126.It Dv RTA_OIF 127(uint32_t) transmit interface index. 128.It Dv RTA_GATEWAY 129(binary) IPv4/IPv6 gateway address, depending on the 130.Va rtm_family . 131.It Dv RTA_METRICS 132(nested) Container attribute, listing route properties. 133The only supported sub-attribute is 134.Dv RTAX_MTU , which stores path MTU as uint32_t. 135.It Dv RTA_MULTIPATH 136This attribute contains multipath route nexthops with their weights. 137These nexthops are represented as a sequence of 138.Va rtnexthop 139structures, each followed by 140.Dv RTA_GATEWAY 141or 142.Dv RTA_VIA 143attributes. 144.Bd -literal 145struct rtnexthop { 146 unsigned short rtnh_len; 147 unsigned char rtnh_flags; 148 unsigned char rtnh_hops; /* nexthop weight */ 149 int rtnh_ifindex; 150}; 151.Ed 152.Pp 153The 154.Va rtnh_len 155field specifies the total nexthop info length, including both 156.Va struct rtnexthop 157and the following TLVs. 158The 159.Va rtnh_hops 160field stores relative nexthop weight, used for load balancing between group 161members. 162The 163.Va rtnh_ifindex 164field contains the index of the transmit interface. 165.Pp 166The following TLVs can follow the structure: 167.Bd -literal -offset indent -compact 168RTA_GATEWAY IPv4/IPv6 nexthop address of the gateway 169RTA_VIA IPv6 nexthop address for IPv4 route 170RTA_KNH_ID Kernel-specific index of the nexthop 171.Ed 172.It Dv RTA_KNH_ID 173(uint32_t) (FreeBSD-specific) Auto-allocated kernel index of the nexthop. 174.It Dv RTA_RTFLAGS 175(uint32_t) (FreeBSD-specific) rtsock route flags. 176.It Dv RTA_TABLE 177(uint32_t) Fib number of the route. 178Default route table is 179.Dv RT_TABLE_MAIN . 180To explicitely specify "all tables" one needs to set the value to 181.Dv RT_TABLE_UNSPEC . 182.It Dv RTA_EXPIRES 183(uint32_t) seconds till path expiration. 184.It Dv RTA_NH_ID 185(uint32_t) useland nexthop or nexthop group index. 186.El 187.Ss Groups 188The following groups are defined: 189.Bd -literal -offset indent -compact 190RTNLGRP_IPV4_ROUTE Notifies on IPv4 route arrival/removal/change 191RTNLGRP_IPV6_ROUTE Notifies on IPv6 route arrival/removal/change 192.Ed 193.Sh NEXTHOPS 194All nexthop/nexthop group configuration messages share the common header: 195.Bd -literal 196struct nhmsg { 197 unsigned char nh_family; /* transport family */ 198 unsigned char nh_scope; /* ignored on RX, filled by kernel */ 199 unsigned char nh_protocol; /* Routing protocol that installed nh */ 200 unsigned char resvd; 201 unsigned int nh_flags; /* RTNH_F_* flags from route.h */ 202}; 203.Ed 204The 205.Va nh_family 206specificies the gateway address family. 207It can be different from route address family for IPv4 routes with IPv6 208nexthops. 209The 210.Va nh_protocol 211is similar to 212.Va rtm_protocol 213field, which designates originator application identity. 214.Pp 215The following messages are supported: 216.Ss RTM_NEWNEXTHOP 217Creates a new nexthop or nexthop group. 218.Ss RTM_DELNEXTHOP 219Deletes nexthop or nexthhop group. 220The required object is specified by the 221.Dv RTA_NH_ID 222attribute. 223.Ss RTM_GETNEXTHOP 224Fetches a single nexthop or all nexthops/nexthop groups, depending on the 225.Dv NLM_F_DUMP 226flag. 227The following filters are recognised by the kernel: 228.Pp 229.Bd -literal -offset indent -compact 230RTA_NH_ID nexthop or nexthtop group id 231NHA_GROUPS match only nexthtop groups 232.Ed 233.Ss TLVs 234.Bl -tag -width indent 235.It Dv RTA_NH_ID 236(uint32_t) Nexthhop index used to identify particular nexthop or nexthop group. 237Should be provided by userland at the nexthtop creation time. 238.It Dv NHA_GROUP 239This attribute designates the nexthtop group and contains all of its nexthtops 240and their relative weights. 241The attribute constists of a list of 242.Va nexthop_grp 243structures: 244.Bd -literal 245struct nexthop_grp { 246 uint32_t id; /* nexhop userland index */ 247 uint8_t weight; /* weight of this nexthop */ 248 uint8_t resvd1; 249 uint16_t resvd2; 250}; 251.Ed 252.It Dv NHA_GROUP_TYPE 253(uint16_t) Nexthtop group type, set to one of the following types: 254.Bd -literal -offset indent -compact 255NEXTHOP_GRP_TYPE_MPATH default multipath group 256.Ed 257.It Dv NHA_BLACKHOLE 258(flag) Marks the nexthtop as blackhole. 259.It Dv NHA_OIF 260(uint32_t) Transmit interface index of the nexthtop. 261.It Dv NHA_GATEWAY 262(binary) IPv4/IPv6 gateway address 263.It Dv NHA_GROUPS 264(flag) Matches nexthtop groups during dump. 265.El 266.Ss Groups 267The following groups are defined: 268.Bd -literal -offset indent -compact 269RTNLGRP_NEXTHOP Notifies on nexthop/groups arrival/removal/change 270.Ed 271.Sh INTERFACES 272All interface configuration messages share the common header: 273.Bd -literal 274struct ifinfomsg { 275 unsigned char ifi_family; /* not used, set to 0 */ 276 unsigned char __ifi_pad; 277 unsigned short ifi_type; /* ARPHRD_* */ 278 int ifi_index; /* Inteface index */ 279 unsigned ifi_flags; /* IFF_* flags */ 280 unsigned ifi_change; /* IFF_* change mask */ 281}; 282.Ed 283.Ss RTM_NEWLINK 284Creates a new interface. 285The only mandatory TLV is 286.Dv IFLA_IFNAME . 287.Ss RTM_DELLINK 288Deletes the interface specified by 289.Dv IFLA_IFNAME . 290.Ss RTM_GETLINK 291Fetches a single interface or all interfaces in the current VNET, depending on the 292.Dv NLM_F_DUMP 293flag. 294Each interface is reported as a 295.Dv RTM_NEWLINK 296message. 297The following filters are recognised by the kernel: 298.Pp 299.Bd -literal -offset indent -compact 300ifi_index interface index 301IFLA_IFNAME interface name 302IFLA_ALT_IFNAME interface name 303.Ed 304.Ss TLVs 305.Bl -tag -width indent 306.It Dv IFLA_ADDRESS 307(binary) Llink-level interface address (MAC). 308.It Dv IFLA_BROADCAST 309(binary) (readonly) Link-level broadcast address. 310.It Dv IFLA_IFNAME 311(string) New interface name. 312.It Dv IFLA_IFALIAS 313(string) Interface description. 314.It Dv IFLA_LINK 315(uint32_t) (readonly) Interface index. 316.It Dv IFLA_MASTER 317(uint32_t) Parent interface index. 318.It Dv IFLA_LINKINFO 319(nested) Interface type-specific attributes: 320.Bd -literal -offset indent -compact 321IFLA_INFO_KIND (string) interface type ("vlan") 322IFLA_INFO_DATA (nested) custom attributes 323.Ed 324The following types and attributes are supported: 325.Bl -tag -width indent 326.It Dv vlan 327.Bd -literal -offset indent -compact 328IFLA_VLAN_ID (uint16_t) 802.1Q vlan id 329IFLA_VLAN_PROTOCOL (uint16_t) Protocol: ETHERTYPE_VLAN or ETHERTYPE_QINQ 330.Ed 331.El 332.It Dv IFLA_OPERSTATE 333(uint8_t) Interface operational state per RFC 2863. 334Can be one of the following: 335.Bd -literal -offset indent -compact 336IF_OPER_UNKNOWN status can not be determined 337IF_OPER_NOTPRESENT some (hardware) component not present 338IF_OPER_DOWN down 339IF_OPER_LOWERLAYERDOWN some lower-level interface is down 340IF_OPER_TESTING in some test mode 341IF_OPER_DORMANT "up" but waiting for some condition (802.1X) 342IF_OPER_UP ready to pass packets 343.Ed 344.It Dv IFLA_STATS64 345(readonly) Consists of the following 64-bit counters structure: 346.Bd -literal 347struct rtnl_link_stats64 { 348 uint64_t rx_packets; /* total RX packets (IFCOUNTER_IPACKETS) */ 349 uint64_t tx_packets; /* total TX packets (IFCOUNTER_OPACKETS) */ 350 uint64_t rx_bytes; /* total RX bytes (IFCOUNTER_IBYTES) */ 351 uint64_t tx_bytes; /* total TX bytes (IFCOUNTER_OBYTES) */ 352 uint64_t rx_errors; /* RX errors (IFCOUNTER_IERRORS) */ 353 uint64_t tx_errors; /* RX errors (IFCOUNTER_OERRORS) */ 354 uint64_t rx_dropped; /* RX drop (no space in ring/no bufs) (IFCOUNTER_IQDROPS) */ 355 uint64_t tx_dropped; /* TX drop (IFCOUNTER_OQDROPS) */ 356 uint64_t multicast; /* RX multicast packets (IFCOUNTER_IMCASTS) */ 357 uint64_t collisions; /* not supported */ 358 uint64_t rx_length_errors; /* not supported */ 359 uint64_t rx_over_errors; /* not supported */ 360 uint64_t rx_crc_errors; /* not supported */ 361 uint64_t rx_frame_errors; /* not supported */ 362 uint64_t rx_fifo_errors; /* not supported */ 363 uint64_t rx_missed_errors; /* not supported */ 364 uint64_t tx_aborted_errors; /* not supported */ 365 uint64_t tx_carrier_errors; /* not supported */ 366 uint64_t tx_fifo_errors; /* not supported */ 367 uint64_t tx_heartbeat_errors; /* not supported */ 368 uint64_t tx_window_errors; /* not supported */ 369 uint64_t rx_compressed; /* not supported */ 370 uint64_t tx_compressed; /* not supported */ 371 uint64_t rx_nohandler; /* dropped due to no proto handler (IFCOUNTER_NOPROTO) */ 372}; 373.Ed 374.El 375.Ss Groups 376The following groups are defined: 377.Bd -literal -offset indent -compact 378RTNLGRP_LINK Notifies on interface arrival/removal/change 379.Ed 380.Sh INTERFACE ADDRESSES 381All interface address configuration messages share the common header: 382.Bd -literal 383struct ifaddrmsg { 384 uint8_t ifa_family; /* Address family */ 385 uint8_t ifa_prefixlen; /* Prefix length */ 386 uint8_t ifa_flags; /* Address-specific flags */ 387 uint8_t ifa_scope; /* Address scope */ 388 uint32_t ifa_index; /* Link ifindex */ 389}; 390.Ed 391.Pp 392The 393.Va ifa_family 394specifies the address family of the interface address. 395The 396.Va ifa_prefixlen 397specifies the prefix length if applicable for the address family. 398The 399.Va ifa_index 400specifies the interface index of the target interface. 401.Ss RTM_NEWADDR 402Not supported 403.Ss RTM_DELADDR 404Not supported 405.Ss RTM_GETADDR 406Fetches interface addresses in the current VNET matching conditions. 407Each address is reported as a 408.Dv RTM_NEWADDR 409message. 410The following filters are recognised by the kernel: 411.Pp 412.Bd -literal -offset indent -compact 413ifa_family required family or AF_UNSPEC 414ifa_index matching interface index or 0 415.Ed 416.Ss TLVs 417.Bl -tag -width indent 418.It Dv IFA_ADDRESS 419(binary) masked interface address or destination address for p2p interfaces. 420.It Dv IFA_LOCAL 421(binary) local interface address. 422Set for IPv4 and p2p addresses. 423.It Dv IFA_LABEL 424(string) interface name. 425.It Dv IFA_BROADCAST 426(binary) broacast interface address. 427.El 428.Ss Groups 429The following groups are defined: 430.Bd -literal -offset indent -compact 431RTNLGRP_IPV4_IFADDR Notifies on IPv4 ifaddr arrival/removal/change 432RTNLGRP_IPV6_IFADDR Notifies on IPv6 ifaddr arrival/removal/change 433.Ed 434.Sh NEIGHBORS 435All neighbor configuration messages share the common header: 436.Bd -literal 437struct ndmsg { 438 uint8_t ndm_family; 439 uint8_t ndm_pad1; 440 uint16_t ndm_pad2; 441 int32_t ndm_ifindex; 442 uint16_t ndm_state; 443 uint8_t ndm_flags; 444 uint8_t ndm_type; 445}; 446.Ed 447.Pp 448The 449.Va ndm_family 450field specifies the address family (IPv4 or IPv6) of the neighbor. 451The 452.Va ndm_ifindex 453specifies the interface to operate on. 454The 455.Va ndm_state 456represents the entry state according to the neighbor model. 457The state can be one of the following: 458.Bd -literal -offset indent -compact 459NUD_INCOMPLETE No lladdr, address resolution in progress 460NUD_REACHABLE reachable & recently resolved 461NUD_STALE has lladdr but it's stale 462NUD_DELAY has lladdr, is stale, probes delayed 463NUD_PROBE has lladdr, is stale, probes sent 464NUD_FAILED unused 465.Ed 466.Pp 467The 468.Va ndm_flags 469field stores the options specific to this entry. 470Available flags: 471.Bd -literal -offset indent -compact 472NTF_SELF local station (LLE_IFADDR) 473NTF_PROXY proxy entry (LLE_PUB) 474NTF_STICKY permament entry (LLE_STATIC) 475NTF_ROUTER dst indicated itself as a router 476.Ed 477.Ss RTM_NEWNEIGH 478Creates new neighbor entry. 479The mandatory options are 480.Dv NDA_DST , 481.Dv NDA_LLADDR 482and 483.Dv NDA_IFINDEX . 484.Ss RTM_DELNEIGH 485Deletes the neighbor entry. 486The entry is specified by the combination of 487.Dv NDA_DST 488and 489.Dv NDA_IFINDEX . 490.Ss RTM_GETNEIGH 491Fetches a single neighbor or all neighbors in the current VNET, depending on the 492.Dv NLM_F_DUMP 493flag. 494Each entry is reported as 495.Dv RTM_NEWNEIGH 496message. 497The following filters are recognised by the kernel: 498.Pp 499.Bd -literal -offset indent -compact 500ndm_family required family or AF_UNSPEC 501ndm_ifindex target ifindex 502NDA_IFINDEX target ifindex 503.Ed 504.Ss TLVs 505.Bl -tag -width indent 506.It Dv NDA_DST 507(binary) neighbor IPv4/IPv6 address. 508.It Dv NDA_LLADDR 509(binary) neighbor link-level address. 510.It Dv NDA_IFINDEX 511(uint32_t) interface index. 512.It Dv NDA_FLAGS_EXT 513(uint32_t) extended version of 514.Va ndm_flags . 515.El 516.Ss Groups 517The following groups are defined: 518.Bd -literal -offset indent -compact 519RTNLGRP_NEIGH Notifies on ARP/NDP neighbor arrival/removal/change 520.Ed 521.Sh SEE ALSO 522.Xr netlink 4 , 523.Xr route 4 524.Sh HISTORY 525The 526.Dv NETLINK_ROUTE 527protocol family appeared in 528.Fx 14.0 . 529.Sh AUTHORS 530The netlink was implementated by 531.An -nosplit 532.An Alexander Chernikov Aq Mt melifaro@FreeBSD.org . 533It was derived from the Google Summer of Code 2021 project by 534.An Ng Peng Nam Sean . 535