Replicast v0.1
Mark Smith, <markzzzsmith@yahoo.com.au>
16th January 2011

1. Introduction
~~~~~~~~~~~~~~~
Replicast replicates or copies the payloads of UDP datagrams from one source to
one or more destinations.

Sources can be -

o  IPv4 or IPv6
o  unicast or multicast

Destinations can be -

o  IPv4 and/or IPv6
o  unicast and/or multicast

Some examples of what replicast can be used for -

o  make IPv4 multicast traffic  available to IPv6 multicast clients or
   vice-versa.
o  take IPv4 or IPv6 multicast traffic from one group available over a
   number of different IPv4 and/or IPv6 multicast groups.
o  take IPv4 or IPv6 multicast traffic from one group and unicast it to one
   or more IPv4 or IPv6 destinations.
o  take IPv4 or IPv6 unicast traffic and multicast it to one or more IPv4
   and/or IPv6 multicast destinations.


2. Command Line Options
~~~~~~~~~~~~~~~~~~~~~~~
See "replicast -help" for the available command line options and some examples.


3. Option Notes
~~~~~~~~~~~~~~~~
The "replicast -help" text may be a bit terse, here are some additional notes.

3.1 -4in and -6in unicast addresses
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For IPv4, the address 0.0.0.0 represents any unicast address on the host. For
IPv6 the equivalent is [::].

3.2 -4in and -6in interface selection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For IPv4 multicast groups, and for most IPv6 multicast groups, the incoming
interface can be specified, instead of the host's route table being used.

For IPv4, either the interface name or one of it's assigned IPv4 addresses
can be used. For IPv6, the interface name is used.

For IPv6 link-local multicast or unicast sources, the incoming interface
*must* be specified, as the route table cannot unambiguously determine
which interface is intended just from the IPv6 link-local address.

3.3 -4mcoutif and -6mcoutif interface selection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The output interface for IPv4 or IPv6 multicast can be specified as an
alternative to the host's multicast route table. For unicast destinations this
option has no effect; the host's unicast route table will always be used.

3.4 -4mcloop and -6mcloop
~~~~~~~~~~~~~~~~~~~~~~~~~
By default, for all multicast applications, multicast transmissions are also
looped back to the host, so that local applications can also receive them.

replicast *reverses* this default, as it is less likely that traffic
transmitted by replicast will be of interest to local applications. The -4mcloop
or -6mcloop command line options can be used to switch looping of multicast
transmissions back on.

3.5 -4mcttl and -6mchops defaults
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default, for safety, the IPv4 TTL and IPv6 hop-count for multicast
transmissions is 1, limiting the multicast traffic to the link the host is
attached to. These options have no effect on the ttl or hop-count for unicast
traffic; the host's unicast value will be used.


4. Miscellaneous Notes
~~~~~~~~~~~~~~~~~~~~~~

4.1 Static multicast routes under Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Unless interfaces are specified, inbound and outbound multicast interfaces
are selected using route table lookups for the multicast address, for both
IPv4 and IPv6, using the longest match rule.

4.1.1 IPv4
~~~~~~~~~~
For IPv4, the main unicast route table is used.

To create an IPv4 multicast static route, directing all multicast receiving
and transmitting applications to use eth0, use the following command :

ip route add 224.0.0.0/4 dev eth0

To then have receivers or transmitters use eth1 for IPv4 multicast group
224.0.0.35, use :

ip route add 224.0.0.35/32 dev eth1


4.1.2 IPv6
~~~~~~~~~~
For IPv6, the "local" unicast route table is used for multicast route matching, rather than the main  route table.

To view the "local" unicast route table, use the following :

ip -6 route show table local

There will already be some default multicast routes created by the kernel for
ff00::/8.

The following command will add a multicast route for all site-local multicast
addresses, using the eth0 interface :

ip -6 route add ff05::/16 dev eth0 table local

As with IPv4, a more specific route can be used to select a different
interface :

ip -6 route add ff05::30/128 dev eth1 table local


4.2 Viewing multicast group membership under Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

IPv4, IPv6 and link layer multicast memberships are viewed using the 

	ip maddr show

command. An interface name can be specified e.g.

	ip maddr show dev eth0


4.3 Forcing IPv4 IGMP or IPv6 MLD version under Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Linux kernels have default IGMP and MLD versions of 3 and 2 respectively. There
may be instances where these versions aren't supported by IGMP or MLD receivers
on the local link, such as multicast routers.

To override the IPv4 IGMP version used on an interface, specify the version to
use using the 'force_igmp_version' file under:

/proc/sys/net/ipv4/conf/<interface>

For IPv6 MLD, specify the version to use using the 'force_mld_version' file
under:

/proc/sys/net/ipv6/conf/<interface>

