restructure the page into one single list for all routing commands;

while there, whack anything either out of date or not useful

joint work with claudio

1 files changed, 282 insertions, 377 deletions

diff --git a/sbin/route/route.8 b/sbin/route/route.8
index 4015d2b7ef7..0b4368d29ec 100644
--- a/sbin/route/route.8
+++ b/sbin/route/route.8
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: route.8,v 1.111 2023/02/21 07:47:24 jmc Exp $
+.\"	$OpenBSD: route.8,v 1.112 2023/03/02 17:11:33 jmc Exp $
 .\"	$NetBSD: route.8,v 1.6 1995/03/18 15:00:13 cgd Exp $
 .\"
 .\" Copyright (c) 1983, 1991, 1993
@@ -30,7 +30,7 @@
 .\"
 .\"	@(#)route.8	8.3 (Berkeley) 3/19/94
 .\"
-.Dd $Mdocdate: February 21 2023 $
+.Dd $Mdocdate: March 2 2023 $
 .Dt ROUTE 8
 .Os
 .Sh NAME
@@ -46,33 +46,25 @@
 .Ar arg ...
 .Oc
 .Sh DESCRIPTION
-.Nm
-is a utility used to manually view and manipulate the network routing tables.
-.Nm
-can be used to modify nearly any aspect of the routing policy,
-except packet forwarding, which can be manipulated through the
-.Xr sysctl 8
-command.
-.Pp
+At system start,
+routing tables are initialised and configured by
+.Xr netstart 8 .
 The
 .Nm
-utility supports a limited number of general options,
-but a rich command language enables the user to specify
-any arbitrary request that could be delivered via the
-programmatic interface discussed in
-.Xr route 4 .
+utility can be used to view or manually manipulate the network routing tables.
+Only the superuser may modify the routing tables.
 .Pp
 The options are as follows:
 .Bl -tag -width Ds
 .It Fl d
-Run in debug-only mode, i.e., don't actually modify the routing table.
+Run in debug-only mode, i.e. don't actually modify the routing table.
 .It Fl n
 Bypass attempts to print host and network names symbolically
 when reporting actions.
-(The process of translating between symbolic
+The process of translating between symbolic
 names and numerical equivalents can be quite time consuming, and
 may require correct operation of the network; thus it may be expedient
-to forgo this, especially when attempting to repair networking operations.)
+to forgo this, especially when attempting to repair networking operations.
 .It Fl q
 Suppress all output.
 .It Fl T Ar rtable
@@ -85,23 +77,206 @@ Write routing messages to a fake device
 .Pa ( /dev/null )
 instead of a real routing socket to test route manipulation.
 .It Fl v
-(verbose) Print additional details.
+Print additional details.
 .El
 .Pp
-.Tg command
-The
-.Nm
-utility provides the following simple commands:
+The commands are as follows:
+.Pp
+.Bl -tag -width "XXXX" -compact
+.It Xo
+.Nm route
+.Op Fl dnqtv
+.Op Fl T Ar rtable
+.Cm add
+.Op Ar modifier
+.Ar destination
+.Ar gateway
+.Xc
+.It Xo
+.Nm route
+.Op Fl dnqtv
+.Op Fl T Ar rtable
+.Cm change
+.Op Ar modifier
+.Ar destination
+.Ar gateway
+.Xc
+Add a new route, or modify an existing route, to the host or network at
+.Ar destination .
+.Ar gateway
+is the next-hop intermediary by which packets should be routed.
+See
+.Sx Address notation and interpretation
+for more information.
+.Pp
+A number of modifiers can be used with
+.Cm add
+and
+.Cm change ,
+and as documented with the other commands:
 .Pp
 .Bl -tag -width Ds -compact
