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