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 237Note that some implementations may issue custom ``NLMSG_DONE`` messages 238in reply to ``do`` action requests. In that case the payload is 239implementation-specific and may also be absent. 240 241.. _res_fam: 242 243Resolving the Family ID 244----------------------- 245 246This section explains how to find the Family ID of a subsystem. 247It also serves as an example of Generic Netlink communication. 248 249Generic Netlink is itself a subsystem exposed via the Generic Netlink API. 250To avoid a circular dependency Generic Netlink has a statically allocated 251Family ID (``GENL_ID_CTRL`` which is equal to ``NLMSG_MIN_TYPE``). 252The Generic Netlink family implements a command used to find out information 253about other families (``CTRL_CMD_GETFAMILY``). 254 255To get information about the Generic Netlink family named for example 256``"test1"`` we need to send a message on the previously opened Generic Netlink 257socket. The message should target the Generic Netlink Family (1), be a 258``do`` (2) call to ``CTRL_CMD_GETFAMILY`` (3). A ``dump`` version of this 259call would make the kernel respond with information about *all* the families 260it knows about. Last but not least the name of the family in question has 261to be specified (4) as an attribute with the appropriate type:: 262 263 struct nlmsghdr: 264 __u32 nlmsg_len: 32 265 __u16 nlmsg_type: GENL_ID_CTRL // (1) 266 __u16 nlmsg_flags: NLM_F_REQUEST | NLM_F_ACK // (2) 267 __u32 nlmsg_seq: 1 268 __u32 nlmsg_pid: 0 269 270 struct genlmsghdr: 271 __u8 cmd: CTRL_CMD_GETFAMILY // (3) 272 __u8 version: 2 /* or 1, doesn't matter */ 273 __u16 reserved: 0 274 275 struct nlattr: // (4) 276 __u16 nla_len: 10 277 __u16 nla_type: CTRL_ATTR_FAMILY_NAME 278 char data: test1\0 279 280 (padding:) 281 char data: \0\0 282 283The length fields in Netlink (:c:member:`nlmsghdr.nlmsg_len` 284and :c:member:`nlattr.nla_len`) always *include* the header. 285Attribute headers in netlink must be aligned to 4 bytes from the start 286of the message, hence the extra ``\0\0`` after ``CTRL_ATTR_FAMILY_NAME``. 287The attribute lengths *exclude* the padding. 288 289If the family is found kernel will reply with two messages, the response 290with all the information about the family:: 291 292 /* Message #1 - reply */ 293 struct nlmsghdr: 294 __u32 nlmsg_len: 136 295 __u16 nlmsg_type: GENL_ID_CTRL 296 __u16 nlmsg_flags: 0 297 __u32 nlmsg_seq: 1 /* echoed from our request */ 298 __u32 nlmsg_pid: 5831 /* The PID of our user space process */ 299 300 struct genlmsghdr: 301 __u8 cmd: CTRL_CMD_GETFAMILY 302 __u8 version: 2 303 __u16 reserved: 0 304 305 struct nlattr: 306 __u16 nla_len: 10 307 __u16 nla_type: CTRL_ATTR_FAMILY_NAME 308 char data: test1\0 309 310 (padding:) 311 data: \0\0 312 313 struct nlattr: 314 __u16 nla_len: 6 315 __u16 nla_type: CTRL_ATTR_FAMILY_ID 316 __u16: 123 /* The Family ID we are after */ 317 318 (padding:) 319 char data: \0\0 320 321 struct nlattr: 322 __u16 nla_len: 9 323 __u16 nla_type: CTRL_ATTR_FAMILY_VERSION 324 __u16: 1 325 326 /* ... etc, more attributes will follow. */ 327 328And the error code (success) since ``NLM_F_ACK`` had been set on the request:: 329 330 /* Message #2 - the ACK */ 331 struct nlmsghdr: 332 __u32 nlmsg_len: 36 333 __u16 nlmsg_type: NLMSG_ERROR 334 __u16 nlmsg_flags: NLM_F_CAPPED /* There won't be a payload */ 335 __u32 nlmsg_seq: 1 /* echoed from our request */ 336 __u32 nlmsg_pid: 5831 /* The PID of our user space process */ 337 338 int error: 0 339 340 struct nlmsghdr: /* Copy of the request header as we sent it */ 341 __u32 nlmsg_len: 32 342 __u16 nlmsg_type: GENL_ID_CTRL 343 __u16 nlmsg_flags: NLM_F_REQUEST | NLM_F_ACK 344 __u32 nlmsg_seq: 1 345 __u32 nlmsg_pid: 0 346 347The order of attributes (struct nlattr) is not guaranteed so the user 348has to walk the attributes and parse them. 349 350Note that Generic Netlink sockets are not associated or bound to a single 351family. A socket can be used to exchange messages with many different 352families, selecting the recipient family on message-by-message basis using 353the :c:member:`nlmsghdr.nlmsg_type` field. 354 355.. _ext_ack: 356 357Extended ACK 358------------ 359 360Extended ACK controls reporting of additional error/warning TLVs 361in ``NLMSG_ERROR`` and ``NLMSG_DONE`` messages. To maintain backward 362compatibility this feature has to be explicitly enabled by setting 363the ``NETLINK_EXT_ACK`` setsockopt() to ``1``. 364 365Types of extended ack attributes are defined in enum nlmsgerr_attrs. 366The most commonly used attributes are ``NLMSGERR_ATTR_MSG``, 367``NLMSGERR_ATTR_OFFS`` and ``NLMSGERR_ATTR_MISS_*``. 368 369``NLMSGERR_ATTR_MSG`` carries a message in English describing 370the encountered problem. These messages are far more detailed 371than what can be expressed thru standard UNIX error codes. 372 373``NLMSGERR_ATTR_OFFS`` points to the attribute which caused the problem. 374 375``NLMSGERR_ATTR_MISS_TYPE`` and ``NLMSGERR_ATTR_MISS_NEST`` 376inform about a missing attribute. 377 378Extended ACKs can be reported on errors as well as in case of success. 379The latter should be treated as a warning. 380 381Extended ACKs greatly improve the usability of Netlink and should 382always be enabled, appropriately parsed and reported to the user. 383 384Advanced topics 385=============== 386 387Dump consistency 388---------------- 389 390Some of the data structures kernel uses for storing objects make 391it hard to provide an atomic snapshot of all the objects in a dump 392(without impacting the fast-paths updating them). 393 394Kernel may set the ``NLM_F_DUMP_INTR`` flag on any message in a dump 395(including the ``NLMSG_DONE`` message) if the dump was interrupted and 396may be inconsistent (e.g. missing objects). User space should retry 397the dump if it sees the flag set. 398 399Introspection 400------------- 401 402The basic introspection abilities are enabled by access to the Family 403object as reported in :ref:`res_fam`. User can query information about 404the Generic Netlink family, including which operations are supported 405by the kernel and what attributes the kernel understands. 406Family information includes the highest ID of an attribute kernel can parse, 407a separate command (``CTRL_CMD_GETPOLICY``) provides detailed information 408about supported attributes, including ranges of values the kernel accepts. 409 410Querying family information is useful in cases when user space needs 411to make sure that the kernel has support for a feature before issuing 412a request. 413 414.. _nlmsg_pid: 415 416nlmsg_pid 417--------- 418 419:c:member:`nlmsghdr.nlmsg_pid` is the Netlink equivalent of an address. 420It is referred to as Port ID, sometimes Process ID because for historical 421reasons if the application does not select (bind() to) an explicit Port ID 422kernel will automatically assign it the ID equal to its Process ID 423(as reported by the getpid() system call). 424 425Similarly to the bind() semantics of the TCP/IP network protocols the value 426of zero means "assign automatically", hence it is common for applications 427to leave the :c:member:`nlmsghdr.nlmsg_pid` field initialized to ``0``. 428 429The field is still used today in rare cases when kernel needs to send 430a unicast notification. User space application can use bind() to associate 431its socket with a specific PID, it then communicates its PID to the kernel. 432This way the kernel can reach the specific user space process. 433 434This sort of communication is utilized in UMH (User Mode Helper)-like 435scenarios when kernel needs to trigger user space processing or ask user 436space for a policy decision. 437 438Multicast notifications 439----------------------- 440 441One of the strengths of Netlink is the ability to send event notifications 442to user space. This is a unidirectional form of communication (kernel -> 443user) and does not involve any control messages like ``NLMSG_ERROR`` or 444``NLMSG_DONE``. 445 446For example the Generic Netlink family itself defines a set of multicast 447notifications about registered families. When a new family is added the 448sockets subscribed to the notifications will get the following message:: 449 450 struct nlmsghdr: 451 __u32 nlmsg_len: 136 452 __u16 nlmsg_type: GENL_ID_CTRL 453 __u16 nlmsg_flags: 0 454 __u32 nlmsg_seq: 0 455 __u32 nlmsg_pid: 0 456 457 struct genlmsghdr: 458 __u8 cmd: CTRL_CMD_NEWFAMILY 459 __u8 version: 2 460 __u16 reserved: 0 461 462 struct nlattr: 463 __u16 nla_len: 10 464 __u16 nla_type: CTRL_ATTR_FAMILY_NAME 465 char data: test1\0 466 467 (padding:) 468 data: \0\0 469 470 struct nlattr: 471 __u16 nla_len: 6 472 __u16 nla_type: CTRL_ATTR_FAMILY_ID 473 __u16: 123 /* The Family ID we are after */ 474 475 (padding:) 476 char data: \0\0 477 478 struct nlattr: 479 __u16 nla_len: 9 480 __u16 nla_type: CTRL_ATTR_FAMILY_VERSION 481 __u16: 1 482 483 /* ... etc, more attributes will follow. */ 484 485The notification contains the same information as the response 486to the ``CTRL_CMD_GETFAMILY`` request. 487 488The Netlink headers of the notification are mostly 0 and irrelevant. 489The :c:member:`nlmsghdr.nlmsg_seq` may be either zero or a monotonically 490increasing notification sequence number maintained by the family. 491 492To receive notifications the user socket must subscribe to the relevant 493notification group. Much like the Family ID, the Group ID for a given 494multicast group is dynamic and can be found inside the Family information. 495The ``CTRL_ATTR_MCAST_GROUPS`` attribute contains nests with names 496(``CTRL_ATTR_MCAST_GRP_NAME``) and IDs (``CTRL_ATTR_MCAST_GRP_ID``) of 497the groups family. 498 499Once the Group ID is known a setsockopt() call adds the socket to the group: 500 501.. code-block:: c 502 503 unsigned int group_id; 504 505 /* .. find the group ID... */ 506 507 setsockopt(fd, SOL_NETLINK, NETLINK_ADD_MEMBERSHIP, 508 &group_id, sizeof(group_id)); 509 510The socket will now receive notifications. 511 512It is recommended to use separate sockets for receiving notifications 513and sending requests to the kernel. The asynchronous nature of notifications 514means that they may get mixed in with the responses making the message 515handling much harder. 516 517Buffer sizing 518------------- 519 520Netlink sockets are datagram sockets rather than stream sockets, 521meaning that each message must be received in its entirety by a single 522recv()/recvmsg() system call. If the buffer provided by the user is too 523short, the message will be truncated and the ``MSG_TRUNC`` flag set 524in struct msghdr (struct msghdr is the second argument 525of the recvmsg() system call, *not* a Netlink header). 526 527Upon truncation the remaining part of the message is discarded. 528 529Netlink expects that the user buffer will be at least 8kB or a page 530size of the CPU architecture, whichever is bigger. Particular Netlink 531families may, however, require a larger buffer. 32kB buffer is recommended 532for most efficient handling of dumps (larger buffer fits more dumped 533objects and therefore fewer recvmsg() calls are needed). 534 535.. _classic_netlink: 536 537Classic Netlink 538=============== 539 540The main differences between Classic and Generic Netlink are the dynamic 541allocation of subsystem identifiers and availability of introspection. 542In theory the protocol does not differ significantly, however, in practice 543Classic Netlink experimented with concepts which were abandoned in Generic 544Netlink (really, they usually only found use in a small corner of a single 545subsystem). This section is meant as an explainer of a few of such concepts, 546with the explicit goal of giving the Generic Netlink 547users the confidence to ignore them when reading the uAPI headers. 548 549Most of the concepts and examples here refer to the ``NETLINK_ROUTE`` family, 550which covers much of the configuration of the Linux networking stack. 551Real documentation of that family, deserves a chapter (or a book) of its own. 552 553Families 554-------- 555 556Netlink refers to subsystems as families. This is a remnant of using 557sockets and the concept of protocol families, which are part of message 558demultiplexing in ``NETLINK_ROUTE``. 559 560Sadly every layer of encapsulation likes to refer to whatever it's carrying 561as "families" making the term very confusing: 562 563 1. AF_NETLINK is a bona fide socket protocol family 564 2. AF_NETLINK's documentation refers to what comes after its own 565 header (struct nlmsghdr) in a message as a "Family Header" 566 3. Generic Netlink is a family for AF_NETLINK (struct genlmsghdr follows 567 struct nlmsghdr), yet it also calls its users "Families". 568 569Note that the Generic Netlink Family IDs are in a different "ID space" 570and overlap with Classic Netlink protocol numbers (e.g. ``NETLINK_CRYPTO`` 571has the Classic Netlink protocol ID of 21 which Generic Netlink will 572happily allocate to one of its families as well). 573 574Strict checking 575--------------- 576 577The ``NETLINK_GET_STRICT_CHK`` socket option enables strict input checking 578in ``NETLINK_ROUTE``. It was needed because historically kernel did not 579validate the fields of structures it didn't process. This made it impossible 580to start using those fields later without risking regressions in applications 581which initialized them incorrectly or not at all. 582 583``NETLINK_GET_STRICT_CHK`` declares that the application is initializing 584all fields correctly. It also opts into validating that message does not 585contain trailing data and requests that kernel rejects attributes with 586type higher than largest attribute type known to the kernel. 587 588``NETLINK_GET_STRICT_CHK`` is not used outside of ``NETLINK_ROUTE``. 589 590Unknown attributes 591------------------ 592 593Historically Netlink ignored all unknown attributes. The thinking was that 594it would free the application from having to probe what kernel supports. 595The application could make a request to change the state and check which 596parts of the request "stuck". 597 598This is no longer the case for new Generic Netlink families and those opting 599in to strict checking. See enum netlink_validation for validation types 600performed. 601 602Fixed metadata and structures 603----------------------------- 604 605Classic Netlink made liberal use of fixed-format structures within 606the messages. Messages would commonly have a structure with 607a considerable number of fields after struct nlmsghdr. It was also 608common to put structures with multiple members inside attributes, 609without breaking each member into an attribute of its own. 610 611This has caused problems with validation and extensibility and 612therefore using binary structures is actively discouraged for new 613attributes. 614 615Request types 616------------- 617 618``NETLINK_ROUTE`` categorized requests into 4 types ``NEW``, ``DEL``, ``GET``, 619and ``SET``. Each object can handle all or some of those requests 620(objects being netdevs, routes, addresses, qdiscs etc.) Request type 621is defined by the 2 lowest bits of the message type, so commands for 622new objects would always be allocated with a stride of 4. 623 624Each object would also have its own fixed metadata shared by all request 625types (e.g. struct ifinfomsg for netdev requests, struct ifaddrmsg for address 626requests, struct tcmsg for qdisc requests). 627 628Even though other protocols and Generic Netlink commands often use 629the same verbs in their message names (``GET``, ``SET``) the concept 630of request types did not find wider adoption. 631 632Notification echo 633----------------- 634 635``NLM_F_ECHO`` requests for notifications resulting from the request 636to be queued onto the requesting socket. This is useful to discover 637the impact of the request. 638 639Note that this feature is not universally implemented. 640 641Other request-type-specific flags 642--------------------------------- 643 644Classic Netlink defined various flags for its ``GET``, ``NEW`` 645and ``DEL`` requests in the upper byte of nlmsg_flags in struct nlmsghdr. 646Since request types have not been generalized the request type specific 647flags are rarely used (and considered deprecated for new families). 648 649For ``GET`` - ``NLM_F_ROOT`` and ``NLM_F_MATCH`` are combined into 650``NLM_F_DUMP``, and not used separately. ``NLM_F_ATOMIC`` is never used. 651 652For ``DEL`` - ``NLM_F_NONREC`` is only used by nftables and ``NLM_F_BULK`` 653only by FDB some operations. 654 655The flags for ``NEW`` are used most commonly in classic Netlink. Unfortunately, 656the meaning is not crystal clear. The following description is based on the 657best guess of the intention of the authors, and in practice all families 658stray from it in one way or another. ``NLM_F_REPLACE`` asks to replace 659an existing object, if no matching object exists the operation should fail. 660``NLM_F_EXCL`` has the opposite semantics and only succeeds if object already 661existed. 662``NLM_F_CREATE`` asks for the object to be created if it does not 663exist, it can be combined with ``NLM_F_REPLACE`` and ``NLM_F_EXCL``. 664 665A comment in the main Netlink uAPI header states:: 666 667 4.4BSD ADD NLM_F_CREATE|NLM_F_EXCL 668 4.4BSD CHANGE NLM_F_REPLACE 669 670 True CHANGE NLM_F_CREATE|NLM_F_REPLACE 671 Append NLM_F_CREATE 672 Check NLM_F_EXCL 673 674which seems to indicate that those flags predate request types. 675``NLM_F_REPLACE`` without ``NLM_F_CREATE`` was initially used instead 676of ``SET`` commands. 677``NLM_F_EXCL`` without ``NLM_F_CREATE`` was used to check if object exists 678without creating it, presumably predating ``GET`` commands. 679 680``NLM_F_APPEND`` indicates that if one key can have multiple objects associated 681with it (e.g. multiple next-hop objects for a route) the new object should be 682added to the list rather than replacing the entire list. 683 684uAPI reference 685============== 686 687.. kernel-doc:: include/uapi/linux/netlink.h 688