2930 beadm should sort by creation date

[illumos-gate.git] / usr / src / man / man1m / in.routed.1m

'\" te
.\" Copyright (c) 2008 Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 1989 AT&T
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH IN.ROUTED 1M "Jul 24, 2008"
.SH NAME
in.routed, routed \- network routing daemon
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/in.routed\fR [\fB-AdghmnqsStVz\fR] [\fB-T\fR \fItracefile\fR [\fB-v\fR]]
 [\fB-F\fR \fInet\fR[/mask ][,metric]] [\fB-P\fR \fIparams\fR]
.fi

.SH DESCRIPTION
.sp
.LP
The daemon \fBin.routed\fR, often referred to as \fBrouted\fR, is invoked at
boot time to manage the network routing tables. It uses Routing Information
Protocol, RIPv1 (RFC 1058), RIPv2 (RFC 2453), and Internet Router Discovery
Protocol (RFC 1256) to maintain the kernel routing table. The RIPv1 protocol is
based on the reference 4.3BSD daemon.
.sp
.LP
\fBin.routed\fR is managed by means of the service management facility (SMF),
using the fault management resource identifier (FMRI):
.sp
.in +2
.nf
svc:/network/routing/route:default
.fi
.in -2
.sp

.sp
.LP
The daemon listens on a \fBudp\fR socket for the \fBroute\fR service (see
\fBservices\fR(4)) for Routing Information Protocol packets. It also sends and
receives multicast Router Discovery ICMP messages. If the host is a router,
\fBin.routed\fR periodically supplies copies of its routing tables to any
directly connected hosts and networks. It also advertises or solicits default
routes using Router Discovery ICMP messages.
.sp
.LP
When started (or when a network interface is later turned on), \fBin.routed\fR
uses an \fBAF_ROUTE\fR address family facility to find those directly connected
interfaces configured into the system and marked "up". It adds necessary routes
for the interfaces to the kernel routing table. Soon after being first started,
and provided there is at least one interface on which RIP has not been
disabled, \fBin.routed\fR deletes all pre-existing non-static routes in the
kernel table. Static routes in the kernel table are preserved and included in
RIP responses if they have a valid RIP metric (see \fBroute\fR(1M)).
.sp
.LP
If more than one interface is present (not counting the loopback interface), it
is assumed that the host should forward packets among the connected networks.
After transmitting a RIP request and Router Discovery Advertisements or
Solicitations on a new interface, the daemon enters a loop, listening for RIP
request and response and Router Discovery packets from other hosts.
.sp
.LP
When a request packet is received, \fBin.routed\fR formulates a reply based on
the information maintained in its internal tables. The response packet
generated contains a list of known routes, each marked with a "hop count"
metric (a count of 16 or greater is considered "infinite"). Advertised metrics
reflect the metric associated with an interface (see \fBifconfig\fR(1M)), so
setting the metric on an interface is an effective way to steer traffic.
.sp
.LP
Responses do not include routes with a first hop on the requesting network, to
implement in part split-horizon. Requests from query programs such as
\fBrtquery\fR(1M) are answered with the complete table.
.sp
.LP
The routing table maintained by the daemon includes space for several gateways
for each destination to speed recovery from a failing router. RIP response
packets received are used to update the routing tables, provided they are from
one of the several currently recognized gateways or advertise a better metric
than at least one of the existing gateways.
.sp
.LP
When an update is applied, \fBin.routed\fR records the change in its own tables
and updates the kernel routing table if the best route to the destination
changes. The change in the kernel routing table is reflected in the next batch
of response packets sent. If the next response is not scheduled for a while, a
flash update response containing only recently changed routes is sent.
.sp
.LP
In addition to processing incoming packets, in.routed also periodically checks
the routing table entries. If an entry has not been updated for 3 minutes, the
entry's metric is set to infinity and marked for deletion. Deletions are
delayed until the route has been advertised with an infnite metric to insure
the invalidation is propagated throughout the local internet. This is a form of
poison reverse.
.sp
.LP
Routes in the kernel table that are added or changed as a result of ICMP
Redirect messages are deleted after a while to minimize black-holes. When a TCP
connection suffers a timeout, the kernel tells \fBin.routed\fR, which deletes
all redirected routes through the gateway involved, advances the age of all RIP
routes through the gateway to allow an alternate to be chosen, and advances of
the age of any relevant Router Discovery Protocol default routes.
.sp
.LP
Hosts acting as internetwork routers gratuitously supply their routing tables
every 30 seconds to all directly connected hosts and networks. These RIP
responses are sent to the broadcast address on nets that support broadcasting,
to the destination address on point-to-point links, and to the router's own
address on other networks. If RIPv2 is enabled, multicast packets are sent on
interfaces that support multicasting.
.sp
.LP
If no response is received on a remote interface, if there are errors while
sending responses, or if there are more errors than input or output (see
\fBnetstat\fR(1M)), then the cable or some other part of the interface is
assumed to be disconnected or broken, and routes are adjusted appropriately.
.sp
.LP
The Internet Router Discovery Protocol is handled similarly. When the daemon is
supplying RIP routes, it also listens for Router Discovery Solicitations and
sends Advertisements. When it is quiet and listening to other RIP routers, it
sends Solicitations and listens for Advertisements. If it receives a good
Advertisement and it is not multi-homed, it stops listening for broadcast or
multicast RIP responses. It tracks several advertising routers to speed
recovery when the currently chosen router dies. If all discovered routers
disappear, the daemon resumes listening to RIP responses. It continues
listening to RIP while using Router Discovery if multi-homed to ensure all
interfaces are used.
.sp
.LP
The Router Discovery standard requires that advertisements have a default
"lifetime" of 30 minutes. That means should something happen, a client can be
without a good route for 30 minutes. It is a good idea to reduce the default to
45 seconds using \fB\fR\fB-P\fR \fBrdisc_interval=45\fR on the command line or
\fBrdisc_interval=45\fR in the \fB/etc/gateways\fR file. See \fBgateways\fR(4).
.sp
.LP
While using Router Discovery (which happens by default when the system has a
single network interface and a Router Discover Advertisement is received),
there is a single default route and a variable number of redirected host routes
in the kernel table. On a host with more than one network interface, this
default route will be via only one of the interfaces. Thus, multi-homed hosts
running with \fB-q\fR might need the \fBno_rdisc\fR argument described below.
.sp
.LP
To support "legacy" systems that can handle neither RIPv2 nor Router Discovery,
you can use the \fBpm_rdisc\fR parameter in the \fB/etc/gateways\fR. See
\fBgateways\fR(4).
.sp
.LP
By default, neither Router Discovery advertisements nor solicitations are sent
over point-to-point links (for example, PPP). The Solaris OE uses a netmask of
all ones (255.255.255.255) on point-to-point links.
.sp
.LP
\fBin.routed\fR supports the notion of "distant" passive or active gateways.
When the daemon is started, it reads the file \fB/etc/gateways\fR to find such
distant gateways that cannot be located using only information from a routing
socket, to discover if some of the local gateways are passive, and to obtain
other parameters. Gateways specified in this manner should be marked passive if
they are not expected to exchange routing information, while gateways marked
active should be willing to exchange RIP packets. Routes through passive
gateways are installed in the kernel's routing tables once upon startup and are
not included in transmitted RIP responses.
.sp
.LP
Distant active gateways are treated like network interfaces. RIP responses are
sent to the distant active gateway. If no responses are received, the
associated route is deleted from the kernel table and RIP responses are
advertised via other interfaces. If the distant gateway resumes sending RIP
responses, the associated route is restored.
.sp
.LP
Distant active gateways can be useful on media that do not support broadcasts
or multicasts but otherwise act like classic shared media, such as some ATM
networks. One can list all RIP routers reachable on the HIPPI or ATM network in
\fB/etc/gateways\fR with a series of "host" lines. Note that it is usually
desirable to use RIPv2 in such situations to avoid generating lists of inferred
host routes.
.sp
.LP
Gateways marked external are also passive, but are not placed in the kernel
routing table, nor are they included in routing updates. The function of
external entries is to indicate that another routing process will install such
a route if necessary, and that other routes to that destination should not be
installed by \fBin.routed\fR. Such entries are required only when both routers
might learn of routes to the same destination.
.SH OPTIONS
.sp
.LP
Listed below are available options. Any other argument supplied is interpreted
as the name of a file in which the actions of \fBin.routed\fR should be logged.
It is better to use \fB-T\fR (described below) instead of appending the name of
the trace file to the command. Associated SMF properties for these options are
described, and can be set by means of a command of the form:
.sp
.in +2
.nf
# \fBrouteadm -m route:default \fIname\fR=\fIvalue\fR\fR
.fi
.in -2
.sp

