1.. SPDX-License-Identifier: BSD-3-Clause 2 3======================= 4Introduction to Netlink 5======================= 6 7Netlink is often described as an ioctl() replacement. 8It aims to replace fixed-format C structures as supplied 9to ioctl() with a format which allows an easy way to add 10or extended the arguments. 11 12To achieve this Netlink uses a minimal fixed-format metadata header 13followed by multiple attributes in the TLV (type, length, value) format. 14 15Unfortunately the protocol has evolved over the years, in an organic 16and undocumented fashion, making it hard to coherently explain. 17To make the most practical sense this document starts by describing 18netlink as it is used today and dives into more "historical" uses 19in later sections. 20 21Opening a socket 22================ 23 24Netlink communication happens over sockets, a socket needs to be 25opened first: 26 27.. code-block:: c 28 29 fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_GENERIC); 30 31The use of sockets allows for a natural way of exchanging information 32in both directions (to and from the kernel). The operations are still 33performed synchronously when applications send() the request but 34a separate recv() system call is needed to read the reply. 35 36A very simplified flow of a Netlink "call" will therefore look 37something like: 38 39.. code-block:: c 40 41 fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_GENERIC); 42 43 /* format the request */ 44 send(fd, &request, sizeof(request)); 45 n = recv(fd, &response, RSP_BUFFER_SIZE); 46 /* interpret the response */ 47 48Netlink also provides natural support for "dumping", i.e. communicating 49to user space all objects of a certain type (e.g. dumping all network 50interfaces). 51 52.. code-block:: c 53 54 fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_GENERIC); 55 56 /* format the dump request */ 57 send(fd, &request, sizeof(request)); 58 while (1) { 59 n = recv(fd, &buffer, RSP_BUFFER_SIZE); 60 /* one recv() call can read multiple messages, hence the loop below */ 61 for (nl_msg in buffer) { 62 if (nl_msg.nlmsg_type == NLMSG_DONE) 63 goto dump_finished; 64 /* process the object */ 65 } 66 } 67 dump_finished: 68 69The first two arguments of the socket() call require little explanation - 70it is opening a Netlink socket, with all headers provided by the user 71(hence NETLINK, RAW). The last argument is the protocol within Netlink. 72This field used to identify the subsystem with which the socket will 73communicate. 74 75Classic vs Generic Netlink 76-------------------------- 77 78Initial implementation of Netlink depended on a static allocation 79of IDs to subsystems and provided little supporting infrastructure. 80Let us refer to those protocols collectively as **Classic Netlink**. 81The list of them is defined on top of the ``include/uapi/linux/netlink.h`` 82file, they include among others - general networking (NETLINK_ROUTE), 83iSCSI (NETLINK_ISCSI), and audit (NETLINK_AUDIT). 84 85**Generic Netlink** (introduced in 2005) allows for dynamic registration of 86subsystems (and subsystem ID allocation), introspection and simplifies 87implementing the kernel side of the interface. 88 89The following section describes how to use Generic Netlink, as the 90number of subsystems using Generic Netlink outnumbers the older 91protocols by an order of magnitude. There are also no plans for adding 92more Classic Netlink protocols to the kernel. 93Basic information on how communicating with core networking parts of 94the Linux kernel (or another of the 20 subsystems using Classic 95Netlink) differs from Generic Netlink is provided later in this document. 96 97Generic Netlink 98=============== 99 100In addition to the Netlink fixed metadata header each Netlink protocol 101defines its own fixed metadata header. (Similarly to how network 102headers stack - Ethernet > IP > TCP we have Netlink > Generic N. > Family.) 103 104A Netlink message always starts with struct nlmsghdr, which is followed 105by a protocol-specific header. In case of Generic Netlink the protocol 106header is struct genlmsghdr. 107 108The practical meaning of the fields in case of Generic Netlink is as follows: 109 110.. code-block:: c 111 112 struct nlmsghdr { 113 __u32 nlmsg_len; /* Length of message including headers */ 114 __u16 nlmsg_type; /* Generic Netlink Family (subsystem) ID */ 115 __u16 nlmsg_flags; /* Flags - request or dump */ 116 __u32 nlmsg_seq; /* Sequence number */ 117 __u32 nlmsg_pid; /* Port ID, set to 0 */ 118 }; 119 struct genlmsghdr { 120 __u8 cmd; /* Command, as defined by the Family */ 121 __u8 version; /* Irrelevant, set to 1 */ 122 __u16 reserved; /* Reserved, set to 0 */ 123 }; 124 /* TLV attributes follow... */ 125 126In Classic Netlink :c:member:`nlmsghdr.nlmsg_type` used to identify 127which operation within the subsystem the message was referring to 128(e.g. get information about a netdev). Generic Netlink needs to mux 129multiple subsystems in a single protocol so it uses this field to 130identify the subsystem, and :c:member:`genlmsghdr.cmd` identifies 131the operation instead. (See :ref:`res_fam` for 132information on how to find the Family ID of the subsystem of interest.) 133Note that the first 16 values (0 - 15) of this field are reserved for 134control messages both in Classic Netlink and Generic Netlink. 135See :ref:`nl_msg_type` for more details. 136 137There are 3 usual types of message exchanges on a Netlink socket: 138 139 - performing a single action (``do``); 140 - dumping information (``dump``); 141 - getting asynchronous notifications (``multicast``). 142 143Classic Netlink is very flexible and presumably allows other types 144of exchanges to happen, but in practice those are the three that get 145used. 146 147Asynchronous notifications are sent by the kernel and received by 148the user sockets which subscribed to them. ``do`` and ``dump`` requests 149are initiated by the user. :c:member:`nlmsghdr.nlmsg_flags` should 150be set as follows: 151 152 - for ``do``: ``NLM_F_REQUEST | NLM_F_ACK`` 153 - for ``dump``: ``NLM_F_REQUEST | NLM_F_ACK | NLM_F_DUMP`` 154 155:c:member:`nlmsghdr.nlmsg_seq` should be a set to a monotonically 156increasing value. The value gets echoed back in responses and doesn't 157matter in practice, but setting it to an increasing value for each 158message sent is considered good hygiene. The purpose of the field is 159matching responses to requests. Asynchronous notifications will have 160:c:member:`nlmsghdr.nlmsg_seq` of ``0``. 161 162:c:member:`nlmsghdr.nlmsg_pid` is the Netlink equivalent of an address. 163This field can be set to ``0`` when talking to the kernel. 164See :ref:`nlmsg_pid` for the (uncommon) uses of the field. 165 166The expected use for :c:member:`genlmsghdr.version` was to allow 167versioning of the APIs provided by the subsystems. No subsystem to 168date made significant use of this field, so setting it to ``1`` seems 169like a safe bet. 170 171.. _nl_msg_type: 172 173Netlink message types 174--------------------- 175 176As previously mentioned :c:member:`nlmsghdr.nlmsg_type` carries 177protocol specific values but the first 16 identifiers are reserved 178(first subsystem specific message type should be equal to 179``NLMSG_MIN_TYPE`` which is ``0x10``). 180 181There are only 4 Netlink control messages defined: 182 183 - ``NLMSG_NOOP`` - ignore the message, not used in practice; 184 - ``NLMSG_ERROR`` - carries the return code of an operation; 185 - ``NLMSG_DONE`` - marks the end of a dump; 186 - ``NLMSG_OVERRUN`` - socket buffer has overflown, not used to date. 187 188``NLMSG_ERROR`` and ``NLMSG_DONE`` are of practical importance. 189They carry return codes for operations. Note that unless 190the ``NLM_F_ACK`` flag is set on the request Netlink will not respond 191with ``NLMSG_ERROR`` if there is no error. To avoid having to special-case 192this quirk it is recommended to always set ``NLM_F_ACK``. 193 194The format of ``NLMSG_ERROR`` is described by struct nlmsgerr:: 195 196 ---------------------------------------------- 197 | struct nlmsghdr - response header | 198 ---------------------------------------------- 199 | int error | 200 ---------------------------------------------- 201 | struct nlmsghdr - original request header | 202 ---------------------------------------------- 203 | ** optionally (1) payload of the request | 204 ---------------------------------------------- 205 | ** optionally (2) extended ACK | 206 ---------------------------------------------- 207 208There are two instances of struct nlmsghdr here, first of the response 209and second of the request. ``NLMSG_ERROR`` carries the information about 210the request which led to the error. This could be useful when trying 211to match requests to responses or re-parse the request to dump it into 212logs. 213 214The payload of the request is not echoed in messages reporting success 215(``error == 0``) or if ``NETLINK_CAP_ACK`` setsockopt() was set. 216The latter is common 217and perhaps recommended as having to read a copy of every request back 218from the kernel is rather wasteful. The absence of request payload 219is indicated by ``NLM_F_CAPPED`` in :c:member:`nlmsghdr.nlmsg_flags`. 220 221The second optional element of ``NLMSG_ERROR`` are the extended ACK 222attributes. See :ref:`ext_ack` for more details. The presence 223of extended ACK is indicated by ``NLM_F_ACK_TLVS`` in 224:c:member:`nlmsghdr.nlmsg_flags`. 225 226``NLMSG_DONE`` is simpler, the request is never echoed but the extended 227ACK attributes may be present:: 228 229 ---------------------------------------------- 230 | struct nlmsghdr - response header | 231 ---------------------------------------------- 232 | int error | 233 ---------------------------------------------- 234 | ** optionally extended ACK | 235 ---------------------------------------------- 236 237.. _res_fam: 238 239Resolving the Family ID 240----------------------- 241 242This section explains how to find the Family ID of a subsystem. 243It also serves as an example of Generic Netlink communication. 244 245Generic Netlink is itself a subsystem exposed via the Generic Netlink API. 246To avoid a circular dependency Generic Netlink has a statically allocated 247Family ID (``GENL_ID_CTRL`` which is equal to ``NLMSG_MIN_TYPE``). 248The Generic Netlink family implements a command used to find out information 249about other families (``CTRL_CMD_GETFAMILY``). 250 251To get information about the Generic Netlink family named for example 252``"test1"`` we need to send a message on the previously opened Generic Netlink 253socket. The message should target the Generic Netlink Family (1), be a 254``do`` (2) call to ``CTRL_CMD_GETFAMILY`` (3). A ``dump`` version of this 255call would make the kernel respond with information about *all* the families 256it knows about. Last but not least the name of the family in question has 257to be specified (4) as an attribute with the appropriate type:: 258 259 struct nlmsghdr: 260 __u32 nlmsg_len: 32 261 __u16 nlmsg_type: GENL_ID_CTRL // (1) 262 __u16 nlmsg_flags: NLM_F_REQUEST | NLM_F_ACK // (2) 263 __u32 nlmsg_seq: 1 264 __u32 nlmsg_pid: 0 265 266 struct genlmsghdr: 267 __u8 cmd: CTRL_CMD_GETFAMILY // (3) 268 __u8 version: 2 /* or 1, doesn't matter */ 269 __u16 reserved: 0 270 271 struct nlattr: // (4) 272 __u16 nla_len: 10 273 __u16 nla_type: CTRL_ATTR_FAMILY_NAME 274 char data: test1\0 275 276 (padding:) 277 char data: \0\0 278 279The length fields in Netlink (:c:member:`nlmsghdr.nlmsg_len` 280and :c:member:`nlattr.nla_len`) always *include* the header. 281Attribute headers in netlink must be aligned to 4 bytes from the start 282of the message, hence the extra ``\0\0`` after ``CTRL_ATTR_FAMILY_NAME``. 283The attribute lengths *exclude* the padding. 284 285If the family is found kernel will reply with two messages, the response 286with all the information about the family:: 287 288 /* Message #1 - reply */ 289 struct nlmsghdr: 290 __u32 nlmsg_len: 136 291 __u16 nlmsg_type: GENL_ID_CTRL 292 __u16 nlmsg_flags: 0 293 __u32 nlmsg_seq: 1 /* echoed from our request */ 294 __u32 nlmsg_pid: 5831 /* The PID of our user space process */ 295 296 struct genlmsghdr: 297 __u8 cmd: CTRL_CMD_GETFAMILY 298 __u8 version: 2 299 __u16 reserved: 0 300 301 struct nlattr: 302 __u16 nla_len: 10 303 __u16 nla_type: CTRL_ATTR_FAMILY_NAME 304 char data: test1\0 305 306 (padding:) 307 data: \0\0 308 309 struct nlattr: 310 __u16 nla_len: 6 311 __u16 nla_type: CTRL_ATTR_FAMILY_ID 312 __u16: 123 /* The Family ID we are after */ 313 314 (padding:) 315 char data: \0\0 316 317 struct nlattr: 318 __u16 nla_len: 9 319 __u16 nla_type: CTRL_ATTR_FAMILY_VERSION 320 __u16: 1 321 322 /* ... etc, more attributes will follow. */ 323 324And the error code (success) since ``NLM_F_ACK`` had been set on the request:: 325 326 /* Message #2 - the ACK */ 327 struct nlmsghdr: 328 __u32 nlmsg_len: 36 329 __u16 nlmsg_type: NLMSG_ERROR 330 __u16 nlmsg_flags: NLM_F_CAPPED /* There won't be a payload */ 331 __u32 nlmsg_seq: 1 /* echoed from our request */ 332 __u32 nlmsg_pid: 5831 /* The PID of our user space process */ 333 334 int error: 0 335 336 struct nlmsghdr: /* Copy of the request header as we sent it */ 337 __u32 nlmsg_len: 32 338 __u16 nlmsg_type: GENL_ID_CTRL 339 __u16 nlmsg_flags: NLM_F_REQUEST | NLM_F_ACK 340 __u32 nlmsg_seq: 1 341 __u32 nlmsg_pid: 0 342 343The order of attributes (struct nlattr) is not guaranteed so the user 344has to walk the attributes and parse them. 345 346Note that Generic Netlink sockets are not associated or bound to a single 347family. A socket can be used to exchange messages with many different 348families, selecting the recipient family on message-by-message basis using 349the :c:member:`nlmsghdr.nlmsg_type` field. 350 351.. _ext_ack: 352 353Extended ACK 354------------ 355 356Extended ACK controls reporting of additional error/warning TLVs 357in ``NLMSG_ERROR`` and ``NLMSG_DONE`` messages. To maintain backward 358compatibility this feature has to be explicitly enabled by setting 359the ``NETLINK_EXT_ACK`` setsockopt() to ``1``. 360 361Types of extended ack attributes are defined in enum nlmsgerr_attrs. 362The most commonly used attributes are ``NLMSGERR_ATTR_MSG``, 363``NLMSGERR_ATTR_OFFS`` and ``NLMSGERR_ATTR_MISS_*``. 364 365``NLMSGERR_ATTR_MSG`` carries a message in English describing 366the encountered problem. These messages are far more detailed 367than what can be expressed thru standard UNIX error codes. 368 369``NLMSGERR_ATTR_OFFS`` points to the attribute which caused the problem. 370 371``NLMSGERR_ATTR_MISS_TYPE`` and ``NLMSGERR_ATTR_MISS_NEST`` 372inform about a missing attribute. 373 374Extended ACKs can be reported on errors as well as in case of success. 375The latter should be treated as a warning. 376 377Extended ACKs greatly improve the usability of Netlink and should 378always be enabled, appropriately parsed and reported to the user. 379 380Advanced topics 381=============== 382 383Dump consistency 384---------------- 385 386Some of the data structures kernel uses for storing objects make 387it hard to provide an atomic snapshot of all the objects in a dump 388(without impacting the fast-paths updating them). 389 390Kernel may set the ``NLM_F_DUMP_INTR`` flag on any message in a dump 391(including the ``NLMSG_DONE`` message) if the dump was interrupted and 392may be inconsistent (e.g. missing objects). User space should retry 393the dump if it sees the flag set. 394 395Introspection 396------------- 397 398The basic introspection abilities are enabled by access to the Family 399object as reported in :ref:`res_fam`. User can query information about 400the Generic Netlink family, including which operations are supported 401by the kernel and what attributes the kernel understands. 402Family information includes the highest ID of an attribute kernel can parse, 403a separate command (``CTRL_CMD_GETPOLICY``) provides detailed information 404about supported attributes, including ranges of values the kernel accepts. 405 406Querying family information is useful in cases when user space needs 407to make sure that the kernel has support for a feature before issuing 408a request. 409 410.. _nlmsg_pid: 411 412nlmsg_pid 413--------- 414 415:c:member:`nlmsghdr.nlmsg_pid` is the Netlink equivalent of an address. 416It is referred to as Port ID, sometimes Process ID because for historical 417reasons if the application does not select (bind() to) an explicit Port ID 418kernel will automatically assign it the ID equal to its Process ID 419(as reported by the getpid() system call). 420 421Similarly to the bind() semantics of the TCP/IP network protocols the value 422of zero means "assign automatically", hence it is common for applications 423to leave the :c:member:`nlmsghdr.nlmsg_pid` field initialized to ``0``. 424 425The field is still used today in rare cases when kernel needs to send 426a unicast notification. User space application can use bind() to associate 427its socket with a specific PID, it then communicates its PID to the kernel. 428This way the kernel can reach the specific user space process. 429 430This sort of communication is utilized in UMH (User Mode Helper)-like 431scenarios when kernel needs to trigger user space processing or ask user 432space for a policy decision. 433 434Multicast notifications 435----------------------- 436 437One of the strengths of Netlink is the ability to send event notifications 438to user space. This is a unidirectional form of communication (kernel -> 439user) and does not involve any control messages like ``NLMSG_ERROR`` or 440``NLMSG_DONE``. 441 442For example the Generic Netlink family itself defines a set of multicast 443notifications about registered families. When a new family is added the 444sockets subscribed to the notifications will get the following message:: 445 446 struct nlmsghdr: 447 __u32 nlmsg_len: 136 448 __u16 nlmsg_type: GENL_ID_CTRL 449 __u16 nlmsg_flags: 0 450 __u32 nlmsg_seq: 0 451 __u32 nlmsg_pid: 0 452 453 struct genlmsghdr: 454 __u8 cmd: CTRL_CMD_NEWFAMILY 455 __u8 version: 2 456 __u16 reserved: 0 457 458 struct nlattr: 459 __u16 nla_len: 10 460 __u16 nla_type: CTRL_ATTR_FAMILY_NAME 461 char data: test1\0 462 463 (padding:) 464 data: \0\0 465 466 struct nlattr: 467 __u16 nla_len: 6 468 __u16 nla_type: CTRL_ATTR_FAMILY_ID 469 __u16: 123 /* The Family ID we are after */ 470 471 (padding:) 472 char data: \0\0 473 474 struct nlattr: 475 __u16 nla_len: 9 476 __u16 nla_type: CTRL_ATTR_FAMILY_VERSION 477 __u16: 1 478 479 /* ... etc, more attributes will follow. */ 480 481The notification contains the same information as the response 482to the ``CTRL_CMD_GETFAMILY`` request. 483 484The Netlink headers of the notification are mostly 0 and irrelevant. 485The :c:member:`nlmsghdr.nlmsg_seq` may be either zero or a monotonically 486increasing notification sequence number maintained by the family. 487 488To receive notifications the user socket must subscribe to the relevant 489notification group. Much like the Family ID, the Group ID for a given 490multicast group is dynamic and can be found inside the Family information. 491The ``CTRL_ATTR_MCAST_GROUPS`` attribute contains nests with names 492(``CTRL_ATTR_MCAST_GRP_NAME``) and IDs (``CTRL_ATTR_MCAST_GRP_ID``) of 493the groups family. 494 495Once the Group ID is known a setsockopt() call adds the socket to the group: 496 497.. code-block:: c 498 499 unsigned int group_id; 500 501 /* .. find the group ID... */ 502 503 setsockopt(fd, SOL_NETLINK, NETLINK_ADD_MEMBERSHIP, 504 &group_id, sizeof(group_id)); 505 506The socket will now receive notifications. 507 508It is recommended to use separate sockets for receiving notifications 509and sending requests to the kernel. The asynchronous nature of notifications 510means that they may get mixed in with the responses making the message 511handling much harder. 512 513Buffer sizing 514------------- 515 516Netlink sockets are datagram sockets rather than stream sockets, 517meaning that each message must be received in its entirety by a single 518recv()/recvmsg() system call. If the buffer provided by the user is too 519short, the message will be truncated and the ``MSG_TRUNC`` flag set 520in struct msghdr (struct msghdr is the second argument 521of the recvmsg() system call, *not* a Netlink header). 522 523Upon truncation the remaining part of the message is discarded. 524 525Netlink expects that the user buffer will be at least 8kB or a page 526size of the CPU architecture, whichever is bigger. Particular Netlink 527families may, however, require a larger buffer. 32kB buffer is recommended 528for most efficient handling of dumps (larger buffer fits more dumped 529objects and therefore fewer recvmsg() calls are needed). 530 531Classic Netlink 532=============== 533 534The main differences between Classic and Generic Netlink are the dynamic 535allocation of subsystem identifiers and availability of introspection. 536In theory the protocol does not differ significantly, however, in practice 537Classic Netlink experimented with concepts which were abandoned in Generic 538Netlink (really, they usually only found use in a small corner of a single 539subsystem). This section is meant as an explainer of a few of such concepts, 540with the explicit goal of giving the Generic Netlink 541users the confidence to ignore them when reading the uAPI headers. 542 543Most of the concepts and examples here refer to the ``NETLINK_ROUTE`` family, 544which covers much of the configuration of the Linux networking stack. 545Real documentation of that family, deserves a chapter (or a book) of its own. 546 547Families 548-------- 549 550Netlink refers to subsystems as families. This is a remnant of using 551sockets and the concept of protocol families, which are part of message 552demultiplexing in ``NETLINK_ROUTE``. 553 554Sadly every layer of encapsulation likes to refer to whatever it's carrying 555as "families" making the term very confusing: 556 557 1. AF_NETLINK is a bona fide socket protocol family 558 2. AF_NETLINK's documentation refers to what comes after its own 559 header (struct nlmsghdr) in a message as a "Family Header" 560 3. Generic Netlink is a family for AF_NETLINK (struct genlmsghdr follows 561 struct nlmsghdr), yet it also calls its users "Families". 562 563Note that the Generic Netlink Family IDs are in a different "ID space" 564and overlap with Classic Netlink protocol numbers (e.g. ``NETLINK_CRYPTO`` 565has the Classic Netlink protocol ID of 21 which Generic Netlink will 566happily allocate to one of its families as well). 567 568Strict checking 569--------------- 570 571The ``NETLINK_GET_STRICT_CHK`` socket option enables strict input checking 572in ``NETLINK_ROUTE``. It was needed because historically kernel did not 573validate the fields of structures it didn't process. This made it impossible 574to start using those fields later without risking regressions in applications 575which initialized them incorrectly or not at all. 576 577``NETLINK_GET_STRICT_CHK`` declares that the application is initializing 578all fields correctly. It also opts into validating that message does not 579contain trailing data and requests that kernel rejects attributes with 580type higher than largest attribute type known to the kernel. 581 582``NETLINK_GET_STRICT_CHK`` is not used outside of ``NETLINK_ROUTE``. 583 584Unknown attributes 585------------------ 586 587Historically Netlink ignored all unknown attributes. The thinking was that 588it would free the application from having to probe what kernel supports. 589The application could make a request to change the state and check which 590parts of the request "stuck". 591 592This is no longer the case for new Generic Netlink families and those opting 593in to strict checking. See enum netlink_validation for validation types 594performed. 595 596Fixed metadata and structures 597----------------------------- 598 599Classic Netlink made liberal use of fixed-format structures within 600the messages. Messages would commonly have a structure with 601a considerable number of fields after struct nlmsghdr. It was also 602common to put structures with multiple members inside attributes, 603without breaking each member into an attribute of its own. 604 605This has caused problems with validation and extensibility and 606therefore using binary structures is actively discouraged for new 607attributes. 608 609Request types 610------------- 611 612``NETLINK_ROUTE`` categorized requests into 4 types ``NEW``, ``DEL``, ``GET``, 613and ``SET``. Each object can handle all or some of those requests 614(objects being netdevs, routes, addresses, qdiscs etc.) Request type 615is defined by the 2 lowest bits of the message type, so commands for 616new objects would always be allocated with a stride of 4. 617 618Each object would also have it's own fixed metadata shared by all request 619types (e.g. struct ifinfomsg for netdev requests, struct ifaddrmsg for address 620requests, struct tcmsg for qdisc requests). 621 622Even though other protocols and Generic Netlink commands often use 623the same verbs in their message names (``GET``, ``SET``) the concept 624of request types did not find wider adoption. 625 626Notification echo 627----------------- 628 629``NLM_F_ECHO`` requests for notifications resulting from the request 630to be queued onto the requesting socket. This is useful to discover 631the impact of the request. 632 633Note that this feature is not universally implemented. 634 635Other request-type-specific flags 636--------------------------------- 637 638Classic Netlink defined various flags for its ``GET``, ``NEW`` 639and ``DEL`` requests in the upper byte of nlmsg_flags in struct nlmsghdr. 640Since request types have not been generalized the request type specific 641flags are rarely used (and considered deprecated for new families). 642 643For ``GET`` - ``NLM_F_ROOT`` and ``NLM_F_MATCH`` are combined into 644``NLM_F_DUMP``, and not used separately. ``NLM_F_ATOMIC`` is never used. 645 646For ``DEL`` - ``NLM_F_NONREC`` is only used by nftables and ``NLM_F_BULK`` 647only by FDB some operations. 648 649The flags for ``NEW`` are used most commonly in classic Netlink. Unfortunately, 650the meaning is not crystal clear. The following description is based on the 651best guess of the intention of the authors, and in practice all families 652stray from it in one way or another. ``NLM_F_REPLACE`` asks to replace 653an existing object, if no matching object exists the operation should fail. 654``NLM_F_EXCL`` has the opposite semantics and only succeeds if object already 655existed. 656``NLM_F_CREATE`` asks for the object to be created if it does not 657exist, it can be combined with ``NLM_F_REPLACE`` and ``NLM_F_EXCL``. 658 659A comment in the main Netlink uAPI header states:: 660 661 4.4BSD ADD NLM_F_CREATE|NLM_F_EXCL 662 4.4BSD CHANGE NLM_F_REPLACE 663 664 True CHANGE NLM_F_CREATE|NLM_F_REPLACE 665 Append NLM_F_CREATE 666 Check NLM_F_EXCL 667 668which seems to indicate that those flags predate request types. 669``NLM_F_REPLACE`` without ``NLM_F_CREATE`` was initially used instead 670of ``SET`` commands. 671``NLM_F_EXCL`` without ``NLM_F_CREATE`` was used to check if object exists 672without creating it, presumably predating ``GET`` commands. 673 674``NLM_F_APPEND`` indicates that if one key can have multiple objects associated 675with it (e.g. multiple next-hop objects for a route) the new object should be 676added to the list rather than replacing the entire list. 677 678uAPI reference 679============== 680 681.. kernel-doc:: include/uapi/linux/netlink.h 682