The value 0 restores the IGMP or MLD version back to the kernel's default.


4.4 Permitting multicast through the Linux firewall
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

iptables or ip6tables don't treat multicast traffic as special, although there
are some options/match extensions which do match on packet type.

For example, to accept all incoming IPv4 multicast traffic arriving on eth0:

iptables -A INPUT -d 224/4 -i eth0 -j ACCEPT

Similarly, to accept incoming IPv6 multicast traffic destined to ff02::1234:

ip6tables -A INPUT -d ff02::1234 -j ACCEPT

4.5 VLC
~~~~~~~
(This section needs to be cleaned up a bit)

4.5.1. Multicast IPv6 Streaming
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


4.5.1.1. Sending IPv6 Multicast Streams
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

4.5.1.1.1. Common
~~~~~~~~~~~~~~~~~

4.5.1.1.2. GUI Specific
~~~~~~~~~~~~~~~~~~~~~~~

Stream -> select file -> UDP Legacy destination -> [fe80::221:70ff:fefb:59a1%wlan0]
	- Link-local destination with egress interface name didn't work

Stream -> select file -> UDP Legacy destination -> [ULA addr]
	- ULA destination didn't work
	- prefixing address with @ symbol didn't work

Stream -> select file -> UDP Legacy destination -> [GUA addr]
	- GUA destination didn't work
	- prefixing address with @ symbol didn't work

Stream -> select file -> UDP Legacy destination -> [Site local multicast addr]
	- Site local multicast address didn't work, with static multicast route
	- prefixing address with @ symbol didn't work

Basically seems that IPv6 address entry in GUI doesn't work at all.

4.5.1.1.3. CLI Specific
~~~~~~~~~~~~~~~~~~~~~~~


Multicast, using multicast route to distinguish egress interface

ip -6 route add ff05::/16 dev wlan0 table local
vlc -vvv Movie.mp4 --sout udp://\[ff05::1234\]:1234

Multicast, using interface specifier to distingish egress interface

vlc -vvv Le\ Mans.mp4 --sout udp://\[ff05::1234%wlan0]:1234
*** does not work, so must use static multicast route to distinguish egress interface ***


Unicast link-local destination, specifying egress interface
vlc -vvv Movie.mp4 --sout udp://\[fe80::221:70ff:fefb:59a1%wlan0]:1234



4.5.1.2. Receiving IPv6 Multicast Streams
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

4.5.1.2.1. Common
~~~~~~~~~~~~~~~~~

Multicast, using multicast route to distinguish ingress interface

ip -6 route add ff05::/16 dev eth0 table local


Need to allow ingress traffic through firewall i.e. ip6tables. Can be as simple as allowing traffic with a multicast destination address e.g.,

ip6tables -A INPUT -d ff00::/8 -j ACCEPT

although more specific might be better e.g. hop count value checking, link-local source address if the multicast source is on the same link, etc.


4.5.1.2.2. GUI Specific
~~~~~~~~~~~~~~~~~~~~~~~

Open Stream -> udp://@[::]:1234

	- *** @ symbol disappears when URL is shown at top of VLC window ***
	- IPv6 unicast wildcard, includes link-local addresses

Open Stream -> udp://@[ff05::1234]:1234
	- *** @ symbol disappears when URL is shown at top of VLC window ***
	- Uses IPv6 multicast route to identify ingress interface

4.5.1.2.3. CLI Specific
~~~~~~~~~~~~~~~~~~~~~~~




For non-link local multicast destinations -

Then specify destination multicast address in VLC output URL, escaping square breackets

e.g.

vlc -vvv v\ for\ vendetta.mp4 --sout udp://\[ff02::15\]


For link-local multicast destination, you can specify the output interface, and don't need a multicast route in the local table

e.g.

vlc -vvv v\ for\ vendetta.mp4 --sout udp://\[ff02::32%eth0\]

Don't seem to be able to use loopback interface in this scenario

Can add destination UDP port e.g.

vlc -vvv v\ for\ vendetta.mp4 --ipv6 --sout udp://\[ff02::15%dummy0\]:1234

URL format in GUI for watching streams is 'udp://@[IPv6 MC address]:<port>' - note @ symbol in GUI verses not used on command line. Specyfing interface is not supported via "%<interface>", so an IPv6 multicast route will need to exist in the local table so that VLC listens on the correct input interface. Annoyingly if you leave out the @ symbol, VLC doesn't error, and appears to be working.

Address format when sending streams is e.g. "[ff05::30]", with corresponding route. For link local multicast destinations, specify outgoing interface e.g. [ff02::30%eth0]

4.5.2. Multicast IPv4 Streaming
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

URL format in GUI is 'udp://@<group address>`