smcroute.8

.Dd $Mdocdate: October 29 2015 $
.Dt SMCROUTE 8 SMM
.Os
.Sh NAME
.Nm smcroute
.Nd SMCRoute, a static multicast router
.Sh SYNOPSIS
.Nm smcroute
.Op Fl dnNkhsv
.Op Fl f Ar FILE
.Op Fl e Ar CMD
.Op Fl L Ar LVL
.Op Fl p Ar USER:GROUP
.Op Fl a | Fl r Ar ROUTE
.Op Fl j | Fl l Ar GROUP
.Op Fl x | Fl y Ar GROUP
.Sh DESCRIPTION
.Nm
is a command line tool to manipulate the multicast routes of a UNIX
kernel. It supports both IPv4 and IPv6 multicast routing. SMCRoute can
be used as an alternative to dynamic multicast routers like
.Nm mrouted
or
.Nm pimd
in situations where static multicast routes should be maintained and/or
no proper IGMP or MLD signaling exists.
.Pp
Generally multicast routes exists in the kernel only as long as smcroute
or another multicast routing daemon is running. Only one multicast
routing daemon can be active at a time, so it's impossible to run
smcroute and, e.g.,
.Nm mrouted
at the same time.
.Pp
Because
.Nm
modifies the kernel routing table it needs to run with full
.Ar superuser rights .
Which also means that the same applies to client operations, to be
able to communicate with the daemon.
.Ss WARNING
By using multiple output interfaces (traffic multiplication), using the
input interface also as output interface (direct loop) or constructing
some other forms of indirect loops you can easily flood your networks!
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl d
Start the smcroute daemon.  Will attempt to set up multicast routes and
group joins from the file
.Pa /etc/smcroute.conf ,
or any alternate config file specified by
.Fl f Ar FILE
is also provided.
.It Fl n
Run daemon in foreground, do not detach from controlling terminal
.It Fl N
By default
.Nm
enables virtual interfaces (VIF) on all multicast capable interfaces in
the system.  This option inverts that behavior, all VIFs are disabled by
default.  On systems with many interfaces, where multicast routing only
makes use of a few, this can be very useful.  The config file setting
.Ar phyint IFNAME enable
enables only the interfaces needed.
.It Fl f Ar FILE
Alternate configuration file, default
.Pa /etc/smcroute.conf
.It Fl e Ar CMD
Specify external script or command to be called when
.Nm
has loaded/reloaded all static multicast routes from the configuration
file, or when a source-less (ANY) rule has been installed.
.It Fl L Ar LEVEL
Set log level: none, err, info, notice, debug.  Default is notice.
.It Fl p Ar USER Op :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
.Nm
was built with libcap support.
.It Fl s
Let daemon log to syslog, default unless running in foreground.
.It Fl v
Display program version and exit.
.It Fl h
Print a help message and exit.
.It Fl k
Stop (kill) running daemon.
.El
.Pp
The
.Fl e Ar CMD
option is useful if you want to trigger other processes to start when
.Nm
has completed installing dynamic multicast routes from (*,G) rules in
.Pa /etc/smcroute.conf ,
or when a source-less (ANY) route, a.k.a (*,G) multicast rule, from
.Pa /etc/smcroute.conf .
is matched and installed.  For instance, calling
.Ar conntrack
on Linux to flush firewall connection tracking when NAT:ing multicast.
.Pp
The script
.Ar CMD
is called with an argument
.Ar reload
or
.Ar 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
.Nm
also sets two environment variables:
.Nm source ,
and
.Nm group .
Beware that these environment variables are unconditionally overwritten by
.Nm
and can thus not be used to pass information to the script from outside of
.Nm .
.Sh COMMANDS
The following are commands that can only be passed to an already running daemon.
.Bl -tag -width Ds
.It Fl a Ar IFNAME SOURCE GROUP OUTIFNAME [OUTIFNAME ...]
Add a multicast route to the kernel routing cache so that multicast packets
received on the network interface
.Ar IFNAME
originating from the IP address
.Ar SOURCE
and sent to the multicast group addess
.Ar GROUP
will be forwarded to the outbound network interfaces
.Ar OUTIFNAME [OUTIFNAME ...] .
The interfaces provided as
.Ar INIFNAME
and
.Ar OUTIFNAME
can be any network interface as listed by 'ifconfig' or 'ip link
list' (incl. tunnel interfaces), but not the loopback interface.
.It Fl r Ar IFNAME SOURCE GROUP
Remove a kernel multicast route.
.It Fl j Ar IFNAME GROUP
Join a multicast group on a given interface.
.It Fl l Ar IFNAME GROUP
Leave a multicast group on a given interface.
.It Fl x Ar IFNAME SOURCE GROUP
Join a source specific multicast (SSM) group on a given interface.
.It Fl y Ar IFNAME SOURCE GROUP
Leave a source specific multicast (SSM) group on a given interface.
.El
.Pp
Multicast routes can be added with the
.Fl a
command and removed with the
.Fl r
command.
.Pp
To be able to add/remove routes or join/leave multicast groups using
these commands the
.Nm
daemon must run.  You can also write all rules in the configuration file
and send SIGHUP to the daemon.
.Pp
A multicast route is defined by an input interface
.Ar IFNAME ,
the sender's unicast IP address
.Ar SOURCE ,
the multicast group
.Ar GROUP
and a list of, at least one, output interface
.Ar IFNAME [IFNAME ...] .
.Pp
The sender's address and the multicast group must both be IPv4 addresses
or IPv6 addresses.  If IPv4 addresses are specified then SMCRoute will
operate on the IPv4 multicast routes. If IPv6 addresses are specified
then SMCRoute will operate on the IPv6 multicast routes.
.Pp
The output interfaces are not needed when removing routes using the
.Fl r
command. The first three parameters are sufficient to identify the
source of the multicast route.
.Pp
The intended purpose of
.Nm
is to aid in situations where dynamic multicast routing does not work
properly.  However, dynamic multicast routing is in nearly all cases the
preferred solution.  The reason for this is their ability to translate
Layer-3 signalling to Layer-2 and vice versa (IGMP or MLD).
.Pp
.Nm
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
.Nm
on.  However, this feature of
.Nm
is only intended as a temporary workaround, and only 20 groups can be
joined this way (kernel limit).  For bigger installations it is strongly
recommended that the user instead fix the root cause to why the
designated multicast router does to receive all the required multicast
groups on its input interface(s).
.Pp
To emulate a multicast client using
.Nm
you use the
.Fl j
and
.Fl l
commands to issue join and leave commands for a given multicast group
on a given interface
.Ar IFNAME .
The
.Ar GROUP
may be given in an IPv4 or IPv6 address format.
.Pp
The command is passed to the daemon that passes it to the kernel. The
kernel then tries to join the multicast group
.Ar GROUP
on interface
.Ar 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.
.Pp
With this command
.Nm
allows the integration of nodes that need static multicast routing into
dynamic multicast routing domains.
.Pp
.Sh CONFIGURATION FILE
From version 1.98.0 smcroute supports reading and setting up multicast
routes from a config file. The default location is
.Ar /etc/smcroute.conf ,
but this can be overridden using the
.Fl f Ar FILE
command line option.
.Pp
.Bd -unfilled -offset left
#
# smcroute.conf example
#
# The configuration file supports joining multicast groups, to use
# Layer-2 signaling so that switches and routers open up multicast
# traffic to your interfaces.  Leave is not supported, remove the
# mgroup and SIGHUP your daemon, or send a specific leave command.
#
# NOTE: Use of mgroup should really not be needed!  It is only available
#       to aid a user in figuring out problems in multicast forwarding.
#       Only 20 mgroup lines can be configured, this is a HARD kernel
#       maximum.  If you need more, you probably need to find another
#       way of forwarding multicast to your router.
#
# Similarily supported is setting mroutes. Removing mroutes is not
# supported, remove/comment out the mroute or send a remove command.
#
# Syntax:
#   phyint IFNAME <enable|disable> [ttl-threshold <1-255>]
#   mgroup from IFNAME group MCGROUP
#   mroute from IFNAME [source ADDRESS] group MCGROUP to IFNAME [IFNAME ...]