.sp
.ne 2
.na
\fB\fB-A\fR\fR
.ad
.sp .6
.RS 4n
Do not ignore RIPv2 authentication if we do not care about RIPv2
authentication. This option is required for conformance with RFC 2453. However,
it makes no sense and breaks using RIP as a discovery protocol to ignore all
RIPv2 packets that carry authentication when this machine does not care about
authentication. This option is equivalent to setting the \fBignore_auth\fR
property value to false.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR\fR
.ad
.sp .6
.RS 4n
Do not run in the background. This option is meant for interactive use and is
not usable under the SMF.
.RE

.sp
.ne 2
.na
\fB\fB-F\fR \fBnet[/\fImask\fR][,\fImetric\fR]\fR\fR
.ad
.sp .6
.RS 4n
Minimize routes in transmissions via interfaces with addresses that match
\fInet\fR (network number)/\fImask\fR (netmask), and synthesizes a default
route to this machine with the \fImetric\fR. The intent is to reduce RIP
traffic on slow, point-to-point links, such as PPP links, by replacing many
large UDP packets of RIP information with a single, small packet containing a
"fake" default route. If \fImetric\fR is absent, a value of 14 is assumed to
limit the spread of the "fake" default route. This is a dangerous feature that,
when used carelessly, can cause routing loops. Notice also that more than one
interface can match the specified network number and mask. See also \fB-g\fR.
Use of this option is equivalent to setting the \fBminimize_routes\fR property.
.RE

