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:

• the C uAPI header

• documentation of the protocol as a ReST file - see Documentation/networking/netlink_spec/index.rst

• policy tables for input attribute validation

• operation tables

YAML specifications can be found under Documentation/netlink/specs/

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.

Compatibility levels

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 such as NETLINK_ROUTE

The definition of the schemas (in jsonschema) can be found under Documentation/netlink/.

Schema structure

YAML schema has the following conceptual sections:

• globals

• definitions

• attributes

• operations

• multicast groups

Most properties in the schema accept (or in fact require) a doc sub-property documenting the defined object.

The following sections describe the properties of the most modern genetlink 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.

genetlink

Globals

Attributes listed directly at the root level of the spec file.

name

Name of the family. Name identifies the family in a unique way, since the Family IDs are allocated dynamically.

protocol

The schema level, default is genetlink, which is the only value allowed for new genetlink families.

definitions

Array of type and constant definitions.

name

Name of the type / constant.

type

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)

value

The value for the const.

value-start

The first value for enum and flags, allows overriding the default start value of 0 (for enum) and starting bit (for flags). For flags value-start selects the starting bit, not the shifted value.

Sparse enumerations are not supported.

entries

Array of names of the entries for enum and flags.

header

For C-compatible languages, header which already defines this value. In case the definition is shared by multiple families (e.g. IFNAMSIZ) code generators for C-compatible languages may prefer to add an appropriate include instead of rendering a new definition.

attribute-sets

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 subset-of 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.

name

Uniquely identifies the attribute set, operations and nested attributes refer to the sets by the name.

subset-of

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.

attributes

List of attributes in the set.

Attribute properties

name

Identifies the attribute, unique within the set.

type

Netlink attribute type, see Attribute types.

value

Numerical attribute ID, used in serialized Netlink messages. The value property can be skipped, in which case the attribute ID will be the value of the previous attribute plus one (recursively) and 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) because entry 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).

enum

For integer types specifies that values in the attribute belong to an enum or flags from the definitions section.

enum-as-flags

Treat enum as flags regardless of its type in definitions. When both enum and flags forms are needed definitions should contain an enum and attributes which need the flags form should use this attribute.

nested-attributes

Identifies the attribute space for attributes nested within given attribute. Only valid for complex attributes which may have sub-attributes.

multi-attr (arrays)

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

byte-order

For integer types specifies attribute byte order - little-endian or big-endian.

checks

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 definition (type and nested-attributes) and the checks.

sub-type

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.

display-hint

Optional format indicator that is intended only for choosing the right formatting mechanism when displaying values of this type. Currently supported hints are hex, mac, fddi, ipv4, ipv6 and uuid.

operations

This section describes messages passed between the kernel and the user space. There are three types of entries in this section - operations, notifications and events.

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 - do and dump. do and dump in turn contain a combination of request and 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 do of a SET operation to which the kernel responds with just the netlink error code) request or response section can be skipped. request and response sections list the attributes allowed in a message. The list contains only the names of attributes from a set referred to by the attribute-set property.

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 notify property). 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 event property. Events are considered less idiomatic for netlink and notifications should be preferred.

list

The only property of operations for genetlink, holds the list of operations, notifications etc.

Operation properties

name

Identifies the operation.

value

Numerical message ID, used in serialized Netlink messages. The same enumeration rules are applied as to attribute values.

attribute-set

Specifies the attribute set contained within the message.

do

Specification for the doit request. Should contain request, reply or both of these properties, each holding a Message attribute list.

dump

Specification for the dumpit request. Should contain request, reply or both of these properties, each holding a Message attribute list.

notify

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 (do).

event

Specification of attributes in the event, holds a Message attribute list. event property is mutually exclusive with notify.

mcgrp

Used with event and notify, specifies which multicast group message belongs to.

Message attribute list

request, reply and event properties have a single attributes property which holds the list of attribute names.

Messages can also define pre and post properties which will be rendered as pre_doit and post_doit calls in the kernel (these properties should be ignored by user space).

mcast-groups

This section lists the multicast groups of the family.

list

The only property of mcast-groups for genetlink, holds the list of groups.

Multicast group properties

name

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.

Attribute types

This section describes the attribute types supported by the genetlink compatibility level. Refer to documentation of different levels for additional attribute types.

Common integer types

sint and 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 of cases.

Fix-width integer types

Fixed-width integer types include: u8, u16, u32, u64, s8, s16, s32, s64.

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 byte-order specifies otherwise.

64 bit values are usually aligned by the kernel but it is recommended that the user space is able to deal with unaligned values.

pad

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.

flag

Attribute with no payload, its presence is the entire information.

binary

Raw binary data attribute, the contents are opaque to generic code.

string

Character string. Unless checks has unterminated-ok set to true the string is required to be null terminated. max-len in checks indicates the longest possible string, if not present the length of the string is unbounded.

Note that max-len does not count the terminating character.

nest

Attribute containing other (nested) attributes. nested-attributes specifies which attribute set is used inside.