The Linux Kernel
5.14.0-503.22.1.el9_5.x86_64
  • The Linux kernel user’s and administrator’s guide
  • Kernel Build System
  • The Linux kernel firmware guide
  • Open Firmware and Devicetree
  • The Linux kernel user-space API guide
    • No New Privileges Flag
    • Seccomp BPF (SECure COMPuting with filters)
    • Landlock: unprivileged access control
    • unshare system call
    • Speculation Control
    • OpenCAPI (Open Coherent Accelerator Processor Interface)
    • eBPF Userspace API
    • IOCTLs
    • IOMMU Userspace API
    • IOMMUFD
    • Linux Media Infrastructure userspace API
    • Netlink Handbook
      • Introduction to Netlink
      • Using Netlink protocol specifications
      • Netlink protocol specifications (in YAML)
      • Netlink spec C code generation
      • Netlink specification support for legacy Generic Netlink families
      • Netlink specification support for raw Netlink families
        • Specification
    • Platform Profile Selection (e.g. /sys/firmware/acpi/platform_profile)
    • futex2
    • VDUSE - “vDPA Device in Userspace”
  • Working with the kernel development community
  • Development tools for the kernel
  • How to write kernel documentation
  • Kernel Hacking Guides
  • Linux Tracing Technologies
  • Kernel Maintainer Handbook
  • fault-injection
  • Kernel Livepatching
  • Rust
  • The Linux driver implementer’s API guide
  • Core API Documentation
  • locking
  • Accounting
  • Block
  • cdrom
  • Linux CPUFreq - CPU frequency and voltage scaling code in the Linux(TM) kernel
  • Integrated Drive Electronics (IDE)
  • Frame Buffer
  • fpga
  • Human Interface Devices (HID)
  • I2C/SMBus Subsystem
  • Industrial I/O
  • ISDN
  • InfiniBand
  • LEDs
  • NetLabel
  • Linux Networking Documentation
  • pcmcia
  • Power Management
  • TCM Virtual Device
  • timers
  • Serial Peripheral Interface (SPI)
  • 1-Wire Subsystem
  • Linux Watchdog Support
  • Linux Virtualization Support
  • The Linux Input Documentation
  • Linux Hardware Monitoring
  • Linux GPU Driver Developer’s Guide
  • Security Documentation
  • Sound Subsystem Documentation
  • Linux Kernel Crypto API
  • Filesystems in the Linux kernel
  • Linux Memory Management Documentation
  • BPF Documentation
  • USB support
  • Linux PCI Bus Subsystem
  • Linux SCSI Subsystem
  • Assorted Miscellaneous Devices Documentation
  • Linux Scheduler
  • MHI
  • TTY
  • Assembler Annotations
  • CPU Architectures
  • Kernel tools
  • Unsorted Documentation
  • Atomic Types
  • Atomic bitops
  • Memory Barriers
  • General notification mechanism
  • Translations
The Linux Kernel
  • »
  • The Linux kernel user-space API guide »
  • Netlink Handbook »
  • Netlink specification support for raw Netlink families
  • View page source

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.

Next Previous

© Copyright The kernel development community.

Built with Sphinx using a theme provided by Read the Docs.