.sp
.ne 2
.na
\fB\fB-g\fR\fR
.ad
.sp .6
.RS 4n
Used on internetwork routers to offer a route to the "default" destination. It
is equivalent to \fB-F\fR \fB0/0,1\fR and is present mostly for historical
reasons. A better choice is \fB-P\fR \fBpm_rdisc\fR on the command line or
\fBpm_rdisc\fR in the \fB/etc/gateways\fR file. A larger metric will be used
with the latter alternatives, reducing the spread of the potentially dangerous
default route. The \fB-g\fR (or \fB-P\fR) option is typically used on a gateway
to the Internet, or on a gateway that uses another routing protocol whose
routes are not reported to other local routers. Note that because a metric of 1
is used, this feature is dangerous. Its use more often creates chaos with a
routing loop than solves problems. Use of this option is equivalent to setting
the \fBoffer_default_route\fR property to true.
.RE

.sp
.ne 2
.na
\fB\fB-h\fR\fR
.ad
.sp .6
.RS 4n
Causes host or point-to-point routes not to be advertised, provided there is a
network route going the same direction. That is a limited kind of aggregation.
This option is useful on gateways to LANs that have other gateway machines
connected with point-to-point links such as SLIP. Use of this option is
equivalent to setting the \fBadvertise_host_routes\fR property to false.
.RE

.sp
.ne 2
.na
\fB\fB-m\fR\fR
.ad
.sp .6
.RS 4n
Cause the machine to advertise a host or point-to-point route to its primary
interface. It is useful on multi-homed machines such as NFS servers. This
option should not be used except when the cost of the host routes it generates
is justified by the popularity of the server. It is effective only when the
machine is supplying routing information, because there is more than one
interface. The \fB-m\fR option overrides the \fB-q\fR option to the limited
extent of advertising the host route. Use of this option is equivalent to
setting the \fBadvertise_host_routes_primary\fR property to true.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.sp .6
.RS 4n
Do not install routes in kernel. By default, routes are installed in the
kernel. Use of this option is equivalent to setting the \fBinstall_routes\fR
property to false.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR \fIparams\fR\fR
.ad
.sp .6
.RS 4n
Equivalent to adding the parameter line \fIparams\fR to the \fB/etc/gateways\fR
file. Can also be set by means of the \fBparameters\fR property.
.RE

.sp
.ne 2
.na
\fB\fB-q\fR\fR
.ad
.sp .6
.RS 4n
Opposite of the \fB-s\fR option. This is the default when only one interface is
present. With this explicit option, the daemon is always in "quiet mode" for
RIP and does not supply routing information to other computers. Use of this
option is equivalent to setting the \fBquiet_mode\fR property to true.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.sp .6
.RS 4n
Force \fBin.routed\fR to supply routing information. This is the default if
multiple network interfaces are present on which RIP or Router Discovery have
not been disabled, and if the \fB/dev/ip\fR \fBndd\fR variable
\fBip_forwarding\fR is set to 1. Use of this option is equivalent to setting
the \fBsupply_routes\fR property to true.
.RE

