route is a utility used to manually view and
manipulate the network routing tables. Except for setting up the default
route, it normally is not needed to manipulate routes, as a system routing
table management daemon, such as
ripd(8),
ospfd(8), or
bgpd(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 enables the user to specify
any arbitrary request that could be delivered via the programmatic interface
discussed in route(4).

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.)

Execute a command forcing the process and its children to use the routing
table and appropriate routing domain as specified with the
-Ttableid option.

route
[

-nqv

]
[

-Ttableid

]
flush
[

modifiers

]

Delete all gateway entries from the routing table. When the address family
is specified by any one of the 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 by using the
-iface or
-priority modifiers.

route
[

-nv

]
[

-Ttableid

]
get
[

modifiers

]
address

Extract a routing entry from the kernel. If
-gateway is specified, only routes
whose gateway are in the same address family as the destination are
shown.

When the address family is specified by any one of the
family modifiers (listed below), only
routes having destinations with addresses in the delineated family will be
shown. If the -iface modifier is used
only interface specific messages (link state changes) are shown.

If -gateway is specified, only routes
whose gateway are in the same address family as the destination are shown.

If -label is specified, only routes with
the specified label are shown.

If -priority is specified, only routes
with the specified (numeric) priority are shown. Some well-known
priorities can be given by name. If the priority is negative, then routes
that do not match the numeric priority are shown.

The other commands relating to adding, changing, or deleting routes have the
syntax:

route
[

-dnqtv

]
[

-Ttableid

]
add
[

modifiers

]
destination gateway

route
[

-dnqtv

]
[

-Ttableid

]
change
[

modifiers

]
destination gateway

route
[

-dnqtv

]
[

-Ttableid

]
del[

ete

]
[

modifiers

]
destination gateway

destination is the destination host or network;
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 cause the destination to be
interpreted as a network or a host, respectively. Otherwise, type is chosen
based on the following rules:

The route is assumed to be to a network if any of the following apply to
destination:

it is the word "default", equivalent to 0/0

it is an IPv4 address with less than 3 dots

it is an IPv4 address with a
“/XX” suffix (where
XX is the number of bits in the network
portion of the address and is less than 32)

it is an IPv6 address with a
“/XX” suffix (where
XX is the number of bits in the network
portion of the address and is less than 128)

it is the symbolic name of a network.

If destination is a valid IP address or host
name, it is presumed to be a route to a host.

For example, 192.168.1.1 is interpreted as
-host192.168.1.1
and 192.168.1 is interpreted as
-net192.168.1.
Note, however, that 192.168.2.0 will be interpreted as
-host192.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
192.168.2.0/24, 192.168.2/24,
or alternately 192.168.2.

If the destination is directly reachable via an interface requiring no
intermediary system to act as a gateway, the
-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.

To allow addresses to be interpreted as belonging to a particular address family
(as well as for use in the family arguments
to some commands), the following modifiers may be used:

In the absence of modifiers, an address is assumed to be IPv4, unless containing
a ‘:’ character, when it is treated as IPv6.

The optional modifier -link specifies that
all subsequent addresses are specified as link-level addresses, and the names
must be numeric specifications rather than symbolic names.

The optional -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
AF_INET case can be overridden by making
sure this option follows the destination
parameter. -prefixlen is also available for
a similar purpose, for IPv6/v4.

A specific routing priority can be specified with the optional
-priority qualifier. If no priority is
specified the kernel will set a priority depending on the RTF_STATIC flag to
either RTP_STATIC or RTP_DEFAULT. Note that priority 1 is reserved for kernel
use.

The optional -mpath modifier needs to be
specified with the 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
sysctl(8) variables
net.inet.ip.multipath and
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.

When inserting MPLS routes, particular modifiers must be used. The
-mplslabel modifier needs to be specified
in an ingress LSR to associate a particular label to an IPv4/IPv6 route. The
MPLS traffic -in and
-out modifiers are intended to identify the
ingress label and, optionally, the outgoing one. Additionally, one of the
following operations must be used: -push,
-pop and
-swap. Route's nexthop can be specified
with the modifier -inet.

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:

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 name or interface address.

The optional -label modifier specifies on
route addition or modification that the route should have the given
label associated with it. Route labels can be
used to attach arbitrary information to a route.

All symbolic names specified for a destination
or gateway are looked up using
gethostbyname(3).

route uses a routing socket (see
route(4)) and the message types
RTM_ADD,
RTM_DELETE,
RTM_GET, and
RTM_CHANGE. As such, only the superuser may
modify the routing tables.

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
gethostbyname(3)),
the gateway address is printed numerically as well as symbolically.

%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.

The route command appeared in
4.2BSD. IPv6 support was added by WIDE/KAME project.

The -recvpipe,
-hopcount,
-sendpipe,
-ssthres,
-rtt, and
-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.

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
route_output() from
sys/net/rtsock.c for details.