share/man/man4/netlink.4

   1 .\"
   2 .\" Copyright (C) 2022 Alexander Chernikov <melifaro@FreeBSD.org>.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd November 30, 2022
  28 .Dt NETLINK 4
  29 .Os
  30 .Sh NAME
  31 .Nm Netlink
  32 .Nd Kernel network configuration protocol
  33 .Sh SYNOPSIS
  34 .In netlink/netlink.h
  35 .In netlink/netlink_route.h
  36 .Ft int
  37 .Fn socket AF_NETLINK SOCK_RAW "int family"
  38 .Sh DESCRIPTION
  39 Netlink is a user-kernel message-based communication protocol primarily used
  40 for network stack configuration.
  41 Netlink is easily extendable and supports large dumps and event
  42 notifications, all via a single socket.
  43 The protocol is fully asynchronous, allowing one to issue and track multiple
  44 requests at once.
  45 Netlink consists of multiple families, which commonly group the commands
  46 belonging to the particular kernel subsystem.
  47 Currently, the supported families are:
  48 .Pp
  49 .Bd -literal -offset indent -compact
  50 NETLINK_ROUTE   network configuration,
  51 NETLINK_GENERIC "container" family
  52 .Ed
  53 .Pp
  54 The
  55 .Dv NETLINK_ROUTE
  56 family handles all interfaces, addresses, neighbors, routes, and VNETs
  57 configuration.
  58 More details can be found in
  59 .Xr rtnetlink 4 .
  60 The
  61 .Dv NETLINK_GENERIC
  62 family serves as a
  63 .Do container Dc ,
  64 allowing registering other families under the
  65 .Dv NETLINK_GENERIC
  66 umbrella.
  67 This approach allows using a single netlink socket to interact with
  68 multiple netlink families at once.
  69 More details can be found in
  70 .Xr genetlink 4 .
  71 .Pp
  72 Netlink has its own sockaddr structure:
  73 .Bd -literal
  74 struct sockaddr_nl {
  75         uint8_t         nl_len;         /* sizeof(sockaddr_nl) */
  76         sa_family_t     nl_family;      /* netlink family */
  77         uint16_t        nl_pad;         /* reserved, set to 0 */
  78         uint32_t        nl_pid;         /* automatically selected, set to 0 */
  79         uint32_t        nl_groups;      /* multicast groups mask to bind to */
  80 };
  81 .Ed
  82 .Pp
  83 Typically, filling this structure is not required for socket operations.
  84 It is presented here for completeness.
  85 .Sh PROTOCOL DESCRIPTION
  86 The protocol is message-based.
  87 Each message starts with the mandatory
  88 .Va nlmsghdr
  89 header, followed by the family-specific header and the list of
  90 type-length-value pairs (TLVs).
  91 TLVs can be nested.
  92 All headers and TLVS are padded to 4-byte boundaries.
  93 Each
  94 .Xr send 2 or
  95 .Xr recv 2
  96 system call may contain multiple messages.
  97 .Ss BASE HEADER
  98 .Bd -literal
  99 struct nlmsghdr {
 100         uint32_t nlmsg_len;   /* Length of message including header */
 101         uint16_t nlmsg_type;  /* Message type identifier */
 102         uint16_t nlmsg_flags; /* Flags (NLM_F_) */
 103         uint32_t nlmsg_seq;   /* Sequence number */
 104         uint32_t nlmsg_pid;   /* Sending process port ID */
 105 };
 106 .Ed
 107 .Pp
 108 The
 109 .Va nlmsg_len
 110 field stores the whole message length, in bytes, including the header.
 111 This length has to be rounded up to the nearest 4-byte boundary when
 112 iterating over messages.
 113 The
 114 .Va nlmsg_type
 115 field represents the command/request type.
 116 This value is family-specific.
 117 The list of supported commands can be found in the relevant family
 118 header file.
 119 .Va nlmsg_seq
 120 is a user-provided request identifier.
 121 An application can track the operation result using the
 122 .Dv NLMSG_ERROR
 123 messages and matching the
 124 .Va nlmsg_seq
 125 .
 126 The
 127 .Va nlmsg_pid
 128 field is the message sender id.
 129 This field is optional for userland.
 130 The kernel sender id is zero.
 131 The
 132 .Va nlmsg_flags
 133 field contains the message-specific flags.
 134 The following generic flags are defined:
 135 .Pp
 136 .Bd -literal -offset indent -compact
 137 NLM_F_REQUEST   Indicates that the message is an actual request to the kernel
 138 NLM_F_ACK       Request an explicit ACK message with an operation result
 139 .Ed
 140 .Pp
 141 The following generic flags are defined for the "GET" request types:
 142 .Pp
 143 .Bd -literal -offset indent -compact
 144 NLM_F_ROOT      Return the whole dataset
 145 NLM_F_MATCH     Return all entries matching the criteria
 146 .Ed
 147 These two flags are typically used together, aliased to
 148 .Dv NLM_F_DUMP
 149 .Pp
 150 The following generic flags are defined for the "NEW" request types:
 151 .Pp
 152 .Bd -literal -offset indent -compact
 153 NLM_F_CREATE    Create an object if none exists
 154 NLM_F_EXCL      Don't replace an object if it exists
 155 NLM_F_REPLACE   Replace an existing matching object
 156 NLM_F_APPEND    Append to an existing object
 157 .Ed
 158 .Pp
 159 The following generic flags are defined for the replies:
 160 .Pp
 161 .Bd -literal -offset indent -compact
 162 NLM_F_MULTI     Indicates that the message is part of the message group
 163 NLM_F_DUMP_INTR Indicates that the state dump was not completed
 164 NLM_F_DUMP_FILTERED     Indicates that the dump was filtered per request
 165 NLM_F_CAPPED    Indicates the original message was capped to its header
 166 NLM_F_ACK_TLVS  Indicates that extended ACK TLVs were included
 167 .Ed
 168 .Ss TLVs
 169 Most messages encode their attributes as type-length-value pairs (TLVs).
 170 The base TLV header:
 171 .Bd -literal
 172 struct nlattr {
 173         uint16_t nla_len;       /* Total attribute length */
 174         uint16_t nla_type;      /* Attribute type */
 175 };
 176 .Ed
 177 The TLV type
 178 .Pq Va nla_type
 179 scope is typically the message type or group within a family.
 180 For example, the
 181 .Dv RTN_MULTICAST
 182 type value is only valid for
 183 .Dv RTM_NEWROUTE
 184 ,
 185 .Dv RTM_DELROUTE
 186 and
 187 .Dv RTM_GETROUTE
 188 messages.
 189 TLVs can be nested; in that case internal TLVs may have their own sub-types.
 190 All TLVs are packed with 4-byte padding.
 191 .Ss CONTROL MESSAGES
 192 A number of generic control messages are reserved in each family.
 193 .Pp
 194 .Dv NLMSG_ERROR
 195 reports the operation result if requested, optionally followed by
 196 the metadata TLVs.
 197 The value of
 198 .Va nlmsg_seq
 199 is set to its value in the original messages, while
 200 .Va nlmsg_pid
 201 is set to the socket pid of the original socket.
 202 The operation result is reported via
 203 .Vt "struct nlmsgerr":
 204 .Bd -literal
 205 struct nlmsgerr {
 206         int     error;          /* Standard errno */
 207         struct  nlmsghdr msg;   /* Original message header */
 208 };
 209 .Ed
 210 If the
 211 .Dv NETLINK_CAP_ACK
 212 socket option is not set, the remainder of the original message will follow.
 213 If the
 214 .Dv NETLINK_EXT_ACK
 215 socket option is set, the kernel may add a
 216 .Dv NLMSGERR_ATTR_MSG
 217 string TLV with the textual error description, optionally followed by the
 218 .Dv NLMSGERR_ATTR_OFFS
 219 TLV, indicating the offset from the message start that triggered an error.
 220 If the operation reply is a multipart message, then no
 221 .Dv NLMSG_ERROR
 222 reply is generated, only a
 223 .Dv NLMSG_DONE
 224 message, closing multipart sequence.
 225 .Pp
 226 .Dv NLMSG_DONE
 227 indicates the end of the message group: typically, the end of the dump.
 228 It contains a single
 229 .Vt int
 230 field, describing the dump result as a standard errno value.
 231 .Sh SOCKET OPTIONS
 232 Netlink supports a number of custom socket options, which can be set with
 233 .Xr setsockopt 2
 234 with the
 235 .Dv SOL_NETLINK
 236 .Fa level :
 237 .Bl -tag -width indent
 238 .It Dv NETLINK_ADD_MEMBERSHIP
 239 Subscribes to the notifications for the specific group (int).
 240 .It Dv NETLINK_DROP_MEMBERSHIP
 241 Unsubscribes from the notifications for the specific group (int).
 242 .It Dv NETLINK_LIST_MEMBERSHIPS
 243 Lists the memberships as a bitmask.
 244 .It Dv NETLINK_CAP_ACK
 245 Instructs the kernel to send the original message header in the reply
 246 without the message body.
 247 .It Dv NETLINK_EXT_ACK
 248 Acknowledges ability to receive additional TLVs in the ACK message.
 249 .El
 250 .Pp
 251 Additionally, netlink overrides the following socket options from the
 252 .Dv SOL_SOCKET
 253 .Fa level :
 254 .Bl -tag -width indent
 255 .It Dv SO_RCVBUF
 256 Sets the maximum size of the socket receive buffer.
 257 If the caller has
 258 .Dv PRIV_NET_ROUTE
 259 permission, the value can exceed the currently-set
 260 .Va kern.ipc.maxsockbuf
 261 value.
 262 .El
 263 .Sh SYSCTL VARIABLES
 264 A set of
 265 .Xr sysctl 8
 266 variables is available to tweak run-time parameters:
 267 .Bl -tag -width indent
 268 .It Va net.netlink.sendspace
 269 Default send buffer for the netlink socket.
 270 Note that the socket sendspace has to be at least as long as the longest
 271 message that can be transmitted via this socket.
 272 .El
 273 .Bl -tag -width indent
 274 .It Va net.netlink.recvspace
 275 Default receive buffer for the netlink socket.
 276 Note that the socket recvspace has to be least as long as the longest
 277 message that can be received from this socket.
 278 .El
 279 .Bl -tag -width indent
 280 .It Va net.netlink.nl_maxsockbuf
 281 Maximum receive buffer for the netlink socket that can be set via
 282 .Dv SO_RCVBUF
 283 socket option.
 284 .El
 285 .Sh DEBUGGING
 286 Netlink implements per-functional-unit debugging, with different severities
 287 controllable via the
 288 .Va net.netlink.debug
 289 branch.
 290 These messages are logged in the kernel message buffer and can be seen in
 291 .Xr dmesg 8
 292 .
 293 The following severity levels are defined:
 294 .Bl -tag -width indent
 295 .It Dv LOG_DEBUG(7)
 296 Rare events or per-socket errors are reported here.
 297 This is the default level, not impacting production performance.
 298 .It Dv LOG_DEBUG2(8)
 299 Socket events such as groups memberships, privilege checks, commands and dumps
 300 are logged.
 301 This level does not incur significant performance overhead.
 302 .It Dv LOG_DEBUG3(9)
 303 All socket events, each dumped or modified entities are logged.
 304 Turning it on may result in significant performance overhead.
 305 .El
 306 .Sh ERRORS
 307 Netlink reports operation results, including errors and error metadata, by
 308 sending a
 309 .Dv NLMSG_ERROR
 310 message for each request message.
 311 The following errors can be returned:
 312 .Bl -tag -width Er
 313 .It Bq Er EPERM
 314 when the current privileges are insufficient to perform the required operation;
 315 .It Bo Er ENOBUFS Bc or Bo Er ENOMEM Bc
 316 when the system runs out of memory for
 317 an internal data structure;
 318 .It Bq Er ENOTSUP
 319 when the requested command is not supported by the family or
 320 the family is not supported;
 321 .It Bq Er EINVAL
 322 when some necessary TLVs are missing or invalid, detailed info
 323 may be provided in NLMSGERR_ATTR_MSG and NLMSGERR_ATTR_OFFS TLVs;
 324 .It Bq Er ENOENT
 325 when trying to delete a non-existent object.
 326 .Pp
 327 Additionally, a socket operation itself may fail with one of the errors
 328 specified in
 329 .Xr socket 2
 330 ,
 331 .Xr recv 2
 332 or
 333 .Xr send 2
 334 .
 335 .El
 336 .Sh SEE ALSO
 337 .Xr genetlink 4 ,
 338 .Xr rtnetlink 4
 339 .Rs
 340 .%A "J. Salim"
 341 .%A "H. Khosravi"
 342 .%A "A. Kleen"
 343 .%A "A. Kuznetsov"
 344 .%T "Linux Netlink as an IP Services Protocol"
 345 .%O "RFC 3549"
 346 .Re
 347 .Sh HISTORY
 348 The netlink protocol appeared in
 349 .Fx 13.2 .
 350 .Sh AUTHORS
 351 The netlink was implemented by
 352 .An -nosplit
 353 .An Alexander Chernikov Aq Mt melifaro@FreeBSD.org .
 354 It was derived from the Google Summer of Code 2021 project by
 355 .An Ng Peng Nam Sean .