19d6a6507SJakub Kicinski.. SPDX-License-Identifier: BSD-3-Clause 29d6a6507SJakub Kicinski 39d6a6507SJakub Kicinski.. _kernel_netlink: 49d6a6507SJakub Kicinski 59d6a6507SJakub Kicinski=================================== 69d6a6507SJakub KicinskiNetlink notes for kernel developers 79d6a6507SJakub Kicinski=================================== 89d6a6507SJakub Kicinski 99d6a6507SJakub KicinskiGeneral guidance 109d6a6507SJakub Kicinski================ 119d6a6507SJakub Kicinski 129d6a6507SJakub KicinskiAttribute enums 139d6a6507SJakub Kicinski--------------- 149d6a6507SJakub Kicinski 159d6a6507SJakub KicinskiOlder families often define "null" attributes and commands with value 169d6a6507SJakub Kicinskiof ``0`` and named ``unspec``. This is supported (``type: unused``) 179d6a6507SJakub Kicinskibut should be avoided in new families. The ``unspec`` enum values are 189d6a6507SJakub Kicinskinot used in practice, so just set the value of the first attribute to ``1``. 199d6a6507SJakub Kicinski 209d6a6507SJakub KicinskiMessage enums 219d6a6507SJakub Kicinski------------- 229d6a6507SJakub Kicinski 239d6a6507SJakub KicinskiUse the same command IDs for requests and replies. This makes it easier 249d6a6507SJakub Kicinskito match them up, and we have plenty of ID space. 259d6a6507SJakub Kicinski 269d6a6507SJakub KicinskiUse separate command IDs for notifications. This makes it easier to 279d6a6507SJakub Kicinskisort the notifications from replies (and present them to the user 289d6a6507SJakub Kicinskiapplication via a different API than replies). 299d6a6507SJakub Kicinski 309d6a6507SJakub KicinskiAnswer requests 319d6a6507SJakub Kicinski--------------- 329d6a6507SJakub Kicinski 339d6a6507SJakub KicinskiOlder families do not reply to all of the commands, especially NEW / ADD 349d6a6507SJakub Kicinskicommands. User only gets information whether the operation succeeded or 359d6a6507SJakub Kicinskinot via the ACK. Try to find useful data to return. Once the command is 369d6a6507SJakub Kicinskiadded whether it replies with a full message or only an ACK is uAPI and 379d6a6507SJakub Kicinskicannot be changed. It's better to err on the side of replying. 389d6a6507SJakub Kicinski 399d6a6507SJakub KicinskiSpecifically NEW and ADD commands should reply with information identifying 409d6a6507SJakub Kicinskithe created object such as the allocated object's ID (without having to 419d6a6507SJakub Kicinskiresort to using ``NLM_F_ECHO``). 429d6a6507SJakub Kicinski 439d6a6507SJakub KicinskiNLM_F_ECHO 449d6a6507SJakub Kicinski---------- 459d6a6507SJakub Kicinski 469d6a6507SJakub KicinskiMake sure to pass the request info to genl_notify() to allow ``NLM_F_ECHO`` 479d6a6507SJakub Kicinskito take effect. This is useful for programs that need precise feedback 489d6a6507SJakub Kicinskifrom the kernel (for example for logging purposes). 499d6a6507SJakub Kicinski 509d6a6507SJakub KicinskiSupport dump consistency 519d6a6507SJakub Kicinski------------------------ 529d6a6507SJakub Kicinski 539d6a6507SJakub KicinskiIf iterating over objects during dump may skip over objects or repeat 549d6a6507SJakub Kicinskithem - make sure to report dump inconsistency with ``NLM_F_DUMP_INTR``. 559d6a6507SJakub KicinskiThis is usually implemented by maintaining a generation id for the 569d6a6507SJakub Kicinskistructure and recording it in the ``seq`` member of struct netlink_callback. 579d6a6507SJakub Kicinski 589d6a6507SJakub KicinskiNetlink specification 599d6a6507SJakub Kicinski===================== 609d6a6507SJakub Kicinski 619d6a6507SJakub KicinskiDocumentation of the Netlink specification parts which are only relevant 629d6a6507SJakub Kicinskito the kernel space. 639d6a6507SJakub Kicinski 649d6a6507SJakub KicinskiGlobals 659d6a6507SJakub Kicinski------- 669d6a6507SJakub Kicinski 679d6a6507SJakub Kicinskikernel-policy 689d6a6507SJakub Kicinski~~~~~~~~~~~~~ 699d6a6507SJakub Kicinski 70*294f37fcSDonald HunterDefines whether the kernel validation policy is ``global`` i.e. the same for all 71*294f37fcSDonald Hunteroperations of the family, defined for each operation individually - ``per-op``, 72*294f37fcSDonald Hunteror separately for each operation and operation type (do vs dump) - ``split``. 73*294f37fcSDonald HunterNew families should use ``per-op`` (default) to be able to narrow down the 74*294f37fcSDonald Hunterattributes accepted by a specific command. 759d6a6507SJakub Kicinski 769d6a6507SJakub Kicinskichecks 779d6a6507SJakub Kicinski------ 789d6a6507SJakub Kicinski 799d6a6507SJakub KicinskiDocumentation for the ``checks`` sub-sections of attribute specs. 809d6a6507SJakub Kicinski 819d6a6507SJakub Kicinskiunterminated-ok 829d6a6507SJakub Kicinski~~~~~~~~~~~~~~~ 839d6a6507SJakub Kicinski 849d6a6507SJakub KicinskiAccept strings without the null-termination (for legacy families only). 859d6a6507SJakub KicinskiSwitches from the ``NLA_NUL_STRING`` to ``NLA_STRING`` policy type. 869d6a6507SJakub Kicinski 879d6a6507SJakub Kicinskimax-len 889d6a6507SJakub Kicinski~~~~~~~ 899d6a6507SJakub Kicinski 909d6a6507SJakub KicinskiDefines max length for a binary or string attribute (corresponding 919d6a6507SJakub Kicinskito the ``len`` member of struct nla_policy). For string attributes terminating 929d6a6507SJakub Kicinskinull character is not counted towards ``max-len``. 939d6a6507SJakub Kicinski 949d6a6507SJakub KicinskiThe field may either be a literal integer value or a name of a defined 959d6a6507SJakub Kicinskiconstant. String types may reduce the constant by one 969d6a6507SJakub Kicinski(i.e. specify ``max-len: CONST - 1``) to reserve space for the terminating 979d6a6507SJakub Kicinskicharacter so implementations should recognize such pattern. 989d6a6507SJakub Kicinski 999d6a6507SJakub Kicinskimin-len 1009d6a6507SJakub Kicinski~~~~~~~ 1019d6a6507SJakub Kicinski 1029d6a6507SJakub KicinskiSimilar to ``max-len`` but defines minimum length. 103