SYNOPSIS

DESCRIPTION

Netlink is used to transfer information between kernel and
user-space processes.
It consists of a standard sockets-based interface for user space
processes and an internal kernel API for kernel modules.
The internal kernel interface is not documented in this manual page.
There is also an obsolete netlink interface
via netlink character devices; this interface is not documented here
and is provided only for backward 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 families are:

Transport IPv4 packets from netfilter to user space.
Used by
ip_queue
kernel module.

NETLINK_INET_DIAG

INET socket monitoring.

NETLINK_NFLOG

Netfilter/iptables ULOG.

NETLINK_XFRM

IPsec.

NETLINK_SELINUX

SELinux event notifications.

NETLINK_ISCSI

Open-iSCSI.

NETLINK_AUDIT

Auditing.

NETLINK_FIB_LOOKUP

Access to FIB lookup from user space.

NETLINK_CONNECTOR

Kernel connector.
See
Documentation/connector/*
in the Linux kernel source tree for further information.

NETLINK_NETFILTER

Netfilter subsystem.

NETLINK_IP6_FW

Transport IPv6 packets from netfilter to user space.
Used by
ip6_queue
kernel module.

NETLINK_DNRTMSG

DECnet routing messages.

NETLINK_KOBJECT_UEVENT

Kernel messages to user space.

NETLINK_GENERIC

Generic netlink family for simplified netlink usage.

Netlink messages consist of a byte stream with one or multiple
nlmsghdr
headers and associated payload.
The byte stream should be accessed only with the standard
NLMSG_*
macros.
See
netlink(3)
for further information.

In multipart messages (multiple
nlmsghdr
headers with associated payload in one byte stream) the first and all
following headers have the
NLM_F_MULTI
flag set, except for the last header which has the type
NLMSG_DONE.

nlmsg_type
can be one of the standard message types:
NLMSG_NOOP
message is to be ignored,
NLMSG_ERROR
message signals an error and the payload contains an
nlmsgerr
structure,
NLMSG_DONE
message terminates a multipart message.

Note that
NLM_F_ATOMIC
requires the
CAP_NET_ADMIN
capability or an effective UID of 0.

Additional flag bits for NEW requests

NLM_F_REPLACE

Replace existing matching 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.

nlmsg_seq
and
nlmsg_pid
are used to track messages.
nlmsg_pid
shows the origin of the message.
Note that there isn't a 1:1 relationship between
nlmsg_pid
and the PID of the process if the message originated from a netlink
socket.
See the
ADDRESS FORMATS
section for further information.

Both
nlmsg_seq
and
nlmsg_pid
are opaque to netlink core.

Netlink is not a reliable protocol.
It tries its best to deliver a message to its destination(s),
but may drop messages 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 acknowledgements for
received messages itself.
The kernel tries to send an
NLMSG_ERROR
message for every failed packet.
A user process should follow this convention too.

However, reliable transmissions from kernel to user are impossible
in any case.
The kernel can't send a netlink message if the socket buffer is full:
the message will be dropped and the kernel and the user-space process will
no longer have the same view of kernel state.
It is up to the application to detect when this happens (via the
ENOBUFS
error returned by
recvmsg(2))
and resynchronize.

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 sent to one peer) or sent to
netlink multicast groups
(nl_groups
not equal 0).

nl_pid
is the unicast address of netlink socket.
It's always 0 if the destination is in the kernel.
For a user-space process,
nl_pid
is usually the PID of the process owning the destination socket.
However,
nl_pid
identifies a netlink socket, not a process.
If a process owns several netlink
sockets, then
nl_pid
can be equal to the process ID only for at most one socket.
There are two ways to assign
nl_pid
to a netlink socket.
If the application sets
nl_pid
before calling
bind(2),
then it is up to the application to make sure that
nl_pid
is unique.
If the application sets it to 0, the kernel takes care of assigning it.
The kernel assigns the process ID to the first netlink socket the process
opens and assigns a unique
nl_pid
to every netlink socket that the process subsequently creates.

nl_groups
is a bit mask with every bit representing a netlink group number.
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 bit mask 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 bit mask of the groups it wishes to send to when it calls
sendmsg(2)
or does a
connect(2).
Only processes with an effective UID of 0 or the
CAP_NET_ADMIN
capability may send or listen to a netlink multicast group.
Since Linux 2.6.13,
messages can't be broadcast to multiple groups.
Any replies to a message received for a multicast group should be
sent back to the sending PID and the multicast group.
Some Linux kernel subsystems may additionally allow other users
to send and/or receive messages.
As at Linux 3.0, the
NETLINK_KOBJECT_UEVENT,
NETLINK_GENERIC,
NETLINK_ROUTE,
and
NETLINK_SELINUX
groups allow other users to receive messages.
No groups allow other users to send messages.

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.

NETLINK_SELINUX appeared in Linux 2.6.4.

NETLINK_AUDIT appeared in Linux 2.6.6.

NETLINK_KOBJECT_UEVENT appeared in Linux 2.6.10.

NETLINK_W1 and NETLINK_FIB_LOOKUP appeared in Linux 2.6.13.

NETLINK_INET_DIAG, NETLINK_CONNECTOR and NETLINK_NETFILTER appeared in
Linux 2.6.14.

NETLINK_GENERIC and NETLINK_ISCSI appeared in Linux 2.6.15.

NOTES

It is often better to use netlink via
libnetlink
or
libnl
than via the low-level kernel interface.

BUGS

This manual page is not complete.

EXAMPLE

The following example creates a
NETLINK_ROUTE
netlink socket which will listen to the
RTMGRP_LINK
(network interface create/delete/up/down events) and
RTMGRP_IPV4_IFADDR
(IPv4 addresses add/delete events) multicast groups.

SEE ALSO

COLOPHON

This page is part of release 3.74 of the Linux
man-pages
project.
A description of the project,
information about reporting bugs,
and the latest version of this page,
can be found at
http://www.kernel.org/doc/man-pages/.