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 if the kernel validation policy is per operation (``per-op``)
71or for the entire family (``global``). New families should use ``per-op``
72(default) to be able to narrow down the attributes accepted by a specific
73command.
74
75checks
76------
77
78Documentation for the ``checks`` sub-sections of attribute specs.
79
80unterminated-ok
81~~~~~~~~~~~~~~~
82
83Accept strings without the null-termination (for legacy families only).
84Switches from the ``NLA_NUL_STRING`` to ``NLA_STRING`` policy type.
85
86max-len
87~~~~~~~
88
89Defines max length for a binary or string attribute (corresponding
90to the ``len`` member of struct nla_policy). For string attributes terminating
91null character is not counted towards ``max-len``.
92
93The field may either be a literal integer value or a name of a defined
94constant. String types may reduce the constant by one
95(i.e. specify ``max-len: CONST - 1``) to reserve space for the terminating
96character so implementations should recognize such pattern.
97
98min-len
99~~~~~~~
100
101Similar to ``max-len`` but defines minimum length.
102