Annotation of embedaddon/mrouted/mrouted.8, revision 1.1
1.1 ! misho 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