MROUTED.CONF(5)

📦 version 4.5, in opensuse-leap 16.0

🎀 mrouted.conf(5) — the File Formats Manual glow-up 🎀

✨ NAME ✨

mrouted.conf — the mrouted configuration file, bestie 🫶

🌸 SYNOPSIS 🌸

/etc/mrouted.conf

💖 DESCRIPTION 💖

Okay so real talk: in many cases you do not need to configure mrouted at all. It configures itself automatically to forward multicast on all multicast-capable interfaces, i.e., interfaces that have the IFF_MULTICAST flag set, excluding the loopback interface. It locates other DVMRP capable routers directly reachable via those interfaces. Iconic behavior, honestly ✨

  • mrouted will not start with less than two enabled virtual interfaces (VIFs). A VIF is either a physical multicast-capable interface or a tunnel. The bar is literally on the floor, but it is still a bar 💅
  • mrouted will log a warning if all of its VIFs are tunnels; such a configuration is likely better replaced by more direct (GRE) tunnels (i.e. eliminate the middle man). No cap, it's giving "why are we doing extra hops" 😭

To override the default settings — for example, to add tunnel links to other DVMRP routers — configuration commands may be placed in /etc/mrouted.conf. The file format is free-form: whitespace (including newlines) is not significant. The # character marks start of a comment to end of line. So yes, you can format it however your little heart desires 🦋

