diff --git a/share/man/man3/snl.3 b/share/man/man3/snl.3 index 9fdeeaf56178..78a6b67e88a9 100644 --- a/share/man/man3/snl.3 +++ b/share/man/man3/snl.3 @@ -1,303 +1,303 @@ .\" .\" Copyright (C) 2022 Alexander Chernikov . .\" .\" 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, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, 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 AUTHOR AND CONTRIBUTORS ``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 AUTHOR OR CONTRIBUTORS 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 December 16, 2022 .Dt SNL 3 .Os .Sh NAME .Nm snl_init , .Nm snl_free , .Nm snl_read_message , .Nm snl_send , .Nm snl_get_seq , .Nm snl_allocz , .Nm snl_clear_lb , .Nm snl_parse_nlmsg , .Nm snl_parse_header , .Nm snl_parse_attrs , .Nm snl_parse_attrs_raw , .Nm snl_attr_get_flag , .Nm snl_attr_get_ip , .Nm snl_attr_get_uint16 , .Nm snl_attr_get_uint32 , .Nm snl_attr_get_string , .Nm snl_attr_get_stringn , .Nm snl_attr_get_nla , .Nm snl_field_get_uint8 , .Nm snl_field_get_uint16 , .Nm snl_field_get_uint32 .Nd "simple netlink library" .Sh SYNOPSIS .In netlink/netlink_snl.h .In netlink/netlink_snl_route.h .Ft "bool" .Fn snl_init "struct snl_state *ss" "int netlink_family" .Fn snl_free "struct snl_state *ss" .Ft "struct nlmsghdr *" .Fn snl_read_message "struct snl_state *ss" .Ft "bool" .Fn snl_send "struct snl_state *ss" "void *data" "int sz" .Ft "uint32_t" .Fn snl_get_seq "struct snl_state *ss" .Ft "void *" .Fn snl_allocz "struct snl_state *ss" "int len" .Fn snl_clear_lb "struct snl_state *ss" .Ft "bool" .Fn snl_parse_nlmsg "struct snl_state *ss" "struct nlmsghdr *hdr" "const struct snl_hdr_parser *ps" "void *target" .Ft "bool" .Fn snl_parse_header "struct snl_state *ss" "void *hdr" "int len" "const struct snl_hdr_parser *ps" "int pslen" "void *target" .Ft "bool" .Fn snl_parse_attrs "struct snl_state *ss" "struct nlmsghdr *hdr" "int hdrlen" "const struct snl_attr_parser *ps" "int pslen" "void *target" .Ft "bool" .Fn snl_parse_attrs_raw "struct snl_state *ss" "struct nlattr *nla_head" "int len" "const struct snl_attr_parser *ps" "int pslen" "void *target" .Ft "bool" .Fn snl_attr_get_flag "struct snl_state *ss" "struct nlattr *nla" "void *target" .Ft "bool" .Fn snl_attr_get_uint16 "struct snl_state *ss" "struct nlattr *nla" "void *target" .Ft "bool" .Fn snl_attr_get_uint32 "struct snl_state *ss" "struct nlattr *nla" "void *target" .Ft "bool" .Fn snl_attr_get_string "struct snl_state *ss" "struct nlattr *nla" "void *target" .Ft "bool" .Fn snl_attr_get_stringn "struct snl_state *ss" "struct nlattr *nla" "void *target" .Ft "bool" .Fn snl_attr_get_nla "struct snl_state *ss" "struct nlattr *nla" "void *target" .Ft "bool" .Fn snl_attr_get_ip "struct snl_state *ss" "struct nlattr *nla" "void *target" .Ft "bool" .Fn snl_attr_get_ipvia "struct snl_state *ss" "struct nlattr *nla" "void *target" .Sh DESCRIPTION The .Xr snl 3 library provides an easy way of sending and receiving Netlink messages, taking care of serialisation and deserialisation. .Ss INITIALISATION Call .Fn snl_init with a pointer to the .Dv struct snl_state and the desired Netlink family to initialise the library instance. To free the library instance, call .Fn snl_free . .Pp The library functions are NOT multithread-safe. If multithreading is desired, consider initializing an instance per thread. .Ss MEMORY ALLOCATION The library uses pre-allocated extendable memory buffers to handle message parsing. The typical usage pattern is to allocate the necessary data structures during the message parsing or writing process via .Fn snl_allocz and free all allocated data at once using .Fn snl_clear_lb after handling the message. .Ss COMPOSING AND SENDING MESSAGES The library does not currently offer any wrappers for writing netlink messages. Simple request messages can be composed by filling in all needed fields directly. Example for constructing an interface dump request: .Bd -literal struct { struct nlmsghdr hdr; struct ifinfomsg ifmsg; } msg = { .hdr.nlmsg_type = RTM_GETLINK, .hdr.nlmsg_flags = NLM_F_DUMP | NLM_F_REQUEST, .hdr.nlmsg_seq = snl_get_seq(ss), }; msg.hdr.nlmsg_len = sizeof(msg); .Ed .Fn snl_get_seq can be used to generate a unique message number. To send the resulting message, .Fn snl_send can be used. .Ss RECEIVING AND PARSING MESSAGES To receive a message, use .Fn snl_read_message . Currently, this call is blocking. .Pp The library provides an easy way to convert the message to the pre-defined C structure. For each message type, one needs to define rules, converting the protocol header fields and the desired attributes to the specified structure. It can be accomplished by using message parsers. Each message parser consists of an array of attribute getters and an array of header field getters. The former array needs to be sorted by the attribute type. There is a .Fn SNL_VERIFY_PARSERS macro to check if the order is correct. .Fn SNL_DECLARE_PARSER "parser_name" "family header type" "struct snl_field_parser[]" "struct snl_attr_parser[]" can be used to create a new parser. .Fn SNL_DECLARE_ATTR_PARSER "parser_name" "struct snl_field_parser[]" can be used to create an attribute-only message parser. .Pp Each attribute getter needs to be embedded in the following structure: .Bd -literal typedef bool snl_parse_attr_f(struct snl_state *ss, struct nlattr *attr, const void *arg, void *target); struct snl_attr_parser { uint16_t type; /* Attribute type */ uint16_t off; /* field offset in the target structure */ snl_parse_attr_f *cb; /* getter function to call */ const void *arg; /* getter function custom argument */ }; .Ed The generic attribute getter has the following signature: .Ft "bool" .Fn snl_attr_get_ "struct snl_state *ss" "struct nlattr *nla" "const void *arg" "void *target" . nla contains the pointer of the attribute to use as the datasource. The target field is the pointer to the field in the target structure. It is up to the getter to know the type of the target field. The getter must check the input attribute and return false if the attribute is not formed correctly. Otherwise, the getter fetches the attribute value and stores it in the target, then returns true. It is possible to use .Fn snl_allocz to create the desired data structure . A number of predefined getters for the common data types exist. .Fn snl_attr_get_flag converts a flag-type attribute to an uint8_t value of 1 or 0, depending on the attribute presence. .Fn snl_attr_get_uint16 stores a uint16_t type attribute into the uint16_t target field. .Fn snl_attr_get_uint32 stores a uint32_t type attribute into the uint32_t target field. .Fn snl_attr_get_ip and .Fn snl_attr_get_ipvia stores a pointer to the sockaddr structure with the IPv4/IPv6 address contained in the attribute. Sockaddr is allocated using .Fn snl_allocz . .Fn snl_attr_get_string stores a pointer to the NULL-terminated string. The string itself is allocated using .Fn snl_allocz . .Fn snl_attr_get_nla stores a pointer to the specified attribute. .Fn snl_attr_get_stringn stores a pointer to the non-NULL-terminated string. .Pp Similarly, each family header getter needs to be embedded in the following structure: .Bd -literal typedef void snl_parse_field_f(struct snl_state *ss, void *hdr, void *target); struct snl_field_parser { uint16_t off_in; /* field offset in the input structure */ uint16_t off_out;/* field offset in the target structure */ snl_parse_field_f *cb; /* getter function to call */ }; .Ed The generic field getter has the following signature: .Ft "void" snl_field_get_ "struct snl_state *ss" "void *src" "void *target" . A number of pre-defined getters for the common data types exist. .Fn "snl_field_get_uint8" fetches an uint8_t value and stores it in the target. .Fn "snl_field_get_uint16" fetches an uint8_t value and stores it in the target. .Fn "snl_field_get_uint32" fetches an uint32_t value and stores it in the target. .Sh EXAMPLES The following example demonstrates how to list all system interfaces using netlink. .Bd -literal #include #include #include #include "netlink/netlink_snl.h" #include "netlink/netlink_snl_route.h" struct nl_parsed_link { uint32_t ifi_index; uint32_t ifla_mtu; char *ifla_ifname; }; #define _IN(_field) offsetof(struct ifinfomsg, _field) #define _OUT(_field) offsetof(struct nl_parsed_link, _field) static const struct snl_attr_parser ap_link[] = { { .type = IFLA_IFNAME, .off = _OUT(ifla_ifname), .cb = snl_attr_get_string }, { .type = IFLA_MTU, .off = _OUT(ifla_mtu), .cb = snl_attr_get_uint32 }, }; static const struct snl_field_parser fp_link[] = { {.off_in = _IN(ifi_index), .off_out = _OUT(ifi_index), .cb = snl_field_get_uint32 }, }; #undef _IN #undef _OUT SNL_DECLARE_PARSER(link_parser, struct ifinfomsg, fp_link, ap_link); int main(int ac, char *argv[]) { struct snl_state ss; if (!snl_init(&ss, NETLINK_ROUTE)) return (1); struct { struct nlmsghdr hdr; struct ifinfomsg ifmsg; } msg = { .hdr.nlmsg_type = RTM_GETLINK, .hdr.nlmsg_flags = NLM_F_DUMP | NLM_F_REQUEST, .hdr.nlmsg_seq = snl_get_seq(&ss), }; msg.hdr.nlmsg_len = sizeof(msg); if (!snl_send(&ss, &msg, sizeof(msg))) { snl_free(&ss); return (1); } struct nlmsghdr *hdr; while ((hdr = snl_read_message(&ss)) != NULL && hdr->nlmsg_type != NLMSG_DONE) { if (hdr->nlmsg_seq != msg.hdr.nlmsg_seq) break; struct nl_parsed_link link = {}; if (!snl_parse_nlmsg(&ss, hdr, &link_parser, &link)) continue; printf("Link#%u %s mtu %u\n", link.ifi_index, link.ifla_ifname, link.ifla_mtu); } return (0); } .Ed .Sh SEE ALSO .Xr genetlink 4 , .Xr netlink 4 , and .Xr rtnetlink 4 .Sh HISTORY The .Dv SNL library appeared in -.Fx 14.0 . +.Fx 13.2 . .Sh AUTHORS This library was implemented by .An Alexander Chernikov Aq Mt melifaro@FreeBSD.org . diff --git a/share/man/man4/genetlink.4 b/share/man/man4/genetlink.4 index 2c5b9b99f994..a21963b5e3bd 100644 --- a/share/man/man4/genetlink.4 +++ b/share/man/man4/genetlink.4 @@ -1,147 +1,147 @@ .\" .\" Copyright (C) 2022 Alexander Chernikov . .\" .\" 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, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, 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 AUTHOR AND CONTRIBUTORS ``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 AUTHOR OR CONTRIBUTORS 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 November 1, 2022 .Dt GENETLINK 4 .Os .Sh NAME .Nm genetlink .Nd Generic Netlink .Sh SYNOPSIS .In netlink/netlink.h .In netlink/netlink_generic.h .Ft int .Fn socket AF_NETLINK SOCK_DGRAM NETLINK_GENERIC .Sh DESCRIPTION The .Dv NETLINK_GENERIC is a "container" family, used for dynamic registration of other families belonging to the various subsystems. These subsystems provide a string family name during registration and receive a dynamically-allocated family id. Allocated family identifiers are then used by applications to get access to functions provided by that subsystem via netlink. There are standard methods for resolving string family names to family identifiers. A similar mechanism works for the notification groups provided by those families. .Pp All generic netlink families share a common header: .Bd -literal struct genlmsghdr { uint8_t cmd; /* command within the family */ uint8_t version; /* ABI version for the cmd */ uint16_t reserved; /* reserved: set to 0 */ }; .Ed The family id is encoded in the .Dv nlmsg_type of the base netlink header. The .Va cmd field is the command identifier within the family. The .Va version field is the command version. .Sh METHODS The generic Netlink framework provides the base family, .Dv GENL_ID_CTRL ("nlctrl") with a fixed family id. This family is used to list the details of all registered families. .Pp The following messages are supported by the framework: .Ss CTRL_CMD_GETFAMILY Fetches a single family or all registered families, depending on the .Dv NLM_F_DUMP flag. Each family is reported as .Dv CTRL_CMD_NEWFAMILY message. The following filters are recognised by the kernel: .Pp .Bd -literal -offset indent -compact CTRL_ATTR_FAMILY_ID (uint16_t) current family id assigned by kernel CTRL_ATTR_FAMILY_NAME (string) family name .Ed .Ss TLVs .Bl -tag -width indent .It Dv CTRL_ATTR_FAMILY_ID (uint16_t) Dynamically-assigned family identifier. .It Dv CTRL_ATTR_FAMILY_NAME (string) Family name. .It Dv CTRL_ATTR_HDRSIZE (uint32_t) Family mandatory header size (typically 0). .It Dv CTRL_ATTR_MAXATTR (uint32_t) Maximum attribute number valid for the family. .It Dv CTRL_ATTR_OPS (nested) List of the operations supported by the family. The attribute consists of a list of nested TLVs, with attribute values monotonically incremented, starting from 0. The following attributes are present in each TLV: .Bl -tag -width indent .It Dv CTRL_ATTR_OP_ID Operation (message) number. .It Dv CTRL_ATTR_OP_FLAGS Operation flags. The following flags are supported: .Bd -literal -offset indent -compact GENL_ADMIN_PERM requires elevated permissions GENL_CMD_CAP_DO operation is a modification request GENL_CMD_CAP_DUMP operation is a get/dump request .Ed .El .It Dv CTRL_ATTR_MCAST_GROUPS (nested) List of the notification groups supported by the family. The attribute consists of a list of nested TLVs, with attribute values monotonically incremented, starting from 0. The following attributes are present in each TLV: .Bl -tag -width indent .It Dv CTRL_ATTR_MCAST_GRP_ID Group id that can be used in .Dv NETLINK_ADD_MEMBERSHIP .Xr setsockopt 2 . .It Dv CTRL_ATTR_MCAST_GRP_NAME (string) Human-readable name of the group. .El .El .Ss Groups The following groups are defined: .Bd -literal -offset indent -compact "notify" Notifies on family registrations/removal. .Ed .Sh SEE ALSO .Xr netlink 4 .Sh HISTORY The .Dv NETLINK_GENERIC protocol family appeared in -.Fx 14.0 . +.Fx 13.2 . .Sh AUTHORS The netlink was implementated by .An -nosplit .An Alexander Chernikov Aq Mt melifaro@FreeBSD.org . It was derived from the Google Summer of Code 2021 project by .An Ng Peng Nam Sean . diff --git a/share/man/man4/netlink.4 b/share/man/man4/netlink.4 index c0d9b5a88ade..50adebd0c6c7 100644 --- a/share/man/man4/netlink.4 +++ b/share/man/man4/netlink.4 @@ -1,355 +1,355 @@ .\" .\" Copyright (C) 2022 Alexander Chernikov . .\" .\" 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, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, 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 AUTHOR AND CONTRIBUTORS ``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 AUTHOR OR CONTRIBUTORS 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 November 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_RAW "int family" .Sh DESCRIPTION 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: .Pp .Bd -literal -offset indent -compact NETLINK_ROUTE network configuration, NETLINK_GENERIC "container" family .Ed .Pp The .Dv NETLINK_ROUTE family handles all interfaces, addresses, neighbors, routes, and VNETs configuration. More details can be found in .Xr rtnetlink 4 . The .Dv NETLINK_GENERIC family serves as a .Do container Dc , allowing registering other families under the .Dv NETLINK_GENERIC umbrella. This approach allows using a single netlink socket to interact with multiple netlink families at once. More details can be found in .Xr genetlink 4 . .Pp 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 Typically, filling this structure is not required for socket operations. It is presented here for completeness. .Sh PROTOCOL DESCRIPTION The protocol is message-based. Each message starts with the mandatory .Va nlmsghdr 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 .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 */ }; .Ed .Pp The .Va nlmsg_len 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 .Va nlmsg_type 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. .Va nlmsg_seq is a user-provided request identifier. An application can track the operation result using the .Dv NLMSG_ERROR messages and matching the .Va nlmsg_seq . The .Va nlmsg_pid field is the message sender id. This field is optional for userland. The kernel sender id is zero. The .Va nlmsg_flags field 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 NLM_F_ACK Request an explicit ACK message 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 the criteria .Ed These two flags are typically used together, aliased to .Dv 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 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 .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 Most messages encode their attributes as type-length-value pairs (TLVs). The base TLV header: .Bd -literal struct nlattr { uint16_t nla_len; /* Total attribute length */ uint16_t nla_type; /* Attribute type */ }; .Ed The TLV type .Pq Va nla_type scope is typically the message type or group within a family. For example, the .Dv RTN_MULTICAST type value is only valid for .Dv RTM_NEWROUTE , .Dv RTM_DELROUTE and .Dv RTM_GETROUTE messages. TLVs can be nested; in that case internal TLVs may have their own sub-types. All TLVs are packed with 4-byte padding. .Ss CONTROL MESSAGES A number of generic control messages are reserved in each family. .Pp .Dv NLMSG_ERROR reports the operation result if requested, optionally followed by the metadata TLVs. The value of .Va nlmsg_seq is set to its value in the original messages, while .Va 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 If the .Dv NETLINK_CAP_ACK socket option is not set, the remainder of the original message will follow. If the .Dv NETLINK_EXT_ACK socket option is set, the kernel may add a .Dv NLMSGERR_ATTR_MSG string TLV with the textual error description, optionally followed by the .Dv NLMSGERR_ATTR_OFFS TLV, indicating the offset from the message start that triggered an error. If the operation reply is a multipart message, then no .Dv NLMSG_ERROR reply is generated, only a .Dv NLMSG_DONE message, closing multipart sequence. .Pp .Dv NLMSG_DONE indicates the end of the message group: typically, the end of the dump. It contains a single .Vt int field, describing the dump result as a standard errno value. .Sh SOCKET OPTIONS Netlink supports a number of custom socket options, which can be set with .Xr setsockopt 2 with the .Dv SOL_NETLINK .Fa level : .Bl -tag -width indent .It Dv NETLINK_ADD_MEMBERSHIP Subscribes to the notifications for the specific group (int). .It Dv NETLINK_DROP_MEMBERSHIP Unsubscribes from the notifications for the specific group (int). .It Dv NETLINK_LIST_MEMBERSHIPS Lists the memberships as a bitmask. .It Dv NETLINK_CAP_ACK Instructs the kernel to send the original message header in the reply without the message body. .It Dv NETLINK_EXT_ACK Acknowledges ability to receive additional TLVs in the ACK message. .El .Pp Additionally, netlink overrides the following socket options from the .Dv SOL_SOCKET .Fa level : .Bl -tag -width indent .It Dv SO_RCVBUF Sets the maximum size of the socket receive buffer. If the caller has .Dv PRIV_NET_ROUTE permission, the value can exceed the currently-set .Va kern.ipc.maxsockbuf value. .El .Sh SYSCTL VARIABLES A set of .Xr sysctl 8 variables is available to tweak run-time parameters: .Bl -tag -width indent .It Va net.netlink.sendspace 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. .El .Bl -tag -width indent .It Va net.netlink.recvspace 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. .El .Bl -tag -width indent .It Va net.netlink.nl_maxsockbuf Maximum receive buffer for the netlink socket that can be set via .Dv SO_RCVBUF socket option. .El .Sh DEBUGGING Netlink implements per-functional-unit debugging, with different severities controllable via the .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 memberships, privilege checks, commands and dumps are logged. This level does not incur significant performance overhead. .It Dv LOG_DEBUG3(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 sending a .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 necessary TLVs are missing or invalid, detailed info may be provided in NLMSGERR_ATTR_MSG and NLMSGERR_ATTR_OFFS TLVs; .It Bq Er ENOENT when trying to delete a non-existent object. .Pp Additionally, a socket operation itself may fail with one of the errors specified in .Xr socket 2 , .Xr recv 2 or .Xr send 2 . .El .Sh SEE ALSO .Xr genetlink 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 netlink protocol appeared in -.Fx 14.0 . +.Fx 13.2 . .Sh AUTHORS The netlink was implemented by .An -nosplit .An Alexander Chernikov Aq Mt melifaro@FreeBSD.org . It was derived from the Google Summer of Code 2021 project by .An Ng Peng Nam Sean . diff --git a/share/man/man4/rtnetlink.4 b/share/man/man4/rtnetlink.4 index 5849508b74c2..1e52640eec56 100644 --- a/share/man/man4/rtnetlink.4 +++ b/share/man/man4/rtnetlink.4 @@ -1,534 +1,534 @@ .\" .\" Copyright (C) 2022 Alexander Chernikov . .\" .\" 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, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, 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 AUTHOR AND CONTRIBUTORS ``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 AUTHOR OR CONTRIBUTORS 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 November 1, 2022 .Dt RTNETLINK 4 .Os .Sh NAME .Nm RTNetlink .Nd Network configuration-specific Netlink family .Sh SYNOPSIS .In netlink/netlink.h .In netlink/netlink_route.h .Ft int .Fn socket AF_NETLINK SOCK_RAW NETLINK_ROUTE .Sh DESCRIPTION The .Dv NETLINK_ROUTE family aims to be the primary configuration mechanism for all network-related tasks. Currently it supports configuring interfaces, interface addresses, routes, nexthops and arp/ndp neighbors. .Sh ROUTES All route configuration messages share the common header: .Bd -literal struct rtmsg { unsigned char rtm_family; /* address family */ unsigned char rtm_dst_len; /* Prefix length */ unsigned char rtm_src_len; /* Deprecated, set to 0 */ unsigned char rtm_tos; /* Type of service (not used) */ unsigned char rtm_table; /* deprecated, set to 0 */ unsigned char rtm_protocol; /* Routing protocol id (RTPROT_) */ unsigned char rtm_scope; /* Route distance (RT_SCOPE_) */ unsigned char rtm_type; /* Route type (RTN_) */ unsigned rtm_flags; /* Route flags (not supported) */ }; .Ed .Pp The .Va rtm_family specifies the route family to be operated on. Currently, .Dv AF_INET6 and .Dv AF_INET are the only supported families. The route prefix length is stored in .Va rtm_dst_len . The caller should set the originator identity (one of the .Dv RTPROT_ values) in .Va rtm_protocol . It is useful for users and for the application itself, allowing for easy identification of self-originated routes. The route scope has to be set via .Va rtm_scope field. The supported values are: .Bd -literal -offset indent -compact RT_SCOPE_UNIVERSE Global scope RT_SCOPE_LINK Link scope .Ed .Pp Route type needs to be set. The defined values are: .Bd -literal -offset indent -compact RTN_UNICAST Unicast route RTN_MULTICAST Multicast route RTN_BLACKHOLE Drops traffic towards destination RTN_PROHIBIT Drops traffic and sends reject .Ed .Pp The following messages are supported: .Ss RTM_NEWROUTE Adds a new route. All NL flags are supported. Extending a multipath route requires NLM_F_APPEND flag. .Ss RTM_DELROUTE Tries to delete a route. The route is specified using a combination of .Dv RTA_DST TLV and .Va rtm_dst_len . .Ss RTM_GETROUTE Fetches a single route or all routes in the current VNET, depending on the .Dv NLM_F_DUMP flag. Each route is reported as .Dv RTM_NEWROUTE message. The following filters are recognised by the kernel: .Pp .Bd -literal -offset indent -compact rtm_family required family or AF_UNSPEC RTA_TABLE fib number or RT_TABLE_UNSPEC to return all fibs .Ed .Ss TLVs .Bl -tag -width indent .It Dv RTA_DST (binary) IPv4/IPv6 address, depending on the .Va rtm_family . .It Dv RTA_OIF (uint32_t) transmit interface index. .It Dv RTA_GATEWAY (binary) IPv4/IPv6 gateway address, depending on the .Va rtm_family . .It Dv RTA_METRICS (nested) Container attribute, listing route properties. The only supported sub-attribute is .Dv RTAX_MTU , which stores path MTU as uint32_t. .It Dv RTA_MULTIPATH This attribute contains multipath route nexthops with their weights. These nexthops are represented as a sequence of .Va rtnexthop structures, each followed by .Dv RTA_GATEWAY or .Dv RTA_VIA attributes. .Bd -literal struct rtnexthop { unsigned short rtnh_len; unsigned char rtnh_flags; unsigned char rtnh_hops; /* nexthop weight */ int rtnh_ifindex; }; .Ed .Pp The .Va rtnh_len field specifies the total nexthop info length, including both .Va struct rtnexthop and the following TLVs. The .Va rtnh_hops field stores relative nexthop weight, used for load balancing between group members. The .Va rtnh_ifindex field contains the index of the transmit interface. .Pp The following TLVs can follow the structure: .Bd -literal -offset indent -compact RTA_GATEWAY IPv4/IPv6 nexthop address of the gateway RTA_VIA IPv6 nexthop address for IPv4 route RTA_KNH_ID Kernel-specific index of the nexthop .Ed .It Dv RTA_KNH_ID (uint32_t) (FreeBSD-specific) Auto-allocated kernel index of the nexthop. .It Dv RTA_RTFLAGS (uint32_t) (FreeBSD-specific) rtsock route flags. .It Dv RTA_TABLE (uint32_t) Fib number of the route. Default route table is .Dv RT_TABLE_MAIN . To explicitely specify "all tables" one needs to set the value to .Dv RT_TABLE_UNSPEC . .It Dv RTA_EXPIRES (uint32_t) seconds till path expiration. .It Dv RTA_NH_ID (uint32_t) useland nexthop or nexthop group index. .El .Ss Groups The following groups are defined: .Bd -literal -offset indent -compact RTNLGRP_IPV4_ROUTE Notifies on IPv4 route arrival/removal/change RTNLGRP_IPV6_ROUTE Notifies on IPv6 route arrival/removal/change .Ed .Sh NEXTHOPS All nexthop/nexthop group configuration messages share the common header: .Bd -literal struct nhmsg { unsigned char nh_family; /* transport family */ unsigned char nh_scope; /* ignored on RX, filled by kernel */ unsigned char nh_protocol; /* Routing protocol that installed nh */ unsigned char resvd; unsigned int nh_flags; /* RTNH_F_* flags from route.h */ }; .Ed The .Va nh_family specificies the gateway address family. It can be different from route address family for IPv4 routes with IPv6 nexthops. The .Va nh_protocol is similar to .Va rtm_protocol field, which designates originator application identity. .Pp The following messages are supported: .Ss RTM_NEWNEXTHOP Creates a new nexthop or nexthop group. .Ss RTM_DELNEXTHOP Deletes nexthop or nexthhop group. The required object is specified by the .Dv RTA_NH_ID attribute. .Ss RTM_GETNEXTHOP Fetches a single nexthop or all nexthops/nexthop groups, depending on the .Dv NLM_F_DUMP flag. The following filters are recognised by the kernel: .Pp .Bd -literal -offset indent -compact RTA_NH_ID nexthop or nexthtop group id NHA_GROUPS match only nexthtop groups .Ed .Ss TLVs .Bl -tag -width indent .It Dv RTA_NH_ID (uint32_t) Nexthhop index used to identify particular nexthop or nexthop group. Should be provided by userland at the nexthtop creation time. .It Dv NHA_GROUP This attribute designates the nexthtop group and contains all of its nexthtops and their relative weights. The attribute constists of a list of .Va nexthop_grp structures: .Bd -literal struct nexthop_grp { uint32_t id; /* nexhop userland index */ uint8_t weight; /* weight of this nexthop */ uint8_t resvd1; uint16_t resvd2; }; .Ed .It Dv NHA_GROUP_TYPE (uint16_t) Nexthtop group type, set to one of the following types: .Bd -literal -offset indent -compact NEXTHOP_GRP_TYPE_MPATH default multipath group .Ed .It Dv NHA_BLACKHOLE (flag) Marks the nexthtop as blackhole. .It Dv NHA_OIF (uint32_t) Transmit interface index of the nexthtop. .It Dv NHA_GATEWAY (binary) IPv4/IPv6 gateway address .It Dv NHA_GROUPS (flag) Matches nexthtop groups during dump. .El .Ss Groups The following groups are defined: .Bd -literal -offset indent -compact RTNLGRP_NEXTHOP Notifies on nexthop/groups arrival/removal/change .Ed .Sh INTERFACES All interface configuration messages share the common header: .Bd -literal struct ifinfomsg { unsigned char ifi_family; /* not used, set to 0 */ unsigned char __ifi_pad; unsigned short ifi_type; /* ARPHRD_* */ int ifi_index; /* Inteface index */ unsigned ifi_flags; /* IFF_* flags */ unsigned ifi_change; /* IFF_* change mask */ }; .Ed .Ss RTM_NEWLINK Creates a new interface. The only mandatory TLV is .Dv IFLA_IFNAME . .Ss RTM_DELLINK Deletes the interface specified by .Dv IFLA_IFNAME . .Ss RTM_GETLINK Fetches a single interface or all interfaces in the current VNET, depending on the .Dv NLM_F_DUMP flag. Each interface is reported as a .Dv RTM_NEWLINK message. The following filters are recognised by the kernel: .Pp .Bd -literal -offset indent -compact ifi_index interface index IFLA_IFNAME interface name IFLA_ALT_IFNAME interface name .Ed .Ss TLVs .Bl -tag -width indent .It Dv IFLA_ADDRESS (binary) Llink-level interface address (MAC). .It Dv IFLA_BROADCAST (binary) (readonly) Link-level broadcast address. .It Dv IFLA_IFNAME (string) New interface name. .It Dv IFLA_IFALIAS (string) Interface description. .It Dv IFLA_LINK (uint32_t) (readonly) Interface index. .It Dv IFLA_MASTER (uint32_t) Parent interface index. .It Dv IFLA_LINKINFO (nested) Interface type-specific attributes: .Bd -literal -offset indent -compact IFLA_INFO_KIND (string) interface type ("vlan") IFLA_INFO_DATA (nested) custom attributes .Ed The following types and attributes are supported: .Bl -tag -width indent .It Dv vlan .Bd -literal -offset indent -compact IFLA_VLAN_ID (uint16_t) 802.1Q vlan id IFLA_VLAN_PROTOCOL (uint16_t) Protocol: ETHERTYPE_VLAN or ETHERTYPE_QINQ .Ed .El .It Dv IFLA_OPERSTATE (uint8_t) Interface operational state per RFC 2863. Can be one of the following: .Bd -literal -offset indent -compact IF_OPER_UNKNOWN status can not be determined IF_OPER_NOTPRESENT some (hardware) component not present IF_OPER_DOWN down IF_OPER_LOWERLAYERDOWN some lower-level interface is down IF_OPER_TESTING in some test mode IF_OPER_DORMANT "up" but waiting for some condition (802.1X) IF_OPER_UP ready to pass packets .Ed .It Dv IFLA_STATS64 (readonly) Consists of the following 64-bit counters structure: .Bd -literal struct rtnl_link_stats64 { uint64_t rx_packets; /* total RX packets (IFCOUNTER_IPACKETS) */ uint64_t tx_packets; /* total TX packets (IFCOUNTER_OPACKETS) */ uint64_t rx_bytes; /* total RX bytes (IFCOUNTER_IBYTES) */ uint64_t tx_bytes; /* total TX bytes (IFCOUNTER_OBYTES) */ uint64_t rx_errors; /* RX errors (IFCOUNTER_IERRORS) */ uint64_t tx_errors; /* RX errors (IFCOUNTER_OERRORS) */ uint64_t rx_dropped; /* RX drop (no space in ring/no bufs) (IFCOUNTER_IQDROPS) */ uint64_t tx_dropped; /* TX drop (IFCOUNTER_OQDROPS) */ uint64_t multicast; /* RX multicast packets (IFCOUNTER_IMCASTS) */ uint64_t collisions; /* not supported */ uint64_t rx_length_errors; /* not supported */ uint64_t rx_over_errors; /* not supported */ uint64_t rx_crc_errors; /* not supported */ uint64_t rx_frame_errors; /* not supported */ uint64_t rx_fifo_errors; /* not supported */ uint64_t rx_missed_errors; /* not supported */ uint64_t tx_aborted_errors; /* not supported */ uint64_t tx_carrier_errors; /* not supported */ uint64_t tx_fifo_errors; /* not supported */ uint64_t tx_heartbeat_errors; /* not supported */ uint64_t tx_window_errors; /* not supported */ uint64_t rx_compressed; /* not supported */ uint64_t tx_compressed; /* not supported */ uint64_t rx_nohandler; /* dropped due to no proto handler (IFCOUNTER_NOPROTO) */ }; .Ed .El .Ss Groups The following groups are defined: .Bd -literal -offset indent -compact RTNLGRP_LINK Notifies on interface arrival/removal/change .Ed .Sh INTERFACE ADDRESSES All interface address configuration messages share the common header: .Bd -literal struct ifaddrmsg { uint8_t ifa_family; /* Address family */ uint8_t ifa_prefixlen; /* Prefix length */ uint8_t ifa_flags; /* Address-specific flags */ uint8_t ifa_scope; /* Address scope */ uint32_t ifa_index; /* Link ifindex */ }; .Ed .Pp The .Va ifa_family specifies the address family of the interface address. The .Va ifa_prefixlen specifies the prefix length if applicable for the address family. The .Va ifa_index specifies the interface index of the target interface. .Ss RTM_NEWADDR Not supported .Ss RTM_DELADDR Not supported .Ss RTM_GETADDR Fetches interface addresses in the current VNET matching conditions. Each address is reported as a .Dv RTM_NEWADDR message. The following filters are recognised by the kernel: .Pp .Bd -literal -offset indent -compact ifa_family required family or AF_UNSPEC ifa_index matching interface index or 0 .Ed .Ss TLVs .Bl -tag -width indent .It Dv IFA_ADDRESS (binary) masked interface address or destination address for p2p interfaces. .It Dv IFA_LOCAL (binary) local interface address. Set for IPv4 and p2p addresses. .It Dv IFA_LABEL (string) interface name. .It Dv IFA_BROADCAST (binary) broacast interface address. .El .Ss Groups The following groups are defined: .Bd -literal -offset indent -compact RTNLGRP_IPV4_IFADDR Notifies on IPv4 ifaddr arrival/removal/change RTNLGRP_IPV6_IFADDR Notifies on IPv6 ifaddr arrival/removal/change .Ed .Sh NEIGHBORS All neighbor configuration messages share the common header: .Bd -literal struct ndmsg { uint8_t ndm_family; uint8_t ndm_pad1; uint16_t ndm_pad2; int32_t ndm_ifindex; uint16_t ndm_state; uint8_t ndm_flags; uint8_t ndm_type; }; .Ed .Pp The .Va ndm_family field specifies the address family (IPv4 or IPv6) of the neighbor. The .Va ndm_ifindex specifies the interface to operate on. The .Va ndm_state represents the entry state according to the neighbor model. The state can be one of the following: .Bd -literal -offset indent -compact NUD_INCOMPLETE No lladdr, address resolution in progress NUD_REACHABLE reachable & recently resolved NUD_STALE has lladdr but it's stale NUD_DELAY has lladdr, is stale, probes delayed NUD_PROBE has lladdr, is stale, probes sent NUD_FAILED unused .Ed .Pp The .Va ndm_flags field stores the options specific to this entry. Available flags: .Bd -literal -offset indent -compact NTF_SELF local station (LLE_IFADDR) NTF_PROXY proxy entry (LLE_PUB) NTF_STICKY permament entry (LLE_STATIC) NTF_ROUTER dst indicated itself as a router .Ed .Ss RTM_NEWNEIGH Creates new neighbor entry. The mandatory options are .Dv NDA_DST , .Dv NDA_LLADDR and .Dv NDA_IFINDEX . .Ss RTM_DELNEIGH Deletes the neighbor entry. The entry is specified by the combination of .Dv NDA_DST and .Dv NDA_IFINDEX . .Ss RTM_GETNEIGH Fetches a single neighbor or all neighbors in the current VNET, depending on the .Dv NLM_F_DUMP flag. Each entry is reported as .Dv RTM_NEWNEIGH message. The following filters are recognised by the kernel: .Pp .Bd -literal -offset indent -compact ndm_family required family or AF_UNSPEC ndm_ifindex target ifindex NDA_IFINDEX target ifindex .Ed .Ss TLVs .Bl -tag -width indent .It Dv NDA_DST (binary) neighbor IPv4/IPv6 address. .It Dv NDA_LLADDR (binary) neighbor link-level address. .It Dv NDA_IFINDEX (uint32_t) interface index. .It Dv NDA_FLAGS_EXT (uint32_t) extended version of .Va ndm_flags . .El .Ss Groups The following groups are defined: .Bd -literal -offset indent -compact RTNLGRP_NEIGH Notifies on ARP/NDP neighbor arrival/removal/change .Ed .Sh SEE ALSO .Xr netlink 4 , .Xr route 4 .Sh HISTORY The .Dv NETLINK_ROUTE protocol family appeared in -.Fx 14.0 . +.Fx 13.2 . .Sh AUTHORS The netlink was implementated by .An -nosplit .An Alexander Chernikov Aq Mt melifaro@FreeBSD.org . It was derived from the Google Summer of Code 2021 project by .An Ng Peng Nam Sean .