SMCROUTE(8) | System Manager's Manual (smm) | SMCROUTE(8) |
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.
-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.
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
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.
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/smcrouteTIPS¶
A lot of extra information is sent under the daemon facility and the debug priority to the syslog daemon.November 1, 2011 | Debian |