Changeset View
Standalone View
share/man/man4/netlink.4
- This file was added.
.\" | |||||||||||||||
.\" Copyright (C) 2022 Alexander Chernikov <melifaro@FreeBSD.org>. | |||||||||||||||
.\" | |||||||||||||||
.\" Redistribution and use in source and binary forms, with or without | |||||||||||||||
.\" modification, are permitted provided that the following conditions | |||||||||||||||
.\" are met: | |||||||||||||||
.\" 1. Redistributions of source code must retain the above copyright | |||||||||||||||
.\" notice(s), this list of conditions and the following disclaimer as | |||||||||||||||
.\" the first lines of this file unmodified other than the possible | |||||||||||||||
.\" addition of one or more copyright notices. | |||||||||||||||
imp: I don't think this is our standard wording starting with 'as the first'. It's been flagged as… | |||||||||||||||
emasteUnsubmitted Done Inline ActionsYeah, let's avoid introducing or proliferating non-standard license variants. emaste: Yeah, let's avoid introducing or proliferating non-standard license variants. | |||||||||||||||
.\" 2. Redistributions in binary form must reproduce the above copyright | |||||||||||||||
.\" notice(s), this list of conditions and the following disclaimer in the | |||||||||||||||
.\" documentation and/or other materials provided with the distribution. | |||||||||||||||
.\" | |||||||||||||||
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY | |||||||||||||||
.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED | |||||||||||||||
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE | |||||||||||||||
.\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY | |||||||||||||||
.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES | |||||||||||||||
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR | |||||||||||||||
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER | |||||||||||||||
.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |||||||||||||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |||||||||||||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH | |||||||||||||||
.\" DAMAGE. | |||||||||||||||
.\" | |||||||||||||||
.\" $FreeBSD$ | |||||||||||||||
.\" | |||||||||||||||
.Dd September 30, 2022 | |||||||||||||||
.Dt NETLINK 4 | |||||||||||||||
.Os | |||||||||||||||
.Sh NAME | |||||||||||||||
.Nm Netlink | |||||||||||||||
.Nd Kernel network configuration protocol | |||||||||||||||
.Sh SYNOPSIS | |||||||||||||||
.In netlink/netlink.h | |||||||||||||||
.In netlink/netlink_route.h | |||||||||||||||
.Ft int | |||||||||||||||
.Fn socket AF_NETLINK SOCK_DGRAM int family | |||||||||||||||
.Sh DESCRIPTION | |||||||||||||||
The | |||||||||||||||
Done Inline ActionsDon't use .Tn, it's deprecated (see mdoc(7)). bcr's "mandoc -T lint" comment is also applicable here. pauamma_gundo.com: Don't use .Tn, it's deprecated (see mdoc(7)). bcr's "mandoc -T lint" comment is also applicable… | |||||||||||||||
Done Inline Actions
What should I use instead (if any)? melifaro: > Don't use .Tn, it's deprecated (see mdoc(7)). bcr's "mandoc -T lint" comment is also… | |||||||||||||||
Done Inline ActionsShort answer: nothing [pauamma@gadfly] ~/FreeBSD/src% git grep -E 'Intel|AMD|Linux' | grep -E '\.[1-9]:' | grep -Ev '^contrib/' | wc -l 1382 [pauamma@gadfly] ~/FreeBSD/src% git grep -E '\.Tn +(Intel|AMD|Linux)' | grep -E '\.[1-9]:' | grep -Ev '^contrib/' | wc -l 133 Using 3 common trademarked names: points to .Tn being the exception and nothing the overwhelming majority. mdoc(7) says this about .Tn:
And https://docs.freebsd.org/en/books/fdp-primer/manual-pages/#manual-pages-markup recommends not using those:
pauamma_gundo.com: Short answer: nothing
```
[pauamma@gadfly] ~/FreeBSD/src% git grep -E 'Intel|AMD|Linux' | grep… | |||||||||||||||
.Tn Netlink | |||||||||||||||
is a user-kernel message-based communication protocol primarily used for the | |||||||||||||||
network stack configuration. | |||||||||||||||
.Tn Netlink | |||||||||||||||
is easily extendable and provides support for large dumps and event | |||||||||||||||
notifications, all via a single socket. | |||||||||||||||
The protocol is fully asynchronous, allowing to issue and track multiple | |||||||||||||||
Done Inline ActionsYou need a line break after each sentence stop. bcr: You need a line break after each sentence stop. | |||||||||||||||
requests at once. | |||||||||||||||
Done Inline ActionsWhy "Netlink" here and "The Netlink" above? pauamma_gundo.com: Why "Netlink" here and "The Netlink" above? | |||||||||||||||
.Tn Netlink | |||||||||||||||
consists of multiple families, which commonly group the commands belonging | |||||||||||||||
to the particular kernel subsystem. | |||||||||||||||
Currently, the supported families are: | |||||||||||||||
Done Inline ActionsSame here, line break after sentence stop. bcr: Same here, line break after sentence stop. | |||||||||||||||
.Pp | |||||||||||||||
.Bd -literal -offset indent -compact | |||||||||||||||
NETLINK_ROUTE network configuration, | |||||||||||||||
NETLINK_GENERIC "container" family | |||||||||||||||
.Ed | |||||||||||||||
.Pp | |||||||||||||||
The | |||||||||||||||
.Dv NETLINK_ROUTE | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
family handles all interfaces, addresses, neighrors, routes and VNETs | |||||||||||||||
configuration. | |||||||||||||||
More details can be found in | |||||||||||||||
.Xr rtnetlink 4 | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
page. | |||||||||||||||
The | |||||||||||||||
.Dv NETLINK_GENERIC | |||||||||||||||
Done Inline Actions
Alternative: The .Dv NETLINK_GENERIC family serves as a .Do container Dc , allowing registering other families under the pauamma_gundo.com: Alternative:
```
The
.Dv NETLINK_GENERIC
family serves as a
.Do container Dc ,
allowing… | |||||||||||||||
serves as a "container" family, allowing to register other families under | |||||||||||||||
.Dv NETLINK_GENERIC | |||||||||||||||
umbrella. | |||||||||||||||
Done Inline ActionsSame here, line break after sentence stop. bcr: Same here, line break after sentence stop.
| |||||||||||||||
This approach allows to use single netlink socket to interact with | |||||||||||||||
multiple netlink families at once. | |||||||||||||||
More details can be found in | |||||||||||||||
.Xr genetlink 4 | |||||||||||||||
Done Inline Actions
Does that page already exist? pauamma_gundo.com: Does that page already exist? | |||||||||||||||
page. | |||||||||||||||
.Pp | |||||||||||||||
Done Inline ActionsThere seems to be more the-less "Netlink" instances than "The Netlink", so settle on the former? pauamma_gundo.com: There seems to be more the-less "Netlink" instances than "The Netlink", so settle on the former? | |||||||||||||||
.Tn Netlink has its own sockaddr structure: | |||||||||||||||
.Bd -literal | |||||||||||||||
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 */ | |||||||||||||||
}; | |||||||||||||||
.Ed | |||||||||||||||
.Pp | |||||||||||||||
Normally, filling of this structure is not required for the socket operations. | |||||||||||||||
Done Inline ActionsSame here, line break after sentence stop. bcr: Same here, line break after sentence stop.
| |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
It is presented here for the sake of completness. | |||||||||||||||
.Sh PROTOCOL DESCRIPTION | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
Protocol is message-based. | |||||||||||||||
Each message starts with the mandatory | |||||||||||||||
Done Inline ActionsUnless .Vt only works together with .Va, maybe use it instead of .Fa, since nlmsghdr seems to be a type? (Or am I misreading that?) pauamma_gundo.com: Unless .Vt only works together with .Va, maybe use it instead of .Fa, since nlmsghdr seems to… | |||||||||||||||
.Fa nlmsghdr | |||||||||||||||
header, followed by the family-specific header and the list of | |||||||||||||||
type-length-value pairs (TLVs). | |||||||||||||||
TLVs can be nested. | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
All headers and TLVS are 32-bit-padded. | |||||||||||||||
Each | |||||||||||||||
.Xr send 2 or | |||||||||||||||
.Xr recv 2 | |||||||||||||||
system call may contain multiple messages. | |||||||||||||||
.Ss BASE HEADER | |||||||||||||||
.Bd -literal | |||||||||||||||
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 */ | |||||||||||||||
}; | |||||||||||||||
Done Inline ActionsLine break after sentence stop. bcr: Line break after sentence stop.
| |||||||||||||||
.Ed | |||||||||||||||
.Pp | |||||||||||||||
The | |||||||||||||||
Done Inline ActionsSame question as above re .Fa, and "The" wants an extra noun, like "The ... field" pauamma_gundo.com: Same question as above re .Fa, and "The" wants an extra noun, like "The ... field" | |||||||||||||||
.Fa nlmsg_len | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
is the whole message length, in bytes, incuding the header. | |||||||||||||||
Done Inline Actions"nearest" implies 40 bits get truncated to 32. I think you mean "first greater than or equal" or something along those lines. pauamma_gundo.com: "nearest" implies 40 bits get truncated to 32. I think you mean "first greater than or equal"… | |||||||||||||||
It has to be rounded to the nearest 32-bit boundary when iterating | |||||||||||||||
over messages. | |||||||||||||||
.Fa nlmsg_type | |||||||||||||||
represents the command/request type. | |||||||||||||||
This value is family-specific. | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
The list of the supported commands can be found in the relevant family | |||||||||||||||
header file. | |||||||||||||||
.Fa nlmsg_seq | |||||||||||||||
is a user-provided request identifier. | |||||||||||||||
Done Inline ActionsSame here, line break after sentence stop. bcr: Same here, line break after sentence stop. | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
An application can track the operation result by tracking the | |||||||||||||||
.Dv NLMSG_ERROR | |||||||||||||||
Done Inline ActionsLline break after sentence stop. bcr: Lline break after sentence stop.
| |||||||||||||||
messages and matching the | |||||||||||||||
Not Done Inline Actions.Vt? (Consider that question asked of Fa uses below.) pauamma_gundo.com: .Vt?
(Consider that question asked of Fa uses below.) | |||||||||||||||
Not Done Inline ActionsIt's the field name - so to me, it's closer to the variable name than the variable type. melifaro: It's the field name - so to me, it's closer to the variable name than the variable type. | |||||||||||||||
.Fa nlmsg_seq | |||||||||||||||
. | |||||||||||||||
Done Inline ActionsSee above re "The". pauamma_gundo.com: See above re "The". | |||||||||||||||
The | |||||||||||||||
.Fa nlmsg_pid | |||||||||||||||
Not Done Inline Actions
"id" or "ID"; choose one. pauamma_gundo.com: "id" or "ID"; choose one. | |||||||||||||||
represents message sender id. | |||||||||||||||
This field is optional for userland. | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
Kernel sender ID is zero. | |||||||||||||||
Done Inline ActionsUnless you removed "The" before .Fa above, add one here for consistency. pauamma_gundo.com: Unless you removed "The" before .Fa above, add one here for consistency. | |||||||||||||||
.Fa nlmsg_flags | |||||||||||||||
contains the message-specific flags. | |||||||||||||||
The following generic flags are defined: | |||||||||||||||
.Pp | |||||||||||||||
.Bd -literal -offset indent -compact | |||||||||||||||
NLM_F_REQUEST Indicates that the message is an actual request to the kernel | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
NLM_F_ACK Request an explicit ACK messages with an operation result | |||||||||||||||
.Ed | |||||||||||||||
.Pp | |||||||||||||||
The following generic flags are defined for the "GET" request types: | |||||||||||||||
.Pp | |||||||||||||||
.Bd -literal -offset indent -compact | |||||||||||||||
NLM_F_ROOT Return the whole dataset | |||||||||||||||
NLM_F_MATCH Return all entries matching criteria | |||||||||||||||
.Ed | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
These two flags typically used in a combination, aliased to | |||||||||||||||
Done Inline ActionsWhy not .Dv? pauamma_gundo.com: Why not .Dv? | |||||||||||||||
.Fa NLM_F_DUMP | |||||||||||||||
.Pp | |||||||||||||||
The following generic flags are defined for the "NEW" request types: | |||||||||||||||
.Pp | |||||||||||||||
.Bd -literal -offset indent -compact | |||||||||||||||
NLM_F_CREATE Create an object if not exists | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
NLM_F_EXCL Don't replace an object if exists | |||||||||||||||
NLM_F_REPLACE Replace an existing matching object | |||||||||||||||
NLM_F_APPEND Append to an existing object | |||||||||||||||
.Ed | |||||||||||||||
.Pp | |||||||||||||||
The following generic flags are defined for the replies: | |||||||||||||||
.Pp | |||||||||||||||
.Bd -literal -offset indent -compact | |||||||||||||||
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 | |||||||||||||||
.Ed | |||||||||||||||
.Ss TLVs | |||||||||||||||
Done Inline Actions
Most, not all? pauamma_gundo.com: Most, not all? | |||||||||||||||
Done Inline ActionsSome messages such as NLMSG_DONE simply put error code as single u32 value immediately after the header, instead of enclosing it into TLV. There are just 2-3 such occurrences in the protocol, but they do exist. melifaro: Some messages such as `NLMSG_DONE` simply put error code as single u32 value immediately after… | |||||||||||||||
Done Inline ActionsWould something like "Most messages encode their attributes as type-length-value pairs" be more better, assuming that's actually the case -- that most messages are all TLV, except a few that are entirely non-TLV? emaste: Would something like "Most messages encode their attributes as type-length-value pairs" be more… | |||||||||||||||
Most attributes in the messages are encoded as the type-length-value pair | |||||||||||||||
(TLVs). | |||||||||||||||
The base TLV header: | |||||||||||||||
.Bd -literal | |||||||||||||||
struct nlattr { | |||||||||||||||
uint16_t nla_len; /* Total attribute length */ | |||||||||||||||
uint16_t nla_type; /* Attribute type */ | |||||||||||||||
}; | |||||||||||||||
.Ed | |||||||||||||||
TLV type ( | |||||||||||||||
.Fa nla_type | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
) scope typically is the message type or group of messages within a family. | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
For example, | |||||||||||||||
.Dv RTN_MULTICAST type value is only valid for | |||||||||||||||
.Dv RTM_NEWROUTE | |||||||||||||||
, | |||||||||||||||
.Dv RTM_DELROUTE | |||||||||||||||
and | |||||||||||||||
.Dv RTM_GETROUTE | |||||||||||||||
messages. | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
TLVs can be nested, in that case internal TLVs may have their own sub-types. | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
All TLVs packed with 32-bit padding. | |||||||||||||||
.Ss CONTROL MESSAGES | |||||||||||||||
A number of generic control messages are reserved in each family. | |||||||||||||||
.Pp | |||||||||||||||
.Dv NLMSG_ERROR | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
message reports the operation result, if requested, optionally followed by | |||||||||||||||
the metadata TLVs. | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
Value of the | |||||||||||||||
.Fa nlmsg_seq | |||||||||||||||
Done Inline Actions
Is that what you meant? pauamma_gundo.com: Is that what you meant? | |||||||||||||||
Done Inline ActionsYes, thank you! melifaro: Yes, thank you! | |||||||||||||||
is set to the value of the original messages, while | |||||||||||||||
.Fa nlmsg_pid | |||||||||||||||
is set to the socket pid of the original socket. | |||||||||||||||
The operation result is reported via | |||||||||||||||
.Vt "struct nlmsgerr": | |||||||||||||||
.Bd -literal | |||||||||||||||
struct nlmsgerr { | |||||||||||||||
int error; /* Standard errno */ | |||||||||||||||
struct nlmsghdr msg; /* Original message header */ | |||||||||||||||
}; | |||||||||||||||
.Ed | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
If | |||||||||||||||
.Dv NETLINK_CAP_ACK | |||||||||||||||
socket option is not set, the remainder of the original message will follow. | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
If | |||||||||||||||
.Dv NETLINK_EXT_ACK | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
socket option is set, kernel may add | |||||||||||||||
.Dv NLMSGERR_ATTR_MSG | |||||||||||||||
string TLV with the textual error description, optionally followed by the | |||||||||||||||
.Dv NLMSGERR_ATTR_OFFS | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
TLV, indicating the offset from the message start, that triggered an error. | |||||||||||||||
.Pp | |||||||||||||||
.Dv NLMSG_DONE | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
message indicates the end of the message group - typically, the end of the | |||||||||||||||
dump. | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
It consist of a single | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
.Fa int | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
field, describing dump result as standard errno value. | |||||||||||||||
.Sh SOCKET OPTIONS | |||||||||||||||
Done Inline Actions
Unless all-uppercase is needed here. pauamma_gundo.com: Unless all-uppercase is needed here. | |||||||||||||||
.Tn NETLINK | |||||||||||||||
supports a number of custom socket options which can be set with | |||||||||||||||
.Xr setsockopt 2 | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
with | |||||||||||||||
.Dv SOL_NETLINK | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
level: | |||||||||||||||
.Bl -tag -width indent | |||||||||||||||
.It Dv NETLINK_ADD_MEMBERSHIP | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
Subscribes for the notifications for the specific group (int). | |||||||||||||||
.It Dv NETLINK_ADD_MEMBERSHIP | |||||||||||||||
Unsubscribes from the notifications for the specific group (int). | |||||||||||||||
.It Dv NETLINK_LIST_MEMBERSHIPS | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
Lists the memberships as bitmask. | |||||||||||||||
.It Dv NETLINK_CAP_ACK | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
Instructs kernel to send original message header in the reply, | |||||||||||||||
without the message body. | |||||||||||||||
.It Dv NETLINK_EXT_ACK | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
Acknowledges capability to receive additional TLVs in the ACK message. | |||||||||||||||
.El | |||||||||||||||
.Pp | |||||||||||||||
Additionally, | |||||||||||||||
.Tn Netlink | |||||||||||||||
overrides the following socket options from the | |||||||||||||||
.Dv SOL_SOCKET | |||||||||||||||
Done Inline Actions.Fa again? pauamma_gundo.com: .Fa again? | |||||||||||||||
level: | |||||||||||||||
.Bl -tag -width indent | |||||||||||||||
.It Dv SO_RCVBUF | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
Sets the maximum size od the socket receive buffer. | |||||||||||||||
If the caller has | |||||||||||||||
.Dv PRIV_NET_ROUTE | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
permission, the value can exceed the currenly-set | |||||||||||||||
.Va kern.ipc.maxsockbuf | |||||||||||||||
value. | |||||||||||||||
.El | |||||||||||||||
.Sh SYSCTL VARIABLES | |||||||||||||||
A set of | |||||||||||||||
.Xr sysctl 8 | |||||||||||||||
Done Inline Actions
Does #define NETLINK_FIREWALL 3 /* not supported */ mean there's no firewall (yet?), or no sockopt for it? pauamma_gundo.com: Does
```
#define NETLINK_FIREWALL 3 /* not supported */
```
mean there's no firewall (yet?), or… | |||||||||||||||
Done Inline ActionsWhoops. Part of this section was copied from ipfw(8) and not rephrased :-) Should be better now. Thank you for noticing! melifaro: Whoops. Part of this section was copied from ipfw(8) and not rephrased :-) Should be better now. | |||||||||||||||
variables controls the behaviour of the firewall and | |||||||||||||||
associated modules | |||||||||||||||
.Bl -tag -width indent | |||||||||||||||
.It Va net.netlink.sendspace | |||||||||||||||
Default send buffer for the netlink socket. | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
Note that the socket sendspace has to be greater or equal to the maximum | |||||||||||||||
message that can be transmitted via this socket. | |||||||||||||||
.El | |||||||||||||||
.Bl -tag -width indent | |||||||||||||||
.It Va net.netlink.recvspace | |||||||||||||||
Default receive buffer for the netlink socket. | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
Note that the socket sendspace has to be greater or equal to the maximum | |||||||||||||||
message that can be received from this socket. | |||||||||||||||
.El | |||||||||||||||
.Sh DEBUGGING | |||||||||||||||
.Tn Netlink | |||||||||||||||
Done Inline Actions
"per-file"? Do you mean "per-socket"? pauamma_gundo.com: "per-file"? Do you mean "per-socket"? | |||||||||||||||
Done Inline ActionsNo, it's indeed per-(source)-file: 13:23 [0] m@devel2 sysctl net.netlink.debug net.netlink.debug.nl_linux_debug_level: 7 net.netlink.debug.nl_route_debug_level: 7 net.netlink.debug.nl_nhop_debug_level: 9 net.netlink.debug.nl_neigh_debug_level: 7 net.netlink.debug.nl_iface_drivers_debug_level: 7 net.netlink.debug.nl_iface_debug_level: 7 net.netlink.debug.nl_route_core_debug_level: 7 net.netlink.debug.nl_generic_debug_level: 9 net.netlink.debug.nl_writer_debug_level: 7 net.netlink.debug.nl_parser_debug_level: 7 net.netlink.debug.nl_io_debug_level: 7 net.netlink.debug.nl_domain_debug_level: 7 net.netlink.debug.nl_mod_debug_level: 7 melifaro: No, it's indeed per-(source)-file:
```
13:23 [0] m@devel2 sysctl net.netlink.debug
net.netlink. | |||||||||||||||
Done Inline ActionsSource file granularity is probably not obvious to end users though, something like controllable "per functional area" or so might be clearer? emaste: Source file granularity is probably not obvious to end users though, something like… | |||||||||||||||
implements per-file debugging with different severify controllable via | |||||||||||||||
.Va net.netlink.debug | |||||||||||||||
branch. | |||||||||||||||
These messages are logged in the kernel message buffer and can be seen in | |||||||||||||||
.Xr dmesg 8 | |||||||||||||||
. | |||||||||||||||
The following severity levels are defined: | |||||||||||||||
.Bl -tag -width indent | |||||||||||||||
.It Dv LOG_DEBUG(7) | |||||||||||||||
Rare events or per-socket errors are reported here. | |||||||||||||||
This is the default level, not impacting production performance. | |||||||||||||||
.It Dv LOG_DEBUG2(8) | |||||||||||||||
Socket events such as groups membershp, privilege checks, commands and dumps | |||||||||||||||
are logged. | |||||||||||||||
This level does not incur significant performance overhead. | |||||||||||||||
.It Dv LOG_DEBUG9(9) | |||||||||||||||
All socket events, each dumped or modified entities are logged. | |||||||||||||||
Turning it on may result in significant performance overhead. | |||||||||||||||
.El | |||||||||||||||
.Sh ERRORS | |||||||||||||||
Netlink reports operation results, including errors and error metadata, by | |||||||||||||||
Done Inline Actions
Should say how it reports success. error = 0? pauamma_gundo.com: Should say how it reports success. error = 0? | |||||||||||||||
sending | |||||||||||||||
.Dv NLMSG_ERROR | |||||||||||||||
message for each request message. | |||||||||||||||
The following errors can be returned: | |||||||||||||||
.Bl -tag -width Er | |||||||||||||||
.It Bq Er EPERM | |||||||||||||||
when the current privileges are insufficient to perform the required operation; | |||||||||||||||
.It Bo Er ENOBUFS Bc or Bo Er ENOMEM Bc | |||||||||||||||
when the system runs out of memory for | |||||||||||||||
an internal data structure; | |||||||||||||||
.It Bq Er ENOTSUP | |||||||||||||||
when the requested command is not supported by the family or | |||||||||||||||
the family is not supported; | |||||||||||||||
.It Bq Er EINVAL | |||||||||||||||
when some nessesary TLVs are missing or invalid, detailed info | |||||||||||||||
may be provided in NLMSGERR_ATTR_MSG and NLMSGERR_ATTR_OFFS TLVs; | |||||||||||||||
.It Bq Er ENOENT | |||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
when trying to delete non-existing object. | |||||||||||||||
.Pp | |||||||||||||||
Additionally, a socket operation iself may fail with one of the errors | |||||||||||||||
specified in | |||||||||||||||
.Xr socket 2 | |||||||||||||||
, | |||||||||||||||
.Xr recv 2 | |||||||||||||||
or | |||||||||||||||
.Xr send 2 | |||||||||||||||
. | |||||||||||||||
.El | |||||||||||||||
.Sh SEE ALSO | |||||||||||||||
Not Done Inline ActionsDoes that exist already? pauamma_gundo.com: Does that exist already? | |||||||||||||||
Done Inline ActionsNyet. Should be added soon. melifaro: Nyet. Should be added soon. | |||||||||||||||
.Xr genetrlink 4 , | |||||||||||||||
.Xr rtnetlink 4 | |||||||||||||||
.Rs | |||||||||||||||
.%A "J. Salim" | |||||||||||||||
.%A "H. Khosravi" | |||||||||||||||
.%A "A. Kleen" | |||||||||||||||
.%A "A. Kuznetsov" | |||||||||||||||
.%T "Linux Netlink as an IP Services Protocol" | |||||||||||||||
.%O "RFC 3549" | |||||||||||||||
.Re | |||||||||||||||
.Sh HISTORY | |||||||||||||||
The | |||||||||||||||
.Tn NETLINK | |||||||||||||||
protocol appeared in | |||||||||||||||
.Fx 14.0 . | |||||||||||||||
.Sh AUTHORS | |||||||||||||||
.Tn Netlink | |||||||||||||||
Not Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
implementation was written by | |||||||||||||||
.An -nosplit | |||||||||||||||
.An Alexander Chernikov Aq Mt melifaro@FreeBSD.org . | |||||||||||||||
Not Done Inline Actions
pauamma_gundo.com: | |||||||||||||||
It was derived from the Summer of Code 2021 project by | |||||||||||||||
.An Ng Peng Nam Sean . | |||||||||||||||
Lint: Possible Spelling Mistake Possible spelling error. You wrote 'nam', but did you mean 'name'? Lint: Possible Spelling Mistake: Possible spelling error. You wrote 'nam', but did you mean 'name'? |
I don't think this is our standard wording starting with 'as the first'. It's been flagged as problematical in different contexts.