1NETLINK(7) Linux Programmer's Manual NETLINK(7)
2
6 netlink - Communication between kernel and userspace (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 userspace
17 processes. It consists of a standard sockets-based interface for
18 userspace 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 only provided for back‐
22 wards 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 userspace. 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 userspace.
67 NETLINK_CONNECTOR
69 Kernel connector. See Documentation/connector/* in the kernel
70 source for further information.
71 NETLINK_NETFILTER
73 Netfilter subsystem.
74 NETLINK_IP6_FW
76 Transport IPv6 packets from netfilter to userspace. Used by
77 ip6_queue kernel module.
78 NETLINK_DNRTMSG
80 DECnet routing messages.
81 NETLINK_KOBJECT_UEVENT
83 Kernel messages to userspace.
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 only be
90 accessed 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; /* PID of the sending process. */
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.
126 NLM_F_MULTI The message is part of a multipart mes‐
127 sage terminated by NLMSG_DONE.
128 NLM_F_ACK Request for an acknowledgment on success.
129 NLM_F_ECHO Echo this request.
130 Additional flag bits for GET requests
132 -------------------------------------
133 NLM_F_ROOT Return the complete table instead of a single entry.
136 NLM_F_MATCH Return all entries matching criteria passed in message
137 content. Not implemented yet.
138 NLM_F_ATOMIC Return an atomic snapshot of the table.
139 NLM_F_DUMP Convenience macro; equivalent to (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.
148 NLM_F_EXCL Don't replace if the object already exists.
149 NLM_F_CREATE Create object if it doesn't already exist.
150 NLM_F_APPEND Add to the end of the object list.
151 nlmsg_seq and nlmsg_pid are used to track messages. nlmsg_pid shows
153 the origin of the message. Note that there isn't a 1:1 relationship
154 between nlmsg_pid and the PID of the process if the message originated
155 from a netlink socket. See the ADDRESS FORMATS section for further
156 information.
157 Both nlmsg_seq and nlmsg_pid are opaque to netlink core.
159 Netlink is not a reliable protocol. It tries its best to deliver a
161 message to its destination(s), but may drop messages when an out-of-
162 memory condition or other error occurs. For reliable transfer the
163 sender can request an acknowledgement from the receiver by setting the
164 NLM_F_ACK flag. An acknowledgment is an NLMSG_ERROR packet with the
165 error field set to 0. The application must generate acknowledgements
166 for received messages itself. The kernel tries to send an NLMSG_ERROR
167 message for every failed packet. A user process should follow this
168 convention too.
169 However, reliable transmissions from kernel to user are impossible in
171 any case. The kernel can't send a netlink message if the socket buffer
172 is full: the message will be dropped and the kernel and the userspace
173 process will no longer have the same view of kernel state. It is up to
174 the application to detect when this happens (via the ENOBUFS error
175 returned by recvmsg(2)) and resynchronize.
176 Address Formats
178 The sockaddr_nl structure describes a netlink client in user space or
179 in the kernel. A sockaddr_nl can be either unicast (only sent to one
180 peer) or sent to netlink multicast groups (nl_groups not equal 0).
181 struct sockaddr_nl {
183 sa_family_t nl_family; /* AF_NETLINK */
184 unsigned short nl_pad; /* Zero. */
185 pid_t nl_pid; /* Process ID. */
186 __u32 nl_groups; /* Multicast groups mask. */
187 };
188 nl_pid is the unicast address of netlink socket. It's always 0 if the
190 destination is in the kernel. For a userspace process, nl_pid is usu‐
191 ally the PID of the process owning the destination socket. However,
192 nl_pid identifies a netlink socket, not a process. If a process owns
193 several netlink sockets, then nl_pid can only be equal to the process
194 ID for at most one socket. There are two ways to assign nl_pid to a
195 netlink socket. If the application sets nl_pid before calling bind(2),
196 then it is up to the application to make sure that nl_pid is unique.
197 If the application sets it to 0, the kernel takes care of assigning it.
198 The kernel assigns the process ID to the first netlink socket the
199 process opens and assigns a unique nl_pid to every netlink socket that
200 the process subsequently creates.
201 nl_groups is a bit mask with every bit representing a netlink group
203 number. Each netlink family has a set of 32 multicast groups. When
204 bind(2) is called on the socket, the nl_groups field in the sockaddr_nl
205 should be set to a bit mask of the groups which it wishes to listen to.
206 The default value for this field is zero which means that no multicasts
207 will be received. A socket may multicast messages to any of the multi‐
208 cast groups by setting nl_groups to a bit mask of the groups it wishes
209 to send to when it calls sendmsg(2) or does a connect(2). Only pro‐
210 cesses with an effective UID of 0 or the CAP_NET_ADMIN capability may
211 send or listen to a netlink multicast group. Any replies to a message
212 received for a multicast group should be sent back to the sending PID
213 and the multicast group.
214
216 The socket interface to netlink is a new feature of Linux 2.2.
217 Linux 2.0 supported a more primitive device based netlink interface
219 (which is still available as a compatibility option). This obsolete
220 interface is not described here.
221 NETLINK_SELINUX appeared in Linux 2.6.4.
223 NETLINK_AUDIT appeared in Linux 2.6.6.
225 NETLINK_KOBJECT_UEVENT appeared in Linux 2.6.10.
227 NETLINK_W1 and NETLINK_FIB_LOOKUP appeared in Linux 2.6.13.
229 NETLINK_INET_DIAG, NETLINK_CONNECTOR and NETLINK_NETFILTER appeared in
231 Linux 2.6.14.
232 NETLINK_GENERIC and NETLINK_ISCSI appeared in Linux 2.6.15.
234
236 It is often better to use netlink via libnetlink or libnl than via the
237 low-level kernel interface.
238
240 This manual page is not complete.
241
243 The following example creates a NETLINK_ROUTE netlink socket which will
244 listen to the RTMGRP_LINK (network interface create/delete/up/down
245 events) and RTMGRP_IPV4_IFADDR (IPv4 addresses add/delete events) mul‐
246 ticast groups.
247 struct sockaddr_nl sa;
249 memset(&sa, 0, sizeof(sa));
251 sa.nl_family = AF_NETLINK;
252 sa.nl_groups = RTMGRP_LINK | RTMGRP_IPV4_IFADDR;
253 fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE);
255 bind(fd, (struct sockaddr *) &sa, sizeof(sa));
256 The next example demonstrates how to send a netlink message to the ker‐
258 nel (pid 0). Note that application must take care of message sequence
259 numbers in order to reliably track acknowledgements.
260 struct nlmsghdr *nh; /* The nlmsghdr with payload to send. */
262 struct sockaddr_nl sa;
263 struct iovec iov = { (void *) nh, nh->nlmsg_len };
264 struct msghdr msg;
265 msg = { (void *)&sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
267 memset(&sa, 0, sizeof(sa));
268 sa.nl_family = AF_NETLINK;
269 nh->nlmsg_pid = 0;
270 nh->nlmsg_seq = ++sequence_number;
271 /* Request an ack from kernel by setting NLM_F_ACK. */
272 nh->nlmsg_flags |= NLM_F_ACK;
273 sendmsg(fd, &msg, 0);
275 And the last example is about reading netlink message.
277 int len;
279 char buf[4096];
280 struct iovec iov = { buf, sizeof(buf) };
281 struct sockaddr_nl sa;
282 struct msghdr msg;
283 struct nlmsghdr *nh;
284 msg = { (void *)&sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
286 len = recvmsg(fd, &msg, 0);
287 for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len);
289 nh = NLMSG_NEXT (nh, len)) {
290 /* The end of multipart message. */
291 if (nh->nlmsg_type == NLMSG_DONE)
292 return;
293 if (nh->nlmsg_type == NLMSG_ERROR)
295 /* Do some error handling. */
296 ...
297 /* Continue with parsing payload. */
299 ...
300 }
301
303 cmsg(3), netlink(3), capabilities(7), rtnetlink(7)
304 ftp://ftp.inr.ac.ru/ip-routing/iproute2* for information about lib‐
306 netlink.
307 http://people.suug.ch/~tgr/libnl/ for information about libnl.
309 RFC 3549 "Linux Netlink as an IP Services Protocol"
311
313 This page is part of release 3.25 of the Linux man-pages project. A
314 description of the project, and information about reporting bugs, can
315 be found at http://www.kernel.org/doc/man-pages/.
316Linux 2008-11-11 NETLINK(7)