1.. SPDX-License-Identifier: BSD-3-Clause
  2
  3.. _kernel_netlink:
  4
  5===================================
  6Netlink notes for kernel developers
  7===================================
  8
  9General guidance
 10================
 11
 12Attribute enums
 13---------------
 14
 15Older families often define "null" attributes and commands with value
 16of ``0`` and named ``unspec``. This is supported (``type: unused``)
 17but should be avoided in new families. The ``unspec`` enum values are
 18not used in practice, so just set the value of the first attribute to ``1``.
 19
 20Message enums
 21-------------
 22
 23Use the same command IDs for requests and replies. This makes it easier
 24to match them up, and we have plenty of ID space.
 25
 26Use separate command IDs for notifications. This makes it easier to
 27sort the notifications from replies (and present them to the user
 28application via a different API than replies).
 29
 30Answer requests
 31---------------
 32
 33Older families do not reply to all of the commands, especially NEW / ADD
 34commands. User only gets information whether the operation succeeded or
 35not via the ACK. Try to find useful data to return. Once the command is
 36added whether it replies with a full message or only an ACK is uAPI and
 37cannot be changed. It's better to err on the side of replying.
 38
 39Specifically NEW and ADD commands should reply with information identifying
 40the created object such as the allocated object's ID (without having to
 41resort to using ``NLM_F_ECHO``).
 42
 43NLM_F_ECHO
 44----------
 45
 46Make sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO``
 47to take effect.  This is useful for programs that need precise feedback
 48from the kernel (for example for logging purposes).
 49
 50Support dump consistency
 51------------------------
 52
 53If iterating over objects during dump may skip over objects or repeat
 54them - make sure to report dump inconsistency with ``NLM_F_DUMP_INTR``.
 55This is usually implemented by maintaining a generation id for the
 56structure and recording it in the ``seq`` member of struct netlink_callback.
 57
 58Netlink specification
 59=====================
 60
 61Documentation of the Netlink specification parts which are only relevant
 62to the kernel space.
 63
 64Globals
 65-------
 66
 67kernel-policy
 68~~~~~~~~~~~~~
 69
 70Defines whether the kernel validation policy is ``global`` i.e. the same for all
 71operations of the family, defined for each operation individually - ``per-op``,
 72or separately for each operation and operation type (do vs dump) - ``split``.
 73New families should use ``per-op`` (default) to be able to narrow down the
 74attributes accepted by a specific command.
 75
 76checks
 77------
 78
 79Documentation for the ``checks`` sub-sections of attribute specs.
 80
 81unterminated-ok
 82~~~~~~~~~~~~~~~
 83
 84Accept strings without the null-termination (for legacy families only).
 85Switches from the ``NLA_NUL_STRING`` to ``NLA_STRING`` policy type.
 86
 87max-len
 88~~~~~~~
 89
 90Defines max length for a binary or string attribute (corresponding
 91to the ``len`` member of struct nla_policy). For string attributes terminating
 92null character is not counted towards ``max-len``.
 93
 94The field may either be a literal integer value or a name of a defined
 95constant. String types may reduce the constant by one
 96(i.e. specify ``max-len: CONST - 1``) to reserve space for the terminating
 97character so implementations should recognize such pattern.
 98
 99min-len
100~~~~~~~
101
102Similar to ``max-len`` but defines minimum length.