NAME
route —
manually manipulate the routing
tables
SYNOPSIS
route |
[-dfLnqSsTtv]
command
[[modifiers]
args] |
DESCRIPTION
route 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
routed(8), should tend to this
task.
route can be used to modify nearly any aspect of the routing
policy, except packet forwarding, which can be manipulated through the
sysctl(8) command.
The
route 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
route(4).
-
-
- -d
- Turn on debugging
-
-
- -f
- Remove all routes (as per flush). If used
in conjunction with the add, change,
delete or get commands,
route removes the routes before performing the
command.
-
-
- -L
- Don't show link layer entries in routing table.
-
-
- -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).
-
-
- -q
- Suppress all output from commands that manipulate the
routing table.
-
-
- -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.
-
-
- -s
- (short) Suppresses all output from a 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.
-
-
- -T
- Show tags in the route display.
-
-
- -t
- Test only, don't perform any actions.
-
-
- -v
- (verbose) Print additional details.
The
route utility provides several commands:
- add
- Add a route.
- flush
- Remove all routes.
- flushall
- Remove all routes including the default gateway.
- delete
- Delete a specific route.
- change
- Change aspects of a route (such as its gateway).
- get
- Lookup and display the route for a destination.
- show
- Print out the route table similar to "netstat -r"
(see netstat(1)).
- monitor
- Continuously report any changes to the routing information
base, routing lookup misses, or suspected network partitionings.
The monitor command has the syntax
route
[-n] monitor
[-c
count]
If
count is specified,
route exits after
receiving
count routing messages.
The flush command has the syntax
route
[-n] flush
[family]
If the
flush command is specified,
route
will ``flush'' the routing tables of all gateway entries. When the address
family is specified by any of the
-xns,
-atalk,
-inet,
-inet6,
or
-mpls modifiers, only routes having destinations with
addresses in the delineated family will be manipulated.
The other commands have the following syntax:
route
[-n] command
[-net |
-host] destination
gateway
where
destination is the destination host or network, and
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
destination argument. The optional modifiers
-net and
-host force the destination to be
interpreted as a network or a host, respectively. Otherwise, if the
destination has a ``local address part'' of
INADDR_ANY
, or if the
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
destination can also be
specified in the
net/
bits format.
For example,
128.32
is interpreted as
-host 128.0.0.32
;
128.32.130
is interpreted as
-host
128.32.0.130
;
-net
128.32
is interpreted as
128.32.0.0
; and
-net
128.32.130
is interpreted as
128.32.130.0
.
The keyword
default can be used as the
destination to set up a default route to a smart
gateway. If no other routes match, this default route
will be used as a last resort.
If the destination is directly reachable via an interface requiring no
intermediary system to act as a gateway, the
-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.
The optional modifiers
-xns,
-atalk, and
-link specify that all subsequent addresses are in the XNS,
or AppleTalk address families, or are specified as link-level addresses in the
form described in
link_addr(3), and the names
must be numeric specifications rather than symbolic names.
The optional modifier
-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
mpls(4) stack; therefore
route assumes that the subsequent addresses are in the MPLS
address family. See
mpls(4) for
examples of setting routes involving MPLS.
The optional
-netmask qualifier is intended to achieve the
effect of an 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
AF_INET
case can be overridden by making sure this
option follows the destination parameter.
-prefixlen is also
available for similar purpose, in IPv4 and IPv6 case.
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:
ID |
Modifier |
Flag Bit |
Description |
|
-iface |
~RTF_GATEWAY |
destination is directly reachable |
1 |
-proto1 |
RTF_PROTO1 |
set protocol specific flag #1 |
2 |
-proto2 |
RTF_PROTO2 |
set protocol specific flag #2 |
B |
-blackhole |
RTF_BLACKHOLE |
discard pkts (during updates) |
b |
|
RTF_BROADCAST |
Route represents a broadcast address |
|
-noblackhole |
~RTF_BLACKHOLE |
clear blackhole flag |
C |
-cloning |
RTF_CLONING |
(deprecated) same as -connected |
|
-nocloning |
~RTF_CLONING |
(deprecated) same as
-noconnected |
C |
-connected |
RTF_CONNECTED |
treat as a connected route |
|
-noconnected |
~RTF_CONNECTED |
stop treating a connected route |
D |
|
RTF_DYNAMIC |
created dynamically (redirect) |
G |
|
RTF_GATEWAY |
forwarded to dest by intermediary |
H |
|
RTF_HOST |
host entry (net otherwise) |
l |
|
RTF_LOCAL |
Route represents a local address |
M |
|
RTF_MODIFIED |
modified dynamically (redirect) |
p |
-proxy |
RTF_ANNOUNCE |
make entry a link level proxy |
R |
-reject |
RTF_REJECT |
send ICMP unreachable on match |
|
-noreject |
~RTF_REJECT |
clear reject flag |
S |
-static |
RTF_STATIC |
manually added route |
|
-nostatic |
~RTF_STATIC |
pretend route added automatically |
U |
|
RTF_UP |
route usable |
The optional modifiers
-rtt,
-rttvar,
-sendpipe,
-recvpipe,
-mtu,
-hopcount,
-expire, and
-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
-lock meta-modifier,
or one can specify that all ensuing metrics may be locked by the
-lockrest meta-modifier.
In a
change or
add command where the
destination and gateway are not sufficient to specify the route the
-ifp or
-ifa modifiers may be used to
determine the interface or interface address.
All symbolic names specified for a
destination or
gateway are looked up first as a host name using
gethostbyname(3). If this
lookup fails,
getnetbyname(3) is then
used to interpret the name as that of a network.
route uses a routing socket and the new message types
RTM_ADD
,
RTM_DELETE
,
RTM_GET
, and
RTM_CHANGE
. As
such, only the super-user may modify the routing tables.
EXIT STATUS
The
route utility exits 0 on success, and >0 if an error
occurs. This includes the use of the
get command to look up
a route that is incomplete.
EXAMPLES
This sets the default route to 192.168.0.1:
route add default 192.168.0.1
This shows all routes, without DNS resolution (this is useful if the DNS is not
available):
route -n show
To install a static route through 10.200.0.1 to reach the network
192.168.1.0/28, use this:
route add -net 192.168.1.0 -netmask
255.255.255.240 10.200.0.1
DIAGNOSTICS
-
-
- 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
ioctl(2) call. If the gateway
address used was not the primary address of the gateway (the first one
returned by
gethostbyname(3)),
the gateway address is printed numerically as well as symbolically.
-
-
- delete [ host |
network ] %s: gateway %s flags %x
- As above, but when deleting an entry.
-
-
- %s %s
done
- When the flush command is specified, each
routing table entry deleted is indicated with a message of this form.
-
-
- 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.
-
-
- not in
table
- A delete operation was attempted for an entry which wasn't
present in the tables.
-
-
- 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.
-
-
- Permission
denied
- The attempted operation is privileged. Only root may modify
the routing tables. These privileges are enforced by the kernel.
SEE ALSO
mpls(4),
netintro(4),
route(4),
routed(8),
sysctl(8)
HISTORY
The
route command appeared in
4.2BSD.
IPv6 support was added by WIDE/KAME project.
Since
NetBSD 8.0,
-cloned,
-nocloned,
-llinfo and
-xresolve were obsolete and
-cloning and
-nocloning were deprecated.
-connected and
-noconnected appeared in
NetBSD 8.0.
BUGS
The first paragraph may have slightly exaggerated
routed(8)'s abilities.
Some uses of the
-ifa or
-ifp modifiers with
the add command will incorrectly fail with a “Network is
unreachable” message if there is no default route. See case
RTM_ADD
in
sys/net/rtsock.c:route_output for details.