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