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