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.
103