SMCROUTED(8)

💖 SMCROUTED(8) — System Manager's Manual 💖

okay so bestie, meet smcrouted: SMCRoute, a static multicast router, from the section 8 system manager's manual. this page is long so we're doing it in parts, and part 1 starts right now. 💅✨

---

🦋 NAME 🦋

smcrouted — SMCRoute, a static multicast router

✨ SYNOPSIS ✨

smcrouted [-nNhsv] [-c SEC] [-d SEC] [-e CMD] [-f FILE] [-F FILE]
          [-i NAME] [-l LVL] [-m SEC] [-p USER:GROUP] [-P FILE] [-t ID]
          [-u FILE]

🌸 DESCRIPTION 🌸

smcrouted is a static multicast routing daemon, and the way it gives you fine grained control over the multicast forwarding cache (MFC) in the UNIX kernel? iconic. both IPv4 and IPv6 are fully supported. no cap.

It can be your alternative to dynamic multicast daemons like mrouted(8), pimd(8) or pim6sd(8) in situations where static multicast routes should be maintained and/or no proper IGMP or MLD signaling exists. lowkey perfect for that.

Multicast routes exist in the UNIX kernel only as long as a multicast routing daemon is running. On Linux, multiple multicast routers can run simultaneously using different multicast routing tables. To run smcrouted and mrouted at the same time, set the former to use a routing table other than the default (0).

smcrouted modifies the kernel routing table and needs either full superuser rights, or CAP_NET_ADMIN on Linux. This also applies to the friendly control tool smcroutectl(8). so yeah, permissions are giving main character energy. 👑

🚨 Warning 🚨

Be careful when creating multicast routes. You can easily flood your networks by inadvertently creating routing loops. Either direct loops listing an inbound interface also as an outbound, or indirect loops by going through other routers. seriously, do not play with this. 💀

---

💅 OPTIONS 💅

The following command line options are available:

• -c SEC — Flush unused dynamic (*,G) multicast routes every SEC seconds.

This option is intended for systems with topology changes, i.e., when inbound multicast may change both interface and source IP address. E.g. in a setup with at least two VRRP routers. If there is no way of detecting such a topology change this option makes sure to periodically flush all dynamically learned multicast routes so that traffic may resume. Flushing of a specific route only occurs if it was unused during the last flush interval, i.e. there was no traffic matching it. This avoids toggling between different inbound interfaces if traffic arrives on several interfaces simultaneously. In this case, the first selected inbound interface is retained until traffic on it ceases.

Default is 60 sec, set to 0 to disable. See also the smcroutectl flush command, which can be called manually on topology changes.

• -d SEC — Daemon startup delay. Delays the probe of interfaces and parsing of the configuration file. Note, the PID file is also not created, since the daemon is not ready yet.

This command line option, although useful in some use-cases, is fragile. It is almost always better to rely on an init or process supervisor that handles dependencies properly, like finit(8), which can wait for interfaces to come up and files to be created before starting a service.

• -e CMD — Specify external script or command to be called when smcrouted has loaded/reloaded all static multicast routes from the configuration file, or when a source-less (ANY) rule has been installed.
• -f FILE — Alternate configuration file, default /etc/smcroute.conf
• -F FILE — Check configuration file syntax, use -l LEVEL to increase verbosity. Returns non-zero on error.
• -h — Show summary of command line options and exit.
• -i NAME — Set daemon identity. Used to create unique PID, IPC socket, and configuration file names, as well as set the syslog identity. E.g., -I foo would make smcrouted look for /etc/foo.conf, write its PID to /var/run/foo.pid and create an IPC socket for smcroutectl in /var/run/foo.sock.

For smcroutectl the same option can be used to select the proper smcrouted instance to send IPC to.

This option is required for both daemon and client when running multiple smcrouted instances, using multiple routing tables, on Linux.

• -l LEVEL — Set log level: none, err, notice, info, debug. Default is notice.
• -m SEC — Modify Multicast Router Discovery (mrdisc) announcement interval. Default 20 sec. This option is only available when smcrouted is built with mrdisc support (Linux, and IPv4, only). RFC4286.
• -n — Run daemon in foreground, do not detach from controlling terminal
• -N — By default smcrouted enables multicast routing on all available, and multicast capable, interfaces in the system. These interfaces are enumerated as VIFs, virtual interfaces, of which most UNIX systems have a very limited amount, usually 32. This daemon option inverts the behavior so no interfaces are enabled by default. Useful on systems with many interfaces, where multicast routing only makes use of a few.

The config file setting phyint IFNAME enable is required to enable the required interfaces.

• -p USER [:GROUP] — Drop root privileges to USER:GROUP after start and retain CAP_NET_ADMIN capabilities only. The :GROUP is optional. This option is only available when smcrouted is built with libcap support.
• -P FILE — Set PID file name, and optionally full path, in case you need to override the default identity, or the identity set with -i NAME. Regardless, setting this option overrides all others, but it is recommended to use the ident option instead.
• -s — Let daemon log to syslog, default unless running in foreground.
• -t ID — Set multicast routing table ID. Remember to also create routing rules directing packets to the table. This example uses routing table ID 123:

ip mrule add iif eth0 lookup 123
ip mrule add oif eth0 lookup 123

Note: Only available on Linux.

• -u FILE — UNIX domain socket path, used for the IPC between smcrouted and smcroutectl. Use this to override the default socket path, derived from the daemon identity, -i NAME. This option can be useful when overriding the identity is not sufficient, e.g. for testing. The default depends on how smcrouted is configured at build time, see “FILES”.
• -v — Show program version and support information.

---

The -e CMD option is useful if you want to trigger other processes to start when smcrouted has completed installing dynamic multicast routes from (*,G) rules in /etc/smcroute.conf, or when a source-less (ANY) route, a.k.a (*,G) multicast rule, from /etc/smcroute.conf. is matched and installed. For instance, calling conntrack on Linux to flush firewall connection tracking when NAT:ing multicast.

The script CMD is called with an argument reload or install to let the script know if it is called on SIGHUP/startup, or when a (*,G) rule is matched and installed. In the latter case smcrouted also sets two environment variables: source, and group. Beware that these environment variables are unconditionally overwritten by smcrouted and can thus not be used to pass information to the script from outside of smcrouted.

🌈 OPERATION

💫 Introduction

Okay so picture this: smcrouted boots up and immediately goes snooping around for every network interface that's got the MULTICAST flag turned on. As long as you didn't set the -N flag, each one of those interfaces gets enumerated as a virtual interface (VIF) — and that's the thing the kernel's multicast routing stack actually talks to. 💅

On some operating systems, the enumeration process also wants each interface to have an IP address. But Linux and FreeBSD? They're low maintenance besties — they only need the ifindex and the MULTICAST flag. Periodt.

Now, if an interface doesn't exist yet when smcrouted starts, you can use the -d SEC flag to delay startup. Otherwise? You're gonna have to reload smcrouted (like, with SIGHUP) once a new interface gets added to the system. 🙈

Since VIFs are a limited resource — most operating systems only support 32 in total, which is giving scarcity era — the administrator might need to declare which interfaces to use for multicast routing via the /etc/smcroute.conf phyint directive. And ngl, the recommended move is to always start smcrouted with the -N flag, disabling VIF creation by default, and then selectively enable each interface you're going to route between. It's giving curated. ✨ See smcroute.conf(5) for more.

---

🚧 Multicast Scoping

Because multicast is inherently broadcast, there's an obvious need to limit it. On a LAN this is usually handled automatically by bridges (switches) with built-in multicast snooping — that's IGMP and MLD, iykyk.

Between LANs though, there's also a need to scope multicast, because often the same multicast groups get used for totally different purposes on different LANs. And this? This must be managed by administrators. At least three options exist:

• TTL scoping — the traditional way of "raising walls" between zones. The outbound interfaces of routers are given a TTL threshold greater than the hop it represents. The default TTL threshold is 1. Managing the routers is a lot easier than adjusting the TTL value of each multicast sender. The only real downside? It scales poorly with the number of routers, and it affects all multicast traversing the router's interfaces. 😭
• Administrative scoping (RFC2365) — this one is among the current best practices, defining boundaries for sets of multicast groups instead of limiting all multicast (which is what TTL scoping does). In the case of smcrouted, this is left to the administrator to manage. See mrouted(8) and mrouted.conf(5) for more details. 🎀
• Filtering — some sort of filtering mechanism, like a firewall (Linux netfilter) or a low-level filter (Linux tc or eBPF) that may even have some hardware offloading support (TCAM). The firewall is likely the most common, since it's also often used to set up SNAT or 1:1 NAT (Linux netmap). 🔥

---

📦 Multicast Routes

A multicast route is defined by an input interface IFNAME, the sender's unicast IP address SOURCE (which is optional), the multicast group GROUP, and a list of — at least one — output interfaces IFNAME [IFNAME ...]. It's a whole little ensemble cast. 👑

mroute from eth0                  group 225.1.2.3  to eth1 eth2
mroute from eth0 source 1.2.3.4   group 225.3.2.1  to eth1 eth2

mroute from eth0                  group  ff2e::42  to eth1 eth2
mroute from eth0 source 2001:3::1 group  ff2e::43  to eth1 eth2

Big rule, no exceptions: the sender address and the multicast group must both be either IPv4 or IPv6 addresses. Don't mix, bestie, that's not the vibe. 💀

The output interfaces are not needed when removing routes using the smcroutectl remove command. The first three parameters are sufficient to identify the source of the multicast route. Easy.

The intended purpose of smcrouted is to aid in situations where dynamic multicast routing does not work properly. However, a dynamic multicast routing protocol is in nearly all cases the preferred solution. The reason? Their ability to translate Layer-3 signaling to Layer-2 and vice versa (IGMP or MLD). So like, respect the classics. 🌸

Note: the optional source address multicast routes are not installed in the kernel multicast forwarding cache (MFC) by smcrouted. Instead, it dynamically installs new routes to the kernel MFC — matching the group and inbound interface — when the kernel notifies smcrouted using "upcalls" called NOCACHE messages. This feature was grafted onto smcrouted from mrouted(8), and may not work as intended in all use-cases. 🫶

---

👯 Multicast Groups

smcrouted is capable of simple group join and leave by sending commands to the kernel. The kernel then handles sending Layer-2 IGMP/MLD join and leave frames as needed. This can be used for testing, but it's also useful sometimes to open up multicast from the sender if located on a LAN with switches equipped with IGMP/MLD Snooping.

Here's the tea: such devices will prevent forwarding of multicast unless an IGMP/MLD capable router or multicast client is located on the same physical port as the one you run smcrouted on. But — and this is important — this feature of smcrouted is only intended as a workaround. Some platforms impose a limit on the maximum number of groups that can be joined, and some of these systems can be tuned to increase that limit. For bigger installations, it is strongly recommended to instead address the root cause — e.g. enable multicast router ports on intermediate switches, either statically or by enabling the multicast router discovery feature of smcrouted. Slay the actual problem, not the symptom. 💅

To emulate a multicast client using smcrouted, you use the join and leave commands to issue join and leave commands for a given multicast group on a given interface IFNAME. The GROUP may be given in an IPv4 or IPv6 address format. 🌈

The command is passed to the daemon, which passes it to the kernel. The kernel then tries to join the multicast group GROUP on interface IFNAME by starting IGMP — or MLD, for an IPv6 group address — signaling on the given interface. This signaling may be received by routers/switches connected on that network supporting IGMP/MLD multicast signaling and, in turn, start forwarding the requested multicast stream, eventually reaching your desired interface. It's giving community effort. ✨

---

👯♀️ Multiple Daemon Instances

When running multiple smcrouted instances — using the -t ID command line flag, one per routing table on Linux — it is required to use the -i NAME option for both daemon and client. Why? Because the name of the IPC socket used for communicating is composed from the identity. Matchy matchy or it simply won't work, bestie. 🔑

---

🐛 DEBUGGING

The most common problem when attempting to route multicast is the TTL. Always start by verifying that the TTL of your multicast stream is not set to 1, because the router decrements the TTL of an IP frame before routing it. Rude, but that's just how it is. 😭

Test your setup using ping(8) or iperf(1) — either of which is capable of creating multicast traffic with an adjustable TTL. Iperf in particular is useful since it can act both as a multicast source (sender) and a multicast sink (receiver). Main character energy, honestly. 👑

For more advanced IP multicast testing, the mcjoin(1) tool can be used. 🧚

📝 Note

A lot of extra information is sent under the daemon facility and the debug priority to the syslog daemon. Use smcrouted -s -l debug to enable. Yes, that's the whole tip. Go look at your logs, bestie. 🔍

---

🚦 SIGNALS

For convenience in sending signals, smcrouted writes its process ID to /var/run/smcroute.pid upon startup — unless the -p FILE or -i NAME options are used to change the identity or file name used.

The following signals are supported:

• HUP — tell smcrouted to reload its configuration file and activate the changes. 🔄
• INT — terminates execution gracefully. 🕊️
• TERM — the same as INT. 💜

---

📁 FILES

• /etc/smcroute.conf — optional configuration file for smcrouted. Defined interfaces to use, groups to join, and routes to set when starting, or reloading, smcrouted on SIGHUP. Like the PID file, the name of the configuration file may be different depending on command line options given to the daemon. Most notably, -I IDENT defines the full suite of files used by the smcrouted daemon. See smcroute.conf(5) for details. 📝
• /etc/smcroute.d/*.conf — optional configuration directory, path defined by convention only. The actual configuration directory, or file(s) to include, is defined by /etc/smcroute.conf. See smcroute.conf(5) for details. 📂
• /var/run/smcroute.pid — default PID file (re)created by smcrouted when it has started up and is ready to receive commands. See also the -i NAME or -P FILE options, which can change the default name. 🆔
• /var/run/smcroute.sock — IPC socket created by smcrouted for use by smcroutectl. Same caveats apply to this file as the previous two; command line options -i NAME and -S FILE to the daemon can be used to change the socket file name. 🔌
• /proc/net/ip_mr_cache — Linux specific, holds active IPv4 multicast routes. 🐧
• /proc/net/ip_mr_vif — Linux specific, holds the IPv4 virtual interfaces used by the active multicast routing daemon. 🐧
• /proc/net/ip6_mr_cache — Linux specific, holds active IPv6 multicast routes. 🐧
• /proc/net/ip6_mr_vif — Linux specific, holds the IPv6 virtual interfaces used by the active multicast routing daemon. 🐧
• /proc/net/igmp — Linux specific, holds active IGMP ASM (*,G) joins. 🐧
• /proc/net/igmp6 — Linux specific, holds active MLD ASM (*,G) joins. 🐧
• /proc/net/mcfilter — Linux specific, holds active IGMP SSM (S,G) joins. 🐧
• /proc/net/mcfilter6 — Linux specific, holds active MLD SSM (S,G) joins. 🐧
• /proc/sys/net/ipv4/igmp_max_memberships — Linux specific tuning of max IGMP ASM (*,G) per socket, default 20. 🎛️
• /proc/sys/net/ipv4/igmp_max_msf — Linux specific tuning of max IGMP SSM (S,G) per socket, default 10. 🎛️

BSD systems may consult the netstat(1) tool for stats on virtual multicast interface tables and multicast forwarding caches, and VIF/MIF allocation, as well as the ifmcstat(8) tool for querying group membership. 🦋

EXIT STATUS 💖

okay so smcrouted leverages BSD sysexits.h exit codes (the 64–78 range), which process supervisors like systemd(1) and finit(8) understand. Here's the full rundown of what each code is used for and how to interpret it, bestie:

• 0 — EX_OK — Success. The happy ending, we love to see it 💅✨
• 64 — EX_USAGE — Invalid command line option, or missing argument. Bestie forgot the assignment 😭
• 69 — EX_UNAVAILABLE — Multicast routing socket (or table) already in use. Somebody else is holding the aux, literally 🫶
• 79 — EX_SOFTWARE — Internal error, bug in smcrouted. Not me, not you, it's the code 💀
• 71 — EX_OSERR — Failed fork(), daemon(), getifaddrs(), malloc(), etc. The system said no 🙈
• 76 — EX_PROTOCOL — Kernel does not seem to support multicast routing. The kernel is not giving what it's supposed to give 😔
• 77 — EX_NOPERM — Not enough permissions to run. Permission denied vibes, no cap 👑
• 78 — EX_CONFIG — Parse error in configuration file. The config file is giving syntax error realness 🍓

---

SEE ALSO 🦋

go read these next, bestie, they're the supporting cast:

• smcroute.conf(5)
• smcroutectl(8)
• mrouted(8)
• pimd(8)
• pim6sd(8)
• ping(8)
• mcjoin(1)
• iperf(1)

---

AUTHORS 👑

SMCRoute was originally created by Carsten Schill <carsten@cschill.de>. Initial IPv6 support by Todd Hayton <todd.hayton@gmail.com>. Initial FreeBSD support by Micha Lenk <micha@debian.org>.

SMCRoute is currently maintained by Joachim Wiberg <troglobit@gmail.com>, and Micha Lenk <micha@debian.org> at GitHub: https://github.com/troglobit/smcroute.

give them their flowers, fr fr 💐

---

and that's the whole page, bestie! source: Debian · date: November 28, 2021 · page: SMCROUTED(8). stay slay, keep routing 💖✨