Provided by: smcroute_2.0.0-5_amd64 bug

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.