diff options
Diffstat (limited to 'static/freebsd/man4/netlink.4 3.html')
| -rw-r--r-- | static/freebsd/man4/netlink.4 3.html | 307 |
1 files changed, 0 insertions, 307 deletions
diff --git a/static/freebsd/man4/netlink.4 3.html b/static/freebsd/man4/netlink.4 3.html deleted file mode 100644 index dbfb5498..00000000 --- a/static/freebsd/man4/netlink.4 3.html +++ /dev/null @@ -1,307 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">NETLINK(4)</td> - <td class="head-vol">Device Drivers Manual</td> - <td class="head-rtitle">NETLINK(4)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">Netlink</code> — <span class="Nd">Kernel - network configuration protocol</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">netlink/netlink.h</a>></code> - <br/> - <code class="In">#include - <<a class="In">netlink/netlink_route.h</a>></code></p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">socket</code>(<var class="Fa" style="white-space: nowrap;">AF_NETLINK</var>, - <var class="Fa" style="white-space: nowrap;">SOCK_RAW</var>, - <var class="Fa" style="white-space: nowrap;">int family</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">Netlink is a user-kernel message-based communication protocol - primarily used for network stack configuration. Netlink is easily extendable - and supports large dumps and event notifications, all via a single socket. - The protocol is fully asynchronous, allowing one to issue and track multiple - requests at once. Netlink consists of multiple families, which commonly - group the commands belonging to the particular kernel subsystem. Currently, - the supported families are:</p> -<p class="Pp"></p> -<div class="Bd Bd-indent Li"> -<pre>NETLINK_ROUTE network configuration, -NETLINK_GENERIC "container" family</pre> -</div> -<p class="Pp">The <code class="Dv">NETLINK_ROUTE</code> family handles all - interfaces, addresses, neighbors, routes, and VNETs configuration. More - details can be found in <a class="Xr">rtnetlink(4)</a>. The - <code class="Dv">NETLINK_GENERIC</code> family serves as a - “container”, allowing registering other families under the - <code class="Dv">NETLINK_GENERIC</code> umbrella. This approach allows using - a single netlink socket to interact with multiple netlink families at once. - More details can be found in <a class="Xr">genetlink(4)</a>.</p> -<p class="Pp">Netlink has its own sockaddr structure:</p> -<div class="Bd Pp Li"> -<pre>struct sockaddr_nl { - uint8_t nl_len; /* sizeof(sockaddr_nl) */ - sa_family_t nl_family; /* netlink family */ - uint16_t nl_pad; /* reserved, set to 0 */ - uint32_t nl_pid; /* automatically selected, set to 0 */ - uint32_t nl_groups; /* multicast groups mask to bind to */ -};</pre> -</div> -<p class="Pp">Typically, filling this structure is not required for socket - operations. It is presented here for completeness.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="PROTOCOL_DESCRIPTION"><a class="permalink" href="#PROTOCOL_DESCRIPTION">PROTOCOL - DESCRIPTION</a></h1> -<p class="Pp">The protocol is message-based. Each message starts with the - mandatory <var class="Va">nlmsghdr</var> header, followed by the - family-specific header and the list of type-length-value pairs (TLVs). TLVs - can be nested. All headers and TLVS are padded to 4-byte boundaries. Each - <a class="Xr">send(2)</a> or <a class="Xr">recv(2)</a> system call may - contain multiple messages.</p> -<section class="Ss"> -<h2 class="Ss" id="BASE_HEADER"><a class="permalink" href="#BASE_HEADER">BASE - HEADER</a></h2> -<div class="Bd Li"> -<pre>struct nlmsghdr { - uint32_t nlmsg_len; /* Length of message including header */ - uint16_t nlmsg_type; /* Message type identifier */ - uint16_t nlmsg_flags; /* Flags (NLM_F_) */ - uint32_t nlmsg_seq; /* Sequence number */ - uint32_t nlmsg_pid; /* Sending process port ID */ -};</pre> -</div> -<p class="Pp">The <var class="Va">nlmsg_len</var> field stores the whole message - length, in bytes, including the header. This length has to be rounded up to - the nearest 4-byte boundary when iterating over messages. The - <var class="Va">nlmsg_type</var> field represents the command/request type. - This value is family-specific. The list of supported commands can be found - in the relevant family header file. <var class="Va">nlmsg_seq</var> is a - user-provided request identifier. An application can track the operation - result using the <code class="Dv">NLMSG_ERROR</code> messages and matching - the <var class="Va">nlmsg_seq</var> The <var class="Va">nlmsg_pid</var> - field is the message sender id. This field is optional for userland. The - kernel sender id is zero. The <var class="Va">nlmsg_flags</var> field - contains the message-specific flags. The following generic flags are - defined:</p> -<p class="Pp"></p> -<div class="Bd Bd-indent Li"> -<pre>NLM_F_REQUEST Indicates that the message is an actual request to the kernel -NLM_F_ACK Request an explicit ACK message with an operation result</pre> -</div> -<p class="Pp">The following generic flags are defined for the "GET" - request types:</p> -<p class="Pp"></p> -<div class="Bd Bd-indent Li"> -<pre>NLM_F_ROOT Return the whole dataset -NLM_F_MATCH Return all entries matching the criteria</pre> -</div> -These two flags are typically used together, aliased to - <code class="Dv">NLM_F_DUMP</code> -<p class="Pp">The following generic flags are defined for the "NEW" - request types:</p> -<p class="Pp"></p> -<div class="Bd Bd-indent Li"> -<pre>NLM_F_CREATE Create an object if none exists -NLM_F_EXCL Don't replace an object if it exists -NLM_F_REPLACE Replace an existing matching object -NLM_F_APPEND Append to an existing object</pre> -</div> -<p class="Pp">The following generic flags are defined for the replies:</p> -<p class="Pp"></p> -<div class="Bd Bd-indent Li"> -<pre>NLM_F_MULTI Indicates that the message is part of the message group -NLM_F_DUMP_INTR Indicates that the state dump was not completed -NLM_F_DUMP_FILTERED Indicates that the dump was filtered per request -NLM_F_CAPPED Indicates the original message was capped to its header -NLM_F_ACK_TLVS Indicates that extended ACK TLVs were included</pre> -</div> -</section> -<section class="Ss"> -<h2 class="Ss" id="TLVs"><a class="permalink" href="#TLVs">TLVs</a></h2> -<p class="Pp">Most messages encode their attributes as type-length-value pairs - (TLVs). The base TLV header:</p> -<div class="Bd Pp Li"> -<pre>struct nlattr { - uint16_t nla_len; /* Total attribute length */ - uint16_t nla_type; /* Attribute type */ -};</pre> -</div> -The TLV type (<var class="Va">nla_type</var>) scope is typically the message - type or group within a family. For example, the - <code class="Dv">RTN_MULTICAST</code> type value is only valid for - <code class="Dv">RTM_NEWROUTE</code> , <code class="Dv">RTM_DELROUTE</code> - and <code class="Dv">RTM_GETROUTE</code> messages. TLVs can be nested; in that - case internal TLVs may have their own sub-types. All TLVs are packed with - 4-byte padding. -</section> -<section class="Ss"> -<h2 class="Ss" id="CONTROL_MESSAGES"><a class="permalink" href="#CONTROL_MESSAGES">CONTROL - MESSAGES</a></h2> -<p class="Pp">A number of generic control messages are reserved in each - family.</p> -<p class="Pp"><code class="Dv">NLMSG_ERROR</code> reports the operation result - if requested, optionally followed by the metadata TLVs. The value of - <var class="Va">nlmsg_seq</var> is set to its value in the original - messages, while <var class="Va">nlmsg_pid</var> is set to the socket pid of - the original socket. The operation result is reported via - <var class="Vt">struct nlmsgerr</var>:</p> -<div class="Bd Pp Li"> -<pre>struct nlmsgerr { - int error; /* Standard errno */ - struct nlmsghdr msg; /* Original message header */ -};</pre> -</div> -If the <code class="Dv">NETLINK_CAP_ACK</code> socket option is not set, the - remainder of the original message will follow. If the - <code class="Dv">NETLINK_EXT_ACK</code> socket option is set, the kernel may - add a <code class="Dv">NLMSGERR_ATTR_MSG</code> string TLV with the textual - error description, optionally followed by the - <code class="Dv">NLMSGERR_ATTR_OFFS</code> TLV, indicating the offset from the - message start that triggered an error. Some operations may return additional - metadata encapsulated in the <code class="Dv">NLMSGERR_ATTR_COOKIE</code> TLV. - The metadata format is specific to the operation. If the operation reply is a - multipart message, then no <code class="Dv">NLMSG_ERROR</code> reply is - generated, only a <code class="Dv">NLMSG_DONE</code> message, closing - multipart sequence. -<p class="Pp"><code class="Dv">NLMSG_DONE</code> indicates the end of the - message group: typically, the end of the dump. It contains a single - <var class="Vt">int</var> field, describing the dump result as a standard - errno value.</p> -</section> -</section> -<section class="Sh"> -<h1 class="Sh" id="SOCKET_OPTIONS"><a class="permalink" href="#SOCKET_OPTIONS">SOCKET - OPTIONS</a></h1> -<p class="Pp">Netlink supports a number of custom socket options, which can be - set with <a class="Xr">setsockopt(2)</a> with the - <code class="Dv">SOL_NETLINK</code> <var class="Fa">level</var>:</p> -<dl class="Bl-tag"> - <dt id="NETLINK_ADD_MEMBERSHIP"><a class="permalink" href="#NETLINK_ADD_MEMBERSHIP"><code class="Dv">NETLINK_ADD_MEMBERSHIP</code></a></dt> - <dd>Subscribes to the notifications for the specific group (int).</dd> - <dt id="NETLINK_DROP_MEMBERSHIP"><a class="permalink" href="#NETLINK_DROP_MEMBERSHIP"><code class="Dv">NETLINK_DROP_MEMBERSHIP</code></a></dt> - <dd>Unsubscribes from the notifications for the specific group (int).</dd> - <dt id="NETLINK_LIST_MEMBERSHIPS"><a class="permalink" href="#NETLINK_LIST_MEMBERSHIPS"><code class="Dv">NETLINK_LIST_MEMBERSHIPS</code></a></dt> - <dd>Lists the memberships as a bitmask.</dd> - <dt id="NETLINK_CAP_ACK"><a class="permalink" href="#NETLINK_CAP_ACK"><code class="Dv">NETLINK_CAP_ACK</code></a></dt> - <dd>Instructs the kernel to send the original message header in the reply - without the message body.</dd> - <dt id="NETLINK_EXT_ACK"><a class="permalink" href="#NETLINK_EXT_ACK"><code class="Dv">NETLINK_EXT_ACK</code></a></dt> - <dd>Acknowledges ability to receive additional TLVs in the ACK message.</dd> -</dl> -<p class="Pp">Additionally, netlink overrides the following socket options from - the <code class="Dv">SOL_SOCKET</code> <var class="Fa">level</var>:</p> -<dl class="Bl-tag"> - <dt id="SO_RCVBUF"><a class="permalink" href="#SO_RCVBUF"><code class="Dv">SO_RCVBUF</code></a></dt> - <dd>Sets the maximum size of the socket receive buffer. If the caller has - <code class="Dv">PRIV_NET_ROUTE</code> permission, the value can exceed - the currently-set <var class="Va">kern.ipc.maxsockbuf</var> value.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYSCTL_VARIABLES"><a class="permalink" href="#SYSCTL_VARIABLES">SYSCTL - VARIABLES</a></h1> -<p class="Pp">A set of <a class="Xr">sysctl(8)</a> variables is available to - tweak run-time parameters:</p> -<dl class="Bl-tag"> - <dt id="net.netlink.sendspace"><var class="Va">net.netlink.sendspace</var></dt> - <dd>Default send buffer for the netlink socket. Note that the socket sendspace - has to be at least as long as the longest message that can be transmitted - via this socket.</dd> -</dl> -<dl class="Bl-tag"> - <dt id="net.netlink.recvspace"><var class="Va">net.netlink.recvspace</var></dt> - <dd>Default receive buffer for the netlink socket. Note that the socket - recvspace has to be least as long as the longest message that can be - received from this socket.</dd> -</dl> -<dl class="Bl-tag"> - <dt id="net.netlink.nl_maxsockbuf"><var class="Va">net.netlink.nl_maxsockbuf</var></dt> - <dd>Maximum receive buffer for the netlink socket that can be set via - <code class="Dv">SO_RCVBUF</code> socket option.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="DEBUGGING"><a class="permalink" href="#DEBUGGING">DEBUGGING</a></h1> -<p class="Pp">Netlink implements per-functional-unit debugging, with different - severities controllable via the <var class="Va">net.netlink.debug</var> - branch. These messages are logged in the kernel message buffer and can be - seen in <a class="Xr">dmesg(8)</a> The following severity levels are - defined:</p> -<dl class="Bl-tag"> - <dt id="LOG_DEBUG(7)"><a class="permalink" href="#LOG_DEBUG(7)"><code class="Dv">LOG_DEBUG(7)</code></a></dt> - <dd>Rare events or per-socket errors are reported here. This is the default - level, not impacting production performance.</dd> - <dt id="LOG_DEBUG2(8)"><a class="permalink" href="#LOG_DEBUG2(8)"><code class="Dv">LOG_DEBUG2(8)</code></a></dt> - <dd>Socket events such as groups memberships, privilege checks, commands and - dumps are logged. This level does not incur significant performance - overhead.</dd> - <dt id="LOG_DEBUG3(9)"><a class="permalink" href="#LOG_DEBUG3(9)"><code class="Dv">LOG_DEBUG3(9)</code></a></dt> - <dd>All socket events, each dumped or modified entities are logged. Turning it - on may result in significant performance overhead.</dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="ERRORS"><a class="permalink" href="#ERRORS">ERRORS</a></h1> -<p class="Pp">Netlink reports operation results, including errors and error - metadata, by sending a <code class="Dv">NLMSG_ERROR</code> message for each - request message. The following errors can be returned:</p> -<dl class="Bl-tag"> - <dt id="EPERM">[<a class="permalink" href="#EPERM"><code class="Er">EPERM</code></a>]</dt> - <dd>when the current privileges are insufficient to perform the required - operation;</dd> - <dt>[<code class="Er">ENOBUFS</code>] or [<code class="Er">ENOMEM</code>]</dt> - <dd>when the system runs out of memory for an internal data structure;</dd> - <dt id="ENOTSUP">[<a class="permalink" href="#ENOTSUP"><code class="Er">ENOTSUP</code></a>]</dt> - <dd>when the requested command is not supported by the family or the family is - not supported;</dd> - <dt id="EINVAL">[<a class="permalink" href="#EINVAL"><code class="Er">EINVAL</code></a>]</dt> - <dd>when some necessary TLVs are missing or invalid, detailed info may be - provided in NLMSGERR_ATTR_MSG and NLMSGERR_ATTR_OFFS TLVs;</dd> - <dt id="ENOENT">[<a class="permalink" href="#ENOENT"><code class="Er">ENOENT</code></a>]</dt> - <dd>when trying to delete a non-existent object. - <p class="Pp">Additionally, a socket operation itself may fail with one of - the errors specified in <a class="Xr">socket(2)</a> , - <a class="Xr">recv(2)</a> or <a class="Xr">send(2)</a></p> - </dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">snl(3)</a>, <a class="Xr">genetlink(4)</a>, - <a class="Xr">rtnetlink(4)</a></p> -<p class="Pp"><cite class="Rs"><span class="RsA">J. Salim</span>, - <span class="RsA">H. Khosravi</span>, <span class="RsA">A. Kleen</span>, and - <span class="RsA">A. Kuznetsov</span>, <span class="RsT">Linux Netlink as an - IP Services Protocol</span>, <span class="RsO">RFC 3549</span>.</cite></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The netlink protocol appeared in <span class="Ux">FreeBSD - 13.2</span>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> -<p class="Pp">The netlink was implemented by <span class="An">Alexander - Chernikov</span> - <<a class="Mt" href="mailto:melifaro@FreeBSD.org">melifaro@FreeBSD.org</a>>. - It was derived from the Google Summer of Code 2021 project by - <span class="An">Ng Peng Nam Sean</span>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">November 30, 2022</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |