kernel: Remove some old ISA only drivers.
[dragonfly.git] / usr.sbin / mrouted / mrouted.8
1 .\"COPYRIGHT 1989 by The Board of Trustees of Leland Stanford Junior University.
2 .\"
3 .\" $FreeBSD: src/usr.sbin/mrouted/mrouted.8,v 2003/03/11 22:31:29 trhodes Exp $
4 .\"
5 .Dd May 8, 1995
7 .Os
8 .Sh NAME
9 .Nm mrouted
10 .Nd IP multicast routing daemon
12 .Nm
13 .Op Fl c Ar config_file
14 .Op Fl d Op Ar debug_level
15 .Op Fl p
17 The
18 .Nm
19 utility is an implementation of the Distance-Vector Multicast Routing
20 Protocol (DVMRP), an earlier version of which is specified in RFC 1075.
21 It maintains topological knowledge via a distance-vector routing protocol
22 (like RIP, described in RFC 1058), upon which it implements a multicast
23 datagram forwarding algorithm called Reverse Path Multicasting.
24 .Pp
25 The
26 .Nm
27 utility forwards a multicast datagram along a shortest (reverse) path tree
28 rooted at the subnet on which the datagram originates.
29 The multicast
30 delivery tree may be thought of as a broadcast delivery tree that has
31 been pruned back so that it does not extend beyond those subnetworks
32 that have members of the destination group.
33 Hence, datagrams
34 are not forwarded along those branches which have no listeners of the
35 multicast group.
36 The IP time-to-live of a multicast datagram can be
37 used to limit the range of multicast datagrams.
38 .Pp
39 In order to support multicasting among subnets that are separated by (unicast)
40 routers that do not support IP multicasting,
41 .Nm
42 includes support for
43 "tunnels", which are virtual point-to-point links between pairs of
44 multicast routers
45 located anywhere in an internet.  IP multicast packets are encapsulated for
46 transmission through tunnels, so that they look like normal unicast datagrams
47 to intervening routers and subnets.  The encapsulation
48 is added on entry to a tunnel, and stripped off
49 on exit from a tunnel.
50 The packets are encapsulated using the IP-in-IP protocol
51 (IP protocol number 4).
52 Older versions of
53 .Nm
54 tunneled using IP source routing, which puts a heavy load on some
55 types of routers.
56 This version does not support IP source route tunnelling.
57 .Pp
58 The tunnelling mechanism allows
59 .Nm
60 to establish a virtual internet, for
61 the purpose of multicasting only, which is independent of the physical
62 internet, and which may span multiple Autonomous Systems.  This capability
63 is intended for experimental support of internet multicasting only, pending
64 widespread support for multicast routing by the regular (unicast) routers.
65 The
66 .Nm
67 utility suffers from the well-known scaling problems of any distance-vector
68 routing protocol, and does not (yet) support hierarchical multicast routing.
69 .Pp
70 The
71 .Nm
72 utility
73 handles multicast routing only; there may or may not be unicast routing
74 software running on the same machine as
75 .Nm .
76 With the use of tunnels, it
77 is not necessary for
78 .Nm
79 to have access to more than one physical subnet
80 in order to perform multicast forwarding.
81 .Pp
82 The following options are available:
83 .Bl -tag -width indent
84 .It Fl c Ar config_file
85 Specify an alternative file for configuration commands.
86 Default is
87 .Pa /etc/mrouted.conf .
88 .It Fl d Op Ar debug_level
89 If no
90 .Fl d
91 option is given, or if the debug level is specified as 0,
92 .Nm
93 detaches from the invoking terminal.  Otherwise, it remains attached to the
94 invoking terminal and responsive to signals from that terminal.
95 Regardless of the debug level,
96 .Nm
97 always writes warning and error messages to the system
98 log daemon.  The
99 .Fl debug-level
100 argument is a comma-separated list of any of the following:
101 .Bl -tag -width indent
102 .It "packet"
103 Display the type, source and destination of all packets sent or received.
104 .It "pruning"
105 Display more information about prunes sent or received.
106 .It "routing"
107 Display more information about routing update packets sent or received.
108 .It "route_detail"
109 Display routing updates in excruciating detail.  This is generally way too
110 much information.
111 .It "neighbors"
112 Display information about neighbor discovery.
113 .It "cache"
114 Display insertions, deletions and refreshes of entries in
115 the kernel forwarding cache.
116 .It "timeout"
117 Debug timeouts and periodic processes.
118 .It "interface"
119 Display information about interfaces and their configuration.
120 .It "membership"
121 Display information about group memberships on physical interfaces.
122 .It "traceroute"
123 Display information about multicast traceroute requests
124 passing through this router.
125 .It "igmp"
126 Display IGMP operation including group membership and querier election.
127 .It "icmp"
128 Monitor ICMP handling.
129 .It "rsrr"
130 Monitor RSRR operation.
131 .El
132 .Pp
133 Upon startup,
134 .Nm
135 writes its pid to the file
136 .Pa /var/run/ .
137 .El
139 The
140 .Nm
141 utility automatically configures itself to forward on all multicast-capable
142 interfaces, i.e., interfaces that have the IFF_MULTICAST flag set (excluding
143 the loopback "interface"), and it finds other DVMRP routers directly reachable
144 via those interfaces.  To override the default configuration, or to add
145 tunnel links to other multicast routers,
146 configuration commands may be placed in
147 .Pa /etc/mrouted.conf
148 (or an alternative file, specified by the
149 .Fl c
150 option).
151 .Pp
152 The file format is free-form; whitespace (including newlines) is not
153 significant.
154 The file begins with commands that apply to
155 .Nm Ns 's
156 overall operation or set defaults.
157 .Bl -tag -width indent
158 .It cache_lifetime Ar secs
159 Specifies, in seconds, the lifetime of a multicast forwarding cache
160 entry in the kernel.  Multicast forwarding cache entries in the kernel
161 are checked every
162 .Ar secs
163 seconds, and are refreshed if the source is still
164 active or deleted if not.  Care should be taken when setting this value,
165 as a low value can keep the kernel cache small at the cost of "thrashing"
166 the cache for periodic senders, but high values can cause the kernel
167 cache to grow unacceptably large.  The default is 300 seconds (5 minutes).
168 .It prune_lifetime Ar secs
169 Specifies, in seconds, the average lifetime of prunes that are sent towards
170 parents.  The actual lifetimes will be randomized in the range
171 [.5\fIsecs\fP,1.5\fIsecs\fP].  The default is 7200 (2 hours).  Smaller values
172 cause less state to be kept both at this router and the parent, at the
173 cost of more frequent broadcasts.  However, some routers (e.g.\&
174 .Nm
175 <3.3
176 and all currently known versions of cisco's IOS) do not use the
177 DVMRP generation ID to determine that a neighbor has rebooted.  Prunes
178 sent towards these neighbors should be kept short, in order to shorten
179 the time to recover from a reboot.  For use in this situation, the
180 prune_lifetime keyword may be specified on an interface as described
181 below.
182 .It noflood
183 The
184 .Nm
185 utility
186 uses a DVMRP optimization to prevent having to keep individual routing tables
187 for each neighbor; part of this optimization is that
188 .Nm
189 assumes that it is the forwarder for each of its attached subnets on
190 startup.  This can cause duplicates for a short period (approximately
191 one full route report interval), since both the router that just
192 started up and the proper forwarder will be forwarding traffic.  This
193 behavior can be turned off with the noflood keyword;
194 .Nm
195 will not assume that it is the forwarder on startup.
196 Turning on noflood can cause black holes on restart, which will generally
197 last approximately one full route report interval.
198 The noflood keyword can also be specified on individual interfaces.
199 .It rexmit_prunes Ar [on|off]
200 Default is to retransmit prunes on all point-to-point interfaces
201 (including tunnels) but no multi-access interfaces.  This option
202 may be used to make the default on (or off) for all interfaces.
203 The rexmit_prunes keyword can also be specified on individual interfaces.
204 .It name Ar "boundary-name scoped-addr/mask-len"
205 Associates
206 .Ar boundary-name
207 with the boundary described by
208 .Ar scoped-addr/mask-len ,
209 to help make interface configurations
210 more readable and reduce repetition in the configuration file.
211 .El
212 .Pp
213 The second section of the configuration file, which may optionally
214 be empty, describes options that apply to physical interfaces.
215 .Bl -tag -width indent
216 .It phyint Ar "local-addr|ifname"
217 The phyint command does nothing by itself; it is simply a place holder
218 which interface-specific commands may follow.  An interface address or
219 name may be specified.
220 .It disable
221 Disables multicast forwarding on this interface.  By default,
222 .Nm
223 discovers all locally attached multicast capable interfaces and forwards
224 on all of them.
225 .It netmask Ar netmask
226 If the kernel's netmask does not accurately reflect
227 the subnet (e.g. you're using proxy-ARP in lieu of IP subnetting), use the
228 netmask command to describe the real netmask.
229 .It altnet Ar network/mask-len
230 If a phyint is attached to multiple IP subnets, describe each additional subnet
231 with the altnet keyword.  This command may be specified multiple times
232 to describe multiple subnets.
233 .It igmpv1
234 If there are any IGMPv1 routers on the phyint, use the \fBigmpv1\fP
235 keyword to force
236 .Nm
237 into IGMPv1 mode.  All routers on the phyint
238 must use the same version of IGMP.
239 .It force_leaf
240 Force
241 .Nm
242 to ignore other routers on this interface.
243 .Nm
244 will never send or accept neighbor probes or
245 route reports on this interface.
246 .El
247 .Pp
248 In addition, the common vif commands described later may all be used on
249 a phyint.
250 .Pp
251 The third section of the configuration file, also optional, describes
252 the configuration of any DVMRP tunnels this router might have.
253 .Bl -tag -width indent
254 .It tunnel Ar "local-addr|ifname" Ar "remote-addr|remote-hostname"
255 This command establishes a DVMRP tunnel between this host (on the interface
256 described by
257 .Ar local-addr
258 or
259 .Ar ifname )
260 and a remote host (identified by
261 .Ar remote-addr
262 or
263 .Ar remote-hostname ) .
264 A remote hostname may only be used if
265 it maps to a single IP address.
266 A tunnel must be configured on both routers before it can be used.
267 .Pp
268 Be careful that the unicast route to the remote address goes out the
269 interface specified by the
270 .Ar "local-addr|ifname"
271 argument.  Some
272 .Ux
273 kernels rewrite the source address of
274 .Nm Ns 's
275 packets on their way out to contain the address of the transmission
276 interface.  This is best assured via a static host route.
277 .El
278 .Pp
279 The common vif commands described below
280 may all be used on tunnels or phyints.
281 .Bl -tag -width indent
282 .It metric Ar m
283 The metric is the "cost" associated with receiving a datagram on the given
284 interface or tunnel; it may be used to influence the choice of routes.
285 The metric defaults to 1.  Metrics should be kept as small as possible,
286 because DVMRP cannot route along paths with a sum of metrics greater
287 than 31.
288 .It advert_metric Ar m
289 The advert_metric is the "cost" associated with sending a datagram
290 on the given interface or tunnel; it may be used to influence the choice
291 of routes.  The advert_metric defaults to 0.  Note that the effective
292 metric of a link is one end's metric plus the other end's advert_metric.
293 .It threshold Ar t
294 The threshold is the minimum IP time-to-live required for a multicast datagram
295 to be forwarded to the given interface or tunnel.  It is used to control the
296 scope of multicast datagrams.  (The TTL of forwarded packets is only compared
297 to the threshold, it is not decremented by the threshold.  Every multicast
298 router decrements the TTL by exactly 1.)  The default threshold is 1.
299 .Pp
300 In general, all multicast routers
301 connected to a particular subnet or tunnel should
302 use the same metric and threshold for that subnet or tunnel.
303 .It rate_limit Ar r
304 The rate_limit option allows the network administrator to specify a
305 certain bandwidth in Kbits/second which would be allocated to multicast
306 traffic.  It defaults 0 (unlimited).
307 .It boundary Ar "boundary-name|scoped-addr/mask-len"
308 The boundary option allows an interface
309 to be configured as an administrative boundary for the specified
310 scoped address.
311 Packets belonging to this address will not
312 be forwarded on a scoped interface.  The boundary option accepts either
313 a name or a boundary spec.  This command may be specified several times
314 on an interface in order to describe multiple boundaries.
315 .It passive
316 No packets will be sent on this link or tunnel until we hear from the other
317 end.  This is useful for the "server" end of a tunnel that goes over
318 a dial-on-demand link; configure the "server" end as passive and
319 it will not send its periodic probes until it hears one from the other
320 side, so will not keep the link up.  If this option is specified on both
321 ends of a tunnel, the tunnel will never come up.
322 .It noflood
323 As described above, but only applicable to this interface/tunnel.
324 .It prune_lifetime Ar secs
325 As described above, but only applicable to this interface/tunnel.
326 .It rexmit_prunes Ar "[on|off]"
327 As described above, but only applicable to this interface/tunnel.
328 Recall that prune retransmission
329 defaults to on on point-to-point links and tunnels, and off on
330 multi-access links.
331 .It allow_nonpruners
332 By default,
333 .Nm
334 refuses to peer with DVMRP neighbors that
335 do not claim to support pruning.  This option allows such peerings
336 on this interface.
337 .It notransit
338 A specialized case of route filtering; no route learned from an interface
339 marked "notransit" will be advertised on another interface marked
340 "notransit".  Marking only a single interface "notransit" has no meaning.
341 .It accept|deny Ar "(route/mask-len [exact])+" Op bidir
342 The
343 .Li accept
344 and
345 .Li deny
346 commands allow rudimentary route filtering.  The
347 .Li accept
348 command causes
349 .Nm
350 to accept only the listed routes on the configured interface; the
351 .Li deny
352 command causes
353 .Nm
354 to accept all but the listed routes.
355 Only one of
356 .Li accept
357 or
358 .Li deny
359 commands may be used on a given interface.
360 .Pp
361 The list of routes follows the
362 .Li accept
363 or
364 .Li deny
365 keyword.  If the keyword
366 .Ar exact
367 follows a route, then only that route is matched; otherwise, that route
368 and any more specific route is matched.  For example,
369 .Li deny 0/0
370 denys all routes, while
371 .Li deny 0/0 exact
372 denys only the default route.  The default route may also be specified
373 with the
374 .Li default
375 keyword.
376 .Pp
377 The
378 .Ar bidir
379 keyword enables bidirectional route filtering; the filter will be applied
380 to routes on both output and input.  Without the
381 .Ar bidir
382 keyword,
383 .Li accept
384 and
385 .Li deny
386 filters are only applied on input.  Poison reverse routes are never
387 filtered out.
388 .El
389 .Pp
390 The
391 .Nm
392 utility will not initiate execution if it has fewer than two enabled vifs,
393 where a vif (virtual interface) is either a physical multicast-capable
394 interface or a tunnel.  It will log a warning if all of its vifs are
395 tunnels; such an
396 .Nm
397 configuration would be better replaced by more
398 direct tunnels (i.e. eliminate the middle man).
400 This is an example configuration for a mythical multicast router at a big
401 school.
402 .Bd -literal
403 #
404 # mrouted.conf example
405 #
406 # Name our boundaries to make it easier
407 name LOCAL
408 name EE
409 #
410 # lnc1 is our gateway to compsci, don't forward our
411 #     local groups to them
412 phyint lnc1 boundary EE
413 #
414 # lnc2 is our interface on the classroom net, it has four
415 #     different length subnets on it.
416 # note that you can use either an ip address or an
417 # interface name
418 phyint boundary EE altnet
419         altnet altnet
420 #
421 # atm0 is our ATM interface, which doesn't properly
422 #      support multicasting.
423 phyint atm0 disable
424 #
425 # This is an internal tunnel to another EE subnet
426 # Remove the default tunnel rate limit, since this
427 #   tunnel is over ethernets
428 tunnel metric 1 threshold 1
429         rate_limit 0
430 #
431 # This is our tunnel to the outside world.
432 # Careful with those boundaries, Eugene.
433 tunnel metric 1 threshold 32
434         boundary LOCAL boundary EE
435 .Ed
437 The
438 .Nm
439 utility responds to the following signals:
440 .Bl -tag -width indent
441 .It HUP
442 Restarts
443 .Nm .
444 The configuration file is reread every time this signal is evoked.
445 .It INT
446 Terminate execution gracefully (i.e., by sending
447 good-bye messages to all neighboring routers).
448 .It TERM
449 Same as INT.
450 .It USR1
451 Dump the internal routing tables to
452 .Pa /var/tmp/mrouted.dump .
453 .It USR2
454 Dump the internal cache tables to
455 .Pa /var/tmp/mrouted.cache .
456 .It QUIT
457 Dump the internal routing tables to stderr (only if
458 .Nm
459 was invoked with a non-zero debug level).
460 .El
461 .Pp
462 For convenience in sending signals,
463 .Nm
464 writes its pid to
465 .Pa /var/run/
466 upon startup.
467 .Sh FILES
468 .Bl -tag -width /var/tmp/mrouted.cache -compact
469 .It Pa /etc/mrouted.conf
470 .It Pa /var/run/
471 .It Pa /var/tmp/mrouted.dump
472 .It Pa /var/tmp/mrouted.cache
473 .El
475 The routing tables look like this:
476 .Bd -literal
477 Virtual Interface Table
478  Vif  Local-Address                    Metric  Thresh  Flags
479   0      subnet: 36.2/16       1       1    querier
480                     groups:
482                    pkts in: 3456
483                   pkts out: 2322323
485   1     subnet: 36.11/16      1       1    querier
486                     groups:
489                    pkts in: 345
490                   pkts out: 3456
492   2      tunnel:     3       1
493                      peers: (3.255)
494                 boundaries: 239.0.1/24
495                           : 239.1.2/24
496                    pkts in: 34545433
497                   pkts out: 234342
499   3      tunnel:     3       16
501 Multicast Routing Table (1136 entries)
502  Origin-Subnet   From-Gateway    Metric Tmr In-Vif  Out-Vifs
503  36.2                               1    45    0    1* 2  3*
504  36.8            4    15    2    0* 1* 3*
505  36.11                              1    20    1    0* 2  3*
506  .
507  .
508  .
509 .Ed
510 .Pp
511 In this example, there are four vifs connecting to two subnets and two
512 tunnels.  The vif 3 tunnel is not in use (no peer address). The vif 0 and
513 vif 1 subnets have some groups present; tunnels never have any groups.  This
514 instance of
515 .Nm
516 is the one responsible for sending periodic group
517 membership queries on the vif 0 and vif 1 subnets, as indicated by the
518 "querier" flags.
519 The list of boundaries indicate the scoped addresses on that
520 interface.
521 A count of the no. of incoming and outgoing packets is also
522 shown at each interface.
523 .Pp
524 Associated with each subnet from which a multicast datagram can originate
525 is the address of the previous hop router (unless the subnet is directly-
526 connected), the metric of the path back to the origin, the amount of time
527 since we last received an update for this subnet, the incoming vif for
528 multicasts from that origin, and a list of outgoing vifs.  "*" means that
529 the outgoing vif is connected to a leaf of the broadcast tree rooted at the
530 origin, and a multicast datagram from that origin will be forwarded on that
531 outgoing vif only if there are members of the destination group on that leaf.
532 .Pp
533 The
534 .Nm
535 utility also maintains a copy of the kernel forwarding cache table.
536 Entries
537 are created and deleted by
538 .Nm .
539 .Pp
540 The cache tables look like this:
541 .Bd -literal
542 Multicast Routing Cache Table (147 entries)
543  Origin             Mcast-group     CTmr  Age Ptmr IVif Forwvifs
544  13.2.116/22     3m   2m    -  0    1
545 >
546 >
547  138.96.48/21     5m   2m    -  0    1
548 >
549  128.9.160/20     3m   2m    -  0    1
550 >
551  198.106.194/24     9m  28s   9m  0P
552 >
553 .Ed
554 .Pp
555 Each entry is characterized by the origin subnet number and mask and the
556 destination multicast group.
557 .Pp
558 The 'CTmr' field indicates the lifetime
559 of the entry.  The entry is deleted from the cache table
560 (or refreshed, if traffic is flowing)
561 when the timer decrements to zero.  The 'Age' field is the time since
562 this cache entry was originally created.  Since cache entries get refreshed
563 if traffic is flowing, routing entries can grow very old.
564 .Pp
565 The 'Ptmr' field is simply a dash if no prune was sent upstream, or the
566 amount of time until the upstream prune will time out.
567 .Pp
568 The 'Ivif' field indicates the
569 incoming vif for multicast packets from that origin.  Each router also
570 maintains a record of the number of prunes received from neighboring
571 routers for a particular source and group.
572 If there are no members of
573 a multicast group on any downward link of the multicast tree for a
574 subnet, a prune message is sent to the upstream router.
575 They are
576 indicated by a "P" after the vif number.
577 .Pp
578 The Forwvifs field shows the
579 interfaces along which datagrams belonging to the source-group are
580 forwarded.
581 A "p" indicates that no datagrams are being forwarded along
582 that interface.
583 An unlisted interface is a leaf subnet with no
584 members of the particular group on that subnet.
585 A "b" on an interface
586 indicates that it is a boundary interface, i.e. traffic will not be
587 forwarded on the scoped address on that interface.
588 .Pp
589 An additional line with a ">" as the first character is printed for
590 each source on the subnet.  Note that there can be many sources in
591 one subnet.
592 An additional line with a "<" as the first character is printed
593 describing any prunes received from downstream dependent neighbors
594 for this subnet and group.
595 .Sh SEE ALSO
596 .Xr map-mbone 8 ,
597 .Xr mrinfo 8 ,
598 .Xr mtrace 8
599 .Pp
600 DVMRP is described, along with other multicast routing algorithms, in the
601 paper "Multicast Routing in Internetworks and Extended LANs" by S. Deering,
602 in the Proceedings of the ACM SIGCOMM '88 Conference.
604 .An Steve Deering ,
605 .An Ajit Thyagarajan ,
606 .An Bill Fenner .