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