🌈 config commands, in order, no skips 🌈

  • cache-lifetime <60-86400> — This setting defines the time in seconds that a cached multicast route stays in kernel before timing out. The value of this entry should lie between 300 (5 min) and 86400 (1 day). It defaults to 300. The syntax says <60-86400>, and the prose says 300–86400; that's what the page says, bestie 🍓
  • prune-lifetime <120-86400> — The average lifetime in seconds of prunes sent towards parents. The actual lifetimes are randomized in the range [.5secs, 1.5secs]. Smaller values cause less state to be kept both at this router and the parent, at the cost of more frequent broadcasts. However, some routers (e.g. mrouted <3.3 and all currently known versions of Cisco's IOS) do not use the DVMRP generation ID to determine that a neighbor has rebooted. Prunes sent towards these neighbors should be kept short, in order to shorten the time to recover from a reboot. For use in this situation, the prune-lifetime keyword may be specified on an interface as described below. It defaults to 7200.
  • name boundary-name scoped-addr/mask-len — The name option assigns names to boundaries to make configuration per interface/tunnel easier. Cute little nickname for your boundary 🎀
  • noflood — mrouted uses a DVMRP optimization to prevent having to keep individual routing tables for each neighbor; part of this optimization is that mrouted assumes that it is the forwarder for each of its attached subnets on startup. This can cause duplicates for a short period (approximately one full route report interval), since both the router that just started up and the proper forwarder will be forwarding traffic. This behavior can be turned off with the noflood keyword; mrouted will not assume that it is the forwarder on startup. Turning on noflood can cause black holes on restart, which generally lasts approximately one full route report interval.

The noflood keyword can also be specified on individual interfaces.

  • rexmit-prunes [on | off] — The default is to retransmit prunes on all point-to-point interfaces (including tunnels) but no multi-access interfaces. This option may be used to make the default on (or off) for all interfaces.

The rexmit-prunes keyword can also be specified on individual interfaces.

  • no router-alert — Some multicast routers, and some IGMP snooping switches, do not support IP options like Router Alert, which is enabled in mrouted by default. This command disables this IP option. Regardless of this setting, mrouted always calculates the IP payload offset based on the IP header length value of ingressing DVMRP and IGMP frames. So the math still math-ing 🧮
  • router-timeout <1-1024> — Known in the RFC as Other Querier Present Interval, controls the timer used to detect when an elected IGMP querier stops sending queries. When the timer expires, mrouted will assume the role as querier. The default is calculated based on the igmp-robustness value, see below. Setting this to any value overrides the RFC algorithm, which may be necessary in some scenarios.
Note: it is strongly recommended to leave this setting commented out. Use the igmp-robustness setting to tweak behavior instead. Trust the process, bestie 🙈
  • igmp-query-interval <1-1024> — This setting controls the IGMP query interval in seconds, used when this router is elected querier on a LAN. The query interval on all eligable IGMP queriers on a LAN must be the same. Default: 125.
Note: this value must be greater than the igmp-query-response-interval.
  • igmp-query-response-interval <1-1024> — Controls the Max Resp Code in IGMP queries, which encodes the maximum time allowed before responding to a query. Can be used to control the burstiness of IGMP/MLD traffic, a lower value causes burstier traffic. Default 10 sec.
Note: this value must always be less than the igmp-query-interval.
  • igmp-query-last-member-interval <1-1024> — This setting controls the maximum time in seconds between group specific IGMP queries. These are sent as response to a host on a LAN requesting to leave a multicast group. The purpose is to double-check that there is no other host on the LAN that still wants the group. Default: 1.

See also igmp-robustness (below), which controls how many group-specific queries are sent. It's giving "one more vibe check before you leave" 💅

  • igmp-robustness <2-10> — The robustness setting controls many aspects of IGMP timers, for end devices and routers alike. Default 2.
    • Group Membership Timeout — Number of seconds before mrouted determines that there are no more members of a group on a LAN. Formula:
robustness x query-interval + query-response-interval
  • Other Querier Present Interval — Number of seconds before mrouted determines there is no longer an elected querier on the LAN. See also router-timeout. Formula:
robustness x query-interval + query-response-interval / 2
  • Last Member Query Count — Number of group-specific queries sent before mrouted assumes there are no further local members of a group on the LAN. The number of group-specific queries is equal to the value of the robustness variable. Math girlie behavior 🔥
  • no phyint — By default all interfaces are enabled. This command disables all interfaces, useful on routers with lots of interfaces where mrouted should run on only a select few. Very "I have 99 problems and I only want 3 of them" energy 😭

Example:

no phyint
phyint eth10 enable
phyint eth12 enable
Note: Most UNIX kernels, including Linux, have a hard coded limit of 32 VIFs. In non-trivial setups this limit is often reached, causing weird errors that can be difficuly to debug. The recommendation for those cases is to disable all phyint (this setting), and then selectively enable only the ones needed. Not me fighting the kernel limit at 2 a.m. 💀
  • phyint <local-addr | ifname> [disable | enable] [passive] [blaster] [force-leaf] [noflood] [igmpv1 | igmpv2 | igmpv3] [static-group group] [altnet network/mask-len] [boundary boundary-name | scoped-addr/mask-len] [metric <1-31>] [advert-metric <0-31>] [prune-lifetime sec] [rexmit-prunes [on | off]] [allow-nonpruners] [notransit] [accept|deny (route/mask-len [exact])+ [bidir]] [rate-limit kbps] [threshold ttl] — This setting selects and alters properties of the physical interfaces mrouted operates on. Interfaces can be identified using their local IP address or their name.
NOTE: All phyint commands must precede tunnel commands. Order matters, bestie — put it before the tunnel stuff, periodt 👑
  • disable | enable — Selectively disable or enable this interface. Only enabled interfaces get a VIF in the kernel.
  • beside [on | off] — This is a tunnel option. For compatibility with older mrouted routers the default is to unicast control traffic "beside" the tunnel. To encapsulate all control traffic inside the tunnel use beside off.
  • igmpv1 | igmpv2 | igmpv3 — mrouted supports all IGMP versions. Use these flags to force compatibility modes on the given interface. Default: igmpv3.
  • static-group group — This setting makes mrouted behave as if an IGMPv2 join for group was received on the phyint. Useful when there is no IGMP capable hosts on the LAN, or when a group should always be routed. The group is listed as static in the mroutectl output.

In setups where there is only a single multicast router running mrouted, this works just as a (*,G) route in smcrouted(8). With the added exception for better handling of dynamic changes to the input interface. Slay, honestly 🌟

  • (the option from the previous bullet, still going 💅) — This can also be used for testing routing without having to set up IGMP capable receivers.
  • join-group group — this one makes mrouted join the group you want, on the phyint connected to the LAN that's the source of the multicast being forwarded. Super useful when you've got switches doing IGMP snooping that don't clock mrouted as a multicast router, so they block flooding multicast on that port 😤. Most managed switches let you configure a static multicast router port, but sometimes that just isn't a thing, or you can't get at the switch config.
  • altnet network/mask-len — if an interface is attached to multiple IP subnets, describe each extra subnet with this keyword. One keyword per subnet, bestie.
  • boundary boundary-name | scoped-addr/mask-len — lets an interface be configured as an administrative boundary for the specified scoped address. Packets belonging to this address will not be forwarded on a scoped interface. The boundary option accepts either a name or a boundary spec.
  • metric &lt;1-31&gt; — the "cost" associated with sending a datagram on the given interface or tunnel; it may be used to influence the choice of routes. Defaults to 1. Keep metrics as small as possible, because mrouted cannot route along paths with a sum of metrics greater than 31 😭.
  • advert-metric &lt;0-31&gt; — the "cost" advertised to neighbors for the given interface or tunnel; it may be used to influence the choice of routes on the neighbor side. Defaults to 0. Note that the effective metric of a link is one end's metric plus the other end's advert-metric 🫶.
  • force-leaf — force mrouted to ignore other routers on this interface. It will never send or accept neighbor probes or route reports on this interface.
  • noflood — as described above, but only applicable to this interface/tunnel.
  • passive — no packets will be sent on this link or tunnel until we hear from the other end. This is useful for the "server" end of a tunnel that goes over a dial-on-demand link; configure the "server" end as passive and it won't send its periodic probes until it hears one from the other side, so it won't keep the link up ✨. > Heads up: if you specify this option on both ends of a tunnel, the tunnel will never come up. 💀
  • blaster — enables handling of routers (mostly Cisco) that overwhelm socket buffers by "blasting" the whole routing table at once 😵‍💫.
  • prune-lifetime sec — as described above, but only applicable to this interface/tunnel.
  • rexmit-prunes [on | off] — as described above, but only applicable to this interface/tunnel. Recall that prune retransmission defaults to on on point-to-point links and tunnels, and off on multi-access links.
  • allow-nonpruners — by default, mrouted refuses to peer with DVMRP neighbors that don't claim to support pruning. This option allows such peerings on this interface 🌸.
  • notransit — a specialized case of route filtering; no route learned from an interface marked notransit will be advertised on another interface marked notransit. Marking only a single interface notransit has no meaning 🙈.
  • accept|deny (route/mask-len [exact])+ [bidir] — the accept and deny commands allow rudimentary route filtering. The accept command causes mrouted to accept only the listed routes on the configured interface; the deny command causes mrouted to accept all but the listed routes. Only one of accept or deny commands may be used on a given interface.

The list of routes follows the accept or deny keyword. If the keyword exact follows a route, then only that route is matched; otherwise, that route and any more specific route is matched. For example, deny 0/0 denies all routes, while deny 0/0 exact denies only the default route. The default route may also be specified with the default keyword 👑.

The bidir keyword enables bidirectional route filtering; the filter will be applied to routes on both output and input. Without the bidir keyword, accept and deny filters are only applied on input. Poison reverse routes are never filtered out.

  • rate-limit kbps — lets the network administrator specify a certain bandwidth in kbps that would be allocated to multicast traffic. It defaults to 500 kbps on tunnels, and 0 (unlimited) on physical interfaces 🚀.
  • threshold ttl — the minimum IP time-to-live required for a multicast datagram to be forwarded to the given interface or tunnel. It's used to control the scope of multicast datagrams. (The TTL of forwarded packets is only compared to the threshold, it is not decremented by the threshold. Every multicast router decrements the TTL by 1.) The default threshold for multicast is 1.

🚇 the tunnel command, but make it a heading

tunnel local-addr remote-addr [beside [on | off]] [boundary
        boundary-name | scoped-addr/mask-len] [metric <1-31>]
        [advert-metric <0-31>] [noflood] [passive] [blaster]
        [prune-lifetime sec] [rexmit-prunes [on | off]]
        [allow-nonpruners] [rate-limit kbps] [threshold ttl]

This setting can be used to establish a tunnel link between local IP address local-addr and remote IP address remote-addr, and to associate a non-default metric or threshold with that tunnel 🌈. The local IP address local-addr may be replaced by the interface name (e.g. le0). The remote IP address remote-addr may be replaced by a host name, if and only if the host name has a single IP address associated with it. The tunnel must be set up in the mrouted.conf files of both routers before it can be used — no solo tunnels, bestie 🫶.

See the phyint command for details on the relevant tunnel options.

The boundary option to all commands can accept either a name or a network boundary; the boundary and altnet options may be specified as many times as necessary 💅.

In general, all DVMRP routers connected to a particular subnet or tunnel should use the same metric and threshold for that subnet or tunnel. No cap.

🎀 EXAMPLE CONFIGURATION 🎀

This is an example configuration for a mythical multicast router at a big school 🏫✨.

#
# mrouted.conf example
#

# Name our boundaries to make it easier.
name LOCAL 239.255.0.0/16
name EE 239.254.0.0/16

# le1 is our gateway to compsci, don't forward our
# local groups to them.
phyint le1 boundary EE

# le2 is our interface on the classroom net, it has four
# different length subnets on it.
# Note that you can use either an IP address or an interface name
phyint 172.16.12.38 boundary EE
       altnet 172.16.15.0/26
       altnet 172.16.15.128/26
       altnet 172.16.48.0/24

# atm0 is our ATM interface, which doesn't properly
# support multicasting.
phyint atm0 disable

# This is an internal tunnel to another EE subnet.
# Remove the default tunnel rate limit, since this
# tunnel is over Ethernets.
tunnel 192.168.5.4 192.168.55.101
       metric 1 threshold 1 rate-limit 0

# This is our tunnel to the outside world.
# Careful with those boundaries, Eugene.
tunnel 192.168.5.4 10.11.12.13
       metric 1 threshold 32
       boundary LOCAL boundary EE

📁 FILES 📁

  • /etc/mrouted.conf — main configuration file. The one and only.

👀 SEE ALSO 👀

mrouted(8), mroutectl(8) — go read those next, bestie, they're literally the other half of the story 💜

🖋️ AUTHORS 🖋️

This manual page was written by Joachim Wiberg <mailto:troglobit@gmail.com>. Iconic of him, honestly 👑.

✨ that's the whole page, bestie ✨ — this cutie pie came from the Debian crew, dated Jan 1, 2021, and it lives at MROUTED.CONF(5). Go configure something slay 🎀💅🦋

📦 where this page comes from