470 lines
13 KiB
Groff
470 lines
13 KiB
Groff
.\" $NetBSD: route.8,v 1.62 2020/08/29 19:27:08 christos 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.4 (Berkeley) 6/1/94
|
|
.\"
|
|
.Dd August 29, 2020
|
|
.Dt ROUTE 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm route
|
|
.Nd manually manipulate the routing tables
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl dfLnqSsTtv
|
|
.Ar command
|
|
.Oo
|
|
.Op Ar modifiers
|
|
.Ar args
|
|
.Oc
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is a utility used to manually manipulate the network
|
|
routing tables.
|
|
Except for setting up the default route, it is normally not needed,
|
|
as a system routing table management daemon such as
|
|
.Xr routed 8 ,
|
|
should tend to this task.
|
|
.Pp
|
|
.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
|
|
The
|
|
.Nm
|
|
utility supports a limited number of general options,
|
|
but a rich command language, enabling the user to specify
|
|
any arbitrary request that could be delivered via the
|
|
programmatic interface discussed in
|
|
.Xr route 4 .
|
|
.Bl -tag -width Ds
|
|
.It Fl d
|
|
Turn on debugging
|
|
.It Fl f
|
|
Remove all routes (as per
|
|
.Cm flush ) .
|
|
If used in conjunction with the
|
|
.Cm add ,
|
|
.Cm change ,
|
|
.Cm delete
|
|
or
|
|
.Cm get
|
|
commands,
|
|
.Nm
|
|
removes the routes before performing the command.
|
|
.It Fl L
|
|
Don't show link layer entries in routing table.
|
|
.It Fl n
|
|
Bypasses 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 from commands that manipulate the routing table.
|
|
.It Fl S
|
|
Print a space when a flag is missing so that flags are vertically aligned
|
|
instead of printing the flags that are set as a contiguous string.
|
|
.It Fl s
|
|
(short) Suppresses all output from a
|
|
.Cm get
|
|
command except for the actual gateway that will be used.
|
|
How the gateway is printed depends on the type of route being looked up.
|
|
.It Fl T
|
|
Show tags in the route display.
|
|
.It Fl t
|
|
Test only, don't perform any actions.
|
|
.It Fl v
|
|
(verbose) Print additional details.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility provides several commands:
|
|
.Pp
|
|
.Bl -tag -width Fl -compact
|
|
.It Cm add
|
|
Add a route.
|
|
.It Cm flush
|
|
Remove all routes.
|
|
.It Cm flushall
|
|
Remove all routes including the default gateway.
|
|
.It Cm delete
|
|
Delete a specific route.
|
|
.It Cm change
|
|
Change aspects of a route (such as its gateway).
|
|
.It Cm get
|
|
Lookup and display the route for a destination.
|
|
.It Cm show
|
|
Print out the route table similar to "netstat \-r" (see
|
|
.Xr netstat 1 ) .
|
|
.It Cm monitor
|
|
Continuously report any changes to the routing information base,
|
|
routing lookup misses, or suspected network partitionings.
|
|
.El
|
|
.Pp
|
|
The monitor command has the syntax
|
|
.Pp
|
|
.Bd -filled -offset indent -compact
|
|
.Nm
|
|
.Op Fl n
|
|
.Cm monitor
|
|
.Op Fl c Ar count
|
|
.Ed
|
|
.Pp
|
|
If
|
|
.Ar count
|
|
is specified,
|
|
.Nm
|
|
exits after receiving
|
|
.Ar count
|
|
routing messages.
|
|
.Pp
|
|
The flush command has the syntax
|
|
.Pp
|
|
.Bd -filled -offset indent -compact
|
|
.Nm
|
|
.Op Fl n
|
|
.Cm flush
|
|
.Op Ar family
|
|
.Ed
|
|
.Pp
|
|
If the
|
|
.Cm flush
|
|
command is specified,
|
|
.Nm
|
|
will ``flush'' the routing tables of all gateway entries.
|
|
When the address family is specified by any of the
|
|
.Fl atalk ,
|
|
.Fl inet ,
|
|
.Fl inet6 ,
|
|
or
|
|
.Fl mpls
|
|
modifiers, only routes having destinations with addresses in the
|
|
delineated family will be manipulated.
|
|
.Pp
|
|
The other commands have the following syntax:
|
|
.Pp
|
|
.Bd -filled -offset indent -compact
|
|
.Nm
|
|
.Op Fl n
|
|
.Ar command
|
|
.Op Fl net No \&| Fl host
|
|
.Ar destination gateway
|
|
.Ed
|
|
.Pp
|
|
where
|
|
.Ar destination
|
|
is the destination host or network, and
|
|
.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
|
|
.Fl net
|
|
and
|
|
.Fl host
|
|
force the destination to be interpreted as a network or a host, respectively.
|
|
Otherwise, if the
|
|
.Ar destination
|
|
has a ``local address part'' of
|
|
.Dv INADDR_ANY ,
|
|
or if the
|
|
.Ar destination
|
|
is the symbolic name of a network, then the route is
|
|
assumed to be to a network; otherwise, it is presumed to be a
|
|
route to a host.
|
|
Optionally, the
|
|
.Ar destination
|
|
can also be specified in the
|
|
.Ar net Ns / Ns Ar bits
|
|
format.
|
|
.Pp
|
|
For example,
|
|
.Li 128.32
|
|
is interpreted as
|
|
.Fl host Li 128.0.0.32 ;
|
|
.Li 128.32.130
|
|
is interpreted as
|
|
.Fl host Li 128.32.0.130 ;
|
|
.Fl net Li 128.32
|
|
is interpreted as
|
|
.Li 128.32.0.0 ;
|
|
and
|
|
.Fl net Li 128.32.130
|
|
is interpreted as
|
|
.Li 128.32.130.0 .
|
|
.Pp
|
|
The keyword
|
|
.Cm default
|
|
can be used as the
|
|
.Ar destination
|
|
to set up a default route to a smart
|
|
.Ar gateway .
|
|
If no other routes match, this default route will be used as a last resort.
|
|
.Pp
|
|
If the destination is directly reachable
|
|
via an interface requiring
|
|
no intermediary system to act as a gateway, the
|
|
.Fl interface
|
|
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
|
|
The optional modifiers
|
|
.Fl atalk ,
|
|
and
|
|
.Fl link
|
|
specify that all subsequent addresses are in the
|
|
.Tn AppleTalk
|
|
address family,
|
|
or are specified as link-level addresses in the form described in
|
|
.Xr link_addr 3 ,
|
|
and the names must be numeric specifications rather than
|
|
symbolic names.
|
|
.Pp
|
|
The optional modifier
|
|
.Fl tag
|
|
specifies an address associated with the route.
|
|
How the address is used is specific to the address family of
|
|
the destination and the interface used to forward the packet.
|
|
Currently route tags are consumed only by the
|
|
.Xr mpls 4
|
|
stack; therefore
|
|
.Nm
|
|
assumes that the subsequent addresses are in the
|
|
.Tn MPLS
|
|
address family.
|
|
See
|
|
.Xr mpls 4
|
|
for examples of setting routes involving MPLS.
|
|
.Pp
|
|
The optional
|
|
.Fl netmask
|
|
qualifier is intended
|
|
to achieve the effect of an
|
|
.Tn ESIS
|
|
redirect with the netmask option,
|
|
or to manually add subnet routes with
|
|
netmasks different from that of the implied network interface
|
|
(as would otherwise be communicated using the OSPF or ISIS routing protocols).
|
|
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 destination parameter.
|
|
.Fl prefixlen
|
|
is also available for similar purpose, in IPv4 and IPv6 case.
|
|
.Pp
|
|
Routes have associated flags which influence operation of the protocols
|
|
when sending to destinations matched by the routes.
|
|
These flags are displayed using the following ID characters in the routing
|
|
display and may be set (or sometimes cleared)
|
|
by indicating the following corresponding modifiers:
|
|
.Bl -column "ID" "xnoblackhole" "xRTF_BLACKHOLE" "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
|
|
.It Sy "ID" Ta Sy "Modifier" Ta Sy " Flag Bit" Ta Sy "Description"
|
|
.It Li " " Ta -iface Ta ~RTF_GATEWAY Ta destination is directly reachable
|
|
.It Li 1 Ta -proto1 Ta " RTF_PROTO1" Ta set protocol specific flag #1
|
|
.It Li 2 Ta -proto2 Ta " RTF_PROTO2" Ta set protocol specific flag #2
|
|
.It Li B Ta -blackhole Ta " RTF_BLACKHOLE" Ta discard pkts (during updates)
|
|
.It Li b Ta "" Ta " RTF_BROADCAST" Ta Route represents a broadcast address
|
|
.It Li " " Ta -noblackhole Ta ~RTF_BLACKHOLE Ta clear blackhole flag
|
|
.It Li C Ta -cloning Ta " RTF_CLONING" Ta (deprecated) same as
|
|
.Fl connected
|
|
.It Li " " Ta -nocloning Ta ~RTF_CLONING Ta (deprecated) same as
|
|
.Fl noconnected
|
|
.It Li C Ta -connected Ta " RTF_CONNECTED" Ta treat as a connected route
|
|
.It Li " " Ta -noconnected Ta ~RTF_CONNECTED Ta stop treating a connected route
|
|
.It Li D Ta "" Ta " RTF_DYNAMIC" Ta created dynamically (redirect)
|
|
.It Li G Ta "" Ta " RTF_GATEWAY" Ta forwarded to dest by intermediary
|
|
.It Li H Ta "" Ta " RTF_HOST" Ta host entry (net otherwise)
|
|
.It Li L Ta "" Ta " RTF_LLDATA" Ta local link, generated by ARP or NDP
|
|
.It Li l Ta "" Ta " RTF_LOCAL" Ta Route represents a local address
|
|
.It Li M Ta "" Ta " RTF_MODIFIED" Ta modified dynamically (redirect)
|
|
.It Li p Ta -proxy Ta " RTF_ANNOUNCE" Ta make entry a link level proxy
|
|
.It Li R Ta -reject Ta " RTF_REJECT" Ta send ICMP unreachable on match
|
|
.It Li " " Ta -noreject Ta ~RTF_REJECT Ta clear reject flag
|
|
.It Li S Ta -static Ta " RTF_STATIC" Ta manually added route
|
|
.It Li " " Ta -nostatic Ta ~RTF_STATIC Ta pretend route added automatically
|
|
.It Li U Ta "" Ta " RTF_UP" Ta route usable
|
|
.El
|
|
.Pp
|
|
The optional modifiers
|
|
.Fl rtt ,
|
|
.Fl rttvar ,
|
|
.Fl sendpipe ,
|
|
.Fl recvpipe ,
|
|
.Fl mtu ,
|
|
.Fl hopcount ,
|
|
.Fl expire ,
|
|
and
|
|
.Fl ssthresh
|
|
provide initial values to quantities maintained in the routing entry
|
|
by transport level protocols, such as TCP or TP4.
|
|
These may be individually locked by preceding each such modifier to
|
|
be locked by
|
|
the
|
|
.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
|
|
.Fl ifp
|
|
or
|
|
.Fl ifa
|
|
modifiers may be used to determine the interface or interface address.
|
|
.Pp
|
|
All symbolic names specified for a
|
|
.Ar destination
|
|
or
|
|
.Ar gateway
|
|
are looked up first as a host name using
|
|
.Xr gethostbyname 3 .
|
|
If this lookup fails,
|
|
.Xr getnetbyname 3
|
|
is then used to interpret the name as that of a network.
|
|
.Pp
|
|
.Nm
|
|
uses a routing socket and the new message types
|
|
.Dv RTM_ADD ,
|
|
.Dv RTM_DELETE ,
|
|
.Dv RTM_GET ,
|
|
and
|
|
.Dv RTM_CHANGE .
|
|
As such, only the super-user may modify
|
|
the routing tables.
|
|
.Sh EXIT STATUS
|
|
.Ex -std route
|
|
This includes the use of the
|
|
.Cm get
|
|
command to look up a route that is incomplete.
|
|
.Sh EXAMPLES
|
|
This sets the default route to 192.168.0.1:
|
|
.Dl route add default 192.168.0.1
|
|
This shows all routes, without DNS resolution (this is useful if the
|
|
DNS is not available):
|
|
.Dl route -n show
|
|
To install a static route through 10.200.0.1 to reach the network
|
|
192.168.1.0/28, use this:
|
|
.Dl route add -net 192.168.1.0 -netmask 255.255.255.240 10.200.0.1
|
|
.Sh DIAGNOSTICS
|
|
.Bl -tag -width Ds
|
|
.It Sy "add [host \&| network ] %s: gateway %s flags %x"
|
|
The specified route is being added to the tables.
|
|
The values printed are from the routing table entry supplied in the
|
|
.Xr ioctl 2
|
|
call.
|
|
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 Sy "delete [ host \&| network ] %s: gateway %s flags %x"
|
|
As above, but when deleting an entry.
|
|
.It Sy "%s %s done"
|
|
When the
|
|
.Cm flush
|
|
command is specified, each routing table entry deleted
|
|
is indicated with a message of this form.
|
|
.It Sy "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 Sy "not in table"
|
|
A delete operation was attempted for an entry which
|
|
wasn't present in the tables.
|
|
.It Sy "routing table overflow"
|
|
An add operation was attempted, but the system was
|
|
low on resources and was unable to allocate memory
|
|
to create the new entry.
|
|
.It Sy "Permission denied"
|
|
The attempted operation is privileged.
|
|
Only root may modify the routing tables.
|
|
These privileges are enforced by the kernel.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr mpls 4 ,
|
|
.Xr netintro 4 ,
|
|
.Xr route 4 ,
|
|
.Xr routed 8 ,
|
|
.Xr sysctl 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
command appeared in
|
|
.Bx 4.2 .
|
|
IPv6 support was added by WIDE/KAME project.
|
|
.Pp
|
|
Since
|
|
.Nx 8.0 ,
|
|
.Fl cloned ,
|
|
.Fl nocloned ,
|
|
.Fl llinfo
|
|
and
|
|
.Fl xresolve
|
|
were obsolete and
|
|
.Fl cloning
|
|
and
|
|
.Fl nocloning
|
|
were deprecated.
|
|
.Fl connected
|
|
and
|
|
.Fl noconnected
|
|
appeared in
|
|
.Nx 8.0 .
|
|
.Sh BUGS
|
|
The first paragraph may have slightly exaggerated
|
|
.Xr routed 8 Ns 's
|
|
abilities.
|
|
.Pp
|
|
Some uses of the
|
|
.Fl ifa
|
|
or
|
|
.Fl ifp
|
|
modifiers with the add command will incorrectly fail with a
|
|
.Dq Network is unreachable
|
|
message if there is no default route.
|
|
See case
|
|
.Dv RTM_ADD
|
|
in
|
|
.Pa sys/net/rtsock.c:route_output
|
|
for details.
|