SMCROUTECTL(8)

💖 SMCROUTECTL(8) — the smcroutectl girlies' guide 💖

okay so bestie, welcome to smcroutectl, section 8 of the System Manager's Manual, and honestly? she's the main character of the SMCRoute saga. ✨

---

🌸 NAME 🌸

smcroutectl — the control and status tool for smcrouted(8). yes really, that's her whole job description, and she ate. 💅

---

🎀 SYNOPSIS 🎀

smcroutectl [-bdptv] [-i NAME] [-u FILE] [COMMAND]

smcroutectl ⟨help | flush | kill | reload | version⟩
smcroutectl ⟨show⟩ [groups | routes]
smcroutectl ⟨add  |   rem⟩ IIF [SOURCE] GROUP[/LEN] OIF [OIF ...]
smcroutectl ⟨join | leave⟩ IIF [SOURCE] GROUP[/LEN]

like. look at her. five commands in one line. iconic. 👑

---

🦋 DESCRIPTION 🦋

so smcroutectl is the control tool for smcrouted(8). what can she do, you ask? literally everything:

• query status 👀
• debug 🐛
• modify the kernel multicast forwarding cache (MFC) 🧠
• manage group interface memberships 🤝
• reload smcroute.conf 🔁
• and kill a running smcrouted 💀

she's giving multicast router remote control and we're obsessed. 🫶

---

✨ OPTIONS ✨

these are the smcroutectl options available to you, bestie, and you're gonna wanna know all of them:

• -b — Batch mode, read commands from stdin. 🍓

$ sudo smcroutectl -b <<-EOF
     join eth0 225.1.2.3
     add eth0 192.168.1.42 225.1.2.3 eth1 eth2
     rem eth1 225.3.4.5 eth3
     leave eth1 225.3.4.5
     EOF

• -d — Enable detailed output in show commands. 🔍 she's nosy and we love that for her.
• -i NAME — Connect to an smcrouted instance that runs with another identity, NAME.

fr fr: this option is required for both smcrouted and smcroutectl when you're running multiple smcrouted instances, e.g., when using multiple routing tables, on Linux. no cap. 😤

• -p — Use plain table headings in show command output. No ANSI control characters are used, not even for probing screen width. so unbothered, so minimal. 🧘
• -t — Skip table headings entirely in show command output. headings? never heard of her. 🙈
• -u FILE — UNIX domain socket path, used for the IPC between smcrouted and smcroutectl. Use this to override the default socket path, otherwise derived from the identity, -i NAME. This option can be useful when overriding the identity is not sufficient, e.g. for testing. The default depends on how smcroutectl is configured at build time, see “FILES”. 🔌💜

---

🌈 OPERATION 🌈

so the IIF and OIF arguments in the smcroutectl commands below are the interface names, or interface wildcards of the form eth+, which matches eth0, eth10, etc. wildcards are available for both inbound and outbound interfaces. yes bestie, both. equal rights. 🎀

a multicast route is defined by:

• an input interface IIF
• the sender's unicast IP address SOURCE, which is optional
• the multicast group GROUP
• and a list of, at least one, output interface OIF [OIF ...]

please refer to smcrouted(8) for more details on the operation and how ASM/SSM multicast works. i'm not gatekeeping, but she does explain it better. 💅

---

💜 COMMANDS 💜

commands can be abbreviated to the minimum unambiguous prefix; for example, s g for show groups. the way that's so efficient of her. ✨ the following commands are available:

• add IIF [SOURCE[/LEN]] GROUP[/LEN] OIF [OIF ...] — Add a new multicast route the the kernel MFC, or modify the outbound interfaces (OIF) an existing route. 🔥

the arguments are, in order: IIF the inbound interface, SOURCE originating IP address (may need to be reachable in the unicast routing table to be allowed by the kernel reverse-path check), GROUP the multicast group address, and OIF [OIF ...] the outbound network interface(s).

the interfaces provided as IIF and OIF can be any multicast capable network interface as listed by ifconfig or ip link list, including tunnel interfaces and loopback. provided smcrouted has "enumerated" them. see smcrouted(8), in particular the command line option -N, and the smcroute.conf(5) phyint directive.

to add a (*,G) route, either omit the SOURCE argument completely, or set it to 0.0.0.0 for IPv4, and if you want to specify a range of groups, use the GROUP/LEN modifier, e.g. 225.0.0.0/24. slay. 🌸

• remove IIF [SOURCE[/LEN]] GROUP[/LEN] [OIF [OIF ...]] — Remove or modify the outbound interfaces of a multicast route in the kernel MFC. 🗑️

when no OIF argument is given, this command removes the entire route. with one or more OIF arguments, each outbound interface listed is removed. skipping any unmatched or invalid interface names. when no more outbound interfaces exist, the route will have been transformed into a "stop filter". to remove the route entirely, the command must be given with no OIF arguments. that's the lore, bestie. 📖

• flush — Flush dynamic (*,G) multicast routes now. similar to how -c SEC works in smcrouted, this command initiates an immediate flush of all dynamically installed (*,G) multicast routes. useful when a topology change has been detected and need to be propagated to smcrouted. 🧹✨
• join IIF [SOURCE[/LEN]] GROUP[/LEN] — Join a multicast group, with an optional prefix length, on the given (inbound) interface. the source address is optional, but if given a source specific (SSM) join is performed. note, joining groups is only ever necessary on the inbound interface, never on the outbound. unless, two-way routing the same group. 🤝

note, as mentioned in smcrouted(8), joining a group to open up traffic in layer-2 network switches is only a workaround to direct multicast towards SMCRoute. when routing lots of traffic it is advised to avoid this mechanism. instead, use multicast router ports, or similar settings on the switches, or if they support multicast router discovery (MRDISC), see RFC4286. 🚨

• leave IIF [SOURCE[/LEN]] GROUP[/LEN] — Leave a multicast group, with optional prefix length, on a given (inbound) interface. as with the join command, above, the source address is optional, but if the group was subscribed to with source it must be unsubscribed with source as well. 👋 no hard feelings.
• help [cmd] — Print a usage information message. she's helpful like that. 💁
• kill — Tell a running smcrouted to exit gracefully, same as SIGTERM. 💀 graceful, but make it dramatic.
• reload — Tell smcrouted to reload its configuration and activate the changes. same as SIGHUP. note, any routes or groups added or removed with smcroutectl will be lost. only the configuration set in the file smcroute.conf is activated. 😭 rip your manual tweaks, they're gone.
• show [groups|routes] — Show joined multicast groups or multicast routes, defaults to show routes. can be combined with the -d option to get details for each multicast route. 👀✨
• version — Show program version and support information. 💖

---

👑 SEE ALSO 👑

smcrouted(8), smcroute.conf(5)

---

🫶 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. absolute legends, every single one. 🌟

---

and that's the whole page, bestie!! this beauty landed via Debian on November 28, 2021, and honestly the date is giving vintage-but-timeless. 💅✨ go forth and route your multicast, you've got this. 🦋💖