]>
Commit | Line | Data |
---|---|---|
77117f4f MK |
1 | '\" t |
2 | .\" Don't change the first line, it tells man that tbl is needed. | |
3 | .\" This man page is Copyright (c) 1998 by Andi Kleen. Subject to the GPL. | |
4 | .\" Based on the original comments from Alexey Kuznetsov | |
5 | .\" Modified 2005-12-27 by Hasso Tepper <hasso@estpak.ee> | |
6 | .\" $Id: netlink.7,v 1.8 2000/06/22 13:23:00 ak Exp $ | |
608bf950 | 7 | .TH NETLINK 7 2012-08-05 "Linux" "Linux Programmer's Manual" |
77117f4f | 8 | .SH NAME |
7fac88a9 | 9 | netlink \- Communication between kernel and user space (AF_NETLINK) |
77117f4f MK |
10 | .SH SYNOPSIS |
11 | .nf | |
12 | .B #include <asm/types.h> | |
13 | .B #include <sys/socket.h> | |
14 | .B #include <linux/netlink.h> | |
15 | ||
d4c8c97c | 16 | .BI "netlink_socket = socket(AF_NETLINK, " socket_type ", " netlink_family ); |
77117f4f MK |
17 | .fi |
18 | .SH DESCRIPTION | |
19 | Netlink is used to transfer information between kernel and | |
7fac88a9 MK |
20 | user-space processes. |
21 | It consists of a standard sockets-based interface for user space | |
77117f4f MK |
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; this interface is not documented here | |
5fab2e7c | 26 | and is only provided for backward compatibility. |
77117f4f MK |
27 | |
28 | Netlink is a datagram-oriented service. | |
29 | Both | |
30 | .B SOCK_RAW | |
31 | and | |
32 | .B SOCK_DGRAM | |
33 | are valid values for | |
34 | .IR socket_type . | |
35 | However, the netlink protocol does not distinguish between datagram | |
36 | and raw sockets. | |
37 | ||
38 | .I netlink_family | |
39 | selects the kernel module or netlink group to communicate with. | |
40 | The currently assigned netlink families are: | |
41 | .TP | |
42 | .B NETLINK_ROUTE | |
43 | Receives routing and link updates and may be used to modify the routing | |
44 | tables (both IPv4 and IPv6), IP addresses, link parameters, | |
45 | neighbor setups, queueing disciplines, traffic classes and | |
46 | packet classifiers (see | |
47 | .BR rtnetlink (7)). | |
48 | .TP | |
49 | .B NETLINK_W1 | |
50 | Messages from 1-wire subsystem. | |
51 | .TP | |
52 | .B NETLINK_USERSOCK | |
53 | Reserved for user-mode socket protocols. | |
54 | .TP | |
55 | .B NETLINK_FIREWALL | |
7fac88a9 | 56 | Transport IPv4 packets from netfilter to user space. |
77117f4f MK |
57 | Used by |
58 | .I ip_queue | |
59 | kernel module. | |
60 | .TP | |
61 | .B NETLINK_INET_DIAG | |
62 | .\" FIXME More details on NETLINK_INET_DIAG needed. | |
63 | INET socket monitoring. | |
64 | .TP | |
65 | .B NETLINK_NFLOG | |
66 | Netfilter/iptables ULOG. | |
67 | .TP | |
68 | .B NETLINK_XFRM | |
69 | .\" FIXME More details on NETLINK_XFRM needed. | |
70 | IPsec. | |
71 | .TP | |
72 | .B NETLINK_SELINUX | |
73 | SELinux event notifications. | |
74 | .TP | |
75 | .B NETLINK_ISCSI | |
76 | .\" FIXME More details on NETLINK_ISCSI needed. | |
77 | Open-iSCSI. | |
78 | .TP | |
79 | .B NETLINK_AUDIT | |
80 | .\" FIXME More details on NETLINK_AUDIT needed. | |
81 | Auditing. | |
82 | .TP | |
83 | .B NETLINK_FIB_LOOKUP | |
84 | .\" FIXME More details on NETLINK_FIB_LOOKUP needed. | |
7fac88a9 | 85 | Access to FIB lookup from user space. |
77117f4f MK |
86 | .TP |
87 | .B NETLINK_CONNECTOR | |
88 | Kernel connector. | |
89 | See | |
90 | .I Documentation/connector/* | |
66a9882e | 91 | in the Linux kernel source tree for further information. |
77117f4f MK |
92 | .TP |
93 | .B NETLINK_NETFILTER | |
94 | .\" FIXME More details on NETLINK_NETFILTER needed. | |
95 | Netfilter subsystem. | |
96 | .TP | |
97 | .B NETLINK_IP6_FW | |
7fac88a9 | 98 | Transport IPv6 packets from netfilter to user space. |
77117f4f MK |
99 | Used by |
100 | .I ip6_queue | |
101 | kernel module. | |
102 | .TP | |
103 | .B NETLINK_DNRTMSG | |
104 | DECnet routing messages. | |
105 | .TP | |
106 | .B NETLINK_KOBJECT_UEVENT | |
107 | .\" FIXME More details on NETLINK_KOBJECT_UEVENT needed. | |
7fac88a9 | 108 | Kernel messages to user space. |
77117f4f MK |
109 | .TP |
110 | .B NETLINK_GENERIC | |
111 | Generic netlink family for simplified netlink usage. | |
112 | .PP | |
113 | Netlink messages consist of a byte stream with one or multiple | |
114 | .I nlmsghdr | |
115 | headers and associated payload. | |
116 | The byte stream should only be accessed with the standard | |
117 | .B NLMSG_* | |
118 | macros. | |
119 | See | |
120 | .BR netlink (3) | |
121 | for further information. | |
122 | ||
123 | In multipart messages (multiple | |
124 | .I nlmsghdr | |
125 | headers with associated payload in one byte stream) the first and all | |
126 | following headers have the | |
127 | .B NLM_F_MULTI | |
128 | flag set, except for the last header which has the type | |
129 | .BR NLMSG_DONE . | |
130 | ||
131 | After each | |
132 | .I nlmsghdr | |
133 | the payload follows. | |
134 | ||
135 | .in +4n | |
136 | .nf | |
137 | struct nlmsghdr { | |
138 | __u32 nlmsg_len; /* Length of message including header. */ | |
139 | __u16 nlmsg_type; /* Type of message content. */ | |
140 | __u16 nlmsg_flags; /* Additional flags. */ | |
141 | __u32 nlmsg_seq; /* Sequence number. */ | |
b8896b6e | 142 | __u32 nlmsg_pid; /* Sender port ID. */ |
77117f4f MK |
143 | }; |
144 | .fi | |
145 | .in | |
146 | ||
147 | .I nlmsg_type | |
148 | can be one of the standard message types: | |
149 | .B NLMSG_NOOP | |
150 | message is to be ignored, | |
151 | .B NLMSG_ERROR | |
152 | message signals an error and the payload contains an | |
153 | .I nlmsgerr | |
154 | structure, | |
155 | .B NLMSG_DONE | |
156 | message terminates a multipart message. | |
157 | ||
158 | .in +4n | |
159 | .nf | |
160 | struct nlmsgerr { | |
161 | int error; /* Negative errno or 0 for acknowledgements */ | |
162 | struct nlmsghdr msg; /* Message header that caused the error */ | |
163 | }; | |
164 | .fi | |
165 | .in | |
166 | ||
167 | A netlink family usually specifies more message types, see the | |
168 | appropriate manual pages for that, for example, | |
169 | .BR rtnetlink (7) | |
170 | for | |
171 | .BR NETLINK_ROUTE . | |
77117f4f MK |
172 | .TS |
173 | tab(:); | |
3421b826 | 174 | l s |
77117f4f | 175 | lB l. |
3421b826 BIG |
176 | Standard flag bits in \fInlmsg_flags\fP |
177 | _ | |
77117f4f MK |
178 | NLM_F_REQUEST:Must be set on all request messages. |
179 | NLM_F_MULTI:T{ | |
180 | The message is part of a multipart message terminated by | |
181 | .BR NLMSG_DONE . | |
182 | T} | |
183 | NLM_F_ACK:Request for an acknowledgment on success. | |
184 | NLM_F_ECHO:Echo this request. | |
185 | .TE | |
3421b826 BIG |
186 | .ad |
187 | .sp 1 | |
188 | .\" No right adustment for text blocks in tables | |
189 | .na | |
77117f4f MK |
190 | .TS |
191 | tab(:); | |
3421b826 | 192 | l s |
77117f4f | 193 | lB l. |
3421b826 BIG |
194 | Additional flag bits for GET requests |
195 | _ | |
77117f4f MK |
196 | NLM_F_ROOT:Return the complete table instead of a single entry. |
197 | NLM_F_MATCH:T{ | |
198 | Return all entries matching criteria passed in message content. | |
199 | Not implemented yet. | |
200 | T} | |
201 | .\" FIXME NLM_F_ATOMIC is not used any more? | |
202 | NLM_F_ATOMIC:Return an atomic snapshot of the table. | |
3421b826 BIG |
203 | NLM_F_DUMP:T{ |
204 | Convenience macro; equivalent to (NLM_F_ROOT|NLM_F_MATCH). | |
205 | T} | |
77117f4f | 206 | .TE |
3421b826 BIG |
207 | .ad |
208 | .sp 1 | |
77117f4f MK |
209 | Note that |
210 | .B NLM_F_ATOMIC | |
211 | requires the | |
212 | .B CAP_NET_ADMIN | |
213 | capability or an effective UID of 0. | |
214 | ||
3421b826 | 215 | .na |
77117f4f MK |
216 | .TS |
217 | tab(:); | |
3421b826 | 218 | l s |
77117f4f | 219 | lB l. |
3421b826 BIG |
220 | Additional flag bits for NEW requests |
221 | _ | |
77117f4f MK |
222 | NLM_F_REPLACE:Replace existing matching object. |
223 | NLM_F_EXCL:Don't replace if the object already exists. | |
224 | NLM_F_CREATE:Create object if it doesn't already exist. | |
225 | NLM_F_APPEND:Add to the end of the object list. | |
226 | .TE | |
3421b826 BIG |
227 | .ad |
228 | .sp 1 | |
77117f4f MK |
229 | .I nlmsg_seq |
230 | and | |
231 | .I nlmsg_pid | |
232 | are used to track messages. | |
233 | .I nlmsg_pid | |
234 | shows the origin of the message. | |
235 | Note that there isn't a 1:1 relationship between | |
236 | .I nlmsg_pid | |
237 | and the PID of the process if the message originated from a netlink | |
238 | socket. | |
239 | See the | |
240 | .B ADDRESS FORMATS | |
241 | section for further information. | |
242 | ||
243 | Both | |
244 | .I nlmsg_seq | |
245 | and | |
246 | .I nlmsg_pid | |
247 | .\" FIXME Explain more about nlmsg_seq and nlmsg_pid. | |
248 | are opaque to netlink core. | |
249 | ||
250 | Netlink is not a reliable protocol. | |
251 | It tries its best to deliver a message to its destination(s), | |
252 | but may drop messages when an out-of-memory condition or | |
253 | other error occurs. | |
254 | For reliable transfer the sender can request an | |
255 | acknowledgement from the receiver by setting the | |
256 | .B NLM_F_ACK | |
257 | flag. | |
258 | An acknowledgment is an | |
259 | .B NLMSG_ERROR | |
260 | packet with the error field set to 0. | |
261 | The application must generate acknowledgements for | |
262 | received messages itself. | |
263 | The kernel tries to send an | |
264 | .B NLMSG_ERROR | |
265 | message for every failed packet. | |
266 | A user process should follow this convention too. | |
267 | ||
268 | However, reliable transmissions from kernel to user are impossible | |
269 | in any case. | |
270 | The kernel can't send a netlink message if the socket buffer is full: | |
7fac88a9 | 271 | the message will be dropped and the kernel and the user-space process will |
77117f4f MK |
272 | no longer have the same view of kernel state. |
273 | It is up to the application to detect when this happens (via the | |
274 | .B ENOBUFS | |
275 | error returned by | |
276 | .BR recvmsg (2)) | |
277 | and resynchronize. | |
278 | .SS Address Formats | |
279 | The | |
280 | .I sockaddr_nl | |
281 | structure describes a netlink client in user space or in the kernel. | |
282 | A | |
283 | .I sockaddr_nl | |
284 | can be either unicast (only sent to one peer) or sent to | |
285 | netlink multicast groups | |
286 | .RI ( nl_groups | |
287 | not equal 0). | |
288 | ||
289 | .in +4n | |
290 | .nf | |
291 | struct sockaddr_nl { | |
292 | sa_family_t nl_family; /* AF_NETLINK */ | |
293 | unsigned short nl_pad; /* Zero. */ | |
b8896b6e | 294 | pid_t nl_pid; /* Port ID. */ |
77117f4f MK |
295 | __u32 nl_groups; /* Multicast groups mask. */ |
296 | }; | |
297 | .fi | |
298 | .in | |
299 | ||
300 | .I nl_pid | |
301 | is the unicast address of netlink socket. | |
302 | It's always 0 if the destination is in the kernel. | |
7fac88a9 | 303 | For a user-space process, |
77117f4f MK |
304 | .I nl_pid |
305 | is usually the PID of the process owning the destination socket. | |
306 | However, | |
307 | .I nl_pid | |
308 | identifies a netlink socket, not a process. | |
309 | If a process owns several netlink | |
310 | sockets, then | |
311 | .I nl_pid | |
312 | can only be equal to the process ID for at most one socket. | |
313 | There are two ways to assign | |
314 | .I nl_pid | |
315 | to a netlink socket. | |
316 | If the application sets | |
317 | .I nl_pid | |
318 | before calling | |
319 | .BR bind (2), | |
320 | then it is up to the application to make sure that | |
321 | .I nl_pid | |
322 | is unique. | |
323 | If the application sets it to 0, the kernel takes care of assigning it. | |
324 | The kernel assigns the process ID to the first netlink socket the process | |
325 | opens and assigns a unique | |
326 | .I nl_pid | |
327 | to every netlink socket that the process subsequently creates. | |
328 | ||
329 | .I nl_groups | |
330 | is a bit mask with every bit representing a netlink group number. | |
331 | Each netlink family has a set of 32 multicast groups. | |
332 | When | |
333 | .BR bind (2) | |
334 | is called on the socket, the | |
335 | .I nl_groups | |
336 | field in the | |
337 | .I sockaddr_nl | |
338 | should be set to a bit mask of the groups which it wishes to listen to. | |
339 | The default value for this field is zero which means that no multicasts | |
340 | will be received. | |
341 | A socket may multicast messages to any of the multicast groups by setting | |
342 | .I nl_groups | |
343 | to a bit mask of the groups it wishes to send to when it calls | |
344 | .BR sendmsg (2) | |
345 | or does a | |
346 | .BR connect (2). | |
347 | Only processes with an effective UID of 0 or the | |
348 | .B CAP_NET_ADMIN | |
349 | capability may send or listen to a netlink multicast group. | |
350 | Any replies to a message received for a multicast group should be | |
351 | sent back to the sending PID and the multicast group. | |
dfad7db9 JM |
352 | Some Linux kernel subsystems may additionally allow other users |
353 | to send and/or receive messages. | |
50b57418 MK |
354 | As at Linux 3.0, the |
355 | .BR NETLINK_KOBJECT_UEVENT , | |
dfad7db9 | 356 | .BR NETLINK_GENERIC , |
50b57418 MK |
357 | .BR NETLINK_ROUTE , |
358 | and | |
359 | .BR NETLINK_SELINUX | |
dfad7db9 JM |
360 | groups allow other users to receive messages. |
361 | No groups allow other users to send messages. | |
77117f4f MK |
362 | .SH VERSIONS |
363 | The socket interface to netlink is a new feature of Linux 2.2. | |
364 | ||
e929e68b | 365 | Linux 2.0 supported a more primitive device-based netlink interface |
77117f4f MK |
366 | (which is still available as a compatibility option). |
367 | This obsolete interface is not described here. | |
368 | ||
369 | NETLINK_SELINUX appeared in Linux 2.6.4. | |
370 | ||
371 | NETLINK_AUDIT appeared in Linux 2.6.6. | |
372 | ||
373 | NETLINK_KOBJECT_UEVENT appeared in Linux 2.6.10. | |
374 | ||
375 | NETLINK_W1 and NETLINK_FIB_LOOKUP appeared in Linux 2.6.13. | |
376 | ||
377 | NETLINK_INET_DIAG, NETLINK_CONNECTOR and NETLINK_NETFILTER appeared in | |
378 | Linux 2.6.14. | |
379 | ||
380 | NETLINK_GENERIC and NETLINK_ISCSI appeared in Linux 2.6.15. | |
381 | .SH NOTES | |
382 | It is often better to use netlink via | |
383 | .I libnetlink | |
384 | or | |
385 | .I libnl | |
386 | than via the low-level kernel interface. | |
387 | .SH BUGS | |
388 | This manual page is not complete. | |
389 | .SH EXAMPLE | |
390 | The following example creates a | |
391 | .B NETLINK_ROUTE | |
392 | netlink socket which will listen to the | |
393 | .B RTMGRP_LINK | |
394 | (network interface create/delete/up/down events) and | |
395 | .B RTMGRP_IPV4_IFADDR | |
396 | (IPv4 addresses add/delete events) multicast groups. | |
397 | ||
398 | .in +4n | |
399 | .nf | |
400 | struct sockaddr_nl sa; | |
401 | ||
402 | memset(&sa, 0, sizeof(sa)); | |
63042553 VN |
403 | sa.nl_family = AF_NETLINK; |
404 | sa.nl_groups = RTMGRP_LINK | RTMGRP_IPV4_IFADDR; | |
77117f4f MK |
405 | |
406 | fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE); | |
48011c24 | 407 | bind(fd, (struct sockaddr *) &sa, sizeof(sa)); |
77117f4f MK |
408 | .fi |
409 | .in | |
410 | ||
411 | The next example demonstrates how to send a netlink message to the | |
412 | kernel (pid 0). | |
413 | Note that application must take care of message sequence numbers | |
414 | in order to reliably track acknowledgements. | |
415 | ||
416 | .in +4n | |
417 | .nf | |
418 | struct nlmsghdr *nh; /* The nlmsghdr with payload to send. */ | |
419 | struct sockaddr_nl sa; | |
13f78d96 | 420 | struct iovec iov = { nh, nh\->nlmsg_len }; |
77117f4f MK |
421 | struct msghdr msg; |
422 | ||
13f78d96 | 423 | msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 }; |
77117f4f MK |
424 | memset(&sa, 0, sizeof(sa)); |
425 | sa.nl_family = AF_NETLINK; | |
426 | nh\->nlmsg_pid = 0; | |
427 | nh\->nlmsg_seq = ++sequence_number; | |
428 | /* Request an ack from kernel by setting NLM_F_ACK. */ | |
429 | nh\->nlmsg_flags |= NLM_F_ACK; | |
430 | ||
431 | sendmsg(fd, &msg, 0); | |
432 | .fi | |
433 | .in | |
434 | ||
435 | And the last example is about reading netlink message. | |
436 | ||
437 | .in +4n | |
438 | .nf | |
439 | int len; | |
440 | char buf[4096]; | |
441 | struct iovec iov = { buf, sizeof(buf) }; | |
442 | struct sockaddr_nl sa; | |
443 | struct msghdr msg; | |
444 | struct nlmsghdr *nh; | |
445 | ||
13f78d96 | 446 | msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 }; |
77117f4f MK |
447 | len = recvmsg(fd, &msg, 0); |
448 | ||
449 | for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len); | |
450 | nh = NLMSG_NEXT (nh, len)) { | |
451 | /* The end of multipart message. */ | |
452 | if (nh\->nlmsg_type == NLMSG_DONE) | |
453 | return; | |
454 | ||
455 | if (nh\->nlmsg_type == NLMSG_ERROR) | |
456 | /* Do some error handling. */ | |
457 | ... | |
458 | ||
459 | /* Continue with parsing payload. */ | |
460 | ... | |
461 | } | |
462 | .fi | |
463 | .in | |
464 | .SH "SEE ALSO" | |
465 | .BR cmsg (3), | |
466 | .BR netlink (3), | |
467 | .BR capabilities (7), | |
468 | .BR rtnetlink (7) | |
173fe7e7 | 469 | |
608bf950 SK |
470 | .UR ftp://ftp.inr.ac.ru\:/ip-routing\:/iproute2* |
471 | information about libnetlink | |
472 | .UE | |
173fe7e7 | 473 | |
608bf950 SK |
474 | .UR http://people.suug.ch\:/~tgr\:/libnl/ |
475 | information about libnl | |
476 | .UE | |
173fe7e7 | 477 | |
77117f4f | 478 | RFC 3549 "Linux Netlink as an IP Services Protocol" |