Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 590 insertions, 0 deletions

diff --git a/man/man7/rtnetlink.7 b/man/man7/rtnetlink.7
new file mode 100644
index 0000000..ce4cf35
--- /dev/null
+++ b/man/man7/rtnetlink.7
@@ -0,0 +1,590 @@
+'\" t
+.\" SPDX-License-Identifier: Linux-man-pages-1-para
+.\"
+.\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
+.\"
+.\" Based on the original comments from Alexey Kuznetsov, written with
+.\" help from Matthew Wilcox.
+.\" $Id: rtnetlink.7,v 1.8 2000/01/22 01:55:04 freitag Exp $
+.\"
+.TH rtnetlink 7 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+rtnetlink \- Linux routing socket
+.SH SYNOPSIS
+.nf
+.B #include <asm/types.h>
+.B #include <linux/netlink.h>
+.B #include <linux/rtnetlink.h>
+.B #include <sys/socket.h>
+.P
+.BI "rtnetlink_socket = socket(AF_NETLINK, int " socket_type ", NETLINK_ROUTE);"
+.fi
+.SH DESCRIPTION
+Rtnetlink allows the kernel's routing tables to be read and altered.
+It is used within the kernel to communicate between
+various subsystems, though this usage is not documented here, and for
+communication with user-space programs.
+Network routes, IP addresses, link parameters, neighbor setups, queueing
+disciplines, traffic classes and packet classifiers may all be controlled
+through
+.B NETLINK_ROUTE
+sockets.
+It is based on netlink messages; see
+.BR netlink (7)
+for more information.
+.\" FIXME . ? all these macros could be moved to rtnetlink(3)
+.SS Routing attributes
+Some rtnetlink messages have optional attributes after the initial header:
+.P
+.in +4n
+.EX
+struct rtattr {
+    unsigned short rta_len;    /* Length of option */
+    unsigned short rta_type;   /* Type of option */
+    /* Data follows */
+};
+.EE
+.in
+.P
+These attributes should be manipulated using only the RTA_* macros
+or libnetlink, see
+.BR rtnetlink (3).
+.SS Messages
+Rtnetlink consists of these message types
+(in addition to standard netlink messages):
+.TP
+.B RTM_NEWLINK
+.TQ
+.B RTM_DELLINK
+.TQ
+.B RTM_GETLINK
+Create, remove, or get information about a specific network interface.
+These messages contain an
+.I ifinfomsg
+structure followed by a series of
+.I rtattr
+structures.
+.IP
+.EX
+struct ifinfomsg {
+    unsigned char  ifi_family; /* AF_UNSPEC */
+    unsigned short ifi_type;   /* Device type */
+    int            ifi_index;  /* Interface index */
+    unsigned int   ifi_flags;  /* Device flags  */
+    unsigned int   ifi_change; /* change mask */
+};
+.EE
+.IP
+.\" FIXME Document ifinfomsg.ifi_type
+.I ifi_flags
+contains the device flags, see
+.BR netdevice (7);
+.I ifi_index
+is the unique interface index
+(since Linux 3.7, it is possible to feed a nonzero value with the
+.B RTM_NEWLINK
+message, thus creating a link with the given
+.IR ifindex );
+.I ifi_change
+is reserved for future use and should be always set to 0xFFFFFFFF.
+.TS
+tab(:);
+c s s
+lb l l.
+Routing attributes
+rta_type:Value type:Description
+_
+IFLA_UNSPEC:-:unspecified
+IFLA_ADDRESS:hardware address:interface L2 address
+IFLA_BROADCAST:hardware address:L2 broadcast address
+IFLA_IFNAME:asciiz string:Device name
+IFLA_MTU:unsigned int:MTU of the device
+IFLA_LINK:int:Link type
+IFLA_QDISC:asciiz string:Queueing discipline
+IFLA_STATS:T{
+see below
+T}:Interface Statistics
+IFLA_PERM_ADDRESS:hardware address:T{
+hardware address provided by device (since Linux 5.5)
+T}
+.TE
+.IP
+The value type for
+.B IFLA_STATS
+is
+.I struct rtnl_link_stats
+.RI ( "struct net_device_stats"
+in Linux 2.4 and earlier).
+.TP
+.B RTM_NEWADDR
+.TQ
+.B RTM_DELADDR
+.TQ
+.B RTM_GETADDR
+Add, remove, or receive information about an IP address associated with
+an interface.
+In Linux 2.2, an interface can carry multiple IP addresses,
+this replaces the alias device concept in Linux 2.0.
+In Linux 2.2, these messages
+support IPv4 and IPv6 addresses.
+They contain an
+.I ifaddrmsg
+structure, optionally followed by
+.I rtattr
+routing attributes.
+.IP
+.EX
+struct ifaddrmsg {
+    unsigned char ifa_family;    /* Address type */
+    unsigned char ifa_prefixlen; /* Prefixlength of address */
+    unsigned char ifa_flags;     /* Address flags */
+    unsigned char ifa_scope;     /* Address scope */
+    unsigned int  ifa_index;     /* Interface index */
+};
+.EE
+.IP
+.I ifa_family
+is the address family type (currently
+.B AF_INET
+or
+.BR AF_INET6 ),
+.I ifa_prefixlen
+is the length of the address mask of the address if defined for the
+family (like for IPv4),
+.I ifa_scope
+is the address scope,
+.I ifa_index
+is the interface index of the interface the address is associated with.
+.I ifa_flags
+is a flag word of
+.B IFA_F_SECONDARY
+for secondary address (old alias interface),
+.B IFA_F_PERMANENT
+for a permanent address set by the user and other undocumented flags.
+.TS
+tab(:);
+c s s
+lb l l.
+Attributes
+rta_type:Value type:Description
+_
+IFA_UNSPEC:-:unspecified
+IFA_ADDRESS:raw protocol address:interface address
+IFA_LOCAL:raw protocol address:local address
+IFA_LABEL:asciiz string:name of the interface
+IFA_BROADCAST:raw protocol address:broadcast address
+IFA_ANYCAST:raw protocol address:anycast address
+IFA_CACHEINFO:struct ifa_cacheinfo:Address information
+.TE
+.\" FIXME Document struct ifa_cacheinfo
+.TP
+.B RTM_NEWROUTE
+.TQ
+.B RTM_DELROUTE
+.TQ
+.B RTM_GETROUTE
+Create, remove, or receive information about a network route.
+These messages contain an
+.I rtmsg
+structure with an optional sequence of
+.I rtattr
+structures following.
+For
+.BR RTM_GETROUTE ,
+setting
+.I rtm_dst_len
+and
+.I rtm_src_len
+to 0 means you get all entries for the specified routing table.
+For the other fields, except
+.I rtm_table
+and
+.IR rtm_protocol ,
+0 is the wildcard.
+.IP
+.EX
+struct rtmsg {
+    unsigned char rtm_family;   /* Address family of route */
+    unsigned char rtm_dst_len;  /* Length of destination */
+    unsigned char rtm_src_len;  /* Length of source */
+    unsigned char rtm_tos;      /* TOS filter */
+    unsigned char rtm_table;    /* Routing table ID;
+                                   see RTA_TABLE below */
+    unsigned char rtm_protocol; /* Routing protocol; see below */
+    unsigned char rtm_scope;    /* See below */
+    unsigned char rtm_type;     /* See below */
+\&
+    unsigned int  rtm_flags;
+};
+.EE
+.TS
+tab(:);
+lb l.
+rtm_type:Route type
+_
+RTN_UNSPEC:unknown route
+RTN_UNICAST:a gateway or direct route
+RTN_LOCAL:a local interface route
+RTN_BROADCAST:T{
+a local broadcast route (sent as a broadcast)
+T}
+RTN_ANYCAST:T{
+a local broadcast route (sent as a unicast)
+T}
+RTN_MULTICAST:a multicast route
+RTN_BLACKHOLE:a packet dropping route
+RTN_UNREACHABLE:an unreachable destination
+RTN_PROHIBIT:a packet rejection route
+RTN_THROW:continue routing lookup in another table
+RTN_NAT:a network address translation rule
+RTN_XRESOLVE:T{
+refer to an external resolver (not implemented)
+T}
+.TE
+.TS
+tab(:);
+lb l.
+rtm_protocol:Route origin
+_
+RTPROT_UNSPEC:unknown
+RTPROT_REDIRECT:T{
+by an ICMP redirect (currently unused)
+T}
+RTPROT_KERNEL:by the kernel
+RTPROT_BOOT:during boot
+RTPROT_STATIC:by the administrator
+.TE
+.IP
+Values larger than
+.B RTPROT_STATIC
+are not interpreted by the kernel, they are just for user information.
+They may be used to tag the source of a routing information or to
+distinguish between multiple routing daemons.
+See
+.I <linux/rtnetlink.h>
+for the routing daemon identifiers which are already assigned.
+.IP
+.I rtm_scope
+is the distance to the destination:
+.TS
+tab(:);
+lb l.
+RT_SCOPE_UNIVERSE:global route
+RT_SCOPE_SITE:T{
+interior route in the local autonomous system
+T}
+RT_SCOPE_LINK:route on this link
+RT_SCOPE_HOST:route on the local host
+RT_SCOPE_NOWHERE:destination doesn't exist
+.TE
+.IP
+The values between
+.B RT_SCOPE_UNIVERSE
+and
+.B RT_SCOPE_SITE
+are available to the user.
+.IP
+The
+.I rtm_flags
+have the following meanings:
+.TS
+tab(:);
+lb l.
+RTM_F_NOTIFY:T{
+if the route changes, notify the user via rtnetlink
+T}
+RTM_F_CLONED:route is cloned from another route
+RTM_F_EQUALIZE:a multipath equalizer (not yet implemented)
+.TE
+.IP
+.I rtm_table
+specifies the routing table
+.TS
+tab(:);
+lb l.
+RT_TABLE_UNSPEC:an unspecified routing table
+RT_TABLE_DEFAULT:the default table
+RT_TABLE_MAIN:the main table
+RT_TABLE_LOCAL:the local table
+.TE
+.IP
+The user may assign arbitrary values between
+.B RT_TABLE_UNSPEC
+and
+.BR RT_TABLE_DEFAULT .
+.\" Keep table on same page
+.bp +1
+.TS
+tab(:);
+c s s
+lb2 l2 l.
+Attributes
+rta_type:Value type:Description
+_
+RTA_UNSPEC:-:ignored
+RTA_DST:protocol address:Route destination address
+RTA_SRC:protocol address:Route source address
+RTA_IIF:int:Input interface index
+RTA_OIF:int:Output interface index
+RTA_GATEWAY:protocol address:The gateway of the route
+RTA_PRIORITY:int:Priority of route
+RTA_PREFSRC:protocol address:Preferred source address
+RTA_METRICS:int:Route metric
+RTA_MULTIPATH::T{
+Multipath nexthop data
+br
+(see below).
+T}
+RTA_PROTOINFO::No longer used
+RTA_FLOW:int:Route realm
+RTA_CACHEINFO:struct rta_cacheinfo:(see linux/rtnetlink.h)
+RTA_SESSION::No longer used
+RTA_MP_ALGO::No longer used
+RTA_TABLE:int:T{
+Routing table ID; if set,
+.br
+rtm_table is ignored
+T}
+RTA_MARK:int:
+RTA_MFC_STATS:struct rta_mfc_stats:(see linux/rtnetlink.h)
+RTA_VIA:struct rtvia:T{
+Gateway in different AF
+(see below)
+T}
+RTA_NEWDST:protocol address:T{
+Change packet
+destination address
+T}
+RTA_PREF:char:T{
+RFC4191 IPv6 router
+preference (see below)
+T}
+RTA_ENCAP_TYPE:short:T{
+Encapsulation type for
+.br
+lwtunnels (see below)
+T}
+RTA_ENCAP::Defined by RTA_ENCAP_TYPE
+RTA_EXPIRES:int:T{
+Expire time for IPv6
+routes (in seconds)
+T}
+.TE
+.IP
+.B RTA_MULTIPATH
+contains several packed instances of
+.I struct rtnexthop
+together with nested RTAs
+.RB ( RTA_GATEWAY ):
+.IP
+.in +4n
+.EX
+struct rtnexthop {
+    unsigned short rtnh_len;     /* Length of struct + length
+                                    of RTAs */
+    unsigned char  rtnh_flags;   /* Flags (see
+                                    linux/rtnetlink.h) */
+    unsigned char  rtnh_hops;    /* Nexthop priority */
+    int            rtnh_ifindex; /* Interface index for this
+                                    nexthop */
+}
+.EE
+.in
+.IP
+There exist a bunch of
+.B RTNH_*
+macros similar to
+.B RTA_*
+and
+.B NLHDR_*
+macros
+useful to handle these structures.
+.IP
+.in +4n
+.EX
+struct rtvia {
+    unsigned short rtvia_family;
+    unsigned char  rtvia_addr[0];
+};
+.EE
+.in
+.IP
+.I rtvia_addr
+is the address,
+.I rtvia_family
+is its family type.
+.IP
+.B RTA_PREF
+may contain values
+.BR ICMPV6_ROUTER_PREF_LOW ,
+.BR ICMPV6_ROUTER_PREF_MEDIUM ,
+and
+.B ICMPV6_ROUTER_PREF_HIGH
+defined incw
+.IR <linux/icmpv6.h> .
+.IP
+.B RTA_ENCAP_TYPE
+may contain values
+.BR LWTUNNEL_ENCAP_MPLS ,
+.BR LWTUNNEL_ENCAP_IP ,
+.BR LWTUNNEL_ENCAP_ILA ,
+or
+.B LWTUNNEL_ENCAP_IP6
+defined in
+.IR <linux/lwtunnel.h> .
+.IP
+.B Fill these values in!
+.TP
+.B RTM_NEWNEIGH
+.TQ
+.B RTM_DELNEIGH
+.TQ
+.B RTM_GETNEIGH
+Add, remove, or receive information about a neighbor table
+entry (e.g., an ARP entry).
+The message contains an
+.I ndmsg
+structure.
+.IP
+.EX
+struct ndmsg {
+    unsigned char ndm_family;
+    int           ndm_ifindex;  /* Interface index */
+    __u16         ndm_state;    /* State */
+    __u8          ndm_flags;    /* Flags */
+    __u8          ndm_type;
+};
+\&
+struct nda_cacheinfo {
+    __u32         ndm_confirmed;
+    __u32         ndm_used;
+    __u32         ndm_updated;
+    __u32         ndm_refcnt;
+};
+.EE
+.IP
+.I ndm_state
+is a bit mask of the following states:
+.TS
+tab(:);
+lb l.
+NUD_INCOMPLETE:a currently resolving cache entry
+NUD_REACHABLE:a confirmed working cache entry
+NUD_STALE:an expired cache entry
+NUD_DELAY:an entry waiting for a timer
+NUD_PROBE:a cache entry that is currently reprobed
+NUD_FAILED:an invalid cache entry
+NUD_NOARP:a device with no destination cache
+NUD_PERMANENT:a static entry
+.TE
+.IP
+Valid
+.I ndm_flags
+are:
+.TS
+tab(:);
+lb l.
+NTF_PROXY:a proxy arp entry
+NTF_ROUTER:an IPv6 router
+.TE
+.IP
+.\" FIXME .
+.\" document the members of the struct better
+The
+.I rtattr
+struct has the following meanings for the
+.I rta_type
+field:
+.TS
+tab(:);
+lb l.
+NDA_UNSPEC:unknown type
+NDA_DST:a neighbor cache n/w layer destination address
+NDA_LLADDR:a neighbor cache link layer address
+NDA_CACHEINFO:cache statistics
+.TE
+.IP
+If the
+.I rta_type
+field is
+.BR NDA_CACHEINFO ,
+then a
+.I struct nda_cacheinfo
+header follows.
+.TP
+.B RTM_NEWRULE
+.TQ
+.B RTM_DELRULE
+.TQ
+.B RTM_GETRULE
+Add, delete, or retrieve a routing rule.
+Carries a
+.I struct rtmsg
+.TP
+.B RTM_NEWQDISC
+.TQ
+.B RTM_DELQDISC
+.TQ
+.B RTM_GETQDISC
+Add, remove, or get a queueing discipline.
+The message contains a
+.I struct tcmsg
+and may be followed by a series of
+attributes.
+.IP
+.EX
+struct tcmsg {
+    unsigned char    tcm_family;
+    int              tcm_ifindex;   /* interface index */
+    __u32            tcm_handle;    /* Qdisc handle */
+    __u32            tcm_parent;    /* Parent qdisc */
+    __u32            tcm_info;
+};
+.EE
+.TS
+tab(:);
+c s s
+lb2 l2 l.
+Attributes
+rta_type:Value type:Description
+_
+TCA_UNSPEC:-:unspecified
+TCA_KIND:asciiz string:Name of queueing discipline
+TCA_OPTIONS:byte sequence:Qdisc-specific options follow
+TCA_STATS:struct tc_stats:Qdisc statistics
+TCA_XSTATS:qdisc-specific:Module-specific statistics
+TCA_RATE:struct tc_estimator:Rate limit
+.TE
+.IP
+In addition, various other qdisc-module-specific attributes are allowed.
+For more information see the appropriate include files.
+.TP
+.B RTM_NEWTCLASS
+.TQ
+.B RTM_DELTCLASS
+.TQ
+.B RTM_GETTCLASS
+Add, remove, or get a traffic class.
+These messages contain a
+.I struct tcmsg
+as described above.
+.TP
+.B RTM_NEWTFILTER
+.TQ
+.B RTM_DELTFILTER
+.TQ
+.B RTM_GETTFILTER
+Add, remove, or receive information about a traffic filter.
+These messages contain a
+.I struct tcmsg
+as described above.
+.SH VERSIONS
+.B rtnetlink
+is a new feature of Linux 2.2.
+.SH BUGS
+This manual page is incomplete.
+.SH SEE ALSO
+.BR cmsg (3),
+.BR rtnetlink (3),
+.BR ip (7),
+.BR netlink (7)