1: .\" $OpenBSD: mrouted.8,v 1.22 2010/04/05 16:47:01 deraadt Exp $
2: .\" The mrouted program is covered by the license in the accompanying file
3: .\" named "LICENSE". Use of the mrouted program represents acceptance of
4: .\" the terms and conditions listed in that file.
5: .\"
6: .\" The mrouted program is COPYRIGHT 1989 by The Board of Trustees of
7: .\" Leland Stanford Junior University.
8: .Dd $Mdocdate: April 5 2010 $
9: .Dt MROUTED 8 SMM
10: .Os
11: .Sh NAME
12: .Nm mrouted
13: .Nd IP multicast routing daemon
14: .Sh SYNOPSIS
15: .Nm mrouted
16: .Op Fl fhp
17: .Op Fl c Ar FILE
18: .Op Fl d Op Ar [LEVEL[,LEVEL,...]
19: .Sh DESCRIPTION
20: .Nm
21: is an implementation of the Distance-Vector Multicast Routing
22: Protocol (DVMRP), an earlier version of which is specified in RFC 1075.
23: It maintains topological knowledge via a distance-vector routing protocol
24: (like RIP, described in RFC 1058), upon which it implements a multicast
25: datagram forwarding algorithm called Reverse Path Multicasting.
26: .Pp
27: .Nm
28: forwards a multicast datagram along a shortest (reverse) path tree
29: rooted at the subnet on which the datagram originates.
30: The multicast delivery tree may be thought of as a broadcast delivery
31: tree that has been pruned back so that it does not extend beyond those
32: subnetworks that have members of the destination group.
33: Hence, datagrams are not forwarded along those branches which have no
34: listeners of the multicast group.
35: The IP time-to-live of a multicast datagram can be
36: used to limit the range of multicast datagrams.
37: .Pp
38: In order to support multicasting among subnets that are separated by (unicast)
39: routers that do not support IP multicasting,
40: .Nm
41: includes support for
42: "tunnels", which are virtual point-to-point links between pairs of
43: .Nm
44: daemons located anywhere in an internet.
45: IP multicast packets are encapsulated for transmission through tunnels,
46: so that they look like normal unicast datagrams to intervening routers
47: and subnets.
48: The encapsulation is added on entry to a tunnel, and stripped off on exit
49: from a tunnel.
50: By default, the packets are encapsulated using the IP-in-IP protocol
51: (IP protocol number 4).
52: Older versions of
53: .Nm
54: tunnel use 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 the purpose of multicasting only,
61: which is independent of the physical internet, and which may span
62: multiple Autonomous Systems.
63: This capability is intended for experimental support of internet
64: multicasting only, pending widespread support for multicast routing
65: by the regular (unicast) routers.
66: .Nm
67: 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: .Nm
71: handles multicast routing only; there may or may not be unicast routing
72: software running on the same machine as
73: .Nm mrouted .
74: With the use of tunnels, it is not necessary for
75: .Nm
76: to have access to more than one physical subnet
77: in order to perform multicast forwarding.
78: .Pp
79: .Sh OPTIONS
80: This program follows the usual UNIX command line syntax, with long options starting
81: with two dashes (`-'). The options are as follows:
82: .Bl -tag -width Ds
83: .It Fl h, -help
84: Print a help message and exit.
85: .It Fl f, -foreground
86: Run in foreground, do not detach from the calling terminal.
87: .It Fl c, -config=FILE
88: Specify an alternative configuration file, instead of the default
89: .Pa /etc/mrouted.conf .
90: .It Fl d, -debug[=LEVEL[,LEVEL...]
91: By default,
92: .Nm
93: detaches from the invoking terminal.
94: If this option is specified,
95: .Nm
96: it runs in foreground of the starting terminal and responds to signals.
97: If
98: .Fl d
99: is given with no argument, the debug level defaults to
100: .Nm igmp, cache, interface, groups, prunes, routes and peers .
101:
102: Regardless of the debug level,
103: .Nm
104: always writes warning and error messages to the system log daemon.
105: Debug levels have the following effects:
106: .Pp
107: .Bl -tag -width TERM -compact -offset indent
108: .It Cm packet
109: Debug inbound/outbout packets
110: .It Cm prunes
111: Pruning operations, or pruned routes
112: .It Cm routes
113: Routing messages
114: .It Cm rtdetail
115: Detailed routing information
116: .It Cm peers
117: Neighbor gossip
118: .It Cm cache
119: Debug routing cache
120: .It Cm timeout
121: Debug timeouts
122: .It Cm interface
123: Show interface, or vif, debug messages
124: .It Cm groups
125: Debug group memberships
126: .It Cm mtrace
127: Multicast traceroute information
128: .It Cm igmp
129: Debug IGMP messages
130: .It Cm icmp
131: Debug ICMP messages
132: .It Cm rsrr
133: Debug RSRR messages
134: .El
135: .It Fl p
136: Start
137: .Nm
138: in a non-pruning mode. This was previously used in routers for test purposes only.
139: However, this is no longer supported and this option is only kept for compatibility
140: reasons.
141: .It Fl r, -show-routes
142: Show state of VIFs and multicast routing tables. This command sends SIGUSR1 to a
143: running mrouted, waits for the dump file to be updated, and then displays the result
144: on stdout.
145: .El
146: .Pp
147: .Sh CONFIGURATION
148: .Nm
149: automatically configures itself to forward on all multicast-capable
150: interfaces, i.e. interfaces that have the IFF_MULTICAST flag set (excluding
151: the loopback "interface"), and it finds other
152: .Nm
153: directly reachable via those interfaces.
154: To override the default configuration, or to add tunnel links to other
155: .Nm mrouted ,
156: configuration commands may be placed in
157: .Pa /etc/mrouted.conf .
158: There are five types of configuration commands:
159: .Bl -item -offset indent
160: .It
161: .Cm cache_lifetime
162: .Ar ct
163: .It
164: .Cm name
165: .Ar boundary-name | scoped-addr Ns / Ns Ar mask-len
166: .It
167: .Cm phyint
168: .Ar local-addr
169: .Oo
170: .Cm altnet
171: .Ar network Ns / Ns Ar mask-len
172: .Oc
173: .br
174: .Oo
175: .Cm boundary
176: .Ar boundary-name | scoped-addr Ns / Ns Ar mask-len
177: .Oc
178: .Op Cm disable
179: .br
180: .Op Cm metric Ar m
181: .Op Cm rate_limit Ar b
182: .Op Cm threshold Ar t
183: .It
184: .Cm pruning
185: .Op Cm off | on
186: .It
187: .Cm tunnel
188: .Ar local-addr
189: .Ar remote-addr
190: .br
191: .Oo
192: .Cm boundary
193: .Ar boundary-name | scoped-addr Ns / Ns Ar mask-len
194: .Oc
195: .Op Cm metric Ar m
196: .Op Cm rate_limit Ar b
197: .Op Cm threshold Ar t
198: .El
199: .Pp
200: The file format is free-form: whitespace (including newlines) is not
201: significant.
202: The
203: .Cm boundary
204: option
205: can accept either a name or a boundary;
206: the
207: .Cm boundary
208: and
209: .Cm altnet
210: options may be specified as many times as necessary.
211: .Pp
212: The
213: .Nm cache_lifetime
214: is a value that determines the amount of time that a
215: cached multicast route stays in kernel before timing out.
216: The value of this entry should lie between 300 (5 min) and 86400 (1 day).
217: It defaults to 300.
218: .Pp
219: The
220: .Nm name
221: option assigns names to boundaries to make configuration easier.
222: .Pp
223: The
224: .Nm phyint
225: command can be used to disable multicast routing on the physical
226: interface identified by local IP address
227: .Ar local-addr ,
228: or to associate a non-default metric or threshold with the specified
229: physical interface.
230: The local IP address
231: .Ar local-addr
232: may be replaced by the interface name (e.g. le0).
233: If a phyint is attached to multiple IP subnets, describe each additional
234: subnet with the
235: .Cm altnet
236: keyword.
237: Phyint commands must precede tunnel commands.
238: .Pp
239: The
240: .Nm pruning
241: option is provided for
242: .Nm
243: to act as a non-pruning router. This is no longer supported and the
244: configuration option is only kept for compatibility reasons.
245: .Pp
246: The
247: .Nm tunnel
248: command can be used to establish a tunnel link between local IP address
249: .Ar local-addr
250: and remote IP address
251: .Ar remote-addr ,
252: and to associate a non-default metric or threshold with that tunnel.
253: The local IP address
254: .Ar local-addr
255: may be replaced by the interface name (e.g. le0).
256: The remote IP address
257: .Ar remote-addr
258: may be replaced by a host name, if and only if the host name has a single
259: IP address associated with it.
260: The tunnel must be set up in the mrouted.conf files of both routers before
261: it can be used.
262: .\"For backwards compatibility with older versions of
263: .\".Nm ,
264: .\"the srcrt keyword specifies
265: .\"encapsulation using IP source routing.
266: .Pp
267: .Cm boundary
268: allows an interface to be configured as an administrative boundary
269: for the specified scoped address.
270: Packets belonging to this address will not be forwarded on a scoped interface.
271: The boundary option accepts either a name or a boundary spec.
272: .Pp
273: .Cm metric
274: is the "cost" associated with sending a datagram on the given
275: interface or tunnel; it may be used to influence the choice of routes.
276: The metric defaults to 1.
277: Metrics should be kept as small as possible, because
278: .Nm
279: cannot route along paths with a sum of metrics greater than 31.
280: .Pp
281: .Cm rate_limit
282: allows the network administrator to specify a
283: certain bandwidth in Kbits/second which would be allocated to multicast
284: traffic.
285: It defaults to 500Kbps on tunnels, and 0 (unlimited) on physical interfaces.
286: .Pp
287: .Cm threshold
288: is the minimum IP time-to-live required for a multicast datagram
289: to be forwarded to the given interface or tunnel.
290: It is used to control the scope of multicast datagrams.
291: (The TTL of forwarded packets is only compared to the threshold,
292: it is not decremented by the threshold.
293: Every multicast router decrements the TTL by 1.)
294: The default threshold is 1.
295: .Pp
296: In general, all
297: .Nm
298: connected to a particular subnet or tunnel should
299: use the same metric and threshold for that subnet or tunnel.
300: .Pp
301: .Nm
302: will not initiate execution
303: if it has fewer than two enabled virtual interfaces (vifs),
304: where a vif is either a physical multicast-capable
305: interface or a tunnel.
306: It will log a warning if all of its vifs are tunnels; such an
307: .Nm
308: configuration would be better replaced by more
309: direct tunnels (i.e. eliminate the middle man).
310: .Sh EXAMPLE CONFIGURATION
311: This is an example configuration for a mythical multicast router at a big
312: school.
313: .Bd -unfilled -offset left
314: #
315: # mrouted.conf example
316: #
317: # Name our boundaries to make it easier.
318: name LOCAL 239.255.0.0/16
319: name EE 239.254.0.0/16
320: #
321: # le1 is our gateway to compsci, don't forward our
322: # local groups to them.
323: phyint le1 boundary EE
324: #
325: # le2 is our interface on the classroom net, it has four
326: # different length subnets on it.
327: # Note that you can use either an ip address or an
328: # interface name
329: phyint 172.16.12.38 boundary EE altnet 172.16.15.0/26
330: altnet 172.16.15.128/26 altnet 172.16.48.0/24
331: #
332: # atm0 is our ATM interface, which doesn't properly
333: # support multicasting.
334: phyint atm0 disable
335: #
336: # This is an internal tunnel to another EE subnet.
337: # Remove the default tunnel rate limit, since this
338: # tunnel is over Ethernets.
339: tunnel 192.168.5.4 192.168.55.101 metric 1 threshold 1
340: rate_limit 0
341: #
342: # This is our tunnel to the outside world.
343: # Careful with those boundaries, Eugene.
344: tunnel 192.168.5.4 10.11.12.13 metric 1 threshold 32
345: boundary LOCAL boundary EE
346: .Ed
347: .Sh SIGNALS
348: .Nm
349: responds to the following signals:
350: .Pp
351: .Bl -tag -width TERM -compact
352: .It HUP
353: Restarts
354: .Nm mrouted .
355: The configuration file is reread every time this signal is evoked.
356: .It INT
357: Terminates execution gracefully (i.e. by sending
358: good-bye messages to all neighboring routers).
359: .It TERM
360: The same as INT.
361: .It USR1
362: Dumps the internal routing tables to
363: .Pa /var/run/mrouted/mrouted.dump .
364: .It USR2
365: Dumps the internal cache tables to
366: .Pa /var/run/mrouted/mrouted.cache .
367: .It QUIT
368: Dumps the internal routing tables to stderr (only if
369: .Nm
370: was invoked with a non-zero debug level).
371: .El
372: .Pp
373: For convenience in sending signals,
374: .Nm
375: writes its process ID to
376: .Pa /var/run/mrouted.pid
377: upon startup.
378: .Sh FILES
379: .Bl -tag -width /var/run/mrouted/mrouted.cache -compact
380: .It Pa /etc/mrouted.conf
381: .It Pa /var/run/mrouted/mrouted.cache
382: .It Pa /var/run/mrouted/mrouted.dump
383: .It Pa /var/run/mrouted.pid
384: .El
385: .Sh EXAMPLES
386: The routing tables look like this:
387: .Bd -unfilled -offset left
388: Virtual Interface Table
389: Vif Local-Address Metric Thresh Flags
390: 0 36.2.0.8 subnet: 36.2 1 1 querier
391: groups: 224.0.2.1
392: 224.0.0.4
393: pkts in: 3456
394: pkts out: 2322323
395:
396: 1 36.11.0.1 subnet: 36.11 1 1 querier
397: groups: 224.0.2.1
398: 224.0.1.0
399: 224.0.0.4
400: pkts in: 345
401: pkts out: 3456
402:
403: 2 36.2.0.8 tunnel: 36.8.0.77 3 1
404: peers: 36.8.0.77 (2.2)
405: boundaries: 239.0.1
406: : 239.1.2
407: pkts in: 34545433
408: pkts out: 234342
409:
410: 3 36.2.0.8 tunnel: 36.6.8.23 3 16
411:
412: Multicast Routing Table (1136 entries)
413: Origin-Subnet From-Gateway Metric Tmr In-Vif Out-Vifs
414: 36.2 1 45 0 1* 2 3*
415: 36.8 36.8.0.77 4 15 2 0* 1* 3*
416: 36.11 1 20 1 0* 2 3*
417: .
418: .
419: .
420: .Ed
421: .Pp
422: In this example, there are four vifs connecting to two subnets and two
423: tunnels.
424: The vif 3 tunnel is not in use (no peer address).
425: The vif 0 and vif 1 subnets have some groups present;
426: tunnels never have any groups.
427: This instance of
428: .Nm
429: is the one responsible for sending periodic group membership queries on the
430: vif 0 and vif 1 subnets, as indicated by the "querier" flags.
431: The list of boundaries indicate the scoped addresses on that interface.
432: A count of the number of incoming and outgoing packets is also
433: shown at each interface.
434: .Pp
435: Associated with each subnet from which a multicast datagram can originate
436: is the address of the previous hop router (unless the subnet is directly-
437: connected), the metric of the path back to the origin, the amount of time
438: since we last received an update for this subnet, the incoming vif for
439: multicasts from that origin, and a list of outgoing vifs.
440: "*" means that the outgoing vif is connected to a leaf of the broadcast
441: tree rooted at the origin, and a multicast datagram from that origin will
442: be forwarded on that outgoing vif only if there are members of the
443: destination group on that leaf.
444: .Pp
445: .Nm
446: also maintains a copy of the kernel forwarding cache table.
447: Entries are created and deleted by
448: .Nm mrouted .
449: .Pp
450: The cache tables look like this:
451: .Bd -unfilled -offset left
452: Multicast Routing Cache Table (147 entries)
453: Origin Mcast-group CTmr Age Ptmr IVif Forwvifs
454: 13.2.116/22 224.2.127.255 3m 2m - 0 1
455: \*(Gt13.2.116.19
456: \*(Gr13.2.116.196
457: 138.96.48/21 224.2.127.255 5m 2m - 0 1
458: \*(Gt138.96.48.108
459: 128.9.160/20 224.2.127.255 3m 2m - 0 1
460: \*(Gt128.9.160.45
461: 198.106.194/24 224.2.135.190 9m 28s 9m 0P
462: \*(Gt198.106.194.22
463: .Ed
464: .Pp
465: Each entry is characterized by the origin subnet number and mask and the
466: destination multicast group.
467: .Pp
468: The 'CTmr' field indicates the lifetime of the entry.
469: The entry is deleted from the cache table when the timer decrements to zero.
470: The 'Age' field is the time since this cache entry was originally created.
471: Since cache entries get refreshed if traffic is flowing,
472: routing entries can grow very old.
473: .Pp
474: The 'Ptmr' field is simply a dash if no prune was sent upstream, or the
475: amount of time until the upstream prune will time out.
476: The 'Ivif' field indicates the incoming vif for multicast packets from
477: that origin.
478: .Pp
479: Each router also maintains a record of the number of prunes received from
480: neighboring routers for a particular source and group.
481: .Pp
482: If there are no members of a multicast group on any downward link of the
483: multicast tree for a subnet, a prune message is sent to the upstream router.
484: They are indicated by a "P" after the vif number.
485: .Pp
486: The Forwvifs field shows the interfaces along which datagrams belonging to
487: the source-group are forwarded.
488: .Pp
489: A "p" indicates that no datagrams are being forwarded along that interface.
490: An unlisted interface is a leaf subnet with no members of the particular
491: group on that subnet.
492: .Pp
493: A "b" on an interface indicates that it is a boundary interface, i.e.\&
494: traffic will not be forwarded on the scoped address on that interface.
495: An additional line with a
496: .Sq \*(Gt
497: as the first character is printed for
498: each source on the subnet.
499: .Pp
500: Note that there can be many sources in one subnet.
501: .Sh SEE ALSO
502: .Xr map-mbone 8 ,
503: .Xr mrinfo 8 ,
504: .Xr mtrace 8 ,
505: .Xr pimd 8
506: .Pp
507: DVMRP is described, along with other multicast routing algorithms, in the
508: paper "Multicast Routing in Internetworks and Extended LANs" by S. Deering,
509: in the Proceedings of the ACM SIGCOMM '88 Conference.
510: .Sh AUTHORS
511: Steve Deering, Ajit Thyagarajan, Bill Fenner, David Thaler and Daniel Zappala. With
512: contributions by many others.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to mrouted.8 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / mrouted