# This example disables the creation of a multicast VIF for WiFi
# interface wlan0.  The kernel (at least Linux) sets the ALLMULTI
# flag for all interfaces that have a VIF enabled.  Hence, it can
# cause quite a bit of unnecessary traffic to reach the CPU if too
# many interfaces have a VIF (or MIF in IPv6 lingo).  Only enable
# interfaces required for inbound and outbound traffic.
phyint wlan0 disable

# The following example instructs the kernel to join the multicast
# group 225.1.2.3 on interface eth0.  Followed by setting up an
# mroute of the same multicast stream, but from the explicit sender
# 192.168.1.42 on the eth0 network and forward to eth1 and eth2.
#
mgroup from eth0 group 225.1.2.3
mroute from eth0 group 225.1.2.3 source 192.168.1.42 to eth1 eth2

# Here we allow routing of multicast to group 225.3.2.1 from ANY
# source coming in from interface eth0 and forward to eth1 and eth2.
# NOTE: Routing from ANY source is currently only available for IPv4
#       multicast.
mgroup from eth0 group 225.3.2.1
mroute from eth0 group 225.3.2.1 to eth1 eth2
.Ed
.Pp
Fairly simple. As usual, to identify the origin of the inbound multicast
we need the
.Ar IFNAME ,
the sender's IP address and, of course, the multicast group address,
.Ar MCGROUP .
The last argument is a list of outbound interfaces.
.Pp
From 1.99.0 the sender's IP address is actually optional for IPv4
multicast routes. If omitted it defaults to 0.0.0.0 (INADDR_ANY) and
will cause
.Nm
to dynamically at runtime add new routes, matching the group and inbound
interface, to the kernel. This feauture is experimental.
.Pp
Following the standard UNIX tradition the file format support comments
at the beginning of the line using a hash sign.  It is untested to have
comments at the end of a line, but should work.
.Pp
When starting up, the daemon by default lists the success of parsing each
line and setting up a route.
.Sh LIMITS
The current version compiles and runs fine on Linux kernel version
2.4, 2.6 and 3.0. Known limits:
.Pp
.Bl -tag -width TERM -compact -offset indent
.It Cm Multicast routes
Depends on the kernel, more than 200, probably more than 1000
.It Cm Multicast group memberships
Max. 20, see caveat above
.El
.Pp
.Sh SIGNALS
.Nm
responds to the following signals:
.Pp
.Bl -tag -width TERM -compact
.It HUP
Restarts
.Nm .
The configuration file is re-read every time this signal is received.
.It INT
Terminates execution gracefully.
.It TERM
The same as INT.
.El
.Pp
For convenience in sending signals,
.Nm
writes its process ID to
.Pa /var/run/smcroute.pid
upon startup.
.Pp
.Sh 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
.Xr ping 8
or
.Xr 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
.Xr omping 8
tool can be used.
.Pp
.Sh FILES
.Bl -tag -width /proc/net/ip6_mr_cache -compact
.It Pa /etc/smcroute.conf
Routes to be added/restored when starting, or restarting the daemon on
SIGHUP.
.It Pa /var/run/smcroute.pid
Pidfile (re)created by
.Nm
daemon when it has started up and is ready to receive commands.
.It Pa /proc/net/ip_mr_cache
Holds active IPv4 multicast routes.
.It Pa /proc/net/ip_mr_vif
Holds the IPv4 virtual interfaces used by the active multicast routing daemon.
.It Pa /proc/net/ip6_mr_cache
Holds active IPv6 multicast routes.
.It Pa /proc/net/ip6_mr_vif
Holds the IPv6 virtual interfaces used by the active multicast routing daemon.
.It Pa /var/run/smcroute
IPC socket created by the smcroute daemon.
.It Pa /proc/net/igmp
Holds active IGMP joins.
.It Pa /proc/net/igmp6
Holds active MLD joins.
.El
.Pp
.Sh SEE ALSO
.Xr mrouted 8 ,
.Xr pimd 8 ,
.Xr omping 8 ,
.Xr ping 8 ,
.Xr iperf 1
.Sh BUGS
The English wording of this man page.
.Sh AUTHORS
Originally written by Carsten Schill <carsten@cschill.de>.
Support for IPv6 was added by Todd Hayton <todd.hayton@gmail.com>.
Support for FreeBSD was added by Micha Lenk <micha@debian.org>.
.Pp
SMCRoute is maintained by Joachim Nilsson <troglobit@gmail.com>, Todd Hayton
<todd.hayton@gmail.com>, Micha Lenk <micha@debian.org> and Julien BLACHE
<jblache@debian.org> at
.Ar https://github.com/troglobit/smcroute
.
.Sh TIPS
A lot of extra information is sent under the daemon facility and the
debug priority to the syslog daemon.