Debian Codegraph @

upstream/debian-unstable/man7/netlink.7

raw
1 '\" t
2 .\" Copyright 1998, Andi Kleen <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: GPL-1.0-or-later
6 .\"
7 .TH netlink 7 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 netlink \- communication between kernel and user space (AF_NETLINK)
10 .SH SYNOPSIS
11 .nf
12 .B #include <asm/types.h>
13 .B #include <sys/socket.h>
14 .B #include <linux/netlink.h>
15 .P
16 .BI "netlink_socket = socket(AF_NETLINK, " socket_type ", " netlink_family );
17 .fi
18 .SH DESCRIPTION
19 Netlink is used to transfer information
20 between the kernel and user-space processes.
21 It consists of a standard sockets-based interface for user space
22 processes and an internal kernel API for kernel modules.
23 The internal kernel interface is not documented in this manual page.
24 There is also an obsolete netlink interface
25 via netlink character devices;
26 this interface is not documented here,
27 and is provided only for backward compatibility.
28 .P
29 Netlink is a datagram-oriented service.
30 Both
31 .B SOCK_RAW
32 and
33 .B SOCK_DGRAM
34 are valid values for
35 .IR socket_type .
36 However, the netlink protocol does not distinguish between datagram
37 and raw sockets.
38 .P
39 .I netlink_family
40 selects the kernel module or netlink group to communicate with.
41 The currently assigned netlink families are:
42 .TP
43 .B NETLINK_ROUTE
44 Receives routing and link updates and may be used to modify the routing
45 tables (both IPv4 and IPv6), IP addresses, link parameters,
46 neighbor setups, queueing disciplines, traffic classes, and
47 packet classifiers (see
48 .BR rtnetlink (7)).
49 .TP
50 .BR NETLINK_W1 " (Linux 2.6.13 to Linux 2.16.17)"
51 Messages from 1-wire subsystem.
52 .TP
53 .B NETLINK_USERSOCK
54 Reserved for user-mode socket protocols.
55 .TP
56 .BR NETLINK_FIREWALL " (up to and including Linux 3.4)"
57 .\" removed by commit d16cf20e2f2f13411eece7f7fb72c17d141c4a84
58 Transport IPv4 packets from netfilter to user space.
59 Used by
60 .I ip_queue
61 kernel module.
62 After a long period of being declared obsolete (in favor of the more advanced
63 .I nfnetlink_queue
64 feature),
65 .B NETLINK_FIREWALL
66 was removed in Linux 3.5.
67 .TP
68 .BR NETLINK_SOCK_DIAG " (since Linux 3.3)"
69 .\" commit 7f1fb60c4fc9fb29fbb406ac8c4cfb4e59e168d6
70 Query information about sockets of various protocol families from the kernel
71 (see
72 .BR sock_diag (7)).
73 .TP
74 .BR NETLINK_INET_DIAG " (since Linux 2.6.14)"
75 An obsolete synonym for
76 .BR NETLINK_SOCK_DIAG .
77 .TP
78 .BR NETLINK_NFLOG " (up to and including Linux 3.16)"
79 Netfilter/iptables ULOG.
80 .TP
81 .B NETLINK_XFRM
82 .\" FIXME More details on NETLINK_XFRM needed.
83 IPsec.
84 .TP
85 .BR NETLINK_SELINUX " (since Linux 2.6.4)"
86 SELinux event notifications.
87 .TP
88 .BR NETLINK_ISCSI " (since Linux 2.6.15)"
89 .\" FIXME More details on NETLINK_ISCSI needed.
90 Open-iSCSI.
91 .TP
92 .BR NETLINK_AUDIT " (since Linux 2.6.6)"
93 .\" FIXME More details on NETLINK_AUDIT needed.
94 Auditing.
95 .TP
96 .BR NETLINK_FIB_LOOKUP " (since Linux 2.6.13)"
97 .\" FIXME More details on NETLINK_FIB_LOOKUP needed.
98 Access to FIB lookup from user space.
99 .TP
100 .BR NETLINK_CONNECTOR " (since Linux 2.6.14)"
101 Kernel connector.
102 See
103 .I Documentation/driver\-api/connector.rst
104 (or
105 .I /Documentation/connector/connector.*
106 .\" commit baa293e9544bea71361950d071579f0e4d5713ed
107 in Linux 5.2 and earlier)
108 in the Linux kernel source tree for further information.
109 .TP
110 .BR NETLINK_NETFILTER " (since Linux 2.6.14)"
111 .\" FIXME More details on NETLINK_NETFILTER needed.
112 Netfilter subsystem.
113 .TP
114 .BR NETLINK_SCSITRANSPORT " (since Linux 2.6.19)"
115 .\" commit 84314fd4740ad73550c76dee4a9578979d84af48
116 .\" FIXME More details on NETLINK_SCSITRANSPORT needed.
117 SCSI Transports.
118 .TP
119 .BR NETLINK_RDMA " (since Linux 3.0)"
120 .\" commit b2cbae2c248776d81cc265ff7d48405b6a4cc463
121 .\" FIXME More details on NETLINK_RDMA needed.
122 Infiniband RDMA.
123 .TP
124 .BR NETLINK_IP6_FW " (up to and including Linux 3.4)"
125 Transport IPv6 packets from netfilter to user space.
126 Used by
127 .I ip6_queue
128 kernel module.
129 .TP
130 .B NETLINK_DNRTMSG
131 DECnet routing messages.
132 .TP
133 .BR NETLINK_KOBJECT_UEVENT " (since Linux 2.6.10)"
134 .\" FIXME More details on NETLINK_KOBJECT_UEVENT needed.
135 Kernel messages to user space.
136 .TP
137 .BR NETLINK_GENERIC " (since Linux 2.6.15)"
138 Generic netlink family for simplified netlink usage.
139 .TP
140 .BR NETLINK_CRYPTO " (since Linux 3.2)"
141 .\" commit a38f7907b926e4c6c7d389ad96cc38cec2e5a9e9
142 .\" Author: Steffen Klassert <[email protected]>
143 Netlink interface to request information about ciphers registered
144 with the kernel crypto API as well as allow configuration of the
145 kernel crypto API.
146 .P
147 Netlink messages consist of a byte stream with one or multiple
148 .I nlmsghdr
149 headers and associated payload.
150 The byte stream should be accessed only with the standard
151 .B NLMSG_*
152 macros.
153 See
154 .BR netlink (3)
155 for further information.
156 .P
157 In multipart messages (multiple
158 .I nlmsghdr
159 headers with associated payload in one byte stream) the first and all
160 following headers have the
161 .B NLM_F_MULTI
162 flag set, except for the last header which has the type
163 .BR NLMSG_DONE .
164 .P
165 After each
166 .I nlmsghdr
167 the payload follows.
168 .P
169 .in +4n
170 .EX
171 struct nlmsghdr {
172 __u32 nlmsg_len; /* Size of message including header */
173 __u16 nlmsg_type; /* Type of message content */
174 __u16 nlmsg_flags; /* Additional flags */
175 __u32 nlmsg_seq; /* Sequence number */
176 __u32 nlmsg_pid; /* Sender port ID */
177 };
178 .EE
179 .in
180 .P
181 .I nlmsg_type
182 can be one of the standard message types:
183 .B NLMSG_NOOP
184 message is to be ignored,
185 .B NLMSG_ERROR
186 message signals an error and the payload contains an
187 .I nlmsgerr
188 structure,
189 .B NLMSG_DONE
190 message terminates a multipart message.
191 Error messages get the
192 original request appended, unless the user requests to cap the
193 error message, and get extra error data if requested.
194 .P
195 .in +4n
196 .EX
197 struct nlmsgerr {
198 int error; /* Negative errno or 0 for acknowledgements */
199 struct nlmsghdr msg; /* Message header that caused the error */
200 /*
201 * followed by the message contents
202 * unless NETLINK_CAP_ACK was set
203 * or the ACK indicates success (error == 0).
204 * For example Generic Netlink message with attributes.
205 * message size is aligned with NLMSG_ALIGN()
206 */
207 /*
208 * followed by TLVs defined in enum nlmsgerr_attrs
209 * if NETLINK_EXT_ACK was set
210 */
211 };
212 .EE
213 .in
214 .P
215 A netlink family usually specifies more message types, see the
216 appropriate manual pages for that, for example,
217 .BR rtnetlink (7)
218 for
219 .BR NETLINK_ROUTE .
220 .TS
221 tab(:);
222 l s
223 lB lx.
224 Standard flag bits in \f[I]nlmsg_flags\f[]
225 _
226 NLM_F_REQUEST:T{
227 Must be set on all request messages.
228 T}
229 NLM_F_MULTI:T{
230 The message is part of a multipart message terminated by
231 .BR NLMSG_DONE .
232 T}
233 NLM_F_ACK:T{
234 Request for an acknowledgement on success.
235 T}
236 NLM_F_ECHO:T{
237 Echo this request.
238 T}
239 .TE
240 .\" No right adjustment for text blocks in tables
241 .TS
242 tab(:);
243 l s
244 lB lx.
245 Additional flag bits for GET requests
246 _
247 NLM_F_ROOT:T{
248 Return the complete table instead of a single entry.
249 T}
250 NLM_F_MATCH:T{
251 Return all entries matching criteria passed in message content.
252 Not implemented yet.
253 T}
254 NLM_F_ATOMIC:T{
255 Return an atomic snapshot of the table.
256 T}
257 NLM_F_DUMP:T{
258 Convenience macro;
259 equivalent to
260 (NLM_F_ROOT|NLM_F_MATCH).
261 T}
262 .TE
263 .\" FIXME NLM_F_ATOMIC is not used anymore?
264 .P
265 Note that
266 .B NLM_F_ATOMIC
267 requires the
268 .B CAP_NET_ADMIN
269 capability or an effective UID of 0.
270 .TS
271 tab(:);
272 l s
273 lB lx.
274 Additional flag bits for NEW requests
275 _
276 NLM_F_REPLACE:T{
277 Replace existing matching object.
278 T}
279 NLM_F_EXCL:T{
280 Don't replace if the object already exists.
281 T}
282 NLM_F_CREATE:T{
283 Create object if it doesn't already exist.
284 T}
285 NLM_F_APPEND:T{
286 Add to the end of the object list.
287 T}
288 .TE
289 .P
290 .I nlmsg_seq
291 and
292 .I nlmsg_pid
293 are used to track messages.
294 .I nlmsg_pid
295 shows the origin of the message.
296 Note that there isn't a 1:1 relationship between
297 .I nlmsg_pid
298 and the PID of the process if the message originated from a netlink
299 socket.
300 See the
301 .B ADDRESS FORMATS
302 section for further information.
303 .P
304 Both
305 .I nlmsg_seq
306 and
307 .I nlmsg_pid
308 .\" FIXME Explain more about nlmsg_seq and nlmsg_pid.
309 are opaque to netlink core.
310 .P
311 Netlink is not a reliable protocol.
312 It tries its best to deliver a message to its destination(s),
313 but may drop messages when an out-of-memory condition or
314 other error occurs.
315 For reliable transfer the sender can request an
316 acknowledgement from the receiver by setting the
317 .B NLM_F_ACK
318 flag.
319 An acknowledgement is an
320 .B NLMSG_ERROR
321 packet with the error field set to 0.
322 The application must generate acknowledgements for
323 received messages itself.
324 The kernel tries to send an
325 .B NLMSG_ERROR
326 message for every failed packet.
327 A user process should follow this convention too.
328 .P
329 However, reliable transmissions from kernel to user are impossible
330 in any case.
331 The kernel can't send a netlink message if the socket buffer is full:
332 the message will be dropped and the kernel and the user-space process will
333 no longer have the same view of kernel state.
334 It is up to the application to detect when this happens (via the
335 .B ENOBUFS
336 error returned by
337 .BR recvmsg (2))
338 and resynchronize.
339 .SS Address formats
340 The
341 .I sockaddr_nl
342 structure describes a netlink client in user space or in the kernel.
343 A
344 .I sockaddr_nl
345 can be either unicast (only sent to one peer) or sent to
346 netlink multicast groups
347 .RI ( nl_groups
348 not equal 0).
349 .P
350 .in +4n
351 .EX
352 struct sockaddr_nl {
353 sa_family_t nl_family; /* AF_NETLINK */
354 unsigned short nl_pad; /* Zero */
355 pid_t nl_pid; /* Port ID */
356 __u32 nl_groups; /* Multicast groups mask */
357 };
358 .EE
359 .in
360 .P
361 .I nl_pid
362 is the unicast address of netlink socket.
363 It's always 0 if the destination is in the kernel.
364 For a user-space process,
365 .I nl_pid
366 is usually the PID of the process owning the destination socket.
367 However,
368 .I nl_pid
369 identifies a netlink socket, not a process.
370 If a process owns several netlink
371 sockets, then
372 .I nl_pid
373 can be equal to the process ID only for at most one socket.
374 There are two ways to assign
375 .I nl_pid
376 to a netlink socket.
377 If the application sets
378 .I nl_pid
379 before calling
380 .BR bind (2),
381 then it is up to the application to make sure that
382 .I nl_pid
383 is unique.
384 If the application sets it to 0, the kernel takes care of assigning it.
385 The kernel assigns the process ID to the first netlink socket the process
386 opens and assigns a unique
387 .I nl_pid
388 to every netlink socket that the process subsequently creates.
389 .P
390 .I nl_groups
391 is a bit mask with every bit representing a netlink group number.
392 Each netlink family has a set of 32 multicast groups.
393 When
394 .BR bind (2)
395 is called on the socket, the
396 .I nl_groups
397 field in the
398 .I sockaddr_nl
399 should be set to a bit mask of the groups which it wishes to listen to.
400 The default value for this field is zero which means that no multicasts
401 will be received.
402 A socket may multicast messages to any of the multicast groups by setting
403 .I nl_groups
404 to a bit mask of the groups it wishes to send to when it calls
405 .BR sendmsg (2)
406 or does a
407 .BR connect (2).
408 Only processes with an effective UID of 0 or the
409 .B CAP_NET_ADMIN
410 capability may send or listen to a netlink multicast group.
411 Since Linux 2.6.13,
412 .\" commit d629b836d151d43332492651dd841d32e57ebe3b
413 messages can't be broadcast to multiple groups.
414 Any replies to a message received for a multicast group should be
415 sent back to the sending PID and the multicast group.
416 Some Linux kernel subsystems may additionally allow other users
417 to send and/or receive messages.
418 As at Linux 3.0, the
419 .BR NETLINK_KOBJECT_UEVENT ,
420 .BR NETLINK_GENERIC ,
421 .BR NETLINK_ROUTE ,
422 and
423 .B NETLINK_SELINUX
424 groups allow other users to receive messages.
425 No groups allow other users to send messages.
426 .SS Socket options
427 To set or get a netlink socket option, call
428 .BR getsockopt (2)
429 to read or
430 .BR setsockopt (2)
431 to write the option with the option level argument set to
432 .BR SOL_NETLINK .
433 Unless otherwise noted,
434 .I optval
435 is a pointer to an
436 .IR int .
437 .TP
438 .BR NETLINK_PKTINFO " (since Linux 2.6.14)"
439 .\" commit 9a4595bc7e67962f13232ee55a64e063062c3a99
440 .\" Author: Patrick McHardy <[email protected]>
441 Enable
442 .B nl_pktinfo
443 control messages for received packets to get the extended
444 destination group number.
445 .TP
446 .B NETLINK_ADD_MEMBERSHIP
447 .TQ
448 .BR NETLINK_DROP_MEMBERSHIP " (since Linux 2.6.14)"
449 .\" commit 9a4595bc7e67962f13232ee55a64e063062c3a99
450 .\" Author: Patrick McHardy <[email protected]>
451 Join/leave a group specified by
452 .IR optval .
453 .TP
454 .BR NETLINK_LIST_MEMBERSHIPS " (since Linux 4.2)"
455 .\" commit b42be38b2778eda2237fc759e55e3b698b05b315
456 .\" Author: David Herrmann <[email protected]>
457 Retrieve all groups a socket is a member of.
458 .I optval
459 is a pointer to
460 .B __u32
461 and
462 .I optlen
463 is the size of the array.
464 The array is filled with the full membership set of the
465 socket, and the required array size is returned in
466 .IR optlen .
467 .TP
468 .BR NETLINK_BROADCAST_ERROR " (since Linux 2.6.30)"
469 .\" commit be0c22a46cfb79ab2342bb28fde99afa94ef868e
470 .\" Author: Pablo Neira Ayuso <[email protected]>
471 When not set,
472 .B netlink_broadcast()
473 only reports
474 .B ESRCH
475 errors and silently ignore
476 .B ENOBUFS
477 errors.
478 .TP
479 .BR NETLINK_NO_ENOBUFS " (since Linux 2.6.30)"
480 .\" commit 38938bfe3489394e2eed5e40c9bb8f66a2ce1405
481 .\" Author: Pablo Neira Ayuso <[email protected]>
482 This flag can be used by unicast and broadcast listeners to avoid receiving
483 .B ENOBUFS
484 errors.
485 .TP
486 .BR NETLINK_LISTEN_ALL_NSID " (since Linux 4.2)"
487 .\" commit 59324cf35aba5336b611074028777838a963d03b
488 .\" Author: Nicolas Dichtel <[email protected]>
489 When set, this socket will receive netlink notifications from
490 all network namespaces that have an
491 .I nsid
492 assigned into the network namespace where the socket has been opened.
493 The
494 .I nsid
495 is sent to user space via an ancillary data.
496 .TP
497 .BR NETLINK_CAP_ACK " (since Linux 4.3)"
498 .\" commit 0a6a3a23ea6efde079a5b77688541a98bf202721
499 .\" Author: Christophe Ricard <[email protected]>
500 The kernel may fail to allocate the necessary room for the acknowledgement
501 message back to user space.
502 This option trims off the payload of the original netlink message.
503 The netlink message header is still included, so the user can guess from the
504 sequence number which message triggered the acknowledgement.
505 .SH VERSIONS
506 The socket interface to netlink first appeared Linux 2.2.
507 .P
508 Linux 2.0 supported a more primitive device-based netlink interface
509 (which is still available as a compatibility option).
510 This obsolete interface is not described here.
511 .SH NOTES
512 It is often better to use netlink via
513 .I libnetlink
514 or
515 .I libnl
516 than via the low-level kernel interface.
517 .SH BUGS
518 This manual page is not complete.
519 .SH EXAMPLES
520 The following example creates a
521 .B NETLINK_ROUTE
522 netlink socket which will listen to the
523 .B RTMGRP_LINK
524 (network interface create/delete/up/down events) and
525 .B RTMGRP_IPV4_IFADDR
526 (IPv4 addresses add/delete events) multicast groups.
527 .P
528 .in +4n
529 .EX
530 struct sockaddr_nl sa;
531 \&
532 memset(&sa, 0, sizeof(sa));
533 sa.nl_family = AF_NETLINK;
534 sa.nl_groups = RTMGRP_LINK | RTMGRP_IPV4_IFADDR;
535 \&
536 fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE);
537 bind(fd, (struct sockaddr *) &sa, sizeof(sa));
538 .EE
539 .in
540 .P
541 The next example demonstrates how to send a netlink message to the
542 kernel (pid 0).
543 Note that the application must take care of message sequence numbers
544 in order to reliably track acknowledgements.
545 .P
546 .in +4n
547 .EX
548 struct nlmsghdr *nh; /* The nlmsghdr with payload to send */
549 struct sockaddr_nl sa;
550 struct iovec iov = { nh, nh\->nlmsg_len };
551 struct msghdr msg;
552 \&
553 msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
554 memset(&sa, 0, sizeof(sa));
555 sa.nl_family = AF_NETLINK;
556 nh\->nlmsg_pid = 0;
557 nh\->nlmsg_seq = ++sequence_number;
558 /* Request an ack from kernel by setting NLM_F_ACK */
559 nh\->nlmsg_flags |= NLM_F_ACK;
560 \&
561 sendmsg(fd, &msg, 0);
562 .EE
563 .in
564 .P
565 And the last example is about reading netlink message.
566 .P
567 .in +4n
568 .EX
569 int size;
570 /* 8192 to avoid message truncation on platforms with
571 page size > 4096 */
572 struct nlmsghdr buf[8192/sizeof(struct nlmsghdr)];
573 struct iovec iov = { buf, sizeof(buf) };
574 struct sockaddr_nl sa;
575 struct msghdr msg;
576 struct nlmsghdr *nh;
577 \&
578 msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
579 size = recvmsg(fd, &msg, 0);
580 \&
581 for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, size);
582 nh = NLMSG_NEXT (nh, size)) {
583 /* The end of multipart message */
584 if (nh\->nlmsg_type == NLMSG_DONE)
585 return;
586 \&
587 if (nh\->nlmsg_type == NLMSG_ERROR)
588 /* Do some error handling */
589 ...
590 \&
591 /* Continue with parsing payload */
592 ...
593 }
594 .EE
595 .in
596 .SH SEE ALSO
597 .BR cmsg (3),
598 .BR netlink (3),
599 .BR capabilities (7),
600 .BR rtnetlink (7),
601 .BR sock_diag (7)
602 .P
603 .UR ftp:\://ftp.inr.ac.ru\:/ip\-routing\:/iproute2*
604 information about libnetlink
605 .UE
606 .P
607 .UR http:\://www.infradead.org\:/\[ti]tgr\:/libnl/
608 information about libnl
609 .UE
610 .P
611 RFC 3549 "Linux Netlink as an IP Services Protocol"