route(1M)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | FILES | ATTRIBUTES | SUMMARY OF TRUSTED SOLARIS CHANGES | SEE ALSO | DIAGNOSTICS | NOTES

NAME

route- Manually manipulate the routing tables

SYNOPSIS

route [-fnvq] command [[modifiers]args]
route [-fnvq] [ -t file1] add| delete [host| net] destination [gateway[args]] [extended_metric]
route [-fnvq] [ -t file1] change| get [host| net] destination [gateway[args]] [extended_metric]
route [-n] monitor
route [-n] flush

DESCRIPTION

route manually manipulates the network routing tables. These tables are normally maintained by the system routing daemon, such as in.routed(1M) and in.ripngd(1M).

This utility supports a limited number of general options, but a rich command language. It enables the user to specify any arbitrary request that could be delivered via the programmatic interface discussed in route(7P).

route uses a routing socket and the new message types RTM_ADD, RTM_DELETE, RTM_GET, and RTM_CHANGE.

The route utility must inherit the sys_net_config privilege to operate directly on the routing table for the specific host or network indicated by destination. It also must run with a uid of 0, or have the file_dac_read and file_dac_write privileges.

Trusted Solaris Routing

In the Trusted Solaris environment, as in the Solaris operating environment, routing can be configured by the administrator to be static, that is, determined by a router or route description in a static file, or dynamic, that is, determined at the time of routing. By default, dynamic routing is in effect. The static routing file to establish default gateways (routers) in both environments is /etc/defaultrouter.

In the Trusted Solaris environment, an administrator can establish gateways for specific networks and default gateways in the file /etc/tsolgateways. Routing decisions are made in the order:

1. Get routing information from the file /etc/tsolgateways. If it does not exist,

2. Get routing information from the file /etc/defaultrouter. If it does not exist,

3. Start dynamic routing.

For trusted routing, security attributes must also be associated with a route. The additional security routing information (SRI) includes sensitivity label range, CIPSO DOI, RIPSO label, and RIPSO error. The SRI and the simple metric together compose the extended metric (extended_metric), which is necessary for trusted routing.

If -e is specified in extended_metric, the metric and SRI are obtained from a file composed of a series of lines, each specifying an extended metric value. Both the -e and -m options use the same format. For readability only, the one-line format is shown here as two lines:

metric= val,min_sl=val,max_sl=val,doi= val,
ripso_label= val,ripso_error=val,ripso_only,cipso_only,msix_only 

The val for metric is an integer from 0 to 15. The val for min_sl and max_sl is a sensitivity label in either hex or string form. The val for doi is a nonzero integer. The val for ripso_label is the classification, followed by a space, followed by a list of protections separated by semicolons (;). Both the classification and the protections are specified either in hex or string form. The val for ripso_error is a list of protections separated by semicolons (;). They are specified in either hex or string form. Note that if val contains a space, it must be protected by double quotes.

The three keywords, ripso_only, cipso_only, and msix_only, do not have values. They indicate that a route can only forward packets having RIPSO, CIPSO, or MSIX labels. They must be specified if a SUN_RIPSO, SUN_CIPSO, or SUN_MSIX gateway is involved in a route.

Some keywords are necessary, and others are optional. The following rules apply when specifying the extended metric information.

• metric, min_sl, and max_sl must be specified.

• ripso_label and ripso_error must both be present or both be absent.

• If cipso_only is specified, doi must be specified; and no ripso_label, ripso_error, ripso_only, or msix_only can be specified.

• If ripso_only is specified, ripso_label and ripso_error must be specified; and no doi, cipso_only, or msix_only can be specified.

• If msix_only is specified, no doi, ripso_label, ripso_error, cipso_only, or ripso_only can be specified.

---

Note -

When the -e option is used, emetrics are generated for a route. These emetrics are used for accreditation checks when selecting a route.

Without the -e option, no emetric is generated. If the command adds a remote route, the template of the gateway will be used for accreditation checks when selecting a route, since no emetric is available.

---

OPTIONS

-f

Flush the routing tables of all gateway entries. If this is used in conjunction with one of the commands described above, route flushes the gateways before performing the command.

-n

Prevent attempts to print host and network names symbolically when reporting actions. This is useful, for example, when all name servers are down on your local net, and you need a route before you can contact the name server.

-v

(Verbose) Print additional details.

-q

Suppress all output.

-t file1

Obtain extended metric information from file1, where file1 has the same format as /etc/tsolgateways.

Commands

route executes one of four commands on a route to a destination. Two additional commands operate globally on all routing information. The (six) commands are:

add

Add a route.

change

Change aspects of a route (such as its gateway).

delete

Delete a specific route.

flush

Remove all gateway entries from the routing table.

get

Look up and display the route for a destination.

monitor

Continuously report any changes to the routing information base, routing lookup misses, or suspected network partitionings.

The add, delete, and change commands have the following syntax:

---

route [-fnvq] add | delete [-net | -host] dest gate [args] [ext_metric]

or

route [-fnvq] change | get [-net | -host] dest gate [args] [ext_metric]

---

where dest is the destination host or network, gate is the next-hop intermediary through which packets should be routed, and ext_metric is one of

---

-e file

or

-m emetric_val ... -m emetric_val

---

The -e or -m option is required for add commands, and must be nonzero if the route utilizes one or more gateways. These options are used to specify extended metric information associated with a route. See the explanation in the section Trusted Solaris Routing under DESCRIPTION.

OPERANDS

route executes its commands on routes to destinations.

Destinations

By default, a destination is looked up under the AF_INET address family or as an IPv4 address. All symbolic names specified for a destination or gateway are looked up first as a host name, using getipnodebyname(3SOCKET). If this lookup fails in the AF_INET case, getnetbyname(3SOCKET) is used to interpret the name as that of a network.

