Ubuntu Manpage: smcrouted — SMCRoute, a static multicast router

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  providing  fine  grained  control  over  the  multicast
       forwarding cache (MFC) in the UNIX kernel.  Both IPv4 and IPv6 are fully supported.

       smcrouted  can  be  used  as  an  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.

       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).

   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.

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
When smcrouted starts up it scans for available network interfaces that have the MULTICAST flag set.
Provided the -N flag is not set, each interface is enumerated as a virtual interface (VIF) which is what
the kernel's multicast routing stack uses. The enumeration process on some operating systems also
require each interface to have an IP address, but Linux and FreeBSD systems only require the ifindex and
the MULTICAST flag. If the interface does not yet exist when smcrouted starts, the -d SEC flag can be
used to delay startup. Otherwise smcrouted needs to be reloaded (e.g., using SIGHUP) when a new
interface has been added to the system.

Since VIFs are a limited resource, most operating systems only support 32 in total, the administrator may
need to declare which interfaces to use for multicast routing using the /etc/smcroute.conf phyint
directive. It is recommended to always start smcrouted with the -N flag, disabling VIF creation by
default, and then selectively enable each of the interfaces you are going to route between. See
smcroute.conf(5) for more information.

Multicast Scoping
Because multicast inherently is broadcast there is an obvious need to limit. On a LAN this is usually
managed automatically by bridges (switches) with built-in multicast snooping (IGMP and MLD). Between
LANs there is also the need to scope multicast, often the same multicast groups are used for different
purposes on different LANs. 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 to this is that it scales poorly with the number of routers
and it affects all multicast traversing the router's interfaces.

Administrative scoping (RFC2365)
This is one of the current best practices, defining boundaries for sets of multicast groups
instead of limiting all multicast (as 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, e.g., firewall (Linux netfilter) or 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 is 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 interface IFNAME [IFNAME ...].

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

The sender address and multicast group must both be either IPv4 or IPv6 addresses.

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.

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 for this is their ability to translate Layer-3 signaling to Layer-2 and vice versa (IGMP or
MLD).

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 is
also useful sometimes to open up multicast from the sender if located on a LAN with switches equipped
with IGMP/MLD Snooping. Such devices will prevent forwarding of multicast unless an IGMP/MLD capable
router or multicast client is located on the same physical port as you run smcrouted on. However, 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, some of these systems can be tuned to increase this 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.

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 that passes it to the kernel. The kernel then tries to join the
multicast group GROUP on interface IFNAME by starting IGMP, or MLD for 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 reach your desired interface.

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 to both daemon and client. This because the name of the
IPC socket used for communicating is composed from the identity.

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.  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).  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.

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, actual
configuration directory, or file(s) to include, 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

       smcrouted leverages BSD sysexits.h exit codes (64-78), which  process  supervisors  like  systemd(1)  and
       finit(8) understands.  The following table details what codes are used for and how to interpret them.

             Status    Symbolic Name    Description
             0         EX_OK            Success
             64        EX_USAGE         Invalid command line option, or missing argument
             69        EX_UNAVAILABLE   Multicast routing socket (or table) already in use
             79        EX_SOFTWARE      Internal error, bug in smcrouted
             71        EX_OSERR         Failed fork(), daemon(), getifaddrs(), malloc(), etc.
             76        EX_PROTOCOL      Kernel does not seem to support multicast routing
             77        EX_NOPERM        Not enough permissions to run
             78        EX_CONFIG        Parse error in configuration file

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.

Debian                                          November 28, 2021                                   SMCROUTED(8)