diff options
| -rw-r--r-- | sbin/route/route.8 | 659 |
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 |