Differential D37011 Diff 112471 share/man/man4/rtnetlink.4

Changeset View

Standalone View

View Options

share/man/man4/rtnetlink.4

This file was added.

.\"

.\" 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_DGRAM 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

pauamma_gundo.comUnsubmitted

Done

.Ss RTM_DELROUTE

- Tries to delete the route.

+ Tries to delete a route.

Route is specified using a combination of

pauamma_gundo.com:

.Dv RTA_DST

pauamma_gundo.comUnsubmitted

Done

Tries to delete the route.

- Route is specified using a combination of

+ The route is specified using a combination of

.Dv RTA_DST

pauamma_gundo.com:

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

pauamma_gundo.comUnsubmitted

Not Done

VNET?

pauamma_gundo.com: VNET?

melifaroAuthorUnsubmitted

Not Done

Yes.

melifaro: Yes.

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.

pauamma_gundo.comUnsubmitted

Done

The only supported sub-attribute is

- .Dv RTAX_MTU

- , which stores path MTU as uint32_t.

+ .Dv RTAX_MTU , which stores path MTU as uint32_t.

.It Dv RTA_MULTIPATH

pauamma_gundo.com:

These nexthops are represented as a sequence of

.Va rtnexthop

structures, each followed by

.Dv RTA_GATEWAY

.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.

pauamma_gundo.comUnsubmitted

Done

Deletes nexthop or nexthhop group.

- The required objects is specified by the

+ The required object is specified by the

.Dv RTA_NH_ID

Or "The required objects are" if more than 1.

pauamma_gundo.com: Or "The required objects are" if more than 1.

.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

pauamma_gundo.comUnsubmitted

Done

.Ss RTM_DELLINK

- Deletes an interface, specified by the

+ Deletes the interface specified by

.Dv IFLA_IFNAME .

pauamma_gundo.com:

Fetches a single interface or all interfaces in the current VNET, depending on the

.Dv NLM_F_DUMP

flag.

pauamma_gundo.comUnsubmitted

Not Done

Is this really restricted to VNETs?

pauamma_gundo.com: Is this really restricted to VNETs?

melifaroAuthorUnsubmitted

Done

Well, yes. Similar to ifconfig. There is a socket option & attribute that allows to interact with the objects in the VNET different from the current one, but it’s not implemented yet.

melifaro: Well, yes. Similar to ifconfig. There is a socket option & attribute that allows to interact…

Each interface is reported as a

.Dv RTM_NEWLINK

message.

pauamma_gundo.comUnsubmitted

Done

flag.

- Each interface is reported as

+ Each interface is reported as a

.Dv RTM_NEWLINK

pauamma_gundo.com:

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.

pauamma_gundo.comUnsubmitted

Done

.It Dv IFLA_ADDRESS

- (binary) Contains link-level interface address (MAC).

+ (binary) Link-level interface address (MAC).

.It Dv IFLA_BROADCAST

For brevity and consistency with later ones.

pauamma_gundo.com: For brevity and consistency with later ones.

.It Dv IFLA_IFNAME

(string) New interface name.

pauamma_gundo.comUnsubmitted

Done

.It Dv IFLA_BROADCAST

- (binary) (readonly) Contains link-level broadcast address.

+ (binary) (readonly) Link-level broadcast address.

.It Dv IFLA_IFNAME

pauamma_gundo.com:

.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

pauamma_gundo.comUnsubmitted

Not Done

Is there an active 802.1x standard other than 802.11?

pauamma_gundo.com: Is there an active 802.1x standard other than 802.11?

melifaroAuthorUnsubmitted

Done

A lot (even too many, maybe). 802.1D is about bridging, including loop prevention protocols, .1Q is about vlans and so on. 802.1X is a standard handling authentication in LAN / wireless. If network is using it, there will be a temporary state when an interface is already able to send/receive frames, but encryption is not negotiated yet. This condition is an example of the aforementioned state.

melifaro: A lot (even too many, maybe). 802.1D is about bridging, including loop prevention protocols, .

.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

.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

.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;

pauamma_gundo.comUnsubmitted

Done

RTNLGRP_IPV6_IFADDR Notifies on IPv6 ifaddr arrival/removal/change

.Ed

- .Sh NEIGHBOURS

- All neighbour configuration messages share the common header:

+ .Sh NEIGHBORS

+ All neighbor configuration messages share the common header:

.Bd -literal

struct ndmsg {

US spelling

pauamma_gundo.com: US spelling

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

pauamma_gundo.comUnsubmitted

Done

.Va ndm_family

- specifies the address family (IPv4 or IPv6) of the neighbour.

+ field specifies the address family (IPv4 or IPv6) of the neighbor.

The

.Va ndm_ifindex

(or get rid of "The")

pauamma_gundo.com: (or get rid of "The")

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.

pauamma_gundo.comUnsubmitted

Done

NUD_FAILED unused

.Ed

.Pp

- The ndm_flags stores the options specific to this entry.

+ The

+ .Va ndm_flags

+ field stores the options specific to this entry.

Available flags:

pauamma_gundo.com:

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.

pauamma_gundo.comUnsubmitted

Done

.Ss RTM_NEWNEIGH

- Creates new neighbour entry.

+ Creates new neighbor entry.

The mandatory options are

pauamma_gundo.com:

The mandatory options are

.Dv NDA_DST ,

.Dv NDA_LLADDR

and

.Dv NDA_IFINDEX .

.Ss RTM_DELNEIGH

Deletes the neighbor entry.

pauamma_gundo.comUnsubmitted

Done

.Ss RTM_DELNEIGH

- Deletes the neighbour entry.

+ Deletes the neighbor entry.

The entry is specified by the combination of

pauamma_gundo.com:

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

pauamma_gundo.comUnsubmitted

Done

.Ss RTM_GETNEIGH

- Fetches a single neighbour or all neighbours in the current VNET, depending on the

+ Fetches a single neighbor or all neighbors in the current VNET, depending on the

.Dv NLM_F_DUMP

Also, VNET?

pauamma_gundo.com: Also, VNET?

.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.

pauamma_gundo.comUnsubmitted

Done

.It Dv NDA_DST

- (binary) neighbour IPv4/IPv6 address.

+ (binary) neighbor IPv4/IPv6 address.

.It Dv NDA_LLADDR

pauamma_gundo.com:

.It Dv NDA_LLADDR

(binary) neighbor link-level address.

pauamma_gundo.comUnsubmitted

Done

.It Dv NDA_LLADDR

- (binary) neighbour link-level address.

+ (binary) neighbor link-level address.

.It Dv NDA_IFINDEX

pauamma_gundo.com:

.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

pauamma_gundo.comUnsubmitted

Not Done

.Bd -literal -offset indent -compact

- RTNLGRP_NEIGH Notifies on ARP/NDP neighbour arrival/removal/change

+ RTNLGRP_NEIGH Notifies on ARP/NDP neighbor arrival/removal/change

.Ed

.Sh SEE ALSO

pauamma_gundo.com:

.Ed

.Sh SEE ALSO

.Xr netlink 4 ,

.Xr route 4

.Sh HISTORY

The

.Dv NETLINK_ROUTE

protocol family appeared in

.Fx 14.0 .

.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 .