route [-fnvq] sub-command [ [modifiers] args]

route [-fnvq] [-p [-R root-dir]] add | delete [modifiers] destination gateway
 [args]

route [-fnvq] change | get [modifiers] destination
 [gateway [args]]

route [-fn] monitor [modifiers]

route [-fnvq] flush [modifiers]

route -p [-R root-dir] show

route supports a limited number of general options, but a rich command language. Users can specify an arbitrary request that can be delivered by means of the programmatic interface discussed in route(4P).

route uses a routing socket and the new message types RTM_ADD, RTM_DELETE, RTM_GET, and RTM_CHANGE. While only superusers can modify routing tables, the RTM_GET operation is allowed for non-privileged users.

The add and delete subcommands have the following syntax:

route [ -fnvq ] cmd destination gateway [metric/netmask]

where cmd is add or delete, destination is the destination host or network, and gateway is the next-hop intermediary through which packets should be routed. Modifiers described in OPERANDS can be placed anywhere on the command line.

The get and change subcommands have the following syntax:

route [ -fnvq ] cmd destination [gateway [metric/netmask]]

where cmd is get or change, destination is the destination host or network, and gateway is the next-hop intermediary through which packets should be routed. Modifiers described in OPERANDS can be placed anywhere on the command line.

The monitor subcommand has the following syntax:

route monitor [ -inet | -inet6 ]

Including an optional modifier on the command line before the address changes how the route subcommand interprets it.

The following modifiers are supported: -inet

For IPv4 addresses, routes to a particular host are by default distinguished from those to a network by interpreting the Internet address specified as the destination. If the destination has a local address part (that is, the portion not covered by the netmask) of 0, or if the destination is resolved as 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.

You can force this selection by using one of the following modifiers: -host

For example:

Two modifiers avoid confusion between addresses and keywords (for example, host used as a symbolic host name). You can distinguish a destination by preceding it with the -dst modifier. You can distinguish a gateway address by using the -gateway modifier. If the destination is directly reachable by way of an interface requiring no intermediary IP router to act as a gateway, this can be indicated by using the -interface or -iface modifier.

In the following example, the route does not refer to an external gateway (router), but rather to one of the machine's interfaces. Packets with IP destination addresses matching the destination and mask on such a route are sent out on the interface identified by the gateway address. For interfaces using the ARP protocol, this type of route is used to specify that all matching destinations are local to the physical link. That is, a host could be configured to ARP for all addresses, without regard to the configured interface netmask, by adding a default route using this command. For example:

example# route add default hostname -interface

where gateway address hostname is the name or IP address associated with the network interface over which all matching packets should be sent. On a host with a single network interface, hostname is usually the same as the nodename returned by the uname -n command. See uname(1).

For backward compatibility with older systems, directly reachable routes can also be specified by placing a 0 after the gateway address:

example# route add default hostname 0

This value was once a route metric, but this metric is no longer used. If the value is specified as 0, then the destination is directly reachable (equivalent to specifying -interface). If it is non-zero but cannot be interpreted as a subnet mask, then a gateway is used (default).

With the AF_INET address family or an IPv4 address, a separate subnet mask can be specified. This can be specified in one of the following ways:

If a subnet mask is not specified, the mask used is the subnet mask of the output interface selected by the gateway address, if the classful network of the destination is the same as the classful network of the interface. Otherwise, the classful network mask for the destination address is used.

Each of the following examples creates an IPv4 route to the destination 192.0.2.32 subnet with a subnet mask of 255.255.255.224:

example# route add 192.0.2.32/27 somegateway
example# route add 192.0.2.32 -netmask 255.255.255.224 somegateway
example# route add 192.0.2.32 somegateway 255.255.255.224

For IPv6, only the slash format is accepted. The following example creates an IPv6 route to the destination 33fe:: with a netmask of 16 one-bits followed by 112 zero-bits.

example# route add -inet6 3ffe::/16 somegateway

In cases where the gateway does not uniquely identify the output interface (for example, when several interfaces have the same address), you can use the -ifp ifname modifier to specify the interface by name. For example, -ifp lo0 associates the route with the lo0 interface. If the named interface is an underlying interface in an IPMP (IP multipathing) group, then requests to add a route will automatically be translated to the corresponding IPMP IP interface, and requests to delete or change a route on an underlying interface will fail.

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. These can be individually locked either by preceding each modifier to be locked by the -lock meta-modifier, or by specifying that all ensuing metrics can be locked by the -lockrest meta-modifier.

Some transport layer protocols can support only some of these metrics. The following optional modifiers are supported: -expire

min_sl=val,max_sl=val,doi=val,cipso

sl=VAL,doi=VAL,cipso

The following two flags are also accepted for compatibility with older systems, but have no effect.

The -ifa hostname modifier is also accepted, but has no effect.

change [ host\|| network\|] destination:gateway flags

Combining the all destinations are local route with subnet or network routes can lead to unpredictable results. The search order as it relates to the all destinations are local route are undefined and can vary from release to release.