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