Manual Pages  — NETLINK

Netlink – Kernel network configuration protocol

SYNOPSIS DESCRIPTION PROTOCOL DESCRIPTION BASE HEADER TLVs CONTROL MESSAGES SOCKET OPTIONS SYSCTL VARIABLES DEBUGGING ERRORS SEE ALSO HISTORY AUTHORS

#include <netlink/netlink.h>

#include <netlink/netlink_route.h>

int
socket(AF_NETLINK, SOCK_RAW, int family);

struct nlmsghdr {
        uint32_t nlmsg_len;   /* Length of message including header */
        uint16_t nlmsg_type;  /* Message type identifier */
        uint16_t nlmsg_flags; /* Flags (NLM_F_) */
        uint32_t nlmsg_seq;   /* Sequence number */
        uint32_t nlmsg_pid;   /* Sending process port ID */
};

The nlmsg_len field stores the whole message length, in bytes, including the header. This length has to be rounded up to the nearest 4-byte boundary when iterating over messages. The nlmsg_type field represents the command/request type. This value is family-specific. The list of supported commands can be found in the relevant family header file. nlmsg_seq is a user-provided request identifier. An application can track the operation result using the NLMSG_ERROR messages and matching the nlmsg_seq The nlmsg_pid field is the message sender id. This field is optional for userland. The kernel sender id is zero. The nlmsg_flags field contains the message-specific flags. The following generic flags are defined:

NLM_F_REQUEST   Indicates that the message is an actual request to the kernel
NLM_F_ACK       Request an explicit ACK message with an operation result

The following generic flags are defined for the "GET" request types:

NLM_F_ROOT      Return the whole dataset
NLM_F_MATCH     Return all entries matching the criteria

These two flags are typically used together, aliased to NLM_F_DUMP

The following generic flags are defined for the "NEW" request types:

NLM_F_CREATE    Create an object if none exists
NLM_F_EXCL      Don't replace an object if it exists
NLM_F_REPLACE   Replace an existing matching object
NLM_F_APPEND    Append to an existing object

The following generic flags are defined for the replies:

NLM_F_MULTI     Indicates that the message is part of the message group
NLM_F_DUMP_INTR Indicates that the state dump was not completed
NLM_F_DUMP_FILTERED     Indicates that the dump was filtered per request
NLM_F_CAPPED    Indicates the original message was capped to its header
NLM_F_ACK_TLVS  Indicates that extended ACK TLVs were included

Most messages encode their attributes as type-length-value pairs (TLVs). The base TLV header:

struct nlattr {
        uint16_t nla_len;       /* Total attribute length */
        uint16_t nla_type;      /* Attribute type */
};

The TLV type ( nla_type) scope is typically the message type or group within a family. For example, the RTN_MULTICAST type value is only valid for RTM_NEWROUTE , RTM_DELROUTE and RTM_GETROUTE messages. TLVs can be nested; in that case internal TLVs may have their own sub-types. All TLVs are packed with 4-byte padding.

A number of generic control messages are reserved in each family.

NLMSG_ERROR reports the operation result if requested, optionally followed by the metadata TLVs. The value of nlmsg_seq is set to its value in the original messages, while nlmsg_pid is set to the socket pid of the original socket. The operation result is reported via struct nlmsgerr:

struct nlmsgerr {
        int     error;          /* Standard errno */
        struct  nlmsghdr msg;   /* Original message header */
};

If the NETLINK_CAP_ACK socket option is not set, the remainder of the original message will follow. If the NETLINK_EXT_ACK socket option is set, the kernel may add a NLMSGERR_ATTR_MSG string TLV with the textual error description, optionally followed by the NLMSGERR_ATTR_OFFS TLV, indicating the offset from the message start that triggered an error. Some operations may return additional metadata encapsulated in the NLMSGERR_ATTR_COOKIE TLV. The metadata format is specific to the operation. If the operation reply is a multipart message, then no NLMSG_ERROR reply is generated, only a NLMSG_DONE message, closing multipart sequence.

NLMSG_DONE indicates the end of the message group: typically, the end of the dump. It contains a single int field, describing the dump result as a standard errno value.

Netlink reports operation results, including errors and error metadata, by sending a NLMSG_ERROR message for each request message. The following errors can be returned:

[EPERM]
	when the current privileges are insufficient to perform the required operation;
[ENOBUFS ]or [ENOMEM ]
	when the system runs out of memory for an internal data structure;
[ENOTSUP]
	when the requested command is not supported by the family or the family is not supported;
[EINVAL]
	when some necessary TLVs are missing or invalid, detailed info may be provided in NLMSGERR_ATTR_MSG and NLMSGERR_ATTR_OFFS TLVs;
[ENOENT]
	when trying to delete a non-existent object. Additionally, a socket operation itself may fail with one of the errors specified in socket(2) , recv(2) or send(2)

The netlink protocol appeared in FreeBSD 13.2 .

The netlink was implemented by Alexander Chernikov <Mt melifaro@FreeBSD.org>. It was derived from the Google Summer of Code 2021 project by Ng Peng Nam Sean.