+.It Ar flags
+Various flags can be set on routes
+(viewable using
+.Cm show ) :
+.Pp
+.Bl -tag -width -blackhole -compact
+.It Fl blackhole
+silently discard packets
+.It Fl cloning
+generates a new route on use
+.It Fl iface
+destination is directly reachable
+.It Fl llinfo
+validly translates address to link address
+.It Fl mpath
+multiple gateways for a destination exist
+.It Fl nostatic
+pretend route added by kernel or daemon
+.It Fl proto1
+sets protocol specific routing flag #1
+.It Fl proto2
+sets protocol specific routing flag #2
+.It Fl reject
+emits an ICMP unreachable when matched
+.It Fl static
+manually added route (default)
+.El
+.Pp
+The
+.Fl blackhole
+and
+.Fl reject
+flags require a
+.Ar gateway
+to the loopback interface,
+either 127.0.0.1 or ::1.
+.Pp
+.It Oo Fl lock | Fl lockrest Oc Fl expire Ar n
+.It Oo Fl lock | Fl lockrest Oc Fl mtu Ar n
+Specify the lifetime for the route (e.g. if generated by a redirect)
+or the Maximum Transmission Unit (MTU) size for this path, respectively.
+The value
+.Ar n
+is locked if preceded by
+.Fl lock ;
+if preceded by
+.Fl lockrest
+all following
+.Fl expire
+and
+.Fl mtu
+metrics are locked.
+.Pp
+.It Fl host | net
+Interpret
+.Ar destination
+as a host or network, respectively.
+.Pp
+.It Fl ifa Ar address
+.It Fl ifp Ar ifname
+Where the destination and gateway are not sufficient to specify
+the route,
+these modifiers may be used to determine the interface address
+.Pq Fl ifa
+or name
+.Pq Fl ifp .
+.Pp
+.It Fl label Ar label
+Associate the route with a
+.Ar label .
+Route labels can be used to attach arbitrary information to a route.
+.Pp
+.It Fl mpath
+Used to enter multiple gateways for the same destination address (multipath).
+When multiple routes exist for a destination, one route is selected based
+on the source address of the packet.
+The
+.Xr sysctl 8
+variables
+.Va net.inet.ip.multipath
+and
+.Va net.inet6.ip6.multipath
+are used to control multipath routing.
+If set to 1,
+multiple routes with the same priority are used equally;
+if set to 0,
+the first route selected will be used for subsequent packets to that
+destination regardless of source.
+.Pp
+.It Xo
+.Fl mplslabel in Ar label
+.Fl push Ns | Ns Fl pop Ns | Ns Fl swap
+.Op Fl out Ar label
+.Fl inet Ar nexthop
+.Xc
+For MPLS routes,
+specify an ingress LSR to associate a particular label to an IPv4/IPv6 route.
+The MPLS traffic
+.Fl in
+and
+.Fl out
+modifiers are intended to identify the ingress label and, optionally,
+the outgoing one.
+Additionally, one of the following operations must be used:
+.Fl push ,
+.Fl pop
+or
+.Fl swap .
+Route's nexthop can be specified with the modifier
+.Fl inet .
+.Pp
+.It Fl netmask Ar mask
+.It Fl prefixlen Ar len
+Used to add subnet routes with the specified netmask.
+The netmask should be specified after the
+.Ar destination
+parameter.
+If no netmask is specified,
+an implicit one is used for the
+.Dv AF_INET
+family.
+The network mask can also be specified as a prefix length,
+but in that case one of either
+.Fl inet
+or
+.Fl inet6
+must also be specified.
+.Pp
+.It Fl priority Ar n
+Specifies a routing priority.
+If no priority is specified, the kernel will set a priority depending on the
+.Dv RTF_STATIC
+flag to either
+.Dv RTP_STATIC
+or
+.Dv RTP_DEFAULT .
+Note that priority 1 is reserved for kernel use.
+.El
+.Pp
+.It Xo
+.Nm route
+.Op Fl dnqtv
+.Op Fl T Ar rtable
+.Cm del Ns Op Cm ete
+.Ar destination
+.Op Fl priority Ar n
+.Op Ar gateway
+.Xc
+Delete the route to
+.Ar destination .
+If multiple routes to the destination exist,
+a specific route must be selected by specifying the priority
+and/or a gateway.
+.Pp
 .It Xo
 .Nm route
 .Op Fl T Ar rtable
-.Tg
 .Cm exec
 .Op Ar command ...
 .Xc
-Execute a command forcing the process and its children to use the
+Execute a command, forcing the process and its children to use the
 routing table and appropriate routing domain as specified with the
 .Fl T Ar rtable
 option.
