Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SMCROUTE(8)		    System Manager's Manual		   SMCROUTE(8)

NAME
     smcroute -- SMCRoute, a static multicast router

SYNOPSIS
     smcroute [dnkhv] [-f FILE]	[-e CMD] [-L LVL] [-a|-r ROUTE]	[-j|-l GROUP]

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	rout-
     ing 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	     Start the smcroute	daemon.	 Will attempt to set up	multicast
	     routes and	group joins from the file /etc/smcroute.conf, or any
	     alternate config file specified by	-f FILE	is also	provided.

     -n	     Run daemon	in foreground, do not detach from controlling terminal

     -N	     By	default	smcroute enables virtual interfaces (VIF) on all mul-
	     ticast 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 phyint IFNAME
	     enable enables only the interfaces	needed.

     -f	FILE
	     Alternate configuration file, default /etc/smcroute.conf

     -e	CMD  Specify external script or	command	to be called when smcroute has
	     loaded/reloaded all static	multicast routes from the configura-
	     tion file,	or when	a source-less (ANY) rule has been installed.

     -L	LEVEL
	     Set log level: none, err, info, notice, debug.  Default is
	     notice.

     -s	     Let daemon	log to syslog, default unless running in foreground.

     -v	     Display program version and exit.

     -h	     Print a help message and exit.

     -k	     Stop (kill) running daemon.

     The -e CMD	option is useful if you	want to	trigger	other processes	to
     start when	smcroute 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 fire-
     wall 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	smcroute also sets two envi-
     ronment variables:	source,	and group.  Beware that	these environment
     variables are unconditionally overwritten by smcroute and can thus	not be
     used to pass information to the script from outside of smcroute.

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

     -a	INIFNAME SOURCE	GROUP OUTIFNAME	[OUTIFNAME ...]
	     Add a multicast route to the kernel routing cache so that multi-
	     cast packets received on the network interface INIFNAME originat-
	     ing from the IP address SOURCE and	sent to	the multicast group
	     addess GROUP will be forwarded to the outbound network interfaces
	     OUTIFNAME [OUTIFNAME ...].	 The interfaces	provided as INIFNAME
	     and OUTIFNAME can be any network interface	as listed by 'ifcon-
	     fig' or 'ip link list' (incl. tunnel interfaces), but not the
	     loopback interface.

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

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

     To	be able	to add/remove routes or	join/leave multicast groups using
     these commands the	smcroute daemon	must run.  You can also	write all
     rules in the configuration	file and send SIGHUP to	the daemon.

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

     smcroute 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 for-
     warding of	multicast unless an IGMP/MLD capable router or multicast
     client is located on the same physical port as you	run smcroute on.  How-
     ever, this	feature	of smcroute is only intended as	a temporary work-
     around, 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).

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

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

     From 1.99.0 the sender's IP address is actually optional for IPv4 multi-
     cast 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 experimen-
     tal.

     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 com-
     ments 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
		 Depends on the	kernel,	more than 200, probably	more than 1000
	   Multicast group memberships
		 Max. 20, see caveat above

SIGNALS
     smcroute responds to the following	signals:

     HUP   Restarts smcroute.  The configuration file is re-read 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.

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 omping(8) tool	can be used.

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), omping(8), ping(8), iperf(1)

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

FreeBSD	Ports 11.2	       October 29, 2015		    FreeBSD Ports 11.2

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | COMMANDS | CONFIGURATION FILE | LIMITS | SIGNALS | DEBUGGING | FILES | SEE ALSO | BUGS | AUTHORS | TIPS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=smcroute&sektion=8&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help