--- name: "smcroutectl" section: "8" platform: "linux" package: "smcroute" version: "2.5.7-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/smcroutectl" --- # smcroutectl(8) Control and status tool for smcrouted(8) ## NAME **smcroutectl** – Control and status tool for [smcrouted(8)](/smcrouted/8.md) ## 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\]* ## DESCRIPTION **smcroutectl** is the control tool for [smcrouted(8)](/smcrouted/8.md). It can be used to query status, debug, modify the kernel multicast forwarding cache (MFC), manage group interface memberships, reload **smcroute.conf**, and kill a running **smcrouted**. ## OPTIONS The following **smcroutectl** options are available: - **-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. - **-i** *NAME* Connect to an **smcrouted** instance that runs with another identity, *NAME*. This option is required for both **smcrouted** and **smcroutectl** when running multiple **smcrouted** instances, e.g., when using multiple routing tables, on Linux. - **-p** Use plain table headings in **show** command output. No ANSI control characters are used, not even for probing screen width. - **-t** Skip table headings entirely in **show** command output. - **-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 The *IIF* and *OIF* arguments in the below **smcroutectl** commands 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. 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)](/smcrouted/8.md) for more details on the operation and how ASM/SSM multicast works. ## COMMANDS Commands can be abbreviated to the minimum unambiguous prefix; for example, **s** **g** for **show** **groups**. 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)](/smcrouted/8.md), in particular the command line option **-N**, and the [smcroute.conf(5)](/smcroute.conf/5.md) ‘**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’. - **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. - **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)](/smcrouted/8.md), 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. - **help** **\[cmd\]** Print a usage information message. - **kill** Tell a running **smcrouted** to exit gracefully, same as *SIGTERM*. - **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. - **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)](/smcrouted/8.md), [smcroute.conf(5)](/smcroute.conf/5.md) ## 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**.