@@ -110,16 +285,14 @@ option.
 .Nm route
 .Op Fl nqv
 .Op Fl T Ar rtable
-.Tg
 .Cm flush
-.Op Ar modifier ...
+.Op Ar family
+.Op Fl iface Ar ifname
+.Op Fl priority Ar n
 .Xc
-Delete all gateway entries from the routing table.
-When the address family is specified by any one of the
-.Ar family
-modifiers (listed below), only routes having destinations with addresses
-in the delineated family will be deleted.
-Also, only routes matching a specific interface or priority can be flushed
+Delete all gateway entries from the routing table,
+optionally limited to a specific address family.
+Routes matching a specific interface or priority can be flushed
 by using the
 .Fl iface
 or
@@ -127,48 +300,44 @@ or
 modifiers.
 .Pp
 .It Xo
+.Bk -words
 .Nm route
 .Op Fl nv
 .Op Fl T Ar rtable
-.Tg
 .Cm get
-.Op Ar modifier ...
-.Ar address
+.Ar destination
+.Op Fl priority Ar n
+.Op Ar gateway
+.Ek
 .Xc
-Extract a routing entry from the kernel.
-If
-.Fl gateway
-is specified, only routes whose gateway are in the
-same address family as the destination are shown.
+Display the route to
+.Ar destination .
+If multiple routes to the destination exist,
+a specific route may be selected by specifying the priority
+and/or a gateway.
 .Pp
 .It Xo
 .Nm
 .Op Fl n
 .Op Fl T Ar rtable
-.Tg
 .Cm monitor
-.Op Ar modifier ...
+.Op Ar family
+.Op Fl iface
 .Xc
-Continuously report any changes to the routing information base,
-routing lookup misses, or suspected network partitionings.
-.Pp
-When the address family is specified by any one of the
-.Ar family
-modifiers (listed below), only routes having destinations with addresses
-in the delineated family will be shown.
-If the
+Continuously report any changes to the routing information base.
+The information reported can be limited to a specific address family,
+a specific routing table
+using the
+.Fl T
+option,
+or interface specific messages (link state changes) using the
 .Fl iface
-modifier is used, only interface specific messages (link state changes)
-are shown.
-If a routing table is supplied with
-.Fl T ,
-only changes in that routing table will be displayed.
+modifier.
 .Pp
 .It Xo
 .Ic route
 .Op Fl dtv
 .Op Fl T Ar rtable
-.Tg
 .Cm nameserver
 .Ar interface
 .Op Ar address ...
@@ -184,12 +353,11 @@ a request to remove the nameservers for the given interface is sent.
 .Nm route
 .Op Fl nv
 .Op Fl T Ar rtable
-.Tg
 .Cm show
 .Op Ar family
 .Op Fl gateway
 .Op Fl label Ar label
-.Op Fl priority Ar priority
+.Op Fl priority Ar n
 .Xc
 Display the routing table.
 .Pp
@@ -224,7 +392,7 @@ The mapping between letters and flags is:
 .It 1 Ta Dv RTF_PROTO1 Ta "Protocol specific routing flag #1."
 .It 2 Ta Dv RTF_PROTO2 Ta "Protocol specific routing flag #2."
 .It 3 Ta Dv RTF_PROTO3 Ta "Protocol specific routing flag #3."
-.It B Ta Dv RTF_BLACKHOLE Ta "Just discard pkts (during updates)."
+.It B Ta Dv RTF_BLACKHOLE Ta "Just discard packets."
 .It b Ta Dv RTF_BROADCAST Ta "Correspond to a local broadcast address."
 .It C Ta Dv RTF_CLONING Ta "Generate new routes on use."
 .It c Ta Dv RTF_CLONED Ta "Cloned routes (generated from RTF_CLONING)."
@@ -247,328 +415,79 @@ The mapping between letters and flags is:
 .It Xo
 .Ic route
 .Op Fl T Ar rtable
-.Tg
 .Cm sourceaddr
 .Op Fl inet Ns | Ns Fl inet6
+.Op Fl ifp Ar ifname
 .Op Ar address
 .Xc
