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