XCAST over IPv6 Files

XCAST6-kit README (0.2.1, pre-alpha version)

* Release note
  This document describes how you can set up XCAST6-kit for these platforms.
    NetBSD 1.6.2
    NetBSD 2.0.2
    FreeBSD 4.11-RELEASE
    FreeBSD 5.4-RELEASE

* Installation

1. Install OS into your machine.
   - for NetBSD
   See http://www.netbsd.org/Documentation/ for detailed setup instruction.

   - for FreeBSD
   See http://www.freebsd.org/

   Don't forget to install the kernel sources, since it's required
   to build a XCAST6-enabled kernel.

2. Build XCAST6-enabled kernel.
   2-1. Apply the XCAST6 kernel patch for the kernel sources.
	- patch file for NetBSD 1.6.2
	  xcast6-0.2.1-netbsd-sys-1.6.2.diff.gz
	- patch file for NetBSD 2.0.2
	  xcast6-0.2.1-netbsd-sys-2.0.2.diff.gz
	- patch file for FreeBSD 4.11-RELEASE
	  xcast6-0.2.1-freebsd-sys-4.11.diff.gz
	- patch file for FreeBSD 5.4-RELEASE
	  xcast6-0.2.1-freebsd-sys-5.4.diff.gz

	For example:
	  cd /usr/src/sys
	  gzip -dc /path/to/xcast6-0.2.1-netbsd-sys-2.0.2.diff.gz | patch -p2

   2-2. Configure the kernel.
	- sample configuration file for NetBSD is at
	  /usr/src/sys/arch/i386/conf/GENERIC_XCAST6
	- sample configuration file for FreeBSD is at
	  /usr/src/sys/i386/conf/GENERIC_XCAST6

	Don't forget to include these 2 lines in the
	configuration file for NetBSD:
	      options		XCAST6
	      pseudo-device	xcst	1
	following is for FreeBSD4:
	      options		XCAST6
	      pseudo-device	xcst
	following is for FreeBSD5:
	      options		XCAST6
	      device		xcst

   2-3. Install the kernel and boot the machine with it.

3. Install xcast6.h and in6.h to /usr/include/netinet6.
   For example:
     cp /usr/src/sys/netinet6/{xcast6.h,in6.h} /usr/include/netinet6

4. Build and install the libxcast library.
   For example:
     tar zxvf /path/to/xcast6-0.2.1-libxcast.tar.gz
     cd libxcast
     make
     su root -c 'make includes install'

5. Build and install ping6x.
   For example:
     tar zxvf /path/to/xcast6-0.2.1-ping6x.tar.gz
     cd ping6x
     make
     su root -c 'make install'

6. Build and install traceroute6x.
   For example:
     tar zxvf /path/to/xcast6-0.2.1-traceroute6x.tar.gz
     cd traceroute6x
     make
     su root -c 'make install'

7. For NetBSD 1.6.2, Build and install the modified sysctl command.
   For NetBSD 2.0.2 and FreeBSD, original sysctl can be used for XCAST6-enabled
   kernel.
   Apply the patch for the sysctl sources.
	- patch file for NetBSD 1.6.2
	  xcast6-0.2.1-netbsd-sbin-1.6.2.diff.gz

	For example:
	  cd /usr/src/sbin/sysctl
	  gzip -dc /path/to/xcast6-0.2.1-netbsd-sbin-1.6.2.diff.gz | patch -p3
	  make
	  su root -c 'make install'

* Setup

1. Configure your machine as a normal IPv6 host or a normal IPv6 router
   if the host should act as a router.
   See http://www.netbsd.org/Documentation/network/ipv6/#configuration_files
   and set up /etc/rc.conf for NetBSD.

2. Run the following shell script.

   --------- from here --------
   #! /bin/sh

   xcstif=xcst0
   xcast6rt=ff05::10

   ifconfig $xcstif up
   route -qn add -host -inet6 $xcast6rt ::1
   route -qn change -host -inet6 $xcast6rt -ifp $xcstif
   -------- end  here --------

   You can put these commands in a file like /usr/local/etc/xcast6-setup.sh
   and let it run from /etc/rc.local.

   If you are going to use XCAST6 on site-local addresses, you must run
   the following command:
     /sbin/sysctl -w net.inet6.route6.xcast6_allowsitelocal=1
   /etc/sysctl.conf can be used also.

   For FreeBSD, you don't need to provide above xcast6-setup.sh.
   Instead, you can put following four lines into your /etc/rc.conf:

	ipv6_enable="YES"
	cloned_interfaces="xcst0"
	ifconfig_xcst0="up"
	ipv6_static_routes="xcast"
	ipv6_route_xcast="ff05::10 ::1 -ifp xcst0"


* Test Programs
  - /usr/sbin/ping6x, /usr/sbin/traceroute6x

    Command syntax:
      /usr/sbin/ping6x host0,host1,host2,...,hostN [N-th]
    or
      /usr/sbin/traceroute6x host0,host1,host2,...,hostN [N-th]

    The destinations are specified as host0,host1,host2,...,hostN.
    Only the <N-th> host replies by ICMPv6, while other hosts never reply
    for packets sent by ping6x or traceroute6x.  You can use these command
    to diagnose the reachability to the <N-th> host in the destinations
    and to list up the route to the <N-th> host.

  - tcpdump
    1. Download and extract tcpdump-3.8.3.tar.gz.
       You can download it from:
	http://www.tcpdump.org/
       Also, there is a local copy of the archive.
        http://xcast6.sourceforge.net/archives/tcpdump-3.8.3.tar.gz

    2. Apply the XCAST6 patch for tcpdump.
       For example:
	 cd tcpdump-3.8.3
	 gzip -dc /path/to/xcast6-0.2.1-tcpdump-3.8.3.diff.gz | patch -p1

    3. Configure & make & install.
       For example:
	 sh configure --prefix=/usr
	 make; su root -c 'make install'

