share/man/man4/rtnetlink.4

   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
  39 The
  40 .Dv NETLINK_ROUTE
  41 family aims to be the primary configuration mechanism for all
  42 network-related tasks.
  43 Currently it supports configuring interfaces, interface addresses, routes,
  44 nexthops and arp/ndp neighbors.
  45 .Sh ROUTES
  46 All route configuration messages share the common header:
  47 .Bd -literal
  48 struct 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
  61 The
  62 .Va rtm_family
  63 specifies the route family to be operated on.
  64 Currently,
  65 .Dv AF_INET6
  66 and
  67 .Dv AF_INET
  68 are the only supported families.
  69 The route prefix length is stored in
  70 .Va rtm_dst_len
  71 .
  72 The caller should set the originator identity (one of the
  73 .Dv RTPROT_
  74 values) in
  75 .Va rtm_protocol
  76 .
  77 It is useful for users and for the application itself, allowing for easy
  78 identification of self-originated routes.
  79 The route scope has to be set via
  80 .Va rtm_scope
  81 field.
  82 The supported values are:
  83 .Bd -literal -offset indent -compact
  84 RT_SCOPE_UNIVERSE       Global scope
  85 RT_SCOPE_LINK           Link scope
  86 .Ed
  87 .Pp
  88 Route type needs to be set.
  89 The defined values are:
  90 .Bd -literal -offset indent -compact
  91 RTN_UNICAST     Unicast route
  92 RTN_MULTICAST   Multicast route
  93 RTN_BLACKHOLE   Drops traffic towards destination
  94 RTN_PROHIBIT    Drops traffic and sends reject
  95 .Ed
  96 .Pp
  97 The following messages are supported:
  98 .Ss RTM_NEWROUTE
  99 Adds a new route.
 100 All NL flags are supported.
 101 Extending a multipath route requires NLM_F_APPEND flag.
 102 .Ss RTM_DELROUTE
 103 Tries to delete a route.
 104 The route is specified using a combination of
 105 .Dv RTA_DST
 106 TLV and
 107 .Va rtm_dst_len .
 108 .Ss RTM_GETROUTE
 109 Fetches a single route or all routes in the current VNET, depending on the
 110 .Dv NLM_F_DUMP
 111 flag.
 112 Each route is reported as
 113 .Dv RTM_NEWROUTE
 114 message.
 115 The following filters are recognised by the kernel:
 116 .Pp
 117 .Bd -literal -offset indent -compact
 118 rtm_family      required family or AF_UNSPEC
 119 RTA_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.
 133 The only supported sub-attribute is
 134 .Dv RTAX_MTU , which stores path MTU as  uint32_t.
 135 .It Dv RTA_MULTIPATH
 136 This attribute contains multipath route nexthops with their weights.
 137 These nexthops are represented as a sequence of
 138 .Va rtnexthop
 139 structures, each followed by
 140 .Dv RTA_GATEWAY
 141 or
 142 .Dv RTA_VIA
 143 attributes.
 144 .Bd -literal
 145 struct 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
 153 The
 154 .Va rtnh_len
 155 field specifies the total nexthop info length, including both
 156 .Va struct rtnexthop
 157 and the following TLVs.
 158 The
 159 .Va rtnh_hops
 160 field stores relative nexthop weight, used for load balancing between group
 161 members.
 162 The
 163 .Va rtnh_ifindex
 164 field contains the index of the transmit interface.
 165 .Pp
 166 The following TLVs can follow the structure:
 167 .Bd -literal -offset indent -compact
 168 RTA_GATEWAY     IPv4/IPv6 nexthop address of the gateway
 169 RTA_VIA         IPv6 nexthop address for IPv4 route
 170 RTA_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.
 178 Default route table is
 179 .Dv RT_TABLE_MAIN .
 180 To 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
 188 The following groups are defined:
 189 .Bd -literal -offset indent -compact
 190 RTNLGRP_IPV4_ROUTE      Notifies on IPv4 route arrival/removal/change
 191 RTNLGRP_IPV6_ROUTE      Notifies on IPv6 route arrival/removal/change
 192 .Ed
 193 .Sh NEXTHOPS
 194 All nexthop/nexthop group configuration messages share the common header:
 195 .Bd -literal
 196 struct 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
 204 The
 205 .Va nh_family
 206 specificies the gateway address family.
 207 It can be different from route address family for IPv4 routes with IPv6
 208 nexthops.
 209 The
 210 .Va nh_protocol
 211 is similar to
 212 .Va rtm_protocol
 213 field, which designates originator application identity.
 214 .Pp
 215 The following messages are supported:
 216 .Ss RTM_NEWNEXTHOP
 217 Creates a new nexthop or nexthop group.
 218 .Ss RTM_DELNEXTHOP
 219 Deletes nexthop or nexthhop group.
 220 The required object is specified by the
 221 .Dv RTA_NH_ID
 222 attribute.
 223 .Ss RTM_GETNEXTHOP
 224 Fetches a single nexthop or all nexthops/nexthop groups, depending on the
 225 .Dv NLM_F_DUMP
 226 flag.
 227 The following filters are recognised by the kernel:
 228 .Pp
 229 .Bd -literal -offset indent -compact
 230 RTA_NH_ID       nexthop or nexthtop group id
 231 NHA_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.
 237 Should be provided by userland at the nexthtop creation time.
 238 .It Dv NHA_GROUP
 239 This attribute designates the nexthtop group and contains all of its nexthtops
 240 and their relative weights.
 241 The attribute constists of a list of
 242 .Va nexthop_grp
 243 structures:
 244 .Bd -literal
 245 struct 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
 255 NEXTHOP_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
 267 The following groups are defined:
 268 .Bd -literal -offset indent -compact
 269 RTNLGRP_NEXTHOP         Notifies on nexthop/groups arrival/removal/change
 270 .Ed
 271 .Sh INTERFACES
 272 All interface configuration messages share the common header:
 273 .Bd -literal
 274 struct 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
 284 Creates a new interface.
 285 The only mandatory TLV is
 286 .Dv IFLA_IFNAME .
 287 .Ss RTM_DELLINK
 288 Deletes the interface specified by
 289 .Dv IFLA_IFNAME .
 290 .Ss RTM_GETLINK
 291 Fetches a single interface or all interfaces in the current VNET, depending on the
 292 .Dv NLM_F_DUMP
 293 flag.
 294 Each interface is reported as a
 295 .Dv RTM_NEWLINK
 296 message.
 297 The following filters are recognised by the kernel:
 298 .Pp
 299 .Bd -literal -offset indent -compact
 300 ifi_index       interface index
 301 IFLA_IFNAME     interface name
 302 IFLA_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
 321 IFLA_INFO_KIND          (string) interface type ("vlan")
 322 IFLA_INFO_DATA          (nested) custom attributes
 323 .Ed
 324 The following types and attributes are supported:
 325 .Bl -tag -width indent
 326 .It Dv vlan
 327 .Bd -literal -offset indent -compact
 328 IFLA_VLAN_ID            (uint16_t) 802.1Q vlan id
 329 IFLA_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.
 334 Can be one of the following:
 335 .Bd -literal -offset indent -compact
 336 IF_OPER_UNKNOWN         status can not be determined
 337 IF_OPER_NOTPRESENT      some (hardware) component not present
 338 IF_OPER_DOWN            down
 339 IF_OPER_LOWERLAYERDOWN  some lower-level interface is down
 340 IF_OPER_TESTING         in some test mode
 341 IF_OPER_DORMANT         "up" but waiting for some condition (802.1X)
 342 IF_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
 347 struct 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
 376 The following groups are defined:
 377 .Bd -literal -offset indent -compact
 378 RTNLGRP_LINK            Notifies on interface arrival/removal/change
 379 .Ed
 380 .Sh INTERFACE ADDRESSES
 381 All interface address configuration messages share the common header:
 382 .Bd -literal
 383 struct 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
 392 The
 393 .Va ifa_family
 394 specifies the address family of the interface address.
 395 The
 396 .Va ifa_prefixlen
 397 specifies the prefix length if applicable for the address family.
 398 The
 399 .Va ifa_index
 400 specifies the interface index of the target interface.
 401 .Ss RTM_NEWADDR
 402 Not supported
 403 .Ss RTM_DELADDR
 404 Not supported
 405 .Ss RTM_GETADDR
 406 Fetches interface addresses in the current VNET matching conditions.
 407 Each address is reported as a
 408 .Dv RTM_NEWADDR
 409 message.
 410 The following filters are recognised by the kernel:
 411 .Pp
 412 .Bd -literal -offset indent -compact
 413 ifa_family      required family or AF_UNSPEC
 414 ifa_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.
 422 Set 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
 429 The following groups are defined:
 430 .Bd -literal -offset indent -compact
 431 RTNLGRP_IPV4_IFADDR     Notifies on IPv4 ifaddr arrival/removal/change
 432 RTNLGRP_IPV6_IFADDR     Notifies on IPv6 ifaddr arrival/removal/change
 433 .Ed
 434 .Sh NEIGHBORS
 435 All neighbor configuration messages share the common header:
 436 .Bd -literal
 437 struct 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
 448 The
 449 .Va ndm_family
 450 field specifies the address family (IPv4 or IPv6) of the neighbor.
 451 The
 452 .Va ndm_ifindex
 453 specifies the interface to operate on.
 454 The
 455 .Va ndm_state
 456 represents the entry state according to the neighbor model.
 457 The state can be one of the following:
 458 .Bd -literal -offset indent -compact
 459 NUD_INCOMPLETE          No lladdr, address resolution in progress
 460 NUD_REACHABLE           reachable & recently resolved
 461 NUD_STALE               has lladdr but it's stale
 462 NUD_DELAY               has lladdr, is stale, probes delayed
 463 NUD_PROBE               has lladdr, is stale, probes sent
 464 NUD_FAILED              unused
 465 .Ed
 466 .Pp
 467 The
 468 .Va ndm_flags
 469 field stores the options specific to this entry.
 470 Available flags:
 471 .Bd -literal -offset indent -compact
 472 NTF_SELF                local station (LLE_IFADDR)
 473 NTF_PROXY               proxy entry (LLE_PUB)
 474 NTF_STICKY              permament entry (LLE_STATIC)
 475 NTF_ROUTER              dst indicated itself as a router
 476 .Ed
 477 .Ss RTM_NEWNEIGH
 478 Creates new neighbor entry.
 479 The mandatory options are
 480 .Dv NDA_DST ,
 481 .Dv NDA_LLADDR
 482 and
 483 .Dv NDA_IFINDEX .
 484 .Ss RTM_DELNEIGH
 485 Deletes the neighbor entry.
 486 The entry is specified by the combination of
 487 .Dv NDA_DST
 488 and
 489 .Dv NDA_IFINDEX .
 490 .Ss RTM_GETNEIGH
 491 Fetches a single neighbor or all neighbors in the current VNET, depending on the
 492 .Dv NLM_F_DUMP
 493 flag.
 494 Each entry is reported as
 495 .Dv RTM_NEWNEIGH
 496 message.
 497 The following filters are recognised by the kernel:
 498 .Pp
 499 .Bd -literal -offset indent -compact
 500 ndm_family      required family or AF_UNSPEC
 501 ndm_ifindex     target ifindex
 502 NDA_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
 517 The following groups are defined:
 518 .Bd -literal -offset indent -compact
 519 RTNLGRP_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
 525 The
 526 .Dv NETLINK_ROUTE
 527 protocol family appeared in
 528 .Fx 13.2 .
 529 .Sh AUTHORS
 530 The netlink was implementated by
 531 .An -nosplit
 532 .An Alexander Chernikov Aq Mt melifaro@FreeBSD.org .
 533 It was derived from the Google Summer of Code 2021 project by
 534 .An Ng Peng Nam Sean .