xref: /dragonfly/sbin/routed/routed.8 (revision 7bc7e232)
1.\" $FreeBSD: src/sbin/routed/routed.8,v 1.15.2.9 2002/02/17 08:37:54 schweikh Exp $
2.\" $DragonFly: src/sbin/routed/routed.8,v 1.4 2007/11/23 23:16:36 swildner Exp $
3.\"
4.\" Copyright (c) 1983, 1991, 1993
5.\"	The Regents of the University of California.  All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\" 3. All advertising materials mentioning features or use of this software
16.\"    must display the following acknowledgement:
17.\"	This product includes software developed by the University of
18.\"	California, Berkeley and its contributors.
19.\" 4. Neither the name of the University nor the names of its contributors
20.\"    may be used to endorse or promote products derived from this software
21.\"    without specific prior written permission.
22.\"
23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33.\" SUCH DAMAGE.
34.\"
35.\"     @(#)routed.8	8.2 (Berkeley) 12/11/93
36.\"
37.\" $FreeBSD: src/sbin/routed/routed.8,v 1.15.2.9 2002/02/17 08:37:54 schweikh Exp $
38.\"
39.Dd June 1, 1996
40.Dt ROUTED 8
41.Os
42.Sh NAME
43.Nm routed ,
44.Nm rdisc
45.Nd network RIP and router discovery routing daemon
46.Sh SYNOPSIS
47.Nm
48.Op Fl sqdghmpAtv
49.Op Fl T Ar tracefile
50.Oo
51.Fl F
52.Ar net Ns Op /mask Ns Op ,metric
53.Oc
54.Op Fl P Ar parms
55.Sh DESCRIPTION
56.Nm Routed
57is a daemon invoked at boot time to manage the network
58routing tables.
59It uses Routing Information Protocol, RIPv1 (RFC 1058),
60RIPv2 (RFC 1723),
61and Internet Router Discovery Protocol (RFC 1256)
62to maintain the kernel routing table.
63The RIPv1 protocol is based on the reference
64.Bx 4.3
65daemon.
66.Pp
67It listens on the
68.Xr udp 4
69socket for the
70.Xr route 8
71service (see
72.Xr services 5 )
73for Routing Information Protocol packets.
74It also sends and receives multicast Router Discovery ICMP messages.
75If the host is a router,
76.Nm
77periodically supplies copies
78of its routing tables to any directly connected hosts and networks.
79It also advertises or solicits default routes using Router Discovery
80ICMP messages.
81.Pp
82When started (or when a network interface is later turned on),
83.Nm
84uses an AF_ROUTE address family facility to find those
85directly connected interfaces configured into the
86system and marked "up".
87It adds necessary routes for the interfaces
88to the kernel routing table.
89Soon after being first started, and provided there is at least one
90interface on which RIP has not been disabled,
91.Nm
92deletes all pre-existing
93non-static routes in kernel table.
94Static routes in the kernel table are preserved and
95included in RIP responses if they have a valid RIP metric
96(see
97.Xr route 8 ) .
98.Pp
99If more than one interface is present (not counting the loopback interface),
100it is assumed that the host should forward packets among the
101connected networks.
102After transmitting a RIP
103.Em request
104and
105Router Discovery Advertisements or Solicitations on a new interface,
106the daemon enters a loop, listening for
107RIP request and response and Router Discovery packets from other hosts.
108.Pp
109When a
110.Em request
111packet is received,
112.Nm
113formulates a reply based on the information maintained in its
114internal tables.
115The
116.Em response
117packet generated contains a list of known routes, each marked
118with a "hop count" metric (a count of 16 or greater is
119considered "infinite").
120Advertised metrics reflect the metric associated with interface
121(see
122.Xr ifconfig 8 ) ,
123so setting the metric on an interface
124is an effective way to steer traffic.
125.Pp
126Responses do not include routes with a first hop on the requesting
127network to implement in part
128.Em split-horizon .
129Requests from query programs
130such as
131.Xr rtquery 8
132are answered with the complete table.
133.Pp
134The routing table maintained by the daemon
135includes space for several gateways for each destination
136to speed recovery from a failing router.
137RIP
138.Em response
139packets received are used to update the routing tables provided they are
140from one of the several currently recognized gateways or
141advertise a better metric than at least one of the existing
142gateways.
143.Pp
144When an update is applied,
145.Nm
146records the change in its own tables and updates the kernel routing table
147if the best route to the destination changes.
148The change in the kernel routing table is reflected in the next batch of
149.Em response
150packets sent.
151If the next response is not scheduled for a while, a
152.Em flash update
153response containing only recently changed routes is sent.
154.Pp
155In addition to processing incoming packets,
156.Nm
157also periodically checks the routing table entries.
158If an entry has not been updated for 3 minutes, the entry's metric
159is set to infinity and marked for deletion.
160Deletions are delayed until the route has been advertised with
161an infinite metric to insure the invalidation
162is propagated throughout the local internet.
163This is a form of
164.Em poison reverse .
165.Pp
166Routes in the kernel table that are added or changed as a result
167of ICMP Redirect messages are deleted after a while to minimize
168.Em black-holes .
169When a TCP connection suffers a timeout,
170the kernel tells
171.Nm ,
172which deletes all redirected routes
173through the gateway involved, advances the age of all RIP routes through
174the gateway to allow an alternate to be chosen, and advances of the
175age of any relevant Router Discovery Protocol default routes.
176.Pp
177Hosts acting as internetwork routers gratuitously supply their
178routing tables every 30 seconds to all directly connected hosts
179and networks.
180These RIP responses are sent to the broadcast address on nets that support
181broadcasting,
182to the destination address on point-to-point links, and to the router's
183own address on other networks.
184If RIPv2 is enabled, multicast packets are sent on interfaces that
185support multicasting.
186.Pp
187If no response is received on a remote interface, if there are errors
188while sending responses,
189or if there are more errors than input or output (see
190.Xr netstat 1 ) ,
191then the cable or some other part of the interface is assumed to be
192disconnected or broken, and routes are adjusted appropriately.
193.Pp
194The
195.Em Internet Router Discovery Protocol
196is handled similarly.
197When the daemon is supplying RIP routes, it also listens for
198Router Discovery Solicitations and sends Advertisements.
199When it is quiet and listening to other RIP routers, it
200sends Solicitations and listens for Advertisements.
201If it receives
202a good Advertisement and it is not multi-homed,
203it stops listening for broadcast or multicast RIP responses.
204It tracks several advertising routers to speed recovery when the
205currently chosen router dies.
206If all discovered routers disappear,
207the daemon resumes listening to RIP responses.
208It continues listening to RIP while using Router Discovery
209if multi-homed to ensure all interfaces are used.
210.Pp
211The Router Discovery standard requires that advertisements
212have a default "lifetime" of 30 minutes.  That means should
213something happen, a client can be without a good route for
21430 minutes.  It is a good idea to reduce the default to 45
215seconds using
216.Fl P Cm rdisc_interval=45
217on the command line or
218.Cm rdisc_interval=45
219in the
220.Pa /etc/gateways
221file.
222.Pp
223While using Router Discovery (which happens by default when
224the system has a single network interface and a Router Discover Advertisement
225is received), there is a single default route and a variable number of
226redirected host routes in the kernel table.
227On a host with more than one network interface,
228this default route will be via only one of the interfaces.
229Thus, multi-homed hosts running with \f3\-q\f1 might need
230.Cm no_rdisc
231described below.
232.Pp
233See the
234.Cm pm_rdisc
235facility described below to support "legacy" systems
236that can handle neither RIPv2 nor Router Discovery.
237.Pp
238By default, neither Router Discovery advertisements nor solicitations
239are sent over point to point links (e.g. PPP).
240The netmask associated with point-to-point links (such as SLIP
241or PPP, with the IFF_POINTOPOINT flag) is used by
242.Nm
243to infer the netmask used by the remote system when RIPv1 is used.
244.Pp
245The following options are available:
246.Bl -tag -width indent
247.It Fl s
248force
249.Nm
250to supply routing information.
251This is the default if multiple network interfaces are present on which
252RIP or Router Discovery have not been disabled, and if the kernel switch
253ipforwarding=1.
254.It Fl q
255is the opposite of the
256.Fl s
257option.
258This is the default when only one interface is present.
259With this explicit option, the daemon is always in "quiet-mode" for RIP
260and does not supply routing information to other computers.
261.It Fl d
262do not run in the background.
263This option is meant for interactive use.
264.It Fl g
265used on internetwork routers to offer a route
266to the "default" destination.
267It is equivalent to
268.Fl F
269.Cm 0/0,1
270and is present mostly for historical reasons.
271A better choice is
272.Fl P Cm pm_rdisc
273on the command line or
274.Cm pm_rdisc
275in the
276.Pa /etc/gateways
277file,
278since a larger metric
279will be used, reducing the spread of the potentially dangerous
280default route.
281This is typically used on a gateway to the Internet,
282or on a gateway that uses another routing protocol whose routes
283are not reported to other local routers.
284Notice that because a metric of 1 is used, this feature is
285dangerous.  It is more commonly accidentally used to create chaos with a
286routing loop than to solve problems.
287.It Fl h
288cause host or point-to-point routes to not be advertised,
289provided there is a network route going the same direction.
290That is a limited kind of aggregation.
291This option is useful on gateways to Ethernets that have other gateway
292machines connected with point-to-point links such as SLIP.
293.It Fl m
294cause the machine to advertise a host or point-to-point route to
295its primary interface.
296It is useful on multi-homed machines such as NFS servers.
297This option should not be used except when the cost of
298the host routes it generates is justified by the popularity of
299the server.
300It is effective only when the machine is supplying
301routing information, because there is more than one interface.
302The
303.Fl m
304option overrides the
305.Fl q
306option to the limited extent of advertising the host route.
307.It Fl A
308do not ignore RIPv2 authentication if we do not care about RIPv2
309authentication.
310This option is required for conformance with RFC 1723.
311However, it makes no sense and breaks using RIP as a discovery protocol
312to ignore all RIPv2 packets that carry authentication when this machine
313does not care about authentication.
314.It Fl t
315increase the debugging level, which causes more information to be logged
316on the tracefile specified with
317.Fl T
318or standard out.
319The debugging level can be increased or decreased
320with the
321.Em SIGUSR1
322or
323.Em SIGUSR2
324signals or with the
325.Xr rtquery 8
326command.
327.It Fl T Ar tracefile
328increases the debugging level to at least 1 and
329causes debugging information to be appended to the trace file.
330Note that because of security concerns, it is wisest to not run
331.Nm
332routinely with tracing directed to a file.
333.It Fl v
334display and logs the version of daemon.
335.It Fl F Ar net[/mask][,metric]
336minimize routes in transmissions via interfaces with addresses that match
337.Em net/mask ,
338and synthesizes a default route to this machine with the
339.Em metric .
340The intent is to reduce RIP traffic on slow, point-to-point links
341such as PPP links by replacing many large UDP packets of RIP information
342with a single, small packet containing a "fake" default route.
343If
344.Em metric
345is absent, a value of 14 is assumed to limit
346the spread of the "fake" default route.
347This is a dangerous feature that when used carelessly can cause routing
348loops.
349Notice also that more than one interface can match the specified network
350number and mask.
351See also
352.Fl g .
353.It Fl P Ar parms
354is equivalent to adding the parameter
355line
356.Em parms
357to the
358.Pa /etc/gateways
359file.
360.El
361.Pp
362Any other argument supplied is interpreted as the name
363of a file in which the actions of
364.Nm
365should be logged.
366It is better to use
367.Fl T
368instead of
369appending the name of the trace file to the command.
370.Pp
371.Nm Routed
372also supports the notion of
373"distant"
374.Em passive
375or
376.Em active
377gateways.
378When
379.Nm
380is started, it reads the file
381.Pa /etc/gateways
382to find such distant gateways which may not be located using
383only information from a routing socket, to discover if some
384of the local gateways are
385.Em passive ,
386and to obtain other parameters.
387Gateways specified in this manner should be marked passive
388if they are not expected to exchange routing information,
389while gateways marked active
390should be willing to exchange RIP packets.
391Routes through
392.Em passive
393gateways are installed in the
394kernel's routing tables once upon startup and are not included in
395transmitted RIP responses.
396.Pp
397Distant active gateways are treated like network interfaces.
398RIP responses are sent
399to the distant
400.Em active
401gateway.
402If no responses are received, the associated route is deleted from
403the kernel table and RIP responses advertised via other interfaces.
404If the distant gateway resumes sending RIP responses, the associated
405route is restored.
406.Pp
407Such gateways can be useful on media that do not support broadcasts
408or multicasts but otherwise act like classic shared media like
409Ethernets such as some ATM networks.
410One can list all RIP routers reachable on the HIPPI or ATM network in
411.Pa /etc/gateways
412with a series of
413"host" lines.
414Note that it is usually desirable to use RIPv2 in such situations
415to avoid generating lists of inferred host routes.
416.Pp
417Gateways marked
418.Em external
419are also passive, but are not placed in the kernel
420routing table nor are they included in routing updates.
421The function of external entries is to indicate
422that another routing process
423will install such a route if necessary,
424and that other routes to that destination should not be installed
425by
426.Nm .
427Such entries are only required when both routers may learn of routes
428to the same destination.
429.Pp
430The
431.Pa /etc/gateways
432file is comprised of a series of lines, each in
433one of the following two formats or consist of parameters described later.
434Blank lines and lines starting with '#' are comments.
435.Pp
436.Bd -ragged
437.Cm net
438.Ar Nname[/mask]
439.Cm gateway
440.Ar Gname
441.Cm metric
442.Ar value
443.Pf < Cm passive No \&|
444.Cm active No \&|
445.Cm extern Ns >
446.Ed
447.Bd -ragged
448.Cm host
449.Ar Hname
450.Cm gateway
451.Ar Gname
452.Cm metric
453.Ar value
454.Pf < Cm passive No \&|
455.Cm active No \&|
456.Cm extern Ns >
457.Ed
458.Pp
459.Ar Nname
460or
461.Ar Hname
462is the name of the destination network or host.
463It may be a symbolic network name or an Internet address
464specified in "dot" notation (see
465.Xr inet 3 ) .
466(If it is a name, then it must either be defined in
467.Pa /etc/networks
468or
469.Pa /etc/hosts ,
470or
471.Xr named 8 ,
472must have been started before
473.Nm . )
474.Pp
475.Ar Mask
476is an optional number between 1 and 32 indicating the netmask associated
477with
478.Ar Nname .
479.Pp
480.Ar Gname
481is the name or address of the gateway to which RIP responses should
482be forwarded.
483.Pp
484.Ar Value
485is the hop count to the destination host or network.
486.Pp
487.Cm Host Ar hname
488is equivalent to
489.Cm net Ar nname/32 .
490.Pp
491One of the keywords
492.Cm passive ,
493.Cm active
494or
495.Cm external
496must be present to indicate whether the gateway should be treated as
497.Cm passive
498or
499.Cm active
500(as described above),
501or whether the gateway is
502.Cm external
503to the scope of the RIP protocol.
504.Pp
505As can be seen when debugging is turned on with
506.Fl t ,
507such lines create pseudo-interfaces.
508To set parameters for remote or external interfaces,
509a line starting with
510.Cm if=alias(Hname) ,
511.Cm if=remote(Hname) ,
512etc. should be used.
513.Pp
514Lines that start with neither "net" nor "host" must consist of one
515or more of the following parameter settings, separated by commas or
516blanks:
517.Bl -tag -width Ds
518.It Cm if Ns \&= Ns Ar ifname
519indicates that the other parameters on the line apply to the interface
520name
521.Ar ifname .
522.It Cm subnet Ns \&= Ns Ar nname[/mask][,metric]
523advertises a route to network
524.Ar nname
525with mask
526.Ar mask
527and the supplied metric (default 1).
528This is useful for filling "holes" in CIDR allocations.
529This parameter must appear by itself on a line.
530The network number must specify a full, 32-bit value, as in 192.0.2.0
531instead of 192.0.2.
532.Pp
533Do not use this feature unless necessary.  It is dangerous.
534.It Cm ripv1_mask Ns \&= Ns Ar nname/mask1,mask2
535specifies that netmask of the network of which
536.Cm nname/mask1\f1
537is
538a subnet should be
539.Cm mask2 .
540For example \f2ripv1_mask=192.0.2.16/28,27\f1 marks 192.0.2.16/28
541as a subnet of 192.0.2.0/27 instead of 192.0.2.0/24.
542It is better to turn on RIPv2 instead of using this facility, for example
543with \f2ripv2_out\f1.
544.It Cm passwd Ns \&= Ns Ar XXX[|KeyID[start|stop]]
545specifies a RIPv2 cleartext password that will be included on
546all RIPv2 responses sent, and checked on all RIPv2 responses received.
547Any blanks, tab characters, commas, or '#', '|', or NULL characters in the
548password must be escaped with a backslash (\\).
549The common escape sequences \\n, \\r, \\t, \\b, and \\xxx have their
550usual meanings.
551The
552.Cm KeyID
553must be unique but is ignored for cleartext passwords.
554If present,
555.Cm start
556and
557.Cm stop
558are timestamps in the form year/month/day@hour:minute.
559They specify when the password is valid.
560The valid password with the most future is used on output packets, unless
561all passwords have expired, in which case the password that expired most
562recently is used, or unless no passwords are valid yet, in which case
563no password is output.
564Incoming packets can carry any password that is valid, will
565be valid within 24 hours, or that was valid within 24 hours.
566To protect the secrets, the passwd settings are valid only in the
567.Em /etc/gateways
568file and only when that file is readable only by UID 0.
569.It Cm md5_passwd Ns \&= Ns Ar XXX|KeyID[start|stop]
570specifies a RIPv2 MD5 password.
571Except that a
572.Cm KeyID
573is required, this keyword is similar to
574.Cm passwd .
575.It Cm no_ag
576turns off aggregation of subnets in RIPv1 and RIPv2 responses.
577.It Cm no_super_ag
578turns off aggregation of networks into supernets in RIPv2 responses.
579.It Cm passive
580marks the interface to not be advertised in updates sent via other
581interfaces, and turns off all RIP and router discovery through the interface.
582.It Cm no_rip
583disables all RIP processing on the specified interface.
584If no interfaces are allowed to process RIP packets,
585.Nm
586acts purely as a router discovery daemon.
587.Pp
588Note that turning off RIP without explicitly turning on router
589discovery advertisements with
590.Cm rdisc_adv
591or
592.Fl s
593causes
594.Nm
595to act as a client router discovery daemon, not advertising.
596.It Cm no_rip_mcast
597causes RIPv2 packets to be broadcast instead of multicast.
598.It Cm no_ripv1_in
599causes RIPv1 received responses to be ignored.
600.It Cm no_ripv2_in
601causes RIPv2 received responses to be ignored.
602.It Cm ripv2_out
603turns on RIPv2 output and causes RIPv2 advertisements to be
604multicast when possible.
605.It Cm ripv2
606is equivalent to
607.Cm no_ripv1_in
608and
609.Cm no_ripv1_out .
610This enables RIPv2.
611.It Cm no_rdisc
612disables the Internet Router Discovery Protocol.
613.It Cm no_solicit
614disables the transmission of Router Discovery Solicitations.
615.It Cm send_solicit
616specifies that Router Discovery solicitations should be sent,
617even on point-to-point links,
618which by default only listen to Router Discovery messages.
619.It Cm no_rdisc_adv
620disables the transmission of Router Discovery Advertisements.
621.It Cm rdisc_adv
622specifies that Router Discovery Advertisements should be sent,
623even on point-to-point links,
624which by default only listen to Router Discovery messages.
625.It Cm bcast_rdisc
626specifies that Router Discovery packets should be broadcast instead of
627multicast.
628.It Cm rdisc_pref Ns \&= Ns Ar N
629sets the preference in Router Discovery Advertisements to the optionally
630signed integer
631.Ar N .
632The default preference is 0.
633Default routes with smaller or more negative preferences are preferred by
634clients.
635.It Cm rdisc_interval Ns \&= Ns Ar N
636sets the nominal interval with which Router Discovery Advertisements
637are transmitted to N seconds and their lifetime to 3*N.
638.It Cm fake_default Ns \&= Ns Ar metric
639has an identical effect to
640.Fl F Ar net[/mask][=metric]
641with the network and mask coming from the specified interface.
642.It Cm pm_rdisc
643is similar to
644.Cm fake_default .
645When RIPv2 routes are multicast, so that RIPv1 listeners cannot
646receive them, this feature causes a RIPv1 default route to be
647broadcast to RIPv1 listeners.
648Unless modified with
649.Cm fake_default ,
650the default route is broadcast with a metric of 14.
651That serves as a "poor man's router discovery" protocol.
652.It Cm trust_gateway Ns \&= Ns Ar rname[|net1/mask1|net2/mask2|...]
653causes RIP packets from that router and other routers named in
654other
655.Cm trust_gateway
656keywords to be accepted, and packets from other routers to be ignored.
657If networks are specified, then routes to other networks will be ignored
658from that router.
659.It Cm redirect_ok
660causes RIP to allow ICMP Redirect messages when the system is acting
661as a router and forwarding packets.
662Otherwise, ICMP Redirect messages are overridden.
663.El
664.Sh FILES
665.Bl -tag -width /etc/gateways -compact
666.It Pa /etc/gateways
667for distant gateways
668.El
669.Sh SEE ALSO
670.Xr icmp 4 ,
671.Xr udp 4 ,
672.Xr rtquery 8
673.Rs
674.%T Internet Transport Protocols
675.%R XSIS 028112
676.%Q Xerox System Integration Standard
677.Re
678.Sh HISTORY
679The
680.Nm
681command appeared in
682.Bx 4.2 .
683.Sh BUGS
684It does not always detect unidirectional failures in network interfaces,
685for example, when the output side fails.
686