1NETLINK(7) Linux Programmer's Manual NETLINK(7)
2
6 netlink - communication between kernel and user space (AF_NETLINK)
7
9 #include <asm/types.h>
10 #include <sys/socket.h>
11 #include <linux/netlink.h>
12 netlink_socket = socket(AF_NETLINK, socket_type, netlink_family);
14
16 Netlink is used to transfer information between kernel and user-space
17 processes. It consists of a standard sockets-based interface for user
18 space processes and an internal kernel API for kernel modules. The
19 internal kernel interface is not documented in this manual page. There
20 is also an obsolete netlink interface via netlink character devices;
21 this interface is not documented here and is provided only for backward
22 compatibility.
23 Netlink is a datagram-oriented service. Both SOCK_RAW and SOCK_DGRAM
25 are valid values for socket_type. However, the netlink protocol does
26 not distinguish between datagram and raw sockets.
27 netlink_family selects the kernel module or netlink group to communi‐
29 cate with. The currently assigned netlink families are:
30 NETLINK_ROUTE
32 Receives routing and link updates and may be used to modify the
33 routing tables (both IPv4 and IPv6), IP addresses, link parame‐
34 ters, neighbor setups, queueing disciplines, traffic classes and
35 packet classifiers (see rtnetlink(7)).
36 NETLINK_W1
38 Messages from 1-wire subsystem.
39 NETLINK_USERSOCK
41 Reserved for user-mode socket protocols.
42 NETLINK_FIREWALL
44 Transport IPv4 packets from netfilter to user space. Used by
45 ip_queue kernel module.
46 NETLINK_INET_DIAG
48 INET socket monitoring.
49 NETLINK_NFLOG
51 Netfilter/iptables ULOG.
52 NETLINK_XFRM
54 IPsec.
55 NETLINK_SELINUX
57 SELinux event notifications.
58 NETLINK_ISCSI
60 Open-iSCSI.
61 NETLINK_AUDIT
63 Auditing.
64 NETLINK_FIB_LOOKUP
66 Access to FIB lookup from user space.
67 NETLINK_CONNECTOR
69 Kernel connector. See Documentation/connector/* in the Linux
70 kernel source tree for further information.
71 NETLINK_NETFILTER
73 Netfilter subsystem.
74 NETLINK_IP6_FW
76 Transport IPv6 packets from netfilter to user space. Used by
77 ip6_queue kernel module.
78 NETLINK_DNRTMSG
80 DECnet routing messages.
81 NETLINK_KOBJECT_UEVENT
83 Kernel messages to user space.
84 NETLINK_GENERIC
86 Generic netlink family for simplified netlink usage.
87 Netlink messages consist of a byte stream with one or multiple nlmsghdr
89 headers and associated payload. The byte stream should be accessed
90 only with the standard NLMSG_* macros. See netlink(3) for further
91 information.
92 In multipart messages (multiple nlmsghdr headers with associated pay‐
94 load in one byte stream) the first and all following headers have the
95 NLM_F_MULTI flag set, except for the last header which has the type
96 NLMSG_DONE.
97 After each nlmsghdr the payload follows.
99 struct nlmsghdr {
101 __u32 nlmsg_len; /* Length of message including header. */
102 __u16 nlmsg_type; /* Type of message content. */
103 __u16 nlmsg_flags; /* Additional flags. */
104 __u32 nlmsg_seq; /* Sequence number. */
105 __u32 nlmsg_pid; /* Sender port ID. */
106 };
107 nlmsg_type can be one of the standard message types: NLMSG_NOOP message
109 is to be ignored, NLMSG_ERROR message signals an error and the payload
110 contains an nlmsgerr structure, NLMSG_DONE message terminates a multi‐
111 part message.
112 struct nlmsgerr {
114 int error; /* Negative errno or 0 for acknowledgements */
115 struct nlmsghdr msg; /* Message header that caused the error */
116 };
117 A netlink family usually specifies more message types, see the appro‐
119 priate manual pages for that, for example, rtnetlink(7) for
120 NETLINK_ROUTE.
121 Standard flag bits in nlmsg_flags
123 ──────────────────────────────────────────────────────────
124 NLM_F_REQUEST Must be set on all request messages.
125 NLM_F_MULTI The message is part of a multipart mes‐
126 sage terminated by NLMSG_DONE.
127 NLM_F_ACK Request for an acknowledgment on success.
128 NLM_F_ECHO Echo this request.
129 Additional flag bits for GET requests
132 ────────────────────────────────────────────────────────────────────
133 NLM_F_ROOT Return the complete table instead of a single entry.
134 NLM_F_MATCH Return all entries matching criteria passed in mes‐
136 sage content. Not implemented yet.
137 NLM_F_ATOMIC Return an atomic snapshot of the table.
138 NLM_F_DUMP Convenience macro; equivalent to
139 (NLM_F_ROOT|NLM_F_MATCH).
140 Note that NLM_F_ATOMIC requires the CAP_NET_ADMIN capability or an
142 effective UID of 0.
143 Additional flag bits for NEW requests
145 ────────────────────────────────────────────────────────────
146 NLM_F_REPLACE Replace existing matching object.
147 NLM_F_EXCL Don't replace if the object already exists.
148 NLM_F_CREATE Create object if it doesn't already exist.
149 NLM_F_APPEND Add to the end of the object list.
150 nlmsg_seq and nlmsg_pid are used to track messages. nlmsg_pid shows
152 the origin of the message. Note that there isn't a 1:1 relationship
153 between nlmsg_pid and the PID of the process if the message originated
154 from a netlink socket. See the ADDRESS FORMATS section for further
155 information.
156 Both nlmsg_seq and nlmsg_pid are opaque to netlink core.
158 Netlink is not a reliable protocol. It tries its best to deliver a
160 message to its destination(s), but may drop messages when an out-of-
161 memory condition or other error occurs. For reliable transfer the
162 sender can request an acknowledgement from the receiver by setting the
163 NLM_F_ACK flag. An acknowledgment is an NLMSG_ERROR packet with the
164 error field set to 0. The application must generate acknowledgements
165 for received messages itself. The kernel tries to send an NLMSG_ERROR
166 message for every failed packet. A user process should follow this
167 convention too.
168 However, reliable transmissions from kernel to user are impossible in
170 any case. The kernel can't send a netlink message if the socket buffer
171 is full: the message will be dropped and the kernel and the user-space
172 process will no longer have the same view of kernel state. It is up to
173 the application to detect when this happens (via the ENOBUFS error
174 returned by recvmsg(2)) and resynchronize.
175 Address formats
177 The sockaddr_nl structure describes a netlink client in user space or
178 in the kernel. A sockaddr_nl can be either unicast (only sent to one
179 peer) or sent to netlink multicast groups (nl_groups not equal 0).
180 struct sockaddr_nl {
182 sa_family_t nl_family; /* AF_NETLINK */
183 unsigned short nl_pad; /* Zero. */
184 pid_t nl_pid; /* Port ID. */
185 __u32 nl_groups; /* Multicast groups mask. */
186 };
187 nl_pid is the unicast address of netlink socket. It's always 0 if the
189 destination is in the kernel. For a user-space process, nl_pid is usu‐
190 ally the PID of the process owning the destination socket. However,
191 nl_pid identifies a netlink socket, not a process. If a process owns
192 several netlink sockets, then nl_pid can be equal to the process ID
193 only for at most one socket. There are two ways to assign nl_pid to a
194 netlink socket. If the application sets nl_pid before calling bind(2),
195 then it is up to the application to make sure that nl_pid is unique.
196 If the application sets it to 0, the kernel takes care of assigning it.
197 The kernel assigns the process ID to the first netlink socket the
198 process opens and assigns a unique nl_pid to every netlink socket that
199 the process subsequently creates.
200 nl_groups is a bit mask with every bit representing a netlink group
202 number. Each netlink family has a set of 32 multicast groups. When
203 bind(2) is called on the socket, the nl_groups field in the sockaddr_nl
204 should be set to a bit mask of the groups which it wishes to listen to.
205 The default value for this field is zero which means that no multicasts
206 will be received. A socket may multicast messages to any of the multi‐
207 cast groups by setting nl_groups to a bit mask of the groups it wishes
208 to send to when it calls sendmsg(2) or does a connect(2). Only pro‐
209 cesses with an effective UID of 0 or the CAP_NET_ADMIN capability may
210 send or listen to a netlink multicast group. Since Linux 2.6.13, mes‐
211 sages can't be broadcast to multiple groups. Any replies to a message
212 received for a multicast group should be sent back to the sending PID
213 and the multicast group. Some Linux kernel subsystems may additionally
214 allow other users to send and/or receive messages. As at Linux 3.0,
215 the NETLINK_KOBJECT_UEVENT, NETLINK_GENERIC, NETLINK_ROUTE, and
216 NETLINK_SELINUX groups allow other users to receive messages. No
217 groups allow other users to send messages.
218
220 The socket interface to netlink is a new feature of Linux 2.2.
221 Linux 2.0 supported a more primitive device-based netlink interface
223 (which is still available as a compatibility option). This obsolete
224 interface is not described here.
225 NETLINK_SELINUX appeared in Linux 2.6.4.
227 NETLINK_AUDIT appeared in Linux 2.6.6.
229 NETLINK_KOBJECT_UEVENT appeared in Linux 2.6.10.
231 NETLINK_W1 and NETLINK_FIB_LOOKUP appeared in Linux 2.6.13.
233 NETLINK_INET_DIAG, NETLINK_CONNECTOR and NETLINK_NETFILTER appeared in
235 Linux 2.6.14.
236 NETLINK_GENERIC and NETLINK_ISCSI appeared in Linux 2.6.15.
238
240 It is often better to use netlink via libnetlink or libnl than via the
241 low-level kernel interface.
242
244 This manual page is not complete.
245
247 The following example creates a NETLINK_ROUTE netlink socket which will
248 listen to the RTMGRP_LINK (network interface create/delete/up/down
249 events) and RTMGRP_IPV4_IFADDR (IPv4 addresses add/delete events) mul‐
250 ticast groups.
251 struct sockaddr_nl sa;
253 memset(&sa, 0, sizeof(sa));
255 sa.nl_family = AF_NETLINK;
256 sa.nl_groups = RTMGRP_LINK | RTMGRP_IPV4_IFADDR;
257 fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE);
259 bind(fd, (struct sockaddr *) &sa, sizeof(sa));
260 The next example demonstrates how to send a netlink message to the ker‐
262 nel (pid 0). Note that application must take care of message sequence
263 numbers in order to reliably track acknowledgements.
264 struct nlmsghdr *nh; /* The nlmsghdr with payload to send. */
266 struct sockaddr_nl sa;
267 struct iovec iov = { nh, nh->nlmsg_len };
268 struct msghdr msg;
269 msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
271 memset(&sa, 0, sizeof(sa));
272 sa.nl_family = AF_NETLINK;
273 nh->nlmsg_pid = 0;
274 nh->nlmsg_seq = ++sequence_number;
275 /* Request an ack from kernel by setting NLM_F_ACK. */
276 nh->nlmsg_flags |= NLM_F_ACK;
277 sendmsg(fd, &msg, 0);
279 And the last example is about reading netlink message.
281 int len;
283 char buf[4096];
284 struct iovec iov = { buf, sizeof(buf) };
285 struct sockaddr_nl sa;
286 struct msghdr msg;
287 struct nlmsghdr *nh;
288 msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
290 len = recvmsg(fd, &msg, 0);
291 for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len);
293 nh = NLMSG_NEXT (nh, len)) {
294 /* The end of multipart message. */
295 if (nh->nlmsg_type == NLMSG_DONE)
296 return;
297 if (nh->nlmsg_type == NLMSG_ERROR)
299 /* Do some error handling. */
300 ...
301 /* Continue with parsing payload. */
303 ...
304 }
305
307 cmsg(3), netlink(3), capabilities(7), rtnetlink(7)
308 information about libnetlink ⟨ftp://ftp.inr.ac.ru/ip-routing/iproute2*⟩
310 information about libnl ⟨http://people.suug.ch/~tgr/libnl/⟩
312 RFC 3549 "Linux Netlink as an IP Services Protocol"
314
316 This page is part of release 3.53 of the Linux man-pages project. A
317 description of the project, and information about reporting bugs, can
318 be found at http://www.kernel.org/doc/man-pages/.
319Linux 2013-03-15 NETLINK(7)