Netlink specification support for raw Netlink families¶
This document describes the additional properties required by raw Netlink
families such as NETLINK_ROUTE
which use the netlink-raw
protocol
specification.
Specification¶
The netlink-raw schema extends the genetlink-legacy schema with properties that are needed to specify the protocol numbers and multicast IDs used by raw netlink families. See Classic Netlink for more information. The raw netlink families also make use of type-specific sub-messages.
Globals¶
protonum¶
The protonum
property is used to specify the protocol number to use when
opening a netlink socket.
# SPDX-License-Identifier: ((GPL-2.0 WITH Linux-syscall-note) OR BSD-3-Clause)
name: rt-addr
protocol: netlink-raw
protonum: 0 # part of the NETLINK_ROUTE protocol
Multicast group properties¶
value¶
The value
property is used to specify the group ID to use for multicast
group registration.
mcast-groups:
list:
-
name: rtnlgrp-ipv4-ifaddr
value: 5
-
name: rtnlgrp-ipv6-ifaddr
value: 9
-
name: rtnlgrp-mctp-ifaddr
value: 34
Sub-messages¶
Several raw netlink families such as rt_link and tc use attribute nesting as an abstraction to carry module specific information.
Conceptually it looks as follows:
[OUTER NEST OR MESSAGE LEVEL]
[GENERIC ATTR 1]
[GENERIC ATTR 2]
[GENERIC ATTR 3]
[GENERIC ATTR - wrapper]
[MODULE SPECIFIC ATTR 1]
[MODULE SPECIFIC ATTR 2]
The GENERIC ATTRs
at the outer level are defined in the core (or rt_link or
core TC), while specific drivers, TC classifiers, qdiscs etc. can carry their
own information wrapped in the GENERIC ATTR - wrapper
. Even though the
example above shows attributes nesting inside the wrapper, the modules generally
have full freedom to define the format of the nest. In practice the payload of
the wrapper attr has very similar characteristics to a netlink message. It may
contain a fixed header / structure, netlink attributes, or both. Because of
those shared characteristics we refer to the payload of the wrapper attribute as
a sub-message.
A sub-message attribute uses the value of another attribute as a selector key to choose the right sub-message format. For example if the following attribute has already been decoded:
{ "kind": "gre" }
and we encounter the following attribute spec:
-
name: data
type: sub-message
sub-message: linkinfo-data-msg
selector: kind
Then we look for a sub-message definition called linkinfo-data-msg
and use
the value of the kind
attribute i.e. gre
as the key to choose the
correct format for the sub-message:
sub-messages:
name: linkinfo-data-msg
formats:
-
value: bridge
attribute-set: linkinfo-bridge-attrs
-
value: gre
attribute-set: linkinfo-gre-attrs
-
value: geneve
attribute-set: linkinfo-geneve-attrs
This would decode the attribute value as a sub-message with the attribute-set
called linkinfo-gre-attrs
as the attribute space.
A sub-message can have an optional fixed-header
followed by zero or more
attributes from an attribute-set
. For example the following
tc-options-msg
sub-message defines message formats that use a mixture of
fixed-header
, attribute-set
or both together:
sub-messages:
-
name: tc-options-msg
formats:
-
value: bfifo
fixed-header: tc-fifo-qopt
-
value: cake
attribute-set: tc-cake-attrs
-
value: netem
fixed-header: tc-netem-qopt
attribute-set: tc-netem-attrs
Note that a selector attribute must appear in a netlink message before any sub-message attributes that depend on it.
If an attribute such as kind
is defined at more than one nest level, then a
sub-message selector will be resolved using the value ‘closest’ to the selector.
For example, if the same attribute name is defined in a nested attribute-set
alongside a sub-message selector and also in a top level attribute-set
, then
the selector will be resolved using the value ‘closest’ to the selector. If the
value is not present in the message at the same level as defined in the spec
then this is an error.
Nested struct definitions¶
Many raw netlink families such as tc
make use of nested struct definitions. The netlink-raw
schema makes it
possible to embed a struct within a struct definition using the struct
property. For example, the following struct definition embeds the
tc-ratespec
struct definition for both the rate
and the peakrate
members of struct tc-tbf-qopt
.
-
name: tc-tbf-qopt
type: struct
members:
-
name: rate
type: binary
struct: tc-ratespec
-
name: peakrate
type: binary
struct: tc-ratespec
-
name: limit
type: u32
-
name: buffer
type: u32
-
name: mtu
type: u32