userspace-api/netlink/intro.rst

4 Introduction to Netlink
7 Netlink is often described as an ioctl() replacement.
12 To achieve this Netlink uses a minimal fixed-format metadata header
18 netlink as it is used today and dives into more "historical" uses
24 Netlink communication happens over sockets, a socket needs to be
36 A very simplified flow of a Netlink "call" will therefore look
48 Netlink also provides natural support for "dumping", i.e. communicating
70 it is opening a Netlink socket, with all headers provided by the user
71 (hence NETLINK, RAW). The last argument is the protocol within Netlink.
75 Classic vs Generic Netlink
78 Initial implementation of Netlink depended on a static allocation
80 Let us refer to those protocols collectively as **Classic Netlink**.
81 The list of them is defined on top of the ``include/uapi/linux/netlink.h``
85 **Generic Netlink** (introduced in 2005) allows for dynamic registration of
89 The following section describes how to use Generic Netlink, as the
90 number of subsystems using Generic Netlink outnumbers the older
92 more Classic Netlink protocols to the kernel.
95 Netlink) differs from Generic Netlink is provided later in this document.
97 Generic Netlink
100 In addition to the Netlink fixed metadata header each Netlink protocol
102 headers stack - Ethernet > IP > TCP we have Netlink > Generic N. > Family.)
104 A Netlink message always starts with struct nlmsghdr, which is followed
105 by a protocol-specific header. In case of Generic Netlink the protocol
108 The practical meaning of the fields in case of Generic Netlink is as follows:
114 	__u16	nlmsg_type;	/* Generic Netlink Family (subsystem) ID */
126 In Classic Netlink :c:member:`nlmsghdr.nlmsg_type` used to identify
128 (e.g. get information about a netdev). Generic Netlink needs to mux
134 control messages both in Classic Netlink and Generic Netlink.
137 There are 3 usual types of message exchanges on a Netlink socket:
143 Classic Netlink is very flexible and presumably allows other types
162 :c:member:`nlmsghdr.nlmsg_pid` is the Netlink equivalent of an address.
173 Netlink message types
181 There are only 4 Netlink control messages defined:
190 the ``NLM_F_ACK`` flag is set on the request Netlink will not respond
247 It also serves as an example of Generic Netlink communication.
249 Generic Netlink is itself a subsystem exposed via the Generic Netlink API.
250 To avoid a circular dependency Generic Netlink has a statically allocated
252 The Generic Netlink family implements a command used to find out information
255 To get information about the Generic Netlink family named for example
256 ``"test1"`` we need to send a message on the previously opened Generic Netlink
257 socket. The message should target the Generic Netlink Family (1), be a
283 The length fields in Netlink (:c:member:`nlmsghdr.nlmsg_len`
285 Attribute headers in netlink must be aligned to 4 bytes from the start
350 Note that Generic Netlink sockets are not associated or bound to a single
381 Extended ACKs greatly improve the usability of Netlink and should
404 the Generic Netlink family, including which operations are supported
419 :c:member:`nlmsghdr.nlmsg_pid` is the Netlink equivalent of an address.
441 One of the strengths of Netlink is the ability to send event notifications
446 For example the Generic Netlink family itself defines a set of multicast
488 The Netlink headers of the notification are mostly 0 and irrelevant.
520 Netlink sockets are datagram sockets rather than stream sockets,
525 of the recvmsg() system call, *not* a Netlink header).
529 Netlink expects that the user buffer will be at least 8kB or a page
530 size of the CPU architecture, whichever is bigger. Particular Netlink
537 Classic Netlink
540 The main differences between Classic and Generic Netlink are the dynamic
543 Classic Netlink experimented with concepts which were abandoned in Generic
544 Netlink (really, they usually only found use in a small corner of a single
546 with the explicit goal of giving the Generic Netlink
556 Netlink refers to subsystems as families. This is a remnant of using
566  3. Generic Netlink is a family for AF_NETLINK (struct genlmsghdr follows
569 Note that the Generic Netlink Family IDs are in a different "ID space"
570 and overlap with Classic Netlink protocol numbers (e.g. ``NETLINK_CRYPTO``
571 has the Classic Netlink protocol ID of 21 which Generic Netlink will
593 Historically Netlink ignored all unknown attributes. The thinking was that
598 This is no longer the case for new Generic Netlink families and those opting
605 Classic Netlink made liberal use of fixed-format structures within
628 Even though other protocols and Generic Netlink commands often use
644 Classic Netlink defined various flags for its ``GET``, ``NEW``
655 The flags for ``NEW`` are used most commonly in classic Netlink. Unfortunately,
665 A comment in the main Netlink uAPI header states::
687 .. kernel-doc:: include/uapi/linux/netlink.h