1 .\" $FreeBSD: src/sbin/routed/routed.8,v 1.15.2.9 2002/02/17 08:37:54 schweikh Exp $
3 .\" Copyright (c) 1983, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. All advertising materials mentioning features or use of this software
15 .\" must display the following acknowledgement:
16 .\" This product includes software developed by the University of
17 .\" California, Berkeley and its contributors.
18 .\" 4. Neither the name of the University nor the names of its contributors
19 .\" may be used to endorse or promote products derived from this software
20 .\" without specific prior written permission.
22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .\" @(#)routed.8 8.2 (Berkeley) 12/11/93
36 .\" $FreeBSD: src/sbin/routed/routed.8,v 1.15.2.9 2002/02/17 08:37:54 schweikh Exp $
44 .Nd network RIP and router discovery routing daemon
51 .Ar net Ns Op /mask Ns Op ,metric
56 is a daemon invoked at boot time to manage the network
58 It uses Routing Information Protocol, RIPv1 (RFC\ 1058),
60 and Internet Router Discovery Protocol (RFC 1256)
61 to maintain the kernel routing table.
62 The RIPv1 protocol is based on the reference
72 for Routing Information Protocol packets.
73 It also sends and receives multicast Router Discovery ICMP messages.
74 If the host is a router,
76 periodically supplies copies
77 of its routing tables to any directly connected hosts and networks.
78 It also advertises or solicits default routes using Router Discovery
81 When started (or when a network interface is later turned on),
83 uses an AF_ROUTE address family facility to find those
84 directly connected interfaces configured into the
85 system and marked "up".
86 It adds necessary routes for the interfaces
87 to the kernel routing table.
88 Soon after being first started, and provided there is at least one
89 interface on which RIP has not been disabled,
91 deletes all pre-existing
92 non-static routes in kernel table.
93 Static routes in the kernel table are preserved and
94 included in RIP responses if they have a valid RIP metric
98 If more than one interface is present (not counting the loopback interface),
99 it is assumed that the host should forward packets among the
101 After transmitting a RIP
104 Router Discovery Advertisements or Solicitations on a new interface,
105 the daemon enters a loop, listening for
106 RIP request and response and Router Discovery packets from other hosts.
112 formulates a reply based on the information maintained in its
116 packet generated contains a list of known routes, each marked
117 with a "hop count" metric (a count of 16 or greater is
118 considered "infinite").
119 Advertised metrics reflect the metric associated with interface
122 so setting the metric on an interface
123 is an effective way to steer traffic.
125 Responses do not include routes with a first hop on the requesting
126 network to implement in part
128 Requests from query programs
131 are answered with the complete table.
133 The routing table maintained by the daemon
134 includes space for several gateways for each destination
135 to speed recovery from a failing router.
138 packets received are used to update the routing tables provided they are
139 from one of the several currently recognized gateways or
140 advertise a better metric than at least one of the existing
143 When an update is applied,
145 records the change in its own tables and updates the kernel routing table
146 if the best route to the destination changes.
147 The change in the kernel routing table is reflected in the next batch of
150 If the next response is not scheduled for a while, a
152 response containing only recently changed routes is sent.
154 In addition to processing incoming packets,
156 also periodically checks the routing table entries.
157 If an entry has not been updated for 3 minutes, the entry's metric
158 is set to infinity and marked for deletion.
159 Deletions are delayed until the route has been advertised with
160 an infinite metric to insure the invalidation
161 is propagated throughout the local internet.
165 Routes in the kernel table that are added or changed as a result
166 of ICMP Redirect messages are deleted after a while to minimize
168 When a TCP connection suffers a timeout,
171 which deletes all redirected routes
172 through the gateway involved, advances the age of all RIP routes through
173 the gateway to allow an alternate to be chosen, and advances of the
174 age of any relevant Router Discovery Protocol default routes.
176 Hosts acting as internetwork routers gratuitously supply their
177 routing tables every 30 seconds to all directly connected hosts
179 These RIP responses are sent to the broadcast address on nets that support
181 to the destination address on point-to-point links, and to the router's
182 own address on other networks.
183 If RIPv2 is enabled, multicast packets are sent on interfaces that
184 support multicasting.
186 If no response is received on a remote interface, if there are errors
187 while sending responses,
188 or if there are more errors than input or output (see
190 then the cable or some other part of the interface is assumed to be
191 disconnected or broken, and routes are adjusted appropriately.
194 .Em Internet Router Discovery Protocol
195 is handled similarly.
196 When the daemon is supplying RIP routes, it also listens for
197 Router Discovery Solicitations and sends Advertisements.
198 When it is quiet and listening to other RIP routers, it
199 sends Solicitations and listens for Advertisements.
201 a good Advertisement and it is not multi-homed,
202 it stops listening for broadcast or multicast RIP responses.
203 It tracks several advertising routers to speed recovery when the
204 currently chosen router dies.
205 If all discovered routers disappear,
206 the daemon resumes listening to RIP responses.
207 It continues listening to RIP while using Router Discovery
208 if multi-homed to ensure all interfaces are used.
210 The Router Discovery standard requires that advertisements
211 have a default "lifetime" of 30 minutes. That means should
212 something happen, a client can be without a good route for
213 30 minutes. It is a good idea to reduce the default to 45
215 .Fl P Cm rdisc_interval=45
216 on the command line or
217 .Cm rdisc_interval=45
222 While using Router Discovery (which happens by default when
223 the system has a single network interface and a Router Discover Advertisement
224 is received), there is a single default route and a variable number of
225 redirected host routes in the kernel table.
226 On a host with more than one network interface,
227 this default route will be via only one of the interfaces.
228 Thus, multi-homed hosts running with \f3\-q\f1 might need
234 facility described below to support "legacy" systems
235 that can handle neither RIPv2 nor Router Discovery.
237 By default, neither Router Discovery advertisements nor solicitations
238 are sent over point to point links (e.g. PPP).
239 The netmask associated with point-to-point links (such as SLIP
240 or PPP, with the IFF_POINTOPOINT flag) is used by
242 to infer the netmask used by the remote system when RIPv1 is used.
244 The following options are available:
245 .Bl -tag -width indent
249 to supply routing information.
250 This is the default if multiple network interfaces are present on which
251 RIP or Router Discovery have not been disabled, and if the kernel switch
254 is the opposite of the
257 This is the default when only one interface is present.
258 With this explicit option, the daemon is always in "quiet-mode" for RIP
259 and does not supply routing information to other computers.
261 do not run in the background.
262 This option is meant for interactive use.
264 used on internetwork routers to offer a route
265 to the "default" destination.
269 and is present mostly for historical reasons.
272 on the command line or
277 since a larger metric
278 will be used, reducing the spread of the potentially dangerous
280 This is typically used on a gateway to the Internet,
281 or on a gateway that uses another routing protocol whose routes
282 are not reported to other local routers.
283 Notice that because a metric of 1 is used, this feature is
284 dangerous. It is more commonly accidentally used to create chaos with a
285 routing loop than to solve problems.
287 cause host or point-to-point routes to not be advertised,
288 provided there is a network route going the same direction.
289 That is a limited kind of aggregation.
290 This option is useful on gateways to Ethernets that have other gateway
291 machines connected with point-to-point links such as SLIP.
293 cause the machine to advertise a host or point-to-point route to
294 its primary interface.
295 It is useful on multi-homed machines such as NFS servers.
296 This option should not be used except when the cost of
297 the host routes it generates is justified by the popularity of
299 It is effective only when the machine is supplying
300 routing information, because there is more than one interface.
305 option to the limited extent of advertising the host route.
307 do not ignore RIPv2 authentication if we do not care about RIPv2
309 This option is required for conformance with RFC 1723.
310 However, it makes no sense and breaks using RIP as a discovery protocol
311 to ignore all RIPv2 packets that carry authentication when this machine
312 does not care about authentication.
314 increase the debugging level, which causes more information to be logged
315 on the tracefile specified with
318 The debugging level can be increased or decreased
326 .It Fl T Ar tracefile
327 increases the debugging level to at least 1 and
328 causes debugging information to be appended to the trace file.
329 Note that because of security concerns, it is wisest to not run
331 routinely with tracing directed to a file.
333 display and logs the version of daemon.
334 .It Fl F Ar net[/mask][,metric]
335 minimize routes in transmissions via interfaces with addresses that match
337 and synthesizes a default route to this machine with the
339 The intent is to reduce RIP traffic on slow, point-to-point links
340 such as PPP links by replacing many large UDP packets of RIP information
341 with a single, small packet containing a "fake" default route.
344 is absent, a value of 14 is assumed to limit
345 the spread of the "fake" default route.
346 This is a dangerous feature that when used carelessly can cause routing
348 Notice also that more than one interface can match the specified network
353 is equivalent to adding the parameter
361 Any other argument supplied is interpreted as the name
362 of a file in which the actions of
368 appending the name of the trace file to the command.
371 also supports the notion of
379 is started, it reads the file
381 to find such distant gateways which may not be located using
382 only information from a routing socket, to discover if some
383 of the local gateways are
385 and to obtain other parameters.
386 Gateways specified in this manner should be marked passive
387 if they are not expected to exchange routing information,
388 while gateways marked active
389 should be willing to exchange RIP packets.
392 gateways are installed in the
393 kernel's routing tables once upon startup and are not included in
394 transmitted RIP responses.
396 Distant active gateways are treated like network interfaces.
397 RIP responses are sent
401 If no responses are received, the associated route is deleted from
402 the kernel table and RIP responses advertised via other interfaces.
403 If the distant gateway resumes sending RIP responses, the associated
406 Such gateways can be useful on media that do not support broadcasts
407 or multicasts but otherwise act like classic shared media like
408 Ethernets such as some ATM networks.
409 One can list all RIP routers reachable on the HIPPI or ATM network in
413 Note that it is usually desirable to use RIPv2 in such situations
414 to avoid generating lists of inferred host routes.
418 are also passive, but are not placed in the kernel
419 routing table nor are they included in routing updates.
420 The function of external entries is to indicate
421 that another routing process
422 will install such a route if necessary,
423 and that other routes to that destination should not be installed
426 Such entries are only required when both routers may learn of routes
427 to the same destination.
431 file is comprised of a series of lines, each in
432 one of the following two formats or consist of parameters described later.
433 Blank lines and lines starting with '#' are comments.
442 .Pf < Cm passive No \&|
453 .Pf < Cm passive No \&|
461 is the name of the destination network or host.
462 It may be a symbolic network name or an Internet address
463 specified in "dot" notation (see
465 (If it is a name, then it must either be defined in
471 must have been started before
475 is an optional number between 1 and 32 indicating the netmask associated
480 is the name or address of the gateway to which RIP responses should
484 is the hop count to the destination host or network.
488 .Cm net Ar nname/32 .
495 must be present to indicate whether the gateway should be treated as
499 (as described above),
500 or whether the gateway is
502 to the scope of the RIP protocol.
504 As can be seen when debugging is turned on with
506 such lines create pseudo-interfaces.
507 To set parameters for remote or external interfaces,
509 .Cm if=alias(Hname) ,
510 .Cm if=remote(Hname) ,
513 Lines that start with neither "net" nor "host" must consist of one
514 or more of the following parameter settings, separated by commas or
517 .It Cm if Ns \&= Ns Ar ifname
518 indicates that the other parameters on the line apply to the interface
521 .It Cm subnet Ns \&= Ns Ar nname[/mask][,metric]
522 advertises a route to network
526 and the supplied metric (default 1).
527 This is useful for filling "holes" in CIDR allocations.
528 This parameter must appear by itself on a line.
529 The network number must specify a full, 32-bit value, as in 192.0.2.0
532 Do not use this feature unless necessary. It is dangerous.
533 .It Cm ripv1_mask Ns \&= Ns Ar nname/mask1,mask2
534 specifies that netmask of the network of which
539 For example \f2ripv1_mask=192.0.2.16/28,27\f1 marks 192.0.2.16/28
540 as a subnet of 192.0.2.0/27 instead of 192.0.2.0/24.
541 It is better to turn on RIPv2 instead of using this facility, for example
542 with \f2ripv2_out\f1.
543 .It Cm passwd Ns \&= Ns Ar XXX[|KeyID[start|stop]]
544 specifies a RIPv2 cleartext password that will be included on
545 all RIPv2 responses sent, and checked on all RIPv2 responses received.
546 Any blanks, tab characters, commas, or '#', '|', or NULL characters in the
547 password must be escaped with a backslash (\\).
548 The common escape sequences \\n, \\r, \\t, \\b, and \\xxx have their
552 must be unique but is ignored for cleartext passwords.
557 are timestamps in the form year/month/day@hour:minute.
558 They specify when the password is valid.
559 The valid password with the most future is used on output packets, unless
560 all passwords have expired, in which case the password that expired most
561 recently is used, or unless no passwords are valid yet, in which case
562 no password is output.
563 Incoming packets can carry any password that is valid, will
564 be valid within 24 hours, or that was valid within 24 hours.
565 To protect the secrets, the passwd settings are valid only in the
567 file and only when that file is readable only by UID 0.
568 .It Cm md5_passwd Ns \&= Ns Ar XXX|KeyID[start|stop]
569 specifies a RIPv2 MD5 password.
572 is required, this keyword is similar to
575 turns off aggregation of subnets in RIPv1 and RIPv2 responses.
577 turns off aggregation of networks into supernets in RIPv2 responses.
579 marks the interface to not be advertised in updates sent via other
580 interfaces, and turns off all RIP and router discovery through the interface.
582 disables all RIP processing on the specified interface.
583 If no interfaces are allowed to process RIP packets,
585 acts purely as a router discovery daemon.
587 Note that turning off RIP without explicitly turning on router
588 discovery advertisements with
594 to act as a client router discovery daemon, not advertising.
596 causes RIPv2 packets to be broadcast instead of multicast.
598 causes RIPv1 received responses to be ignored.
600 causes RIPv2 received responses to be ignored.
602 turns on RIPv2 output and causes RIPv2 advertisements to be
603 multicast when possible.
611 disables the Internet Router Discovery Protocol.
613 disables the transmission of Router Discovery Solicitations.
615 specifies that Router Discovery solicitations should be sent,
616 even on point-to-point links,
617 which by default only listen to Router Discovery messages.
619 disables the transmission of Router Discovery Advertisements.
621 specifies that Router Discovery Advertisements should be sent,
622 even on point-to-point links,
623 which by default only listen to Router Discovery messages.
625 specifies that Router Discovery packets should be broadcast instead of
627 .It Cm rdisc_pref Ns \&= Ns Ar N
628 sets the preference in Router Discovery Advertisements to the optionally
631 The default preference is 0.
632 Default routes with smaller or more negative preferences are preferred by
634 .It Cm rdisc_interval Ns \&= Ns Ar N
635 sets the nominal interval with which Router Discovery Advertisements
636 are transmitted to N seconds and their lifetime to 3*N.
637 .It Cm fake_default Ns \&= Ns Ar metric
638 has an identical effect to
639 .Fl F Ar net[/mask][=metric]
640 with the network and mask coming from the specified interface.
644 When RIPv2 routes are multicast, so that RIPv1 listeners cannot
645 receive them, this feature causes a RIPv1 default route to be
646 broadcast to RIPv1 listeners.
649 the default route is broadcast with a metric of 14.
650 That serves as a "poor man's router discovery" protocol.
651 .It Cm trust_gateway Ns \&= Ns Ar rname[|net1/mask1|net2/mask2|...]
652 causes RIP packets from that router and other routers named in
655 keywords to be accepted, and packets from other routers to be ignored.
656 If networks are specified, then routes to other networks will be ignored
659 causes RIP to allow ICMP Redirect messages when the system is acting
660 as a router and forwarding packets.
661 Otherwise, ICMP Redirect messages are overridden.
664 .Bl -tag -width /etc/gateways -compact
673 .%T Internet Transport Protocols
675 .%Q Xerox System Integration Standard
678 It does not always detect unidirectional failures in network interfaces,
679 for example, when the output side fails.