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