|
Packit |
7cfc04 |
'\" t
|
|
Packit |
7cfc04 |
.\" This man page is Copyright (c) 1998 by Andi Kleen.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
|
|
Packit |
7cfc04 |
.\" Subject to the GPL.
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_END
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Based on the original comments from Alexey Kuznetsov
|
|
Packit |
7cfc04 |
.\" Modified 2005-12-27 by Hasso Tepper <hasso@estpak.ee>
|
|
Packit |
7cfc04 |
.\" $Id: netlink.7,v 1.8 2000/06/22 13:23:00 ak Exp $
|
|
Packit |
7cfc04 |
.TH NETLINK 7 2017-09-15 "Linux" "Linux Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
netlink \- communication between kernel and user space (AF_NETLINK)
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
.B #include <asm/types.h>
|
|
Packit |
7cfc04 |
.B #include <sys/socket.h>
|
|
Packit |
7cfc04 |
.B #include <linux/netlink.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "netlink_socket = socket(AF_NETLINK, " socket_type ", " netlink_family );
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
Netlink is used to transfer information between the kernel and
|
|
Packit |
7cfc04 |
user-space processes.
|
|
Packit |
7cfc04 |
It consists of a standard sockets-based interface for user space
|
|
Packit |
7cfc04 |
processes and an internal kernel API for kernel modules.
|
|
Packit |
7cfc04 |
The internal kernel interface is not documented in this manual page.
|
|
Packit |
7cfc04 |
There is also an obsolete netlink interface
|
|
Packit |
7cfc04 |
via netlink character devices; this interface is not documented here
|
|
Packit |
7cfc04 |
and is provided only for backward compatibility.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Netlink is a datagram-oriented service.
|
|
Packit |
7cfc04 |
Both
|
|
Packit |
7cfc04 |
.B SOCK_RAW
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.B SOCK_DGRAM
|
|
Packit |
7cfc04 |
are valid values for
|
|
Packit |
7cfc04 |
.IR socket_type .
|
|
Packit |
7cfc04 |
However, the netlink protocol does not distinguish between datagram
|
|
Packit |
7cfc04 |
and raw sockets.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.I netlink_family
|
|
Packit |
7cfc04 |
selects the kernel module or netlink group to communicate with.
|
|
Packit |
7cfc04 |
The currently assigned netlink families are:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_ROUTE
|
|
Packit |
7cfc04 |
Receives routing and link updates and may be used to modify the routing
|
|
Packit |
7cfc04 |
tables (both IPv4 and IPv6), IP addresses, link parameters,
|
|
Packit |
7cfc04 |
neighbor setups, queueing disciplines, traffic classes and
|
|
Packit |
7cfc04 |
packet classifiers (see
|
|
Packit |
7cfc04 |
.BR rtnetlink (7)).
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_W1 " (Linux 2.6.13 to 2.16.17)"
|
|
Packit |
7cfc04 |
Messages from 1-wire subsystem.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_USERSOCK
|
|
Packit |
7cfc04 |
Reserved for user-mode socket protocols.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_FIREWALL " (up to and including Linux 3.4)"
|
|
Packit |
7cfc04 |
.\" removed by commit d16cf20e2f2f13411eece7f7fb72c17d141c4a84
|
|
Packit |
7cfc04 |
Transport IPv4 packets from netfilter to user space.
|
|
Packit |
7cfc04 |
Used by
|
|
Packit |
7cfc04 |
.I ip_queue
|
|
Packit |
7cfc04 |
kernel module.
|
|
Packit |
7cfc04 |
After a long period of being declared obsolete (in favor of the more advanced
|
|
Packit |
7cfc04 |
.I nfnetlink_queue
|
|
Packit |
7cfc04 |
feature),
|
|
Packit |
7cfc04 |
.BR NETLINK_FIREWALL
|
|
Packit |
7cfc04 |
was removed in Linux 3.5.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_INET_DIAG " (since Linux 2.6.14)"
|
|
Packit |
7cfc04 |
Query information about sockets of various protocol families from the kernel
|
|
Packit |
7cfc04 |
(see
|
|
Packit |
7cfc04 |
.BR sock_diag (7)).
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_SOCK_DIAG " (since Linux 3.3)"
|
|
Packit |
7cfc04 |
.\" commit 7f1fb60c4fc9fb29fbb406ac8c4cfb4e59e168d6
|
|
Packit |
7cfc04 |
A synonym for
|
|
Packit |
7cfc04 |
.BR NETLINK_INET_DIAG .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_NFLOG " (up to and including Linux 3.16)"
|
|
Packit |
7cfc04 |
Netfilter/iptables ULOG.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_XFRM
|
|
Packit |
7cfc04 |
.\" FIXME More details on NETLINK_XFRM needed.
|
|
Packit |
7cfc04 |
IPsec.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_SELINUX " (since Linux 2.6.4)"
|
|
Packit |
7cfc04 |
SELinux event notifications.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_ISCSI " (since Linux 2.6.15)"
|
|
Packit |
7cfc04 |
.\" FIXME More details on NETLINK_ISCSI needed.
|
|
Packit |
7cfc04 |
Open-iSCSI.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_AUDIT " (since Linux 2.6.6)"
|
|
Packit |
7cfc04 |
.\" FIXME More details on NETLINK_AUDIT needed.
|
|
Packit |
7cfc04 |
Auditing.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_FIB_LOOKUP " (since Linux 2.6.13)"
|
|
Packit |
7cfc04 |
.\" FIXME More details on NETLINK_FIB_LOOKUP needed.
|
|
Packit |
7cfc04 |
Access to FIB lookup from user space.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_CONNECTOR " (since Linux 2.6.14)"
|
|
Packit |
7cfc04 |
Kernel connector.
|
|
Packit |
7cfc04 |
See
|
|
Packit |
7cfc04 |
.I Documentation/connector/*
|
|
Packit |
7cfc04 |
in the Linux kernel source tree for further information.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_NETFILTER " (since Linux 2.6.14)"
|
|
Packit |
7cfc04 |
.\" FIXME More details on NETLINK_NETFILTER needed.
|
|
Packit |
7cfc04 |
Netfilter subsystem.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_SCSITRANSPORT " (since Linux 2.6.19)"
|
|
Packit |
7cfc04 |
.\" commit 84314fd4740ad73550c76dee4a9578979d84af48
|
|
Packit |
7cfc04 |
.\" FIXME More details on NETLINK_SCSITRANSPORT needed.
|
|
Packit |
7cfc04 |
SCSI Transports.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_RDMA " (since Linux 3.0)"
|
|
Packit |
7cfc04 |
.\" commit b2cbae2c248776d81cc265ff7d48405b6a4cc463
|
|
Packit |
7cfc04 |
.\" FIXME More details on NETLINK_RDMA needed.
|
|
Packit |
7cfc04 |
Infiniband RDMA.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_IP6_FW " (up to and including Linux 3.4)"
|
|
Packit |
7cfc04 |
Transport IPv6 packets from netfilter to user space.
|
|
Packit |
7cfc04 |
Used by
|
|
Packit |
7cfc04 |
.I ip6_queue
|
|
Packit |
7cfc04 |
kernel module.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B NETLINK_DNRTMSG
|
|
Packit |
7cfc04 |
DECnet routing messages.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_KOBJECT_UEVENT " (since Linux 2.6.10)"
|
|
Packit |
7cfc04 |
.\" FIXME More details on NETLINK_KOBJECT_UEVENT needed.
|
|
Packit |
7cfc04 |
Kernel messages to user space.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_GENERIC " (since Linux 2.6.15)"
|
|
Packit |
7cfc04 |
Generic netlink family for simplified netlink usage.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_CRYPTO " (since Linux 3.2)"
|
|
Packit |
7cfc04 |
.\" commit a38f7907b926e4c6c7d389ad96cc38cec2e5a9e9
|
|
Packit |
7cfc04 |
.\" Author: Steffen Klassert <steffen.klassert@secunet.com>
|
|
Packit |
7cfc04 |
Netlink interface to request information about ciphers registered
|
|
Packit |
7cfc04 |
with the kernel crypto API as well as allow configuration of the
|
|
Packit |
7cfc04 |
kernel crypto API.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Netlink messages consist of a byte stream with one or multiple
|
|
Packit |
7cfc04 |
.I nlmsghdr
|
|
Packit |
7cfc04 |
headers and associated payload.
|
|
Packit |
7cfc04 |
The byte stream should be accessed only with the standard
|
|
Packit |
7cfc04 |
.B NLMSG_*
|
|
Packit |
7cfc04 |
macros.
|
|
Packit |
7cfc04 |
See
|
|
Packit |
7cfc04 |
.BR netlink (3)
|
|
Packit |
7cfc04 |
for further information.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
In multipart messages (multiple
|
|
Packit |
7cfc04 |
.I nlmsghdr
|
|
Packit |
7cfc04 |
headers with associated payload in one byte stream) the first and all
|
|
Packit |
7cfc04 |
following headers have the
|
|
Packit |
7cfc04 |
.B NLM_F_MULTI
|
|
Packit |
7cfc04 |
flag set, except for the last header which has the type
|
|
Packit |
7cfc04 |
.BR NLMSG_DONE .
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
After each
|
|
Packit |
7cfc04 |
.I nlmsghdr
|
|
Packit |
7cfc04 |
the payload follows.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
struct nlmsghdr {
|
|
Packit |
7cfc04 |
__u32 nlmsg_len; /* Length of message including header */
|
|
Packit |
7cfc04 |
__u16 nlmsg_type; /* Type of message content */
|
|
Packit |
7cfc04 |
__u16 nlmsg_flags; /* Additional flags */
|
|
Packit |
7cfc04 |
__u32 nlmsg_seq; /* Sequence number */
|
|
Packit |
7cfc04 |
__u32 nlmsg_pid; /* Sender port ID */
|
|
Packit |
7cfc04 |
};
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.I nlmsg_type
|
|
Packit |
7cfc04 |
can be one of the standard message types:
|
|
Packit |
7cfc04 |
.B NLMSG_NOOP
|
|
Packit |
7cfc04 |
message is to be ignored,
|
|
Packit |
7cfc04 |
.B NLMSG_ERROR
|
|
Packit |
7cfc04 |
message signals an error and the payload contains an
|
|
Packit |
7cfc04 |
.I nlmsgerr
|
|
Packit |
7cfc04 |
structure,
|
|
Packit |
7cfc04 |
.B NLMSG_DONE
|
|
Packit |
7cfc04 |
message terminates a multipart message.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
struct nlmsgerr {
|
|
Packit |
7cfc04 |
int error; /* Negative errno or 0 for acknowledgements */
|
|
Packit |
7cfc04 |
struct nlmsghdr msg; /* Message header that caused the error */
|
|
Packit |
7cfc04 |
};
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
A netlink family usually specifies more message types, see the
|
|
Packit |
7cfc04 |
appropriate manual pages for that, for example,
|
|
Packit |
7cfc04 |
.BR rtnetlink (7)
|
|
Packit |
7cfc04 |
for
|
|
Packit |
7cfc04 |
.BR NETLINK_ROUTE .
|
|
Packit |
7cfc04 |
.TS
|
|
Packit |
7cfc04 |
tab(:);
|
|
Packit |
7cfc04 |
l s
|
|
Packit |
7cfc04 |
lB l.
|
|
Packit |
7cfc04 |
Standard flag bits in \fInlmsg_flags\fP
|
|
Packit |
7cfc04 |
_
|
|
Packit |
7cfc04 |
NLM_F_REQUEST:Must be set on all request messages.
|
|
Packit |
7cfc04 |
NLM_F_MULTI:T{
|
|
Packit |
7cfc04 |
The message is part of a multipart message terminated by
|
|
Packit |
7cfc04 |
.BR NLMSG_DONE .
|
|
Packit |
7cfc04 |
T}
|
|
Packit |
7cfc04 |
NLM_F_ACK:Request for an acknowledgment on success.
|
|
Packit |
7cfc04 |
NLM_F_ECHO:Echo this request.
|
|
Packit |
7cfc04 |
.TE
|
|
Packit |
7cfc04 |
.\" No right adjustment for text blocks in tables
|
|
Packit |
7cfc04 |
.TS
|
|
Packit |
7cfc04 |
tab(:);
|
|
Packit |
7cfc04 |
l s
|
|
Packit |
7cfc04 |
lB l.
|
|
Packit |
7cfc04 |
Additional flag bits for GET requests
|
|
Packit |
7cfc04 |
_
|
|
Packit |
7cfc04 |
NLM_F_ROOT:Return the complete table instead of a single entry.
|
|
Packit |
7cfc04 |
NLM_F_MATCH:T{
|
|
Packit |
7cfc04 |
Return all entries matching criteria passed in message content.
|
|
Packit |
7cfc04 |
Not implemented yet.
|
|
Packit |
7cfc04 |
T}
|
|
Packit |
7cfc04 |
NLM_F_ATOMIC:Return an atomic snapshot of the table.
|
|
Packit |
7cfc04 |
NLM_F_DUMP:T{
|
|
Packit |
7cfc04 |
Convenience macro; equivalent to
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
(NLM_F_ROOT|NLM_F_MATCH).
|
|
Packit |
7cfc04 |
T}
|
|
Packit |
7cfc04 |
.TE
|
|
Packit |
7cfc04 |
.\" FIXME NLM_F_ATOMIC is not used anymore?
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Note that
|
|
Packit |
7cfc04 |
.B NLM_F_ATOMIC
|
|
Packit |
7cfc04 |
requires the
|
|
Packit |
7cfc04 |
.B CAP_NET_ADMIN
|
|
Packit |
7cfc04 |
capability or an effective UID of 0.
|
|
Packit |
7cfc04 |
.TS
|
|
Packit |
7cfc04 |
tab(:);
|
|
Packit |
7cfc04 |
l s
|
|
Packit |
7cfc04 |
lB l.
|
|
Packit |
7cfc04 |
Additional flag bits for NEW requests
|
|
Packit |
7cfc04 |
_
|
|
Packit |
7cfc04 |
NLM_F_REPLACE:Replace existing matching object.
|
|
Packit |
7cfc04 |
NLM_F_EXCL:Don't replace if the object already exists.
|
|
Packit |
7cfc04 |
NLM_F_CREATE:Create object if it doesn't already exist.
|
|
Packit |
7cfc04 |
NLM_F_APPEND:Add to the end of the object list.
|
|
Packit |
7cfc04 |
.TE
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.I nlmsg_seq
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.I nlmsg_pid
|
|
Packit |
7cfc04 |
are used to track messages.
|
|
Packit |
7cfc04 |
.I nlmsg_pid
|
|
Packit |
7cfc04 |
shows the origin of the message.
|
|
Packit |
7cfc04 |
Note that there isn't a 1:1 relationship between
|
|
Packit |
7cfc04 |
.I nlmsg_pid
|
|
Packit |
7cfc04 |
and the PID of the process if the message originated from a netlink
|
|
Packit |
7cfc04 |
socket.
|
|
Packit |
7cfc04 |
See the
|
|
Packit |
7cfc04 |
.B ADDRESS FORMATS
|
|
Packit |
7cfc04 |
section for further information.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Both
|
|
Packit |
7cfc04 |
.I nlmsg_seq
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.I nlmsg_pid
|
|
Packit |
7cfc04 |
.\" FIXME Explain more about nlmsg_seq and nlmsg_pid.
|
|
Packit |
7cfc04 |
are opaque to netlink core.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Netlink is not a reliable protocol.
|
|
Packit |
7cfc04 |
It tries its best to deliver a message to its destination(s),
|
|
Packit |
7cfc04 |
but may drop messages when an out-of-memory condition or
|
|
Packit |
7cfc04 |
other error occurs.
|
|
Packit |
7cfc04 |
For reliable transfer the sender can request an
|
|
Packit |
7cfc04 |
acknowledgement from the receiver by setting the
|
|
Packit |
7cfc04 |
.B NLM_F_ACK
|
|
Packit |
7cfc04 |
flag.
|
|
Packit |
7cfc04 |
An acknowledgment is an
|
|
Packit |
7cfc04 |
.B NLMSG_ERROR
|
|
Packit |
7cfc04 |
packet with the error field set to 0.
|
|
Packit |
7cfc04 |
The application must generate acknowledgements for
|
|
Packit |
7cfc04 |
received messages itself.
|
|
Packit |
7cfc04 |
The kernel tries to send an
|
|
Packit |
7cfc04 |
.B NLMSG_ERROR
|
|
Packit |
7cfc04 |
message for every failed packet.
|
|
Packit |
7cfc04 |
A user process should follow this convention too.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
However, reliable transmissions from kernel to user are impossible
|
|
Packit |
7cfc04 |
in any case.
|
|
Packit |
7cfc04 |
The kernel can't send a netlink message if the socket buffer is full:
|
|
Packit |
7cfc04 |
the message will be dropped and the kernel and the user-space process will
|
|
Packit |
7cfc04 |
no longer have the same view of kernel state.
|
|
Packit |
7cfc04 |
It is up to the application to detect when this happens (via the
|
|
Packit |
7cfc04 |
.B ENOBUFS
|
|
Packit |
7cfc04 |
error returned by
|
|
Packit |
7cfc04 |
.BR recvmsg (2))
|
|
Packit |
7cfc04 |
and resynchronize.
|
|
Packit |
7cfc04 |
.SS Address formats
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I sockaddr_nl
|
|
Packit |
7cfc04 |
structure describes a netlink client in user space or in the kernel.
|
|
Packit |
7cfc04 |
A
|
|
Packit |
7cfc04 |
.I sockaddr_nl
|
|
Packit |
7cfc04 |
can be either unicast (only sent to one peer) or sent to
|
|
Packit |
7cfc04 |
netlink multicast groups
|
|
Packit |
7cfc04 |
.RI ( nl_groups
|
|
Packit |
7cfc04 |
not equal 0).
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
struct sockaddr_nl {
|
|
Packit |
7cfc04 |
sa_family_t nl_family; /* AF_NETLINK */
|
|
Packit |
7cfc04 |
unsigned short nl_pad; /* Zero */
|
|
Packit |
7cfc04 |
pid_t nl_pid; /* Port ID */
|
|
Packit |
7cfc04 |
__u32 nl_groups; /* Multicast groups mask */
|
|
Packit |
7cfc04 |
};
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.I nl_pid
|
|
Packit |
7cfc04 |
is the unicast address of netlink socket.
|
|
Packit |
7cfc04 |
It's always 0 if the destination is in the kernel.
|
|
Packit |
7cfc04 |
For a user-space process,
|
|
Packit |
7cfc04 |
.I nl_pid
|
|
Packit |
7cfc04 |
is usually the PID of the process owning the destination socket.
|
|
Packit |
7cfc04 |
However,
|
|
Packit |
7cfc04 |
.I nl_pid
|
|
Packit |
7cfc04 |
identifies a netlink socket, not a process.
|
|
Packit |
7cfc04 |
If a process owns several netlink
|
|
Packit |
7cfc04 |
sockets, then
|
|
Packit |
7cfc04 |
.I nl_pid
|
|
Packit |
7cfc04 |
can be equal to the process ID only for at most one socket.
|
|
Packit |
7cfc04 |
There are two ways to assign
|
|
Packit |
7cfc04 |
.I nl_pid
|
|
Packit |
7cfc04 |
to a netlink socket.
|
|
Packit |
7cfc04 |
If the application sets
|
|
Packit |
7cfc04 |
.I nl_pid
|
|
Packit |
7cfc04 |
before calling
|
|
Packit |
7cfc04 |
.BR bind (2),
|
|
Packit |
7cfc04 |
then it is up to the application to make sure that
|
|
Packit |
7cfc04 |
.I nl_pid
|
|
Packit |
7cfc04 |
is unique.
|
|
Packit |
7cfc04 |
If the application sets it to 0, the kernel takes care of assigning it.
|
|
Packit |
7cfc04 |
The kernel assigns the process ID to the first netlink socket the process
|
|
Packit |
7cfc04 |
opens and assigns a unique
|
|
Packit |
7cfc04 |
.I nl_pid
|
|
Packit |
7cfc04 |
to every netlink socket that the process subsequently creates.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.I nl_groups
|
|
Packit |
7cfc04 |
is a bit mask with every bit representing a netlink group number.
|
|
Packit |
7cfc04 |
Each netlink family has a set of 32 multicast groups.
|
|
Packit |
7cfc04 |
When
|
|
Packit |
7cfc04 |
.BR bind (2)
|
|
Packit |
7cfc04 |
is called on the socket, the
|
|
Packit |
7cfc04 |
.I nl_groups
|
|
Packit |
7cfc04 |
field in the
|
|
Packit |
7cfc04 |
.I sockaddr_nl
|
|
Packit |
7cfc04 |
should be set to a bit mask of the groups which it wishes to listen to.
|
|
Packit |
7cfc04 |
The default value for this field is zero which means that no multicasts
|
|
Packit |
7cfc04 |
will be received.
|
|
Packit |
7cfc04 |
A socket may multicast messages to any of the multicast groups by setting
|
|
Packit |
7cfc04 |
.I nl_groups
|
|
Packit |
7cfc04 |
to a bit mask of the groups it wishes to send to when it calls
|
|
Packit |
7cfc04 |
.BR sendmsg (2)
|
|
Packit |
7cfc04 |
or does a
|
|
Packit |
7cfc04 |
.BR connect (2).
|
|
Packit |
7cfc04 |
Only processes with an effective UID of 0 or the
|
|
Packit |
7cfc04 |
.B CAP_NET_ADMIN
|
|
Packit |
7cfc04 |
capability may send or listen to a netlink multicast group.
|
|
Packit |
7cfc04 |
Since Linux 2.6.13,
|
|
Packit |
7cfc04 |
.\" commit d629b836d151d43332492651dd841d32e57ebe3b
|
|
Packit |
7cfc04 |
messages can't be broadcast to multiple groups.
|
|
Packit |
7cfc04 |
Any replies to a message received for a multicast group should be
|
|
Packit |
7cfc04 |
sent back to the sending PID and the multicast group.
|
|
Packit |
7cfc04 |
Some Linux kernel subsystems may additionally allow other users
|
|
Packit |
7cfc04 |
to send and/or receive messages.
|
|
Packit |
7cfc04 |
As at Linux 3.0, the
|
|
Packit |
7cfc04 |
.BR NETLINK_KOBJECT_UEVENT ,
|
|
Packit |
7cfc04 |
.BR NETLINK_GENERIC ,
|
|
Packit |
7cfc04 |
.BR NETLINK_ROUTE ,
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR NETLINK_SELINUX
|
|
Packit |
7cfc04 |
groups allow other users to receive messages.
|
|
Packit |
7cfc04 |
No groups allow other users to send messages.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.SS Socket options
|
|
Packit |
7cfc04 |
To set or get a netlink socket option, call
|
|
Packit |
7cfc04 |
.BR getsockopt (2)
|
|
Packit |
7cfc04 |
to read or
|
|
Packit |
7cfc04 |
.BR setsockopt (2)
|
|
Packit |
7cfc04 |
to write the option with the option level argument set to
|
|
Packit |
7cfc04 |
.BR SOL_NETLINK .
|
|
Packit |
7cfc04 |
Unless otherwise noted,
|
|
Packit |
7cfc04 |
.I optval
|
|
Packit |
7cfc04 |
is a pointer to an
|
|
Packit |
7cfc04 |
.IR int .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_PKTINFO " (since Linux 2.6.14)"
|
|
Packit |
7cfc04 |
.\" commit 9a4595bc7e67962f13232ee55a64e063062c3a99
|
|
Packit |
7cfc04 |
.\" Author: Patrick McHardy <kaber@trash.net>
|
|
Packit |
7cfc04 |
Enable
|
|
Packit |
7cfc04 |
.B nl_pktinfo
|
|
Packit |
7cfc04 |
control messages for received packets to get the extended
|
|
Packit |
7cfc04 |
destination group number.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_ADD_MEMBERSHIP ,\ NETLINK_DROP_MEMBERSHIP " (since Linux 2.6.14)"
|
|
Packit |
7cfc04 |
.\" commit 9a4595bc7e67962f13232ee55a64e063062c3a99
|
|
Packit |
7cfc04 |
.\" Author: Patrick McHardy <kaber@trash.net>
|
|
Packit |
7cfc04 |
Join/leave a group specified by
|
|
Packit |
7cfc04 |
.IR optval .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_LIST_MEMBERSHIPS " (since Linux 4.2)"
|
|
Packit |
7cfc04 |
.\" commit b42be38b2778eda2237fc759e55e3b698b05b315
|
|
Packit |
7cfc04 |
.\" Author: David Herrmann <dh.herrmann@gmail.com>
|
|
Packit |
7cfc04 |
Retrieve all groups a socket is a member of.
|
|
Packit |
7cfc04 |
.I optval
|
|
Packit |
7cfc04 |
is a pointer to
|
|
Packit |
7cfc04 |
.B __u32
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.I optlen
|
|
Packit |
7cfc04 |
is the size of the array.
|
|
Packit |
7cfc04 |
The array is filled with the full membership set of the
|
|
Packit |
7cfc04 |
socket, and the required array size is returned in
|
|
Packit |
7cfc04 |
.IR optlen .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_BROADCAST_ERROR " (since Linux 2.6.30)"
|
|
Packit |
7cfc04 |
.\" commit be0c22a46cfb79ab2342bb28fde99afa94ef868e
|
|
Packit |
7cfc04 |
.\" Author: Pablo Neira Ayuso <pablo@netfilter.org>
|
|
Packit |
7cfc04 |
When not set,
|
|
Packit |
7cfc04 |
.B netlink_broadcast()
|
|
Packit |
7cfc04 |
only reports
|
|
Packit |
7cfc04 |
.B ESRCH
|
|
Packit |
7cfc04 |
errors and silently ignore
|
|
Packit |
7cfc04 |
.B NOBUFS
|
|
Packit |
7cfc04 |
errors.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_NO_ENOBUFS " (since Linux 2.6.30)"
|
|
Packit |
7cfc04 |
.\" commit 38938bfe3489394e2eed5e40c9bb8f66a2ce1405
|
|
Packit |
7cfc04 |
.\" Author: Pablo Neira Ayuso <pablo@netfilter.org>
|
|
Packit |
7cfc04 |
This flag can be used by unicast and broadcast listeners to avoid receiving
|
|
Packit |
7cfc04 |
.B ENOBUFS
|
|
Packit |
7cfc04 |
errors.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_LISTEN_ALL_NSID " (since Linux 4.2)"
|
|
Packit |
7cfc04 |
.\" commit 59324cf35aba5336b611074028777838a963d03b
|
|
Packit |
7cfc04 |
.\" Author: Nicolas Dichtel <nicolas.dichtel@6wind.com>
|
|
Packit |
7cfc04 |
When set, this socket will receive netlink notifications from
|
|
Packit |
7cfc04 |
all network namespaces that have an
|
|
Packit |
7cfc04 |
.I nsid
|
|
Packit |
7cfc04 |
assigned into the network namespace where the socket has been opened.
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I nsid
|
|
Packit |
7cfc04 |
is sent to user space via an ancillary data.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR NETLINK_CAP_ACK " (since Linux 4.2)"
|
|
Packit |
7cfc04 |
.\" commit 0a6a3a23ea6efde079a5b77688541a98bf202721
|
|
Packit |
7cfc04 |
.\" Author: Christophe Ricard <christophe.ricard@gmail.com>
|
|
Packit |
7cfc04 |
The kernel may fail to allocate the necessary room for the acknowledgment
|
|
Packit |
7cfc04 |
message back to user space.
|
|
Packit |
7cfc04 |
This option trims off the payload of the original netlink message.
|
|
Packit |
7cfc04 |
The netlink message header is still included, so the user can guess from the
|
|
Packit |
7cfc04 |
sequence number which message triggered the acknowledgment.
|
|
Packit |
7cfc04 |
.SH VERSIONS
|
|
Packit |
7cfc04 |
The socket interface to netlink first appeared Linux 2.2.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Linux 2.0 supported a more primitive device-based netlink interface
|
|
Packit |
7cfc04 |
(which is still available as a compatibility option).
|
|
Packit |
7cfc04 |
This obsolete interface is not described here.
|
|
Packit |
7cfc04 |
.SH NOTES
|
|
Packit |
7cfc04 |
It is often better to use netlink via
|
|
Packit |
7cfc04 |
.I libnetlink
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.I libnl
|
|
Packit |
7cfc04 |
than via the low-level kernel interface.
|
|
Packit |
7cfc04 |
.SH BUGS
|
|
Packit |
7cfc04 |
This manual page is not complete.
|
|
Packit |
7cfc04 |
.SH EXAMPLE
|
|
Packit |
7cfc04 |
The following example creates a
|
|
Packit |
7cfc04 |
.B NETLINK_ROUTE
|
|
Packit |
7cfc04 |
netlink socket which will listen to the
|
|
Packit |
7cfc04 |
.B RTMGRP_LINK
|
|
Packit |
7cfc04 |
(network interface create/delete/up/down events) and
|
|
Packit |
7cfc04 |
.B RTMGRP_IPV4_IFADDR
|
|
Packit |
7cfc04 |
(IPv4 addresses add/delete events) multicast groups.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
struct sockaddr_nl sa;
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
memset(&sa, 0, sizeof(sa));
|
|
Packit |
7cfc04 |
sa.nl_family = AF_NETLINK;
|
|
Packit |
7cfc04 |
sa.nl_groups = RTMGRP_LINK | RTMGRP_IPV4_IFADDR;
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
fd = socket(AF_NETLINK, SOCK_RAW, NETLINK_ROUTE);
|
|
Packit |
7cfc04 |
bind(fd, (struct sockaddr *) &sa, sizeof(sa));
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The next example demonstrates how to send a netlink message to the
|
|
Packit |
7cfc04 |
kernel (pid 0).
|
|
Packit |
7cfc04 |
Note that the application must take care of message sequence numbers
|
|
Packit |
7cfc04 |
in order to reliably track acknowledgements.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
struct nlmsghdr *nh; /* The nlmsghdr with payload to send */
|
|
Packit |
7cfc04 |
struct sockaddr_nl sa;
|
|
Packit |
7cfc04 |
struct iovec iov = { nh, nh\->nlmsg_len };
|
|
Packit |
7cfc04 |
struct msghdr msg;
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
|
|
Packit |
7cfc04 |
memset(&sa, 0, sizeof(sa));
|
|
Packit |
7cfc04 |
sa.nl_family = AF_NETLINK;
|
|
Packit |
7cfc04 |
nh\->nlmsg_pid = 0;
|
|
Packit |
7cfc04 |
nh\->nlmsg_seq = ++sequence_number;
|
|
Packit |
7cfc04 |
/* Request an ack from kernel by setting NLM_F_ACK */
|
|
Packit |
7cfc04 |
nh\->nlmsg_flags |= NLM_F_ACK;
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
sendmsg(fd, &msg, 0);
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
And the last example is about reading netlink message.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
int len;
|
|
Packit |
7cfc04 |
char buf[8192]; /* 8192 to avoid message truncation on
|
|
Packit |
7cfc04 |
platforms with page size > 4096 */
|
|
Packit |
7cfc04 |
struct iovec iov = { buf, sizeof(buf) };
|
|
Packit |
7cfc04 |
struct sockaddr_nl sa;
|
|
Packit |
7cfc04 |
struct msghdr msg;
|
|
Packit |
7cfc04 |
struct nlmsghdr *nh;
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
msg = { &sa, sizeof(sa), &iov, 1, NULL, 0, 0 };
|
|
Packit |
7cfc04 |
len = recvmsg(fd, &msg, 0);
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
for (nh = (struct nlmsghdr *) buf; NLMSG_OK (nh, len);
|
|
Packit |
7cfc04 |
nh = NLMSG_NEXT (nh, len)) {
|
|
Packit |
7cfc04 |
/* The end of multipart message */
|
|
Packit |
7cfc04 |
if (nh\->nlmsg_type == NLMSG_DONE)
|
|
Packit |
7cfc04 |
return;
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
if (nh\->nlmsg_type == NLMSG_ERROR)
|
|
Packit |
7cfc04 |
/* Do some error handling */
|
|
Packit |
7cfc04 |
...
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
/* Continue with parsing payload */
|
|
Packit |
7cfc04 |
...
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.SH SEE ALSO
|
|
Packit |
7cfc04 |
.BR cmsg (3),
|
|
Packit |
7cfc04 |
.BR netlink (3),
|
|
Packit |
7cfc04 |
.BR capabilities (7),
|
|
Packit |
7cfc04 |
.BR rtnetlink (7),
|
|
Packit |
7cfc04 |
.BR sock_diag (7)
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.UR ftp://ftp.inr.ac.ru\:/ip\-routing\:/iproute2*
|
|
Packit |
7cfc04 |
information about libnetlink
|
|
Packit |
7cfc04 |
.UE
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.UR http://www.infradead.org\:/~tgr\:/libnl/
|
|
Packit |
7cfc04 |
information about libnl
|
|
Packit |
7cfc04 |
.UE
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
RFC 3549 "Linux Netlink as an IP Services Protocol"
|
|
Packit |
7cfc04 |
.SH COLOPHON
|
|
Packit |
7cfc04 |
This page is part of release 4.15 of the Linux
|
|
Packit |
7cfc04 |
.I man-pages
|
|
Packit |
7cfc04 |
project.
|
|
Packit |
7cfc04 |
A description of the project,
|
|
Packit |
7cfc04 |
information about reporting bugs,
|
|
Packit |
7cfc04 |
and the latest version of this page,
|
|
Packit |
7cfc04 |
can be found at
|
|
Packit |
7cfc04 |
\%https://www.kernel.org/doc/man\-pages/.
|