652 lines
16 KiB
Groff
652 lines
16 KiB
Groff
.\" $OpenBSD: route.8,v 1.119 2023/08/02 23:34:13 aisha Exp $
|
|
.\" $NetBSD: route.8,v 1.6 1995/03/18 15:00:13 cgd Exp $
|
|
.\"
|
|
.\" Copyright (c) 1983, 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" 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.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
|
|
.\"
|
|
.\" @(#)route.8 8.3 (Berkeley) 3/19/94
|
|
.\"
|
|
.Dd $Mdocdate: August 2 2023 $
|
|
.Dt ROUTE 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm route
|
|
.Nd manually manipulate the routing tables
|
|
.Sh SYNOPSIS
|
|
.Nm route
|
|
.Op Fl dnqtv
|
|
.Op Fl T Ar rtable
|
|
.Ar command
|
|
.Oo
|
|
.Op Ar modifier ...
|
|
.Ar arg ...
|
|
.Oc
|
|
.Sh DESCRIPTION
|
|
At system start,
|
|
routing tables are initialised and configured by
|
|
.Xr netstart 8 .
|
|
The
|
|
.Nm
|
|
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.
|
|
.It Fl n
|
|
Bypass attempts to print host and network names symbolically
|
|
when reporting actions.
|
|
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.
|
|
.It Fl q
|
|
Suppress all output.
|
|
.It Fl T Ar rtable
|
|
Select an alternate routing table to modify or query.
|
|
The default is to use the current routing table.
|
|
The current routing table can be displayed with
|
|
.Xr id 1 .
|
|
.It Fl t
|
|
Write routing messages to a fake device
|
|
.Pa ( /dev/null )
|
|
instead of a real routing socket to test route manipulation.
|
|
.It Fl v
|
|
Print additional details.
|
|
.El
|
|
.Pp
|
|
The commands are as follows:
|
|
.Pp
|
|
.Bl -tag -width "XXXX" -compact
|
|
.It Xo
|
|
.Nm route
|
|
.Op Fl dnqtv
|
|
.Op Fl T Ar rtable
|
|
.Tg
|
|
.Cm add
|
|
.Op Ar modifier
|
|
.Ar destination
|
|
.Ar gateway
|
|
.Xc
|
|
.It Xo
|
|
.Nm route
|
|
.Op Fl dnqtv
|
|
.Op Fl T Ar rtable
|
|
.Tg
|
|
.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
|
|
.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 .
|
|
The route's gateway can be specified using the
|
|
.Fl inet
|
|
or
|
|
.Fl inet6
|
|
modifier before the address.
|
|
.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
|
|
.Tg delete
|
|
.Tg
|
|
.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
|
|
.Ar command
|
|
.Op Ar arg ...
|
|
.Xc
|
|
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.
|
|
.Pp
|
|
.It Xo
|
|
.Nm route
|
|
.Op Fl nqv
|
|
.Op Fl T Ar rtable
|
|
.Tg
|
|
.Cm flush
|
|
.Op Ar family
|
|
.Op Fl iface Ar ifname
|
|
.Op Fl priority Ar n
|
|
.Xc
|
|
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
|
|
.Fl priority
|
|
modifiers.
|
|
.Pp
|
|
.It Xo
|
|
.Bk -words
|
|
.Nm route
|
|
.Op Fl nv
|
|
.Op Fl T Ar rtable
|
|
.Tg
|
|
.Cm get
|
|
.Ar destination
|
|
.Op Fl priority Ar n
|
|
.Op Ar gateway
|
|
.Ek
|
|
.Xc
|
|
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 family
|
|
.Op Fl iface
|
|
.Xc
|
|
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.
|
|
.Pp
|
|
.It Xo
|
|
.Ic route
|
|
.Op Fl dtv
|
|
.Op Fl T Ar rtable
|
|
.Tg
|
|
.Cm nameserver
|
|
.Ar interface
|
|
.Op Ar address ...
|
|
.Xc
|
|
Broadcast a list of up to five nameserver address proposals to
|
|
.Xr resolvd 8 ,
|
|
which is used to update the list of nameservers for the given interface in
|
|
.Xr resolv.conf 5 .
|
|
If no address is given,
|
|
a request to remove the nameservers for the given interface is sent.
|
|
.Pp
|
|
.It Xo
|
|
.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 n
|
|
.Xc
|
|
Display the routing table.
|
|
.Pp
|
|
If
|
|
.Fl gateway
|
|
is specified, only routes whose gateway are in the
|
|
same address family as the destination are shown.
|
|
.Pp
|
|
If
|
|
.Fl label
|
|
is specified, only routes with the specified label are shown.
|
|
.Pp
|
|
If
|
|
.Fl priority
|
|
is specified, only routes with the specified priority are shown.
|
|
It may be specified by number or one of
|
|
.Cm local ,
|
|
.Cm connected ,
|
|
.Cm static ,
|
|
.Cm ospf ,
|
|
.Cm rip ,
|
|
or
|
|
.Cm bgp .
|
|
If the priority is negative, then routes that do not match the numeric
|
|
priority are shown.
|
|
.Pp
|
|
Within the output of
|
|
.Cm show ,
|
|
the "Flags" column indicates what flags are set on the route.
|
|
The mapping between letters and flags is:
|
|
.Bl -column "1" "RTF_BLACKHOLE" "Protocol specific routing flag #1."
|
|
.It Dv 1 Ta Dv RTF_PROTO1 Ta "Protocol specific routing flag #1."
|
|
.It Dv 2 Ta Dv RTF_PROTO2 Ta "Protocol specific routing flag #2."
|
|
.It Dv 3 Ta Dv RTF_PROTO3 Ta "Protocol specific routing flag #3."
|
|
.It Dv B Ta Dv RTF_BLACKHOLE Ta "Just discard packets."
|
|
.It Dv b Ta Dv RTF_BROADCAST Ta "Correspond to a local broadcast address."
|
|
.It Dv C Ta Dv RTF_CLONING Ta "Generate new routes on use."
|
|
.It Dv c Ta Dv RTF_CLONED Ta "Cloned routes (generated from RTF_CLONING)."
|
|
.It Dv D Ta Dv RTF_DYNAMIC Ta "Created dynamically (by redirect)."
|
|
.It Dv G Ta Dv RTF_GATEWAY Ta "Dest requires forwarding by intermediary."
|
|
.It Dv H Ta Dv RTF_HOST Ta "Host entry (net otherwise)."
|
|
.It Dv h Ta Dv RTF_CACHED Ta "Referenced by gateway route."
|
|
.It Dv L Ta Dv RTF_LLINFO Ta "Valid protocol to link address translation."
|
|
.It Dv l Ta Dv RTF_LOCAL Ta "Correspond to a local address."
|
|
.It Dv M Ta Dv RTF_MODIFIED Ta "Modified dynamically (by redirect)."
|
|
.It Dv m Ta Dv RTF_MULTICAST Ta "Correspond to a multicast address."
|
|
.It Dv n Ta Dv RTF_CONNECTED Ta "Interface route."
|
|
.It Dv P Ta Dv RTF_MPATH Ta "Multipath route."
|
|
.It Dv R Ta Dv RTF_REJECT Ta "Host or net unreachable."
|
|
.It Dv S Ta Dv RTF_STATIC Ta "Manually added."
|
|
.It Dv T Ta Dv RTF_MPLS Ta "MPLS route."
|
|
.It Dv U Ta Dv RTF_UP Ta "Route usable."
|
|
.El
|
|
.Pp
|
|
.It Xo
|
|
.Ic route
|
|
.Op Fl T Ar rtable
|
|
.Tg
|
|
.Cm sourceaddr
|
|
.Op Fl ifp Ar ifname | Ar address
|
|
.Xc
|
|
Set the preferred source address to
|
|
.Ar address .
|
|
The source address can be set to the address assigned to interface
|
|
.Ar ifname
|
|
if
|
|
.Fl ifp
|
|
is specified,
|
|
or reset by setting the address to zero.
|
|
If no arguments are given,
|
|
the preferred source addresses are printed.
|
|
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
|
|
.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 assumed to be a route to a network
|
|
if any of the following apply:
|
|
.Pp
|
|
.Bl -bullet -compact
|
|
.It
|
|
the
|
|
.Fl net
|
|
modifier is used
|
|
.It
|
|
it is the word "default", equivalent to 0/0 or ::/0
|
|
.It
|
|
it is an address with a
|
|
.Dq / Ns Em XX
|
|
suffix, where
|
|
.Em XX
|
|
is the number of bits in the network portion of the address
|
|
.It
|
|
it specifies the network portion either with
|
|
.Fl netmask
|
|
or
|
|
.Fl prefixlen
|
|
.El
|
|
.Pp
|
|
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
|
|
or
|
|
.Ar gateway
|
|
are looked up using
|
|
.Xr gethostbyname 3 .
|
|
.Sh FILES
|
|
.Bl -tag -width "/etc/mygate" -compact
|
|
.It Pa /etc/hosts
|
|
host and network name database
|
|
.It Pa /etc/mygate
|
|
default gateway address
|
|
.El
|
|
.Sh EXIT STATUS
|
|
For commands other than
|
|
.Cm exec ,
|
|
the
|
|
.Nm
|
|
utility exits 0 on success, and >0 if an error occurs.
|
|
.Pp
|
|
For the
|
|
.Cm exec
|
|
command the
|
|
.Nm
|
|
utility exits with the exit status of
|
|
.Ar command
|
|
if it could be invoked.
|
|
Otherwise the
|
|
.Nm
|
|
utility exits with one of the following values:
|
|
.Bl -tag -width Ds
|
|
.It 1
|
|
An invalid command line option was passed to
|
|
.Nm
|
|
or setting the routing table failed.
|
|
.It 126
|
|
.Ar command
|
|
was found but could not be invoked.
|
|
.It 127
|
|
.Ar command
|
|
could not be found.
|
|
.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:
|
|
.Pp
|
|
.Dl # route add -inet 192.168.5.0/24 192.168.0.1
|
|
.Pp
|
|
Amend the
|
|
.Xr inet 4
|
|
route to the 192.168.5.0/24 network to use the 192.168.0.2 gateway:
|
|
.Pp
|
|
.Dl # route change -inet 192.168.5.0/24 192.168.0.2
|
|
.Pp
|
|
Delete the
|
|
.Xr inet 4
|
|
route to the 192.168.5.0/24 network:
|
|
.Pp
|
|
.Dl # route delete -inet 192.168.5.0/24
|
|
.Pp
|
|
Add a static
|
|
.Xr inet6 4
|
|
route to a host which is on the vio0 interface that is outside your prefix,
|
|
and use that host as a default gateway, as used by some hosting providers:
|
|
.Pp
|
|
.Dl # route add -inet6 2001:db8:efef::1 -cloning -link -iface vio0
|
|
.Dl # route add -inet6 default 2001:db8:efef::1
|
|
.Sh DIAGNOSTICS
|
|
.Bl -diag
|
|
.It "%s: gateway %s flags %x"
|
|
The specified route is being added to or deleted from the tables.
|
|
If the gateway address used was not the primary address of the gateway
|
|
(the first one returned by
|
|
.Xr gethostbyname 3 ) ,
|
|
the gateway address is printed numerically as well as symbolically.
|
|
.It "%s %s done"
|
|
When the
|
|
.Cm flush
|
|
command is specified, each routing table entry deleted
|
|
is indicated with a message of this form.
|
|
.It "Network is unreachable"
|
|
An attempt to add a route failed because the gateway listed was not
|
|
on a directly connected network.
|
|
The next-hop gateway must be given.
|
|
.It "not in table"
|
|
A
|
|
.Cm delete
|
|
operation was attempted for an entry which
|
|
wasn't present in the tables.
|
|
.It "routing table overflow"
|
|
An
|
|
.Cm add
|
|
operation was attempted, but the system was
|
|
low on resources and was unable to allocate memory
|
|
to create the new entry.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr gethostbyname 3 ,
|
|
.Xr inet_net_pton 3 ,
|
|
.Xr inet_pton 3 ,
|
|
.Xr route 4 ,
|
|
.Xr rtable 4 ,
|
|
.Xr hosts 5 ,
|
|
.Xr mygate 5 ,
|
|
.Xr netstart 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
command appeared in
|
|
.Bx 4.2 .
|
|
IPv6 support was added by WIDE/KAME project.
|
|
.Pp
|
|
The
|
|
.Fl recvpipe ,
|
|
.Fl hopcount ,
|
|
.Fl sendpipe ,
|
|
.Fl ssthresh ,
|
|
.Fl rtt ,
|
|
and
|
|
.Fl rttvar
|
|
modifiers used to be used to initialize various quantities in routing
|
|
table entries.
|
|
The routing system no longer uses these values and the modifiers
|
|
exist now only for compatibility with other operating systems.
|
|
.Sh BUGS
|
|
Some uses of the
|
|
.Fl ifa
|
|
or
|
|
.Fl ifp
|
|
modifiers with the
|
|
.Cm add
|
|
command will incorrectly fail with a
|
|
.Dq Network is unreachable
|
|
message if there is no default route.
|
|
See case
|
|
.Dv RTM_ADD
|
|
in
|
|
.Fn route_output
|
|
from
|
|
.Pa sys/net/rtsock.c
|
|
for details.
|