An optional modifier may be included on the command line before a destination, to force how route interprets a destination:

-host

Forces the destination to be interpreted as a host.

-net

Forces the destination to be interpreted as a network.

-inet

Forces the destination to be interpreted under the AF_INET address family or as an IPv4 address.

-inet6

Forces the destination to be interpreted under the AF_INET6 address family or as an IPv6 address.

In the case of the AF_INET address family or an IPv4 address, routes to a particular host may be distinguished from those to a network by interpreting the Internet address specified as the destination. 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.

For example:

The following route:	Is interpreted as:
128.32	-host 128.0.0.32
128.32.130	-host 128.32.0.130
-net 128.32	128.32.0.0
-net 128.32.130	128.32.130.0

If the destination is directly reachable by way of an interface requiring no intermediary system to act as a gateway, this can be indicated by including one of two optional modifiers after the destination: The interface modifier can be included or a metric of 0 can be specified. These modifiers are illustrated in the following alternative examples:

---

example% route add default hostname -interface example% route add default hostname 0

---

hostname is the name or IP address associated with the network interface all packets should be sent over. On a host with a single network interface, hostname is normally the same as the nodename returned by uname -n (see uname(1)).

In the above examples, the route does not refer to a gateway, but rather to one of the machine's interfaces. Destinations matching 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 all destinations are local. That is, a host should use ARP for all addresses by adding a default route using one of the two commands listed above.

With the AF_INET address family or an IPv4 address, the optional -netmask qualifier is intended to manually add subnet routes with netmasks different from that of the implied network interface. The implicit network mask generated in the AF_INET case can be overridden by making sure this option, and an ensuing address parameter (to be interpreted as a network mask), follows the destination parameter.

Alternatively, the length of the netmask may be supplied by appending a slash character and the length immediately after the destination. For example:

---

example% route add 192.0.2.32/27 somegateway

---

will create an IPv4 route to the destination 192.0.2.32 with a netmask of 255.255.255.224, and

---

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

---

will create an IPv6 route to the destination 33fe:: with a netmask of 16 one-bits followed by 112 zero-bits.

Routing Flags

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 including the following corresponding modifiers on the command line:

Modifier	Flag	Description
-cloning	RTF_CLONING	generates a new route on use
-xresolve	RTF_XRESOLVE	emit mesg on use (for external lookup)
-iface	~RTF_GATEWAY	destination is directly reachable
-static	RTF_STATIC	manually added route
-nostatic	~RTF_STATIC	pretend route added by kernel or daemon
-reject	RTF_REJECT	emit an ICMP unreachable when matched
-blackhole	RTF_BLACKHOLE	silently discard pkts (during updates)
-proto1	RTF_PROTO1	set protocol specific routing flag #1
-proto2	RTF_PROTO2	set protocol specific routing flag #2
-private	RTF_PRIVATE	do not adveritse this route

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

The optional modifiers are defined as follows:

-expire

Lifetime for the entry. This optional modifier is not currently supported.

-hopcount

Maximum hop count. This optional modifier is not currently supported.

-mtu

Maximum MTU in bytes.

-recvpipe

Receive pipe size in bytes.

-rtt

Round trip time in microseconds.

-rttvar

Round trip time variance in microseconds.

-sendpipe

Send pipe size in bytes.

-ssthresh

Send pipe size threshold in bytes.

Some transport layer protocols may support only some of these metrics.

In a change or add command where the destination and gateway are not sufficient to specify the route (for example, , when several interfaces have the same address), the -ifp or -ifa modifiers may be used to determine the interface or interface address.

FILES

/etc/hosts

List of host names and net addresses.

/etc/networks

List of network names and addresses.

/etc/defaultrouter

List of default routes.

/etc/tsolgateways

List of trusted gateways and metrics.

/etc/security/tsol/device_policy

Policy for trusted devices.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	SUNWcsu

SUMMARY OF TRUSTED SOLARIS CHANGES

route must inherit the sys_net_config privilege to operate directly on the routing table for the specific host or network indicated by destination. It also must run with a uid of 0, or have the file_dac_read and file_dac_write privileges. The file /etc/security/tsol/device_policy specifies the access policy for the device special files used by route.

The Trusted Solaris environment adds the file /etc/tsolgateways and the -t option to read it. It also adds the extended_metric arguments to handle security routing information.

SEE ALSO

Trusted Solaris 8 Reference Manual

uname(1), in.rdisc(1M), netstat(1M), routed(1M), device_policy(4), tsolgateways(4)

Trusted Solaris Administrator's Procedures

SunOS 5.8 Reference Manual

get(1), ioctl(2), getipnodebyname(3SOCKET), getnetbyname(3SOCKET), hosts(4), networks(4), attributes(5), ARP(7P), route(7P), routing(7P)

DIAGNOSTICS

add [ host|network] destination:gateway flags

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

delete [ host|network ] destination:gateway flags

As above, but when deleting an entry.

destination done

When the -f flag is specified, or in the flush command, 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. Give the next-hop gateway instead.

not in table

A delete operation was attempted for an entry that is not in the table.

routing table overflow

An add operation was attempted, but the system was unable to allocate memory to create the new entry.

NOTES

All destinations are local assumes that the routers implement the protocol, proxy arp. Normally, using router discovery (see in.rdisc(1M)) is more reliable than using proxy arp.

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 may vary from release to release.

Trusted Solaris 8  Last Revised 4 Apr 2000

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | FILES | ATTRIBUTES | SUMMARY OF TRUSTED SOLARIS CHANGES | SEE ALSO | DIAGNOSTICS | NOTES