Debian Codegraph @

upstream/debian-trixie/man7/netlink.7

raw
1 '\" t
2 .\" This man page is Copyright (c) 1998 by Andi Kleen.
3 .\"
4 .\" SPDX-License-Identifier: GPL-1.0-or-later
5 .\"
6 .\" Based on the original comments from Alexey Kuznetsov
7 .\" Modified 2005-12-27 by Hasso Tepper <[email protected]>
8 .\" $Id: netlink.7,v 1.8 2000/06/22 13:23:00 ak Exp $
9 .TH netlink 7 2024-05-02 "Linux man-pages 6.9.1"
10 .SH NAME
11 netlink \- communication between kernel and user space (AF_NETLINK)
12 .SH SYNOPSIS
13 .nf
14 .B #include <asm/types.h>
15 .B #include <sys/socket.h>
16 .B #include <linux/netlink.h>
17 .P
18 .BI "netlink_socket = socket(AF_NETLINK, " socket_type ", " netlink_family );
19 .fi
20 .SH DESCRIPTION
21 Netlink is used to transfer information between the kernel and
22 user-space processes.
23 It consists of a standard sockets-based interface for user space
24 processes and an internal kernel API for kernel modules.
25 The internal kernel interface is not documented in this manual page.
26 There is also an obsolete netlink interface
27 via netlink character devices; this interface is not documented here
28 and is provided only for backward compatibility.
29 .P
30 Netlink is a datagram-oriented service.
31 Both
32 .B SOCK_RAW
33 and
34 .B SOCK_DGRAM
35 are valid values for
36 .IR socket_type .
37 However, the netlink protocol does not distinguish between datagram
38 and raw sockets.
39 .P
40 .I netlink_family
41 selects the kernel module or netlink group to communicate with.
42 The currently assigned netlink families are:
43 .TP
44 .B NETLINK_ROUTE
45 Receives routing and link updates and may be used to modify the routing
46 tables (both IPv4 and IPv6), IP addresses, link parameters,
47 neighbor setups, queueing disciplines, traffic classes, and
48 packet classifiers (see
49 .BR rtnetlink (7)).
50 .TP
51 .BR NETLINK_W1 " (Linux 2.6.13 to Linux 2.16.17)"
52 Messages from 1-wire subsystem.
53 .TP
54 .B NETLINK_USERSOCK
55 Reserved for user-mode socket protocols.
56 .TP
57 .BR NETLINK_FIREWALL " (up to and including Linux 3.4)"
58 .\" removed by commit d16cf20e2f2f13411eece7f7fb72c17d141c4a84
59 Transport IPv4 packets from netfilter to user space.
60 Used by
61 .I ip_queue
62 kernel module.
63 After a long period of being declared obsolete (in favor of the more advanced
64 .I nfnetlink_queue
65 feature),
66 .B NETLINK_FIREWALL
67 was removed in Linux 3.5.
68 .TP
69 .BR NETLINK_SOCK_DIAG " (since Linux 3.3)"
70 .\" commit 7f1fb60c4fc9fb29fbb406ac8c4cfb4e59e168d6
71 Query information about sockets of various protocol families from the kernel
72 (see
73 .BR sock_diag (7)).
74 .TP
75 .BR NETLINK_INET_DIAG " (since Linux 2.6.14)"
76 An obsolete synonym for
77 .BR NETLINK_SOCK_DIAG .
78 .TP
79 .BR NETLINK_NFLOG " (up to and including Linux 3.16)"
80 Netfilter/iptables ULOG.
81 .TP
82 .B NETLINK_XFRM
83 .\" FIXME More details on NETLINK_XFRM needed.
84 IPsec.
85 .TP
86 .BR NETLINK_SELINUX " (since Linux 2.6.4)"
87 SELinux event notifications.
88 .TP
89 .BR NETLINK_ISCSI " (since Linux 2.6.15)"
90 .\" FIXME More details on NETLINK_ISCSI needed.
91 Open-iSCSI.
92 .TP
93 .BR NETLINK_AUDIT " (since Linux 2.6.6)"
94 .\" FIXME More details on NETLINK_AUDIT needed.
95 Auditing.
96 .TP
97 .BR NETLINK_FIB_LOOKUP " (since Linux 2.6.13)"
98 .\" FIXME More details on NETLINK_FIB_LOOKUP needed.
99 Access to FIB lookup from user space.
100 .TP
101 .BR NETLINK_CONNECTOR " (since Linux 2.6.14)"
102 Kernel connector.
103 See
104 .I Documentation/driver\-api/connector.rst
105 (or
106 .I /Documentation/connector/connector.*
107 .\" commit baa293e9544bea71361950d071579f0e4d5713ed
108 in Linux 5.2 and earlier)
109 in the Linux kernel source tree for further information.
110 .TP
111 .BR NETLINK_NETFILTER " (since Linux 2.6.14)"
112 .\" FIXME More details on NETLINK_NETFILTER needed.
113 Netfilter subsystem.
114 .TP
115 .BR NETLINK_SCSITRANSPORT " (since Linux 2.6.19)"
116 .\" commit 84314fd4740ad73550c76dee4a9578979d84af48
117 .\" FIXME More details on NETLINK_SCSITRANSPORT needed.
118 SCSI Transports.
119 .TP
120 .BR NETLINK_RDMA " (since Linux 3.0)"
121 .\" commit b2cbae2c248776d81cc265ff7d48405b6a4cc463
122 .\" FIXME More details on NETLINK_RDMA needed.
123 Infiniband RDMA.
124 .TP
125 .BR NETLINK_IP6_FW " (up to and including Linux 3.4)"
126 Transport IPv6 packets from netfilter to user space.
127 Used by
128 .I ip6_queue
129 kernel module.
130 .TP
131 .B NETLINK_DNRTMSG
132 DECnet routing messages.
133 .TP
134 .BR NETLINK_KOBJECT_UEVENT " (since Linux 2.6.10)"
135 .\" FIXME More details on NETLINK_KOBJECT_UEVENT needed.
136 Kernel messages to user space.
137 .TP
138 .BR NETLINK_GENERIC " (since Linux 2.6.15)"
139 Generic netlink family for simplified netlink usage.
140 .TP
141 .BR NETLINK_CRYPTO " (since Linux 3.2)"
142 .\" commit a38f7907b926e4c6c7d389ad96cc38cec2e5a9e9
143 .\" Author: Steffen Klassert <[email protected]>
144 Netlink interface to request information about ciphers registered
145 with the kernel crypto API as well as allow configuration of the
146 kernel crypto API.
147 .P
148 Netlink messages consist of a byte stream with one or multiple
149 .I nlmsghdr
150 headers and associated payload.
151 The byte stream should be accessed only with the standard
152 .B NLMSG_*
153 macros.
154 See
155 .BR netlink (3)
156 for further information.
157 .P
158 In multipart messages (multiple
159 .I nlmsghdr
160 headers with associated payload in one byte stream) the first and all
161 following headers have the
162 .B NLM_F_MULTI
163 flag set, except for the last header which has the type
164 .BR NLMSG_DONE .
165 .P
166 After each
167 .I nlmsghdr
168 the payload follows.
169 .P
170 .in +4n
171 .EX
172 struct nlmsghdr {
173 __u32 nlmsg_len; /* Length of message including header */
174 __u16 nlmsg_type; /* Type of message content */
175 __u16 nlmsg_flags; /* Additional flags */
176 __u32 nlmsg_seq; /* Sequence number */
177 __u32 nlmsg_pid; /* Sender port ID */
178 };
179 .EE
180 .in
181 .P
182 .I nlmsg_type
183 can be one of the standard message types:
184 .B NLMSG_NOOP
185 message is to be ignored,
186 .B NLMSG_ERROR
187 message signals an error and the payload contains an
188 .I nlmsgerr
189 structure,
190 .B NLMSG_DONE
191 message terminates a multipart message.
192 Error messages get the
193 original request appended, unless the user requests to cap the
194 error message, and get extra error data if requested.
195 .P
196 .in +4n
197 .EX
198 struct nlmsgerr {
199 int error; /* Negative errno or 0 for acknowledgements */
200 struct nlmsghdr msg; /* Message header that caused the error */
201 /*
202 * followed by the message contents
203 * unless NETLINK_CAP_ACK was set
204 * or the ACK indicates success (error == 0).
205 * For example Generic Netlink message with attributes.
206 * message length is aligned with NLMSG_ALIGN()
207 */
208 /*
209 * followed by TLVs defined in enum nlmsgerr_attrs
210 * if NETLINK_EXT_ACK was set
211 */
212 };
213 .EE
214 .in
215 .P
216 A netlink family usually specifies more message types, see the
217 appropriate manual pages for that, for example,
218 .BR rtnetlink (7)
219 for
220 .BR NETLINK_ROUTE .
221 .TS
222 tab(:);
223 l s
224 lB lx.
225 Standard flag bits in \fInlmsg_flags\fP
226 _
227 NLM_F_REQUEST:T{
228 Must be set on all request messages.
229 T}
230 NLM_F_MULTI:T{
231 The message is part of a multipart message terminated by
232 .BR NLMSG_DONE .
233 T}
234 NLM_F_ACK:T{
235 Request for an acknowledgement on success.
236 T}
237 NLM_F_ECHO:T{
238 Echo this request.
239 T}
240 .TE
241 .\" No right adjustment for text blocks in tables
242 .TS
243 tab(:);
244 l s
245 lB lx.
246 Additional flag bits for GET requests
247 _
248 NLM_F_ROOT:T{
249 Return the complete table instead of a single entry.
250 T}
251 NLM_F_MATCH:T{
252 Return all entries matching criteria passed in message content.
253 Not implemented yet.
254 T}
255 NLM_F_ATOMIC:T{
256 Return an atomic snapshot of the table.
257 T}
258 NLM_F_DUMP:T{
259 Convenience macro; 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 len;
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 len = recvmsg(fd, &msg, 0);
580 \&
581 for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len);
582 nh = NLMSG_NEXT (nh, len)) {
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"