man7/netlink.7

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