1NETLINK(7) Linux Programmer's Manual NETLINK(7)
2
6 netlink - Communication between kernel and userspace (PF_NETLINK)
7
9 #include <asm/types.h>
10 #include <sys/socket.h>
11 #include <linux/netlink.h>
12 netlink_socket = socket(PF_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, neighbour setups, queueing disciplines, traffic classes
35 and 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, e.g. rtnetlink(7) for NETLINK_ROUTE.
120 Standard flag bits in nlmsg_flags
122 ---------------------------------
123 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
131 -------------------------------------
132 NLM_F_ROOT Return the complete table instead of a single entry.
134 NLM_F_MATCH Return all entries matching criteria passed in message
136 content. Not implemented yet.
137 NLM_F_ATOMIC Return an atomic snapshot of the table.
138 NLM_F_DUMP Convenience macro; equivalent to (NLM_F_ROOT|NLM_F_MATCH).
139 Note that NLM_F_ATOMIC requires the CAP_NET_ADMIN capability or an
141 effective UID of 0.
142 Additional flag bits for NEW requests
144 -------------------------------------
145 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 userspace
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 resynchronise.
175
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 bitmask with every bit representing a netlink group num‐
203 ber. 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 bitmask 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 bitmask 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
217 The following example creates a NETLINK_ROUTE netlink socket which will
218 listen to the RTMGRP_LINK (network interface create/delete/up/down
219 events) and RTMGRP_IPV4_IFADDR (IPv4 addresses add/delete events) mul‐
220 ticast groups.
221 struct sockaddr_nl sa;
223 memset (&sa, 0, sizeof(sa));
225 snl.nl_family = AF_NETLINK;
226 snl.nl_groups = RTMGRP_LINK | RTMGRP_IPV4_IFADDR;
227 fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE);
229 bind(fd, (struct sockaddr*)&sa, sizeof(sa));
230 The next example demonstrates how to send a netlink message to the ker‐
232 nel (pid 0). Note that application must take care of message sequence
233 numbers in order to reliably track acknowledgements.
234 struct nlmsghdr *nh; /* The nlmsghdr with payload to send. */
236 struct sockaddr_nl sa;
237 struct iovec iov = { (void *) nh, nh->nlmsg_len };
238 struct msghdr msg;
239 msg = { (void *)&sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
241 memset (&sa, 0, sizeof(sa));
242 sa.nl_family = AF_NETLINK;
243 nh->nlmsg_pid = 0;
244 nh->nlmsg_seq = ++sequence_number;
245 /* Request an ack from kernel by setting NLM_F_ACK. */
246 nh->nlmsg_flags |= NLM_F_ACK;
247 sendmsg (fd, &msg, 0);
249 And the last example is about reading netlink message.
251 int len;
253 char buf[4096];
254 struct iovec iov = { buf, sizeof(buf) };
255 struct sockaddr_nl sa;
256 struct msghdr msg;
257 struct nlmsghdr *nh;
258 msg = { (void *)&sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
260 len = recvmsg (fd, &msg, 0);
261 for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len);
263 nh = NLMSG_NEXT (nh, len)) {
264 /* The end of multipart message. */
265 if (nh->nlmsg_type == NLMSG_DONE)
266 return;
267 if (nh->nlmsg_type == NLMSG_ERROR)
269 /* Do some error handling. */
270 ...
271 /* Continue with parsing payload. */
273 ...
274 }
275
278 This manual page is not complete.
279
282 It is often better to use netlink via libnetlink or libnl than via the
283 low level kernel interface.
284
287 The socket interface to netlink is a new feature of Linux 2.2.
288 Linux 2.0 supported a more primitive device based netlink interface
290 (which is still available as a compatibility option). This obsolete
291 interface is not described here.
292 NETLINK_SELINUX appeared in Linux 2.6.4.
294 NETLINK_AUDIT appeared in Linux 2.6.6.
296 NETLINK_KOBJECT_UEVENT appeared in Linux 2.6.10.
298 NETLINK_W1 and NETLINK_FIB_LOOKUP appeared in Linux 2.6.13.
300 NETLINK_INET_DIAG, NETLINK_CONNECTOR and NETLINK_NETFILTER appeared in
302 Linux 2.6.14.
303 NETLINK_GENERIC and NETLINK_ISCSI appeared in Linux 2.6.15.
305
308 cmsg(3), netlink(3), capabilities(7), rtnetlink(7)
309 ftp://ftp.inr.ac.ru/ip-routing/iproute2* for information about lib‐
311 netlink.
312 http://people.suug.ch/~tgr/libnl/ for information about libnl.
314 RFC 3549 "Linux Netlink as an IP Services Protocol"
316Linux Manual Page 2005-12-27 NETLINK(7)