-.It Xo
-.Ic route
-.Op Fl T Ar rtable
-.Tg
-.Cm sourceaddr
-.Op Fl inet Ns | Ns Fl inet6
-.Fl ifp
-.Ar interface
-.Xc
 Set the preferred source address.
 If
 .Ar address
-is the word "default", 0.0.0.0 or ::, source address will
-be chosen by the kernel for the matching address family.
-When
-.Ar address
-is omitted, preferred source address is printed if set.
+is omitted, the preferred source address is printed, if set.
 If
 .Fl ifp
-is used, source will use IP assigned to
-.Ar interface .
-The preferred source will not be used when:
-.Pp
-.Bl -bullet -compact
-.It
-destination is on-link
-.It
-source address is assigned to a disabled interface
-.El
+is used, the address assigned to the interface
+.Ar ifname
+is used.
+The preferred source address is not used if the destination is on-link
+or the source address is assigned to a disabled interface.
 .El
+.Ss Address notation and interpretation
+Addresses are assumed to be IPv4 unless they contain a colon,
+in which case they are treated as IPv6.
+Alternatively they may be specified as belonging to a particular address family
+using one of the following modifiers:
 .Pp
-.Tg destination
-.Tg gateway
-The other commands relating to adding, changing, or deleting routes
-have the syntax:
-.Pp
-.Bl -tag -width Fl -compact
-.It Xo
-.Nm route
-.Op Fl dnqtv
-.Op Fl T Ar rtable
-.Tg
-.Cm add
-.Op Ar modifier ...
-.Ar destination gateway
-.Xc
-.It Xo
-.Nm route
-.Op Fl dnqtv
-.Op Fl T Ar rtable
-.Tg
-.Cm change
-.Op Ar modifier ...
-.Ar destination gateway
-.Xc
-.It Xo
-.Nm route
-.Op Fl dnqtv
-.Op Fl T Ar rtable
-.Tg delete
-.Tg
-.Cm del Ns Op Cm ete
-.Op Ar modifier ...
-.Ar destination gateway
-.Xc
+.Bl -tag -width "-inet6XXX" -offset indent -compact
+.It Fl inet
+IPv4 addresses;
+see
+.Xr ip 4
+.It Fl inet6
+IPv6 addresses;
+see
+.Xr ip6 4
+.It Fl link
+hardware (link-level) addresses
+.It Fl mpls
+MPLS addresses
+.It Fl sa
+actual
+.Vt sockaddr
+data, in hexadecimal format
 .El
 .Pp
 .Ar destination
-is the destination host or network;
-.Ar gateway
-is the next-hop intermediary via which packets should be routed.
-Routes to a particular host may be distinguished from those to
-a network by interpreting the Internet address specified as the
-.Ar destination
-argument.
-The optional modifiers
-.Tg
-.Fl net
-and
-.Tg
-.Fl host
-cause the destination to be interpreted as a network or a host, respectively.
-Otherwise, type is chosen based on the following rules:
-.Pp
-.Tg default
-The route is assumed to be to a network if any of the following apply to
-.Ar destination :
+is assumed to be a route to a network
+if any of the following apply:
 .Pp
 .Bl -bullet -compact
 .It
-it is the word "default", equivalent to 0/0
+the
+.Fl net
+modifier is used
 .It
-it is an IPv4 address with less than 3 dots
+it is the word "default", equivalent to 0/0 or ::/0
 .It
-it is an IPv4 address with a
+it is an address with a
 .Dq / Ns Em XX
-suffix (where
+suffix, where
 .Em XX
 is the number of bits in the network portion of the address
-and is less than 32)
 .It
