Netlink protocol specifications (in YAML)

Netlink protocol specifications are complete, machine readable descriptions ofNetlink protocols written in YAML. The goal of the specifications is to allowseparating Netlink parsing from user space logic and minimize the amount ofhand written Netlink code for each new family, command, attribute.Netlink specs should be complete and not depend on any other specor C header file, making it easy to use in languages which can’t includekernel headers directly.

Internally kernel uses the YAML specs to generate:

YAML specifications can be found underDocumentation/netlink/specs/

This document describes details of the schema.SeeUsing Netlink protocol specifications for a practical starting guide.

All specs must be licensed under((GPL-2.0WITHLinux-syscall-note)ORBSD-3-Clause)to allow for easy adoption in user space code.

Compatibility levels

There are four schema levels for Netlink specs, from the simplest usedby 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 thatuser capable of parsing more complexgenetlink schemas is also compatiblewith simpler ones. The levels are:

  • genetlink - most streamlined, should be used by all new families

  • genetlink-c - superset ofgenetlink with extra attributes allowingcustomization of define andenumtype and value names; this schema shouldbe equivalent togenetlink for all implementations which don’t interactdirectly with C uAPI headers

  • genetlink-legacy - Generic Netlink catch all schema supporting quirks ofall old genetlink families, strange attribute formats, binary structures etc.

  • netlink-raw - catch all schema supporting pre-Generic Netlink protocolssuch asNETLINK_ROUTE

The definition of the schemas (injsonschema) can be foundunderDocumentation/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) adocsub-property documenting the defined object.

The following sections describe the properties of the most moderngenetlinkschema. See the documentation ofgenetlink-cfor information on how C names are derived from name properties.

See alsoDocumentation/core-api/netlink.rst forinformation on the Netlink specification properties that are only relevant tothe 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, sincethe Family IDs are allocated dynamically.

protocol

The schema level, default isgenetlink, which is the only valueallowed for newgenetlink 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 entryincrementing by 1, (e.g. 0, 1, 2, 3)

  • flags - defines an integer enumeration, with values for each entryoccupying a bit, starting from bit 0, (e.g. 1, 2, 4, 8)

value

The value for theconst.

value-start

The first value forenum andflags, allows overriding the defaultstart value of0 (forenum) and starting bit (forflags).Forflagsvalue-start selects the starting bit, not the shifted value.

Sparse enumerations are not supported.

entries

Array of names of the entries forenum andflags.

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 appropriateinclude 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 resemblethe format of the netlink messages (unlike certain ad-hoc documentationformats seen in kernel comments). In the spec subordinate attribute setsare not defined inline as a nest, but defined in a separate attribute setreferred to with anested-attributes property of the container.

Spec may also contain fractional sets - sets which contain asubset-ofproperty. Such sets describe a section of a full set, allowing narrowing downwhich 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 uAPIin any fashion.

name

Uniquely identifies the attribute set, operations and nested attributesrefer to the sets by thename.

subset-of

Re-defines a portion of another set (a fractional set).Allows narrowing down fields and changing validation criteriaor even types of attributes depending on the nest in which theyare contained. Thevalue of each attribute in the fractionalset 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, seeAttribute types.

value

Numerical attribute ID, used in serialized Netlink messages.Thevalue property can be skipped, in which case the attribute IDwill be the value of the previous attribute plus one (recursively)and1 for the first attribute in the attribute set.

Attributes (and operations) use1 as the default value for the firstentry (unlike enums in definitions which start from0) becauseentry0 is almost always reserved as undefined. Spec can explicitlyset value to0 if needed.

Note that thevalue of an attribute is defined only in its main set(not in subsets).

enum

For integer types specifies that values in the attribute belongto anenum orflags from thedefinitions section.

enum-as-flags

Treatenum asflags regardless of its type indefinitions.When bothenum andflags forms are neededdefinitions shouldcontain anenum and attributes which need theflags form shoulduse 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-endianorbig-endian.

