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