NETLINK(7) Linux Programmer's Manual NETLINK(7)
NAME
netlink, PF_NETLINK - Communication between kernel and
user.
SYNOPSIS
#include <asm/types.h>
#include <sys/socket.h>
#include <linux/netlink.h>
netlink_socket = socket(PF_NETLINK, socket_type, netlink_family);
DESCRIPTION
Netlink is used to transfer information between kernel
modules and user space processes. It consists of a stan-
dard sockets based interface for user processes and an
internal kernel API for kernel modules. The internal ker-
nel interface is not documented in this man page. Also
there is an obsolete netlink interface via netlink charac-
ter devices, this interface is not documented here and is
only provided for backwards compatibility.
Netlink is a datagram oriented service. Both SOCK_RAW and
SOCK_DGRAM are valid values for socket_type; however the
netlink protocol does not distinguish between datagram and
raw sockets.
netlink_family selects the kernel module or netlink group
to communicate with. The currently assigned netlink fami-
lies are:
NETLINK_ROUTE
Receives routing updates and may be used to modify
the IPv4 routing table (see rtnetlink(7)).
NETLINK_FIREWALL
Receives packets sent by the IPv4 firewall code.
NETLINK_ARPD
For managing the arp table in user space.
NETLINK_ROUTE6
Receives and sends IPv6 routing table updates.
NETLINK_IP6_FW
to receive packets that failed the IPv6 firewall
checks (currently not implemented).
NETLINK_TAPBASE...NETLINK_TAPBASE+15
are the instances of the ethertap device. Ethertap
is a pseudo network tunnel device that allows an
ethernet driver to be simulated from user space.
NETLINK_SKIP
Reserved for ENskip.
Linux Man Page 27 Apr 1999 1
NETLINK(7) Linux Programmer's Manual NETLINK(7)
NETLINK_USERSOCK
is reserved for future user space protocols.
Netlink messages consist of a byte stream with one or mul-
tiple nlmsghdr headers and associated payload. For multi-
part messages the first and all following headers have the
NLM_F_MULTI flag set, except for the last header which has
the type NLMSG_DONE. The byte stream should only be
accessed with the standard NLMSG_* macros, see netlink(3).
Netlink is not a reliable protocol. It tries its best to
deliver a message to its destination(s), but may drop mes-
sages when an out of memory condition or other error
occurs. For reliable transfer the sender can request an
acknowledgement from the receiver by setting the NLM_F_ACK
flag. An acknowledgment is an NLMSG_ERROR packet with the
error field set to 0. The application must generate acks
for received messages itself. The kernel tries to send an
NLMSG_ERROR message for every failed packet. A user pro-
cess should follow this convention too.
Each netlink family has a set of 32 multicast groups.
When bind(2) is called on the socket, the nl_groups field
in the sockaddr_nl should be set to a bitmask of the
groups which it wishes to listen to. The default value
for this field is zero which means that no multicasts will
be received. A socket may multicast messages to any of
the multicast groups by setting nl_groups to a bitmask of
the groups it wishes to send to when it calls sendmsg(2)
or does a connect(2). Only users with an effective uid of
0 or the CAP_NET_ADMIN capability may send or listen to a
netlink multicast group. Any replies to a message
received for a multicast group should be sent back to the
sending pid and the multicast group.
struct nlmsghdr
{
__u32 nlmsg_len; /* Length of message including header */
__u16 nlmsg_type; /* Message content */
__u16 nlmsg_flags;/* Additional flags */
__u32 nlmsg_seq; /* Sequence number */
__u32 nlmsg_pid; /* PID of the process that opened the socket */
};
struct nlmsgerr
{
int error; /* negative errno or 0 for acks. */
struct nlmsghdr msg; /* message header that caused the error */
};
After each nlmsghdr the payload follows. nlmsg_type can
be one of the standard message types: NLMSG_NOOP message
is to be ignored, NLMSG_ERROR the message signals an error
Linux Man Page 27 Apr 1999 2
NETLINK(7) Linux Programmer's Manual NETLINK(7)
and the payload contains a nlmsgerr structure, NLMSG_DONE
message terminates a multipart message,
A netlink family usually specifies more message types, see
the appropriate man pages for that, e.g. rtnetlink(7) for
NETLINK_ROUTE.
tab(:); l s l l. Standard Flag bits in nlmsg_flags
NLM_F_REQUEST:set on all request messages NLM_F_MULTI:T{
the message is part of a multipart message terminated by
NLMSG_DONE T} NLM_F_ACK:reply with an acknowledgment on
success NLM_F_ECHO:echo this request
tab(:); l s l l. Additional flag bits for GET requests
NLM_F_ROOT:Return the complete table instead of a single
entry. NLM_F_MATCH:Not implemented yet.
NLM_F_ATOMIC:Return an atomic snapshot of the table.
NLM_F_DUMP:not documented yet.
tab(:); l s l l. Additional flag bits for NEW requests
NLM_F_REPLACE:Override existing object. NLM_F_EXCL:Don't
replace if the object already exists. NLM_F_CREATE:Create
object if it doesn't already exist. NLM_F_APPEND:Add to
the end of the object list.
Note that NLM_F_ATOMIC requires CAP_NET_ADMIN or super
user rights.
ADDRESS FORMATS
The sockaddr_nl structure describes a netlink client in
user space or in the kernel. A sockaddr_nl can be either
unicast (only send to one peer) or send to netlink groups
(nl_groups not equal 0).
struct sockaddr_nl
{
sa_family_t nl_family; /* AF_NETLINK */
unsigned short nl_pad; /* zero */
pid_t nl_pid; /* process pid */
__u32 nl_groups; /* multicast groups mask */
};
nl_pid is the pid of the process owning the destination
socket, or 0 if the destination is in the kernel.
nl_groups is a bitmask with every bit representing a
netlink group number.
BUGS
This man page is not complete.
Linux Man Page 27 Apr 1999 3
NETLINK(7) Linux Programmer's Manual NETLINK(7)
NOTES
It is often better to use netlink via libnetlink than via
the low level kernel interface.
VERSIONS
The socket interface to netlink is a new feature of Linux
2.2
Linux 2.0 supported a more primitive device based netlink
interface (which is still available as a compatibility
option). This obsolete interface is not described here.
SEE ALSO
cmsg(3), rtnetlink(7), netlink(3).
ftp://ftp.inr.ac.ru/ip-routing/iproute2* for libnetlink
Linux Man Page 27 Apr 1999 4