Netlink notes for kernel developers

General guidance

Attribute enums

Older families often define “null” attributes and commands with valueof0 and namedunspec. This is supported (type:unused)but should be avoided in new families. Theunspecenumvalues arenot used in practice, so just set the value of the first attribute to1.

Message enums

Use the same command IDs for requests and replies. This makes it easierto match them up, and we have plenty of ID space.

Use separate command IDs for notifications. This makes it easier tosort the notifications from replies (and present them to the userapplication via a different API than replies).

Answer requests

Older families do not reply to all of the commands, especially NEW / ADDcommands. User only gets information whether the operation succeeded ornot via the ACK. Try to find useful data to return. Once the command isadded whether it replies with a full message or only an ACK is uAPI andcannot be changed. It’s better to err on the side of replying.

Specifically NEW and ADD commands should reply with information identifyingthe created object such as the allocated object’s ID (without having toresort to usingNLM_F_ECHO).

NLM_F_ECHO

Make sure to pass the request info togenl_notify() to allowNLM_F_ECHOto take effect. This is useful for programs that need precise feedbackfrom the kernel (for example for logging purposes).

Support dump consistency

If iterating over objects during dump may skip over objects or repeatthem - make sure to report dump inconsistency withNLM_F_DUMP_INTR.This is usually implemented by maintaining a generation id for thestructure and recording it in theseq member ofstructnetlink_callback.

Netlink specification

Documentation of the Netlink specification parts which are only relevantto the kernel space.

Globals

kernel-policy

Defines whether the kernel validation policy isglobal i.e. the same for alloperations of the family, defined for each operation individually -per-op,or separately for each operation and operation type (do vs dump) -split.New families should useper-op (default) to be able to narrow down theattributes accepted by a specific command.

checks

Documentation for thechecks sub-sections of attribute specs.

unterminated-ok

Accept strings without the null-termination (for legacy families only).Switches from theNLA_NUL_STRING toNLA_STRING policy type.

max-len

Defines max length for a binary or string attribute (correspondingto thelen member ofstructnla_policy). For string attributes terminatingnull character is not counted towardsmax-len.

The field may either be a literal integer value or a name of a definedconstant. String types may reduce the constant by one(i.e. specifymax-len:CONST-1) to reserve space for the terminatingcharacter so implementations should recognize such pattern.

min-len

Similar tomax-len but defines minimum length.