-it is an IPv6 address with a
-.Dq / Ns Em XX
-suffix (where
-.Em XX
-is the number of bits in the network portion of the address
-and is less than 128)
-.It
-it is the symbolic name of a network.
-.El
-.Pp
-If
-.Ar destination
-is a valid IP address or host name, it is presumed to be a route to a host.
-.Pp
-For example,
-.Li 192.168.1.1
-is interpreted as
-.Fl host Li 192.168.1.1
-and
-.Li 192.168.1
-is interpreted as
-.Fl net Li 192.168.1 .
-Note, however, that
-.Li 192.168.2.0
-will be interpreted as
-.Fl host Li 192.168.2.0
-since it is a complete IP address with 3 dots.
-In this case the number of bits in the network portion of the address must
-be explicitly listed, for example
-.Li 192.168.2.0/24 ,
-.Li 192.168.2/24 ,
-or alternately
-.Li 192.168.2 .
-.Pp
-If the destination is directly reachable
-via an interface requiring
-no intermediary system to act as a gateway, the
-.Tg
-.Fl iface
-modifier should be specified;
-the gateway given is the address of this host on the common network,
-indicating the interface to be used for transmission.
-.Pp
-To allow addresses to be interpreted as belonging to a particular address
-family (as well as for use in the
-.Tg
-.Ar family
-arguments to some commands), the following modifiers may be used:
-.Pp
-.Bl -tag -width -inet6 -compact
-.It Fl inet
-Internet Protocol version 4 (IPv4) addresses
-(see
-.Xr ip 4 )
-.It Fl inet6
-Internet Protocol version 6 (IPv6) addresses
-(see
-.Xr ip6 4 )
-.It Fl link
-Hardware (link-level) addresses
-.It Fl mpls
-MPLS addresses
-.It Fl sa
-Actual
-.Vt sockaddr
-data, in hexadecimal format
-.El
-.Pp
-In the absence of modifiers, an address is assumed to be IPv4,
-unless containing a
-.Sq :\&
-character, when it is treated as IPv6.
-.Pp
-The optional modifier
-.Fl link
-specifies that all subsequent addresses are specified as link-level addresses,
-and the names must be numeric specifications rather than
-symbolic names.
-.Pp
-The optional
-.Tg
+it specifies the network portion either with
 .Fl netmask
-qualifier is intended to manually add subnet routes with
-netmasks different from that of the implied network interface
-(as would otherwise be communicated using a routing protocol).
-One specifies an additional ensuing address parameter
-(to be interpreted as a network mask).
-The implicit network mask generated in the
-.Dv AF_INET
-case
-can be overridden by making sure this option follows the
-.Ar destination
-parameter.
-.Tg
-.Fl prefixlen
-is also available for a similar purpose, for IPv6/v4.
-.Pp
-A specific routing priority can be specified with the optional
-.Tg
-.Fl priority
-qualifier.
-If no priority is specified, the kernel will set a priority depending on the
-.Dv RTF_STATIC
-flag to either
-.Dv RTP_STATIC
 or
-.Dv RTP_DEFAULT .
-Note that priority 1 is reserved for kernel use.
-.Pp
-The optional
-.Tg
-.Fl mpath
-modifier needs to be specified with the
-.Cm add
-command to be able to enter multiple gateways for the same destination address
-(multipath).
-When multiple routes exist for a destination, one route is selected based
-on the source address of the packet.
-The
-.Xr sysctl 8
-variables
-.Va net.inet.ip.multipath
-and
-.Va net.inet6.ip6.multipath
-are used to control multipath routing.
-If set to 1,
-multiple routes with the same priority are used equally;
-if set to 0,
-the first route selected will be used for subsequent packets to that
-destination regardless of source.
-.Pp
-When inserting MPLS routes,
-particular modifiers must be used.
-The
-.Tg
-.Fl mplslabel
-modifier needs to be specified in an ingress LSR to associate a particular
-label to an IPv4/IPv6 route.
-The MPLS traffic
-.Fl in
-and
-.Fl out
-modifiers are intended to identify the ingress label and, optionally,
-the outgoing one.
-Additionally, one of the following operations must be used:
-.Fl push ,
-.Fl pop
-and
-.Fl swap .
-Route's nexthop can be specified with the modifier
-.Fl inet .
-.Pp
-Routes have associated flags which influence operation of the protocols
-when sending to destinations matched by the routes.
-These flags may be set (or sometimes cleared)
-by indicating the following corresponding modifiers:
-.Bl -column "-blackhole" "RTF_BLACKHOLE" "description"
-.It Fl blackhole Ta Dv RTF_BLACKHOLE Ta "silently discard pkts (during updates)"
-.It Fl cloning   Ta Dv RTF_CLONING   Ta "generates a new route on use"
-.It Fl iface     Ta Pf ~ Dv RTF_GATEWAY Ta "destination is directly reachable"
-.It Fl llinfo    Ta Dv RTF_LLINFO    Ta "validly translates proto addr to link addr"
-.It Fl mpath     Ta Dv RTF_MPATH     Ta "multiple gateways for a destination exist"
-.It Fl nostatic  Ta Pf ~ Dv RTF_STATIC Ta "pretend route added by kernel or daemon"
-.It Fl proto1    Ta Dv RTF_PROTO1    Ta "set protocol specific routing flag #1"
-.It Fl proto2    Ta Dv RTF_PROTO2    Ta "set protocol specific routing flag #2"
-.It Fl reject    Ta Dv RTF_REJECT    Ta "emit an ICMP unreachable when matched"
-.It Fl static    Ta Dv RTF_STATIC    Ta "manually added route"
-.El
-.Pp
-The optional modifiers
-.Fl expire
-and
-.Fl mtu
-provide initial values to quantities maintained in the routing entry
-by transport level protocols, such as TCP (see
-.Xr tcp 4 ) .
-They have the following meanings:
-.Pp
-.Bl -tag -width "-priority n" -compact
-.It Fl expire Ar n
-Lifetime for route (e.g., if generated by a redirect).
-.It Fl mtu Ar n
-Maximum transmission unit (MTU) size for this path.
+.Fl prefixlen
 .El
 .Pp
