Netlink protocol specifications (in YAML)
Netlink protocol specifications are complete, machine readable descriptions of
Netlink protocols written in YAML. The goal of the specifications is to allow
separating Netlink parsing from user space logic and minimize the amount of
hand written Netlink code for each new family, command, attribute.
Netlink specs should be complete and not depend on any other spec
or C header file, making it easy to use in languages which can't include
kernel headers directly.
Internally kernel uses the YAML specs to generate:
YAML specifications can be found under
This document describes details of the schema.
See Using Netlink protocol specifications for a practical starting guide.
All specs must be licensed under
((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
to allow for easy adoption in user space code.
There are four schema levels for Netlink specs, from the simplest used
by new families to the most complex covering all the quirks of the old ones.
Each next level inherits the attributes of the previous level, meaning that
user capable of parsing more complex
genetlink schemas is also compatible
with simpler ones. The levels are:
genetlink - most streamlined, should be used by all new families
genetlink-c - superset of
genetlink with extra attributes allowing
customization of define and enum type and value names; this schema should
be equivalent to
genetlink for all implementations which don't interact
directly with C uAPI headers
genetlink-legacy - Generic Netlink catch all schema supporting quirks of
all old genetlink families, strange attribute formats, binary structures etc.
netlink-raw - catch all schema supporting pre-Generic Netlink protocols
The definition of the schemas (in
jsonschema) can be found
YAML schema has the following conceptual sections:
Most properties in the schema accept (or in fact require) a
sub-property documenting the defined object.
The following sections describe the properties of the most modern
schema. See the documentation of genetlink-c
for information on how C names are derived from name properties.
See also Documentation/core-api/netlink.rst for
information on the Netlink specification properties that are only relevant to
the kernel space and not part of the user space API.
Attributes listed directly at the root level of the spec file.
Name of the family. Name identifies the family in a unique way, since
the Family IDs are allocated dynamically.
The schema level, default is
genetlink, which is the only value
allowed for new
Array of type and constant definitions.
Name of the type / constant.
One of the following types:
const - a single, standalone constant
enum - defines an integer enumeration, with values for each entry
incrementing by 1, (e.g. 0, 1, 2, 3)
flags - defines an integer enumeration, with values for each entry
occupying a bit, starting from bit 0, (e.g. 1, 2, 4, 8)
The value for the
The first value for
flags, allows overriding the default
start value of
enum) and starting bit (for
value-start selects the starting bit, not the shifted value.
Sparse enumerations are not supported.
Array of names of the entries for
This property contains information about netlink attributes of the family.
All families have at least one attribute set, most have multiple.
attribute-sets is an array, with each entry describing a single set.
Note that the spec is "flattened" and is not meant to visually resemble
the format of the netlink messages (unlike certain ad-hoc documentation
formats seen in kernel comments). In the spec subordinate attribute sets
are not defined inline as a nest, but defined in a separate attribute set
referred to with a
nested-attributes property of the container.
Spec may also contain fractional sets - sets which contain a
property. Such sets describe a section of a full set, allowing narrowing down
which attributes are allowed in a nest or refining the validation criteria.
Fractional sets can only be used in nests. They are not rendered to the uAPI
in any fashion.
Uniquely identifies the attribute set, operations and nested attributes
refer to the sets by the
Re-defines a portion of another set (a fractional set).
Allows narrowing down fields and changing validation criteria
or even types of attributes depending on the nest in which they
are contained. The
value of each attribute in the fractional
set is implicitly the same as in the main set.
List of attributes in the set.
Identifies the attribute, unique within the set.
Numerical attribute ID, used in serialized Netlink messages.
value property can be skipped, in which case the attribute ID
will be the value of the previous attribute plus one (recursively)
1 for the first attribute in the attribute set.
Attributes (and operations) use
1 as the default value for the first
entry (unlike enums in definitions which start from
0 is almost always reserved as undefined. Spec can explicitly
set value to
0 if needed.
Note that the
value of an attribute is defined only in its main set
(not in subsets).
For integer types specifies that values in the attribute belong
flags from the
flags regardless of its type in
flags forms are needed
enum and attributes which need the
flags form should
use this attribute.
Identifies the attribute space for attributes nested within given attribute.
Only valid for complex attributes which may have sub-attributes.
Boolean property signifying that the attribute may be present multiple times.
Allowing an attribute to repeat is the recommended way of implementing arrays
(no extra nesting).
For integer types specifies attribute byte order -
Input validation constraints used by the kernel. User space should query
the policy of the running kernel using Generic Netlink introspection,
rather than depend on what is specified in the spec file.
The validation policy in the kernel is formed by combining the type
nested-attributes) and the
Legacy families have special ways of expressing arrays.
sub-type can be
used to define the type of array members in case array members are not
fully defined as attributes (in a bona fide attribute space). For instance
a C array of u32 values can be specified with
type: binary and
sub-type: u32. Binary types and legacy array formats are described in
more detail in Netlink specification support for legacy Generic Netlink families.
Optional format indicator that is intended only for choosing the right
formatting mechanism when displaying values of this type. Currently supported
This section describes messages passed between the kernel and the user space.
There are three types of entries in this section - operations, notifications
Operations describe the most common request - response communication. User
sends a request and kernel replies. Each operation may contain any combination
of the two modes familiar to netlink users -
dump in turn contain a combination of
response properties. If no explicit message with attributes is passed
in a given direction (e.g. a
dump which does not accept filter, or a
of a SET operation to which the kernel responds with just the netlink error
response section can be skipped.
response sections list the attributes allowed in a message.
The list contains only the names of attributes from a set referred
to by the
Notifications and events both refer to the asynchronous messages sent by
the kernel to members of a multicast group. The difference between the
two is that a notification shares its contents with a GET operation
(the name of the GET operation is specified in the
This arrangement is commonly used for notifications about
objects where the notification carries the full object definition.
Events are more focused and carry only a subset of information rather than full
object state (a made up example would be a link state change event with just
the interface name and the new link state). Events contain the
property. Events are considered less idiomatic for netlink and notifications
should be preferred.
The only property of
genetlink, holds the list of
operations, notifications etc.
Identifies the operation.
Numerical message ID, used in serialized Netlink messages.
The same enumeration rules are applied as to
Specifies the attribute set contained within the message.
Specification for the
doit request. Should contain
or both of these properties, each holding a Message attribute list.
Specification for the
dumpit request. Should contain
or both of these properties, each holding a Message attribute list.
Designates the message as a notification. Contains the name of the operation
(possibly the same as the operation holding this property) which shares
the contents with the notification (
Specification of attributes in the event, holds a Message attribute list.
event property is mutually exclusive with
notify, specifies which multicast group
message belongs to.
Message attribute list
event properties have a single
property which holds the list of attribute names.
Messages can also define
post properties which will be rendered
post_doit calls in the kernel (these properties should
be ignored by user space).
This section lists the multicast groups of the family.
The only property of
genetlink, holds the list
Multicast group properties
Uniquely identifies the multicast group in the family. Similarly to
Family ID, Multicast Group ID needs to be resolved at runtime, based
on the name.
This section describes the attribute types supported by the
compatibility level. Refer to documentation of different levels for additional
Common integer types
uint represent signed and unsigned 64 bit integers.
If the value can fit on 32 bits only 32 bits are carried in netlink
messages, otherwise full 64 bits are carried. Note that the payload
is only aligned to 4B, so the full 64 bit value may be unaligned!
Common integer types should be preferred over fix-width types in majority
Fix-width integer types
Fixed-width integer types include:
Note that types smaller than 32 bit should be avoided as using them
does not save any memory in Netlink messages (due to alignment).
See pad for padding of 64 bit attributes.
The payload of the attribute is the integer in host order unless
64 bit values are usually aligned by the kernel but it is recommended
that the user space is able to deal with unaligned values.
Special attribute type used for padding attributes which require alignment
bigger than standard 4B alignment required by netlink (e.g. 64 bit integers).
There can only be a single attribute of the
pad type in any attribute set
and it should be automatically used for padding when needed.
Attribute with no payload, its presence is the entire information.
Raw binary data attribute, the contents are opaque to generic code.
Character string. Unless
unterminated-ok set to
the string is required to be null terminated.
checks indicates the longest possible string,
if not present the length of the string is unbounded.
max-len does not count the terminating character.
Attribute containing other (nested) attributes.
nested-attributes specifies which attribute set is used inside.