xref: /freebsd/share/man/man4/netlink.4 (revision f374ba41f55c1a127303d92d830dd58eef2f5243)
1.\"
2.\" Copyright (C) 2022 Alexander Chernikov <melifaro@FreeBSD.org>.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.\" $FreeBSD$
26.\"
27.Dd November 30, 2022
28.Dt NETLINK 4
29.Os
30.Sh NAME
31.Nm Netlink
32.Nd Kernel network configuration protocol
33.Sh SYNOPSIS
34.In netlink/netlink.h
35.In netlink/netlink_route.h
36.Ft int
37.Fn socket AF_NETLINK SOCK_RAW "int family"
38.Sh DESCRIPTION
39Netlink is a user-kernel message-based communication protocol primarily used
40for network stack configuration.
41Netlink is easily extendable and supports large dumps and event
42notifications, all via a single socket.
43The protocol is fully asynchronous, allowing one to issue and track multiple
44requests at once.
45Netlink consists of multiple families, which commonly group the commands
46belonging to the particular kernel subsystem.
47Currently, the supported families are:
48.Pp
49.Bd -literal -offset indent -compact
50NETLINK_ROUTE	network configuration,
51NETLINK_GENERIC	"container" family
52.Ed
53.Pp
54The
55.Dv NETLINK_ROUTE
56family handles all interfaces, addresses, neighbors, routes, and VNETs
57configuration.
58More details can be found in
59.Xr rtnetlink 4 .
60The
61.Dv NETLINK_GENERIC
62family serves as a
63.Do container Dc ,
64allowing registering other families under the
65.Dv NETLINK_GENERIC
66umbrella.
67This approach allows using a single netlink socket to interact with
68multiple netlink families at once.
69More details can be found in
70.Xr genetlink 4 .
71.Pp
72Netlink has its own sockaddr structure:
73.Bd -literal
74struct sockaddr_nl {
75	uint8_t		nl_len;		/* sizeof(sockaddr_nl) */
76	sa_family_t	nl_family;	/* netlink family */
77	uint16_t	nl_pad;		/* reserved, set to 0 */
78	uint32_t	nl_pid;		/* automatically selected, set to 0 */
79	uint32_t	nl_groups;	/* multicast groups mask to bind to */
80};
81.Ed
82.Pp
83Typically, filling this structure is not required for socket operations.
84It is presented here for completeness.
85.Sh PROTOCOL DESCRIPTION
86The protocol is message-based.
87Each message starts with the mandatory
88.Va nlmsghdr
89header, followed by the family-specific header and the list of
90type-length-value pairs (TLVs).
91TLVs can be nested.
92All headers and TLVS are padded to 4-byte boundaries.
93Each
94.Xr send 2 or
95.Xr recv 2
96system call may contain multiple messages.
97.Ss BASE HEADER
98.Bd -literal
99struct nlmsghdr {
100	uint32_t nlmsg_len;   /* Length of message including header */
101	uint16_t nlmsg_type;  /* Message type identifier */
102	uint16_t nlmsg_flags; /* Flags (NLM_F_) */
103	uint32_t nlmsg_seq;   /* Sequence number */
104	uint32_t nlmsg_pid;   /* Sending process port ID */
105};
106.Ed
107.Pp
108The
109.Va nlmsg_len
110field stores the whole message length, in bytes, including the header.
111This length has to be rounded up to the nearest 4-byte boundary when
112iterating over messages.
113The
114.Va nlmsg_type
115field represents the command/request type.
116This value is family-specific.
117The list of supported commands can be found in the relevant family
118header file.
119.Va nlmsg_seq
120is a user-provided request identifier.
121An application can track the operation result using the
122.Dv NLMSG_ERROR
123messages and matching the
124.Va nlmsg_seq
125.
126The
127.Va nlmsg_pid
128field is the message sender id.
129This field is optional for userland.
130The kernel sender id is zero.
131The
132.Va nlmsg_flags
133field contains the message-specific flags.
134The following generic flags are defined:
135.Pp
136.Bd -literal -offset indent -compact
137NLM_F_REQUEST	Indicates that the message is an actual request to the kernel
138NLM_F_ACK	Request an explicit ACK message with an operation result
139.Ed
140.Pp
141The following generic flags are defined for the "GET" request types:
142.Pp
143.Bd -literal -offset indent -compact
144NLM_F_ROOT	Return the whole dataset
145NLM_F_MATCH	Return all entries matching the criteria
146.Ed
147These two flags are typically used together, aliased to
148.Dv NLM_F_DUMP
149.Pp
150The following generic flags are defined for the "NEW" request types:
151.Pp
152.Bd -literal -offset indent -compact
153NLM_F_CREATE	Create an object if none exists
154NLM_F_EXCL	Don't replace an object if it exists
155NLM_F_REPLACE	Replace an existing matching object
156NLM_F_APPEND	Append to an existing object
157.Ed
158.Pp
159The following generic flags are defined for the replies:
160.Pp
161.Bd -literal -offset indent -compact
162NLM_F_MULTI	Indicates that the message is part of the message group
163NLM_F_DUMP_INTR	Indicates that the state dump was not completed
164NLM_F_DUMP_FILTERED	Indicates that the dump was filtered per request
165NLM_F_CAPPED	Indicates the original message was capped to its header
166NLM_F_ACK_TLVS	Indicates that extended ACK TLVs were included
167.Ed
168.Ss TLVs
169Most messages encode their attributes as type-length-value pairs (TLVs).
170The base TLV header:
171.Bd -literal
172struct nlattr {
173	uint16_t nla_len;	/* Total attribute length */
174	uint16_t nla_type;	/* Attribute type */
175};
176.Ed
177The TLV type
178.Pq Va nla_type
179scope is typically the message type or group within a family.
180For example, the
181.Dv RTN_MULTICAST
182type value is only valid for
183.Dv RTM_NEWROUTE
184,
185.Dv RTM_DELROUTE
186and
187.Dv RTM_GETROUTE
188messages.
189TLVs can be nested; in that case internal TLVs may have their own sub-types.
190All TLVs are packed with 4-byte padding.
191.Ss CONTROL MESSAGES
192A number of generic control messages are reserved in each family.
193.Pp
194.Dv NLMSG_ERROR
195reports the operation result if requested, optionally followed by
196the metadata TLVs.
197The value of
198.Va nlmsg_seq
199is set to its value in the original messages, while
200.Va nlmsg_pid
201is set to the socket pid of the original socket.
202The operation result is reported via
203.Vt "struct nlmsgerr":
204.Bd -literal
205struct nlmsgerr {
206	int	error;		/* Standard errno */
207	struct	nlmsghdr msg;	/* Original message header */
208};
209.Ed
210If the
211.Dv NETLINK_CAP_ACK
212socket option is not set, the remainder of the original message will follow.
213If the
214.Dv NETLINK_EXT_ACK
215socket option is set, the kernel may add a
216.Dv NLMSGERR_ATTR_MSG
217string TLV with the textual error description, optionally followed by the
218.Dv NLMSGERR_ATTR_OFFS
219TLV, indicating the offset from the message start that triggered an error.
220If the operation reply is a multipart message, then no
221.Dv NLMSG_ERROR
222reply is generated, only a
223.Dv NLMSG_DONE
224message, closing multipart sequence.
225.Pp
226.Dv NLMSG_DONE
227indicates the end of the message group: typically, the end of the dump.
228It contains a single
229.Vt int
230field, describing the dump result as a standard errno value.
231.Sh SOCKET OPTIONS
232Netlink supports a number of custom socket options, which can be set with
233.Xr setsockopt 2
234with the
235.Dv SOL_NETLINK
236.Fa level :
237.Bl -tag -width indent
238.It Dv NETLINK_ADD_MEMBERSHIP
239Subscribes to the notifications for the specific group (int).
240.It Dv NETLINK_DROP_MEMBERSHIP
241Unsubscribes from the notifications for the specific group (int).
242.It Dv NETLINK_LIST_MEMBERSHIPS
243Lists the memberships as a bitmask.
244.It Dv NETLINK_CAP_ACK
245Instructs the kernel to send the original message header in the reply
246without the message body.
247.It Dv NETLINK_EXT_ACK
248Acknowledges ability to receive additional TLVs in the ACK message.
249.El
250.Pp
251Additionally, netlink overrides the following socket options from the
252.Dv SOL_SOCKET
253.Fa level :
254.Bl -tag -width indent
255.It Dv SO_RCVBUF
256Sets the maximum size of the socket receive buffer.
257If the caller has
258.Dv PRIV_NET_ROUTE
259permission, the value can exceed the currently-set
260.Va kern.ipc.maxsockbuf
261value.
262.El
263.Sh SYSCTL VARIABLES
264A set of
265.Xr sysctl 8
266variables is available to tweak run-time parameters:
267.Bl -tag -width indent
268.It Va net.netlink.sendspace
269Default send buffer for the netlink socket.
270Note that the socket sendspace has to be at least as long as the longest
271message that can be transmitted via this socket.
272.El
273.Bl -tag -width indent
274.It Va net.netlink.recvspace
275Default receive buffer for the netlink socket.
276Note that the socket recvspace has to be least as long as the longest
277message that can be received from this socket.
278.El
279.Sh DEBUGGING
280Netlink implements per-functional-unit debugging, with different severities
281controllable via the
282.Va net.netlink.debug
283branch.
284These messages are logged in the kernel message buffer and can be seen in
285.Xr dmesg 8
286.
287The following severity levels are defined:
288.Bl -tag -width indent
289.It Dv LOG_DEBUG(7)
290Rare events or per-socket errors are reported here.
291This is the default level, not impacting production performance.
292.It Dv LOG_DEBUG2(8)
293Socket events such as groups memberships, privilege checks, commands and dumps
294are logged.
295This level does not incur significant performance overhead.
296.It Dv LOG_DEBUG3(9)
297All socket events, each dumped or modified entities are logged.
298Turning it on may result in significant performance overhead.
299.El
300.Sh ERRORS
301Netlink reports operation results, including errors and error metadata, by
302sending a
303.Dv NLMSG_ERROR
304message for each request message.
305The following errors can be returned:
306.Bl -tag -width Er
307.It Bq Er EPERM
308when the current privileges are insufficient to perform the required operation;
309.It Bo Er ENOBUFS Bc or Bo Er ENOMEM Bc
310when the system runs out of memory for
311an internal data structure;
312.It Bq Er ENOTSUP
313when the requested command is not supported by the family or
314the family is not supported;
315.It Bq Er EINVAL
316when some necessary TLVs are missing or invalid, detailed info
317may be provided in NLMSGERR_ATTR_MSG and NLMSGERR_ATTR_OFFS TLVs;
318.It Bq Er ENOENT
319when trying to delete a non-existent object.
320.Pp
321Additionally, a socket operation itself may fail with one of the errors
322specified in
323.Xr socket 2
324,
325.Xr recv 2
326or
327.Xr send 2
328.
329.El
330.Sh SEE ALSO
331.Xr genetlink 4 ,
332.Xr rtnetlink 4
333.Rs
334.%A "J. Salim"
335.%A "H. Khosravi"
336.%A "A. Kleen"
337.%A "A. Kuznetsov"
338.%T "Linux Netlink as an IP Services Protocol"
339.%O "RFC 3549"
340.Re
341.Sh HISTORY
342The netlink protocol appeared in
343.Fx 14.0 .
344.Sh AUTHORS
345The netlink was implemented by
346.An -nosplit
347.An Alexander Chernikov Aq Mt melifaro@FreeBSD.org .
348It was derived from the Google Summer of Code 2021 project by
349.An Ng Peng Nam Sean .
350