.sp
.ne 2
.na
\fB\fB-S\fR\fR
.ad
.sp .6
.RS 4n
If \fBin.routed\fR is not acting as an internetwork router, instead of entering
the whole routing table in the kernel, it enters only a default route for each
internetwork router. This reduces the memory requirements without losing any
routing reliability. This option is provided for compatibility with the
previous, RIPv1-only \fBin.routed\fR. Use of this option is generally
discouraged. Use of this option is equivalent to setting the
\fBdefault_routes_only\fR property to true.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR\fR
.ad
.sp .6
.RS 4n
Runs in the foreground (as with \fB-d\fR) and logs the contents of the packets
received (as with \fB-zz\fR). This is for compatibility with prior versions of
Solaris and has no SMF equivalent.
.RE

.sp
.ne 2
.na
\fB\fB-T\fR \fItracefile\fR\fR
.ad
.sp .6
.RS 4n
Increases the debugging level to at least 1 and causes debugging information to
be appended to the trace file. Because of security concerns, do not to run
\fBin.routed\fR routinely with tracing directed to a file. Use of this option
is equivalent to setting the \fBlog_file\fR property to \fBtrace file path\fR.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.sp .6
.RS 4n
Enables debug. Similar to \fB-z\fR, except, where \fB-z\fR increments
\fBtrace_level\fR, \fB-v\fR sets \fBtrace_level\fR to 1. Also, \fB-v\fR
requires the \fB-T\fR option. Use of this option is equivalent to setting the
\fBdebug\fR property to true.
.RE

.sp
.ne 2
.na
\fB\fB-V\fR\fR
.ad
.sp .6
.RS 4n
Displays the version of the daemon.
.RE

.sp
.ne 2
.na
\fB\fB-z\fR\fR
.ad
.sp .6
.RS 4n
Increase the debugging level, which causes more information to be logged on the
tracefile specified with \fB-T\fR or stdout. The debugging level can be
increased or decreased with the \fBSIGUSR1\fR or \fBSIGUSR2\fR signals or with
the \fBrtquery\fR(1M) command.
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fB/etc/defaultrouter\fR\fR
.ad
.RS 22n
If this file is present and contains the address of a default router, the
system startup script does not run \fBin.routed\fR. See \fBdefaultrouter\fR(4).
.RE

.sp
.ne 2
.na
\fB\fB/etc/gateways\fR\fR
.ad
.RS 22n
List of distant gateways and general configuration options for \fBin.routed\fR.
See \fBgateways\fR(4).
.RE

.SH SEE ALSO
.sp
.LP
\fBroute\fR(1M), \fBrouteadm\fR(1M), \fBrtquery\fR(1M), \fBsvcadm\fR(1M),
\fBioctl\fR(2), \fBinet\fR(3SOCKET), \fBdefaultrouter\fR(4), \fBgateways\fR(4),
\fBattributes\fR(5), \fBicmp\fR(7P), \fBinet\fR(7P), \fBudp\fR(7P)
.sp
.LP
\fIInternet Transport Protocols, XSIS 028112, Xerox System Integration
Standard\fR
.sp
.LP
\fIRouting Information Protocol, v2 (RFC 2453, STD 0056, November 1998)\fR
.sp
.LP
\fIRIP-v2 MD5 Authentication (RFC 2082, January 1997)\fR
.sp
.LP
\fIRouting Information Protocol, v1 (RFC 1058, June 1988)\fR
.sp
.LP
\fIICMP Router Discovery Messages (RFC 1256, September 1991)\fR
.SH NOTES
.sp
.LP
In keeping with its intended design, this daemon deviates from RFC 2453 in two
notable ways:
.RS +4
.TP
.ie t \(bu
.el o
By default, \fBin.routed\fR does not discard authenticated RIPv2 messages when
RIP authentication is not configured. There is little to gain from dropping
authenticated packets when RIPv1 listeners will gladly process them. Using the
\fB-A\fR option causes \fBin.routed\fR to conform to the RFC in this case.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Unauthenticated RIP requests are never discarded, even when RIP authentication
is configured. Forwarding tables are not secret and can be inferred through
other means such as test traffic. RIP is also the most common router-discovery
protocol, and hosts need to send queries that will be answered.
.RE
.sp
.LP
\fBin.routed\fR does not always detect unidirectional failures in network
interfaces, for example, when the output side fails.