NAME

       smcroute — SMCRoute, a static multicast router

SYNOPSIS

       smcroute [OPTIONS] [COMMANDS]

DESCRIPTION

       smcroute  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
       mrouted or pimd in situations where static multicast routes should be maintained and/or no proper IGMP or
       MLD signaling exists.

       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., mrouted at the same time.

       Because smcroute modifies the kernel routing table it needs to run with  full  superuser  rights.   Which
       also means that the same applies to client operations, to be able to communicate with the daemon.

   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!

OPTIONS

       -d      Starts  the  smcroute  daemon  before any of the optional following commands are executed. Please
               note, if started with the -n flag no commands specified on the command line will be run.

       -n      Run in foreground, do not detach from the calling terminal.  This also  means  that  any  further
               commands  from  that  command line are run.  Option flags, however, are accepted, but not command
               flags.

       -f FILE
               Specify an alternative configuration file, instead of the default /etc/smcroute.conf.

       -v      Display version and enable verbose logs.   This  gives  a  more  verbose  output  in  some  error
               situations.  Do not expect too much, see syslog instead.

       -D      Enable additional debug messages.  Do not expect too much, see syslog instead.

       -h      Print a help message and exit.

       -k      Stop (kill) running daemon.

       The  -d  option  to smcroute starts the smcroute daemon. It can be started in the foreground using the -n
       option. The -k option will terminate a running daemon.  The -f FILE option can be used to tell the daemon
       to setup routes from a conf file. By default it looks for /etc/smcroute.conf

COMMANDS

       The following are commands that can only be passed to an already running daemon.

       -a IFNAME SOURCE GROUP IFNAME [IFNAME ...]
               Add a kernel multicast route from {IFNAME, SOURCE & GROUP} to a list of, at least  one,  outbound
               IFNAME.   The  interfaces  can be any network interface as listed by 'ifconfig' or 'ip link list'
               (incl. tunnel interfaces), but not the loopback interface.  Please note that the  SOURCE  address
               is  the  unicast  IPv4 or IPv6 source address of the multicast sender! The GROUP can be either an
               IPv4 or IPv6 formatted multicast group address.

       -r IFNAME SOURCE GROUP
               Remove a kernel multicast route.

       -j IFNAME GROUP
               Join a multicast group on a given interface.

       -l IFNAME GROUP
               Leave a multicast group on a given interface.

       To be able to add/remove routes or join/leave multicast groups the smcroute daemon must run.

       Multicast routes can be added with the -a command and removed with the -r command.

       A multicast route is defined by an input interface IFNAME, the sender's unicast IP  address  SOURCE,  the
       multicast group GROUP and a list of, at least one, output interface IFNAME [IFNAME ...].

       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.

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

       The intended purpose of SMCRoute 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.

       smcroute  can  also  send simple group join and leave commands to the kernel. As a result the kernel will
       send Layer-2 IGMP join and leave frames. 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 smcroute on.

       To emulate a multicast client using smcroute you use the -j and -l  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.

       With this command smcroute allows the integration of  nodes  that  need  static  multicast  routing  into
       dynamic multicast routing domains.

CONFIGURATION FILE

       From  version  1.98.0  smcroute  supports reading and setting up multicast routes from a config file. The
       default location is /etc/smcroute.conf, but this can be overridden using the -f FILE command line option.

       #
       # 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.
       #
       # Similarily supported is setting mroutes. Removing mroutes is not
       # supported, remove/comment out the mroute or send a remove command.
       #
       # Syntax:
       #   mgroup from IFNAME group MCGROUP
       #   mroute from IFNAME [source ADDRESS] group MCGROUP to IFNAME [IFNAME ...]
       #
       # 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

       Fairly simple. As usual, to identify the origin of the inbound multicast we need the IFNAME, the sender's
       IP address and, of course, the multicast group address, MCGROUP.  The last argument is a list of outbound
       interfaces.

       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  smcroute to dynamically at runtime add new routes,
       matching the group and inbound interface, to the kernel. This feauture is experimental.

       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.

       When starting up, the daemon by default lists the success of parsing each line and setting up a route.

LIMITS

       The current version compiles and runs fine on Linux kernel version 2.4, 2.6 and 3.0. Known limits:

             Multicast routes
                   More than 200
             Multicast group membership
                   Max. 20

SIGNALS

       smcroute responds to the following signals:

       HUP   Restarts smcroute.  The configuration file is reread every time this signal is received.
       INT   Terminates execution gracefully.
       TERM  The same as INT.

       For convenience in sending signals, smcroute writes its process ID to /var/run/smcroute.pid upon startup.

FILES

       /etc/smcroute.conf      Routes to be added/restored when starting, or restarting the daemon on SIGHUP.
       /var/run/smcroute.pid   Pidfile (re)created by smcroute daemon when it has started up  and  is  ready  to
                               receive commands.
       /proc/net/ip_mr_cache   Holds active IPv4 multicast routes.
       /proc/net/ip_mr_vif     Holds the IPv4 virtual interfaces used by the active multicast routing daemon.
       /proc/net/ip6_mr_cache  Holds active IPv6 multicast routes.
       /proc/net/ip6_mr_vif    Holds the IPv6 virtual interfaces used by the active multicast routing daemon.
       /var/run/smcroute       IPC socket created by the smcroute daemon.
       /proc/net/igmp          Holds active IGMP joins.
       /proc/net/igmp6         Holds active MLD joins.

SEE ALSO

       mrouted(8), pimd(8)

BUGS

       The English wording of this man page.

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

       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
       https://github.com/troglobit/smcroute

TIPS

       A lot of extra information is sent under the daemon facility and the debug priority to the syslog daemon.

Debian                                          November 01, 2011                                    SMCROUTE(8)