checks

Input validation constraints used by the kernel. User space should querythe 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 typedefinition (type andnested-attributes) and thechecks.

sub-type

Legacy families have special ways of expressing arrays.sub-type can beused to define the type of array members in case array members are notfully defined as attributes (in a bona fide attribute space). For instancea C array of u32 values can be specified withtype:binary andsub-type:u32. Binary types and legacy array formats are described inmore detail inNetlink specification support for legacy Generic Netlink families.

display-hint

Optional format indicator that is intended only for choosing the rightformatting mechanism when displaying values of this type. Currently supportedhints arehex,mac,fddi,ipv4,ipv6 anduuid.

operations

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

Operations describe the most common request - response communication. Usersends a request and kernel replies. Each operation may contain any combinationof the two modes familiar to netlink users -do anddump.do anddump in turn contain a combination ofrequest andresponse properties. If no explicit message with attributes is passedin a given direction (e.g. adump which does not accept filter, or adoof a SET operation to which the kernel responds with just the netlink errorcode)request orresponse section can be skipped.request andresponse sections list the attributes allowed in a message.The list contains only the names of attributes from a set referredto by theattribute-set property.

Notifications and events both refer to the asynchronous messages sent bythe kernel to members of a multicast group. The difference between thetwo is that a notification shares its contents with a GET operation(the name of the GET operation is specified in thenotify property).This arrangement is commonly used for notifications aboutobjects where the notification carries the full object definition.

Events are more focused and carry only a subset of information rather than fullobject state (a made up example would be a link state change event with justthe interface name and the new link state). Events contain theeventproperty. Events are considered less idiomatic for netlink and notificationsshould be preferred.

list

The only property ofoperations forgenetlink, holds the list ofoperations, notifications etc.

Operation properties

name

Identifies the operation.

value

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

attribute-set

Specifies the attribute set contained within the message.

do

Specification for thedoit request. Should containrequest,replyor both of these properties, each holding aMessage attribute list.

dump

Specification for thedumpit request. Should containrequest,replyor both of these properties, each holding aMessage 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 sharesthe contents with the notification (do).

event

Specification of attributes in the event, holds aMessage attribute list.event property is mutually exclusive withnotify.

mcgrp

Used withevent andnotify, specifies which multicast groupmessage belongs to.

Message attribute list

request,reply andevent properties have a singleattributesproperty which holds the list of attribute names.

Messages can also definepre andpost properties which will be renderedaspre_doit andpost_doit calls in the kernel (these properties shouldbe ignored by user space).

mcast-groups

This section lists the multicast groups of the family.

list

The only property ofmcast-groups forgenetlink, holds the listof groups.

Multicast group properties

name

Uniquely identifies the multicast group in the family. Similarly toFamily ID, Multicast Group ID needs to be resolved at runtime, basedon the name.

Attribute types

This section describes the attribute types supported by thegenetlinkcompatibility level. Refer to documentation of different levels for additionalattribute types.

Common integer types

sint anduint represent signed and unsigned 64 bit integers.If the value can fit on 32 bits only 32 bits are carried in netlinkmessages, otherwise full 64 bits are carried. Note that the payloadis only aligned to 4B, so the full 64 bit value may be unaligned!

Common integer types should be preferred over fix-width types in majorityof 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 themdoes not save any memory in Netlink messages (due to alignment).Seepad for padding of 64 bit attributes.

The payload of the attribute is the integer in host order unlessbyte-orderspecifies otherwise.

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

pad

Special attribute type used for padding attributes which require alignmentbigger than standard 4B alignment required by netlink (e.g. 64 bit integers).There can only be a single attribute of thepad type in any attribute setand 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. Unlesschecks hasunterminated-ok set totruethe string is required to be null terminated.max-len inchecks indicates the longest possible string,if not present the length of the string is unbounded.

Note thatmax-len does not count the terminating character.

nest

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