-These may be individually locked by preceding each such modifier to
-be locked by
-the
-.Tg
-.Fl lock
-meta-modifier, or one can
-specify that all ensuing metrics may be locked by the
-.Fl lockrest
-meta-modifier.
-.Pp
-In a
-.Cm change
-or
-.Cm add
-command where the destination and gateway are not sufficient to specify
-the route, the
-.Tg
-.Fl ifp
-or
-.Tg
-.Fl ifa
-modifiers may be used to determine the interface name or interface address.
-.Pp
-The optional
-.Tg
-.Fl label
-modifier specifies on route addition or modification that the route
-should have the given
-.Em label
-associated with it.
-Route labels can be used to attach arbitrary information to a route.
+If
+.Ar destination
+is a valid IP address or host name,
+or the
+.Fl host
+modifier is used,
+it is assumed to be a route to a host.
 .Pp
 All symbolic names specified for a
 .Ar destination
@@ -576,18 +495,6 @@ or
 .Ar gateway
 are looked up using
 .Xr gethostbyname 3 .
-.Pp
-.Nm
-uses a routing socket (see
-.Xr route 4 )
-and the message types
-.Dv RTM_ADD ,
-.Dv RTM_DELETE ,
-.Dv RTM_GET ,
-and
-.Dv RTM_CHANGE .
-As such, only the superuser may modify
-the routing tables.
 .Sh FILES
 .Bl -tag -width "/etc/mygate" -compact
 .It Pa /etc/hosts
@@ -596,6 +503,11 @@ host and network name database
 default gateway address
 .El
 .Sh EXAMPLES
+Show the current IPv4 routing tables,
+without attempting to print hostnames symbolically:
+.Pp
+.Dl $ route -n show -inet
+.Pp
 Add a static
 .Xr inet 4
 route to the 192.168.5.0/24 network via the 192.168.0.1 gateway:
@@ -651,21 +563,14 @@ low on resources and was unable to allocate memory
 to create the new entry.
 .El
 .Sh SEE ALSO
-.Xr id 1 ,
-.Xr netstat 1 ,
 .Xr gethostbyname 3 ,
-.Xr netintro 4 ,
+.Xr inet_net_pton 3 ,
+.Xr inet_pton 3 ,
 .Xr route 4 ,
 .Xr rtable 4 ,
-.Xr tcp 4 ,
 .Xr hosts 5 ,
 .Xr mygate 5 ,
-.Xr resolv.conf 5 ,
-.Xr bgpd 8 ,
-.Xr ospfd 8 ,
-.Xr resolvd 8 ,
-.Xr ripd 8 ,
-.Xr sysctl 8
+.Xr netstart 8
 .Sh HISTORY
 The
 .Nm