* Application Programs

  - vic
    1. Download and extract vic-2.8ucl1.1.5.tar.gz.
       You can download it from:
	http://www-mice.cs.ucl.ac.uk/multimedia/software/vic/
       Also, there is a local copy of the archive.
        http://xcast6.sourceforge.net/archives/vic-2.8ucl1.1.5.tar.gz

    2. Apply the XCAST6 patch for vic.
       For example:
	 cd vic-2.8ucl1.1.5
	 gzip -dc /path/to/xcast6-0.2.1-vic-2.8ucl1.1.5.diff.gz | patch -p1

    3. Configure & make & install.
       For example:
	 cd common.new; sh configure --enable-ipv6; make; cd ..
	 cd tcl-8.0/unix; sh configure; make; cd ../..
	 cd tk-8.0/unix; sh configure; make; cd ../..
	 cd vic; sh configure --enable-ipv6; make
	 su root -c 'make install'

    4. Run vic.
       For example:
         vic -n xcast6 host1,host2,host3/11000

       You can specify the destinations with ',' (comma) separated
       IPv6 addresses and hostnames instead of the group multicast address.

       Note for MDO6 users:
       As you can see, command-line options are changed from vic/MDO6.
       You should explicitly specify the network type "xcast6" with -n
       option.

  - rat
    1. Download and extract rat-4.2.25.tar.gz.
       If you don't install Tcl/Tk, download tcl-8.0.3ucl8.tar.gz and
       tk-8.0.3ucl8.tar.gz, and extract into rat-4.2.25 directory.
       You can download it from:
	http://www-mice.cs.ucl.ac.uk/multimedia/software/rat/
	http://www-mice.cs.ucl.ac.uk/multimedia/software/tcl/
	http://www-mice.cs.ucl.ac.uk/multimedia/software/tk/
       Also, there is a local copy of the archive.
        http://xcast6.sourceforge.net/archives/rat-4.2.25.tar.gz
        http://xcast6.sourceforge.net/archives/tcl-8.0.3ucl8.tar.gz
        http://xcast6.sourceforge.net/archives/tk-8.0.3ucl8.tar.gz

    2. Apply the XCAST6 patch for rat.
       For example:
	 cd rat-4.2.25
	 gzip -dc /path/to/xcast6-0.2.1-rat-4.2.25.diff.gz | patch -p1

    3. Configure & make & install.
       For example:
	 cd common; sh configure --enable-ipv6; make; cd ..
	 cd tcl-8.0/unix; sh configure; make; cd ../..
	 cd tk-8.0/unix; sh configure; make; cd ../..
	 cd rat; sh configure --enable-ipv6; make
	 su root -c 'make install'

    4. Run rat.
       For example:
         rat host1,host2,host3/11111

       You can specify the destinations with ',' (comma) separated
       IPv6 addresses and hostnames instead of the group multicast address.

       Notes:
       - We tested new release of rat-4.2.25 on NetBSD-1.6.2 and FreeBSD.
       - NetBSD audio support is not perfect yet.  Volume setting
	 might not work.
	 You can use the "mixerctl" program to set play / record volumes
	 as follows:
		mixerctl -w inputs.mic.preamp=on	# mic. preamp
		mixerctl -w inputs.dac=200	# play (PCM) volume
		mixerctl -w outputs.master=200	# master play volume
		mixerctl -w inputs.mic=100	# record volume

  - xcgroup
    xcgroup is not an XCAST6-enabled software but a support software
    that provides control plane of XCAST6 datagram delivery system.
    See README.XCAST6 in xcast6-0.2.1-xcgroup.tar.gz for installation and
    usage.

* Advanced Features

  - X2U
    You can use the X2U feature described in
    draft-ooms-xcast-basic-spec-02.txt by setting 1 to the sysctl variable
    net.inet6.route6.xcast6_x2ulevel:

      sysctl -w net.inet6.route6.xcast6_x2ulevel=1

    Premature X2U is not supported in this release.
    See draft-ooms-xcast-basic-spec-02.txt for more details.

  - libxcast_raw (raw socket version of libxcast, not fully working)
    That's for the operating systems that don't support XCAST6 natively.
    This feature needs X2U tunneling on the way of the delivery path;
    you need at least one XCAST6/NetBSD host on the way.
    You can build libxcast_raw by defining a LIBXCAST_RAW preprocessor macro.
    You need root privileges to use the library.  Windows XP users can
    build it with Microsoft Visual C++ 6.0 and the IPv6 Technical Preview
    package by using libxcast_raw.dsw for the workspace file (and
    libxcast_raw.dsp for the project file).  We know several functions of
    libxcast_raw run on Windows XP.  libxcast_raw for *BSD may work, but
    is not tested.  USAGI users can see README.usagi in the source
    directory of the library for reference.

    - Caveats
      - XcastEnableMember() and XcastDisableMember() is not correctly
	implemented.  Do not use now or fix them by yourself :-)

* Mailing list
  There is a mailing list to talk about XCAST6-kit.
  WIDE XCAST6-kit information/announcement mailing list.
  xcast6-kit-users@ml.labs.fujitsu.com

  - To subscribe
    Send email to
    xcast6-kit-users-request@ml.labs.fujitsu.com
    which has command "subscribe" in its body.

  - To get help message of the list
    Send email to
    xcast6-kit-users-request@ml.labs.fujitsu.com
    which has command "help" in its body.