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