===============================================================================
                     X-BONE 1.3 INSTALLATION INSTRUCTIONS
                          http://www.isi.edu/xbone/
                                xbone@isi.edu

                              $Revision: 1.33 $
                        $Date: 2000/10/27 22:30:10 $
===============================================================================

Index:
	Overview

	Supported Platforms

	Required Softwares

	Installation Methods
	    FreeBSD Port
	    Linux RedHat RPM
	    From the Tarball
	    Upgrade From 1.2 to 1.3

	Uninstalling XBone 1.3

	Obtain Host & User Certificates

	Routing Issues, MRTd & GateD

	Known Problems (IPsec & Traceroute)

	Information & Bug Report

===============================================================================
	
>>> Overview: Types of Installations: OM/GUI and RD

    Note: Although both installation options will install all the components
	  and the full source code of X-Bone, the configuration steps and the
	  software dependency are quite different as outlined here. 

    >>> RD (Resource Daemon): 

	Install the X-Bone Resource Daemon on the hosts you choose to 
	participate in overlays either as leaf nodes or as gateways.

    >>> OM/GUI (Overlay Manager & X-Bone GUI):

	Install the X-Bone Overlay Manager and the X-Bone GUI files on the
	host which will be the control center of overlay deployment and
	management center. This option will also configure the Apache-SSL
	web server and the DNS server (named) on that host. 

    >>> Example - A network lab with 10 PCs with Internet connection:

	- Choose one host to set up as the Overlay Manager and Web/GUI server.
	  This host will also be configured as the DNS server by default.

	- Install RD on the remaining 9 PCs.

	This setting will let you construct overlays containing up to 9 nodes:

	- Start Overlay Manager, the web server, DNS-RD (a special version of
	  RD which runs alongside named to dynamically update the DNS records
	  of overlays), and named on the OM/GUI host.

	- Start Resource Daemon on each RD host.

	The users can then access X-Bone through a web browser on any systems
	to deploy and manage overlays containing up to 9 nodes. 

	Please read the FAQ for more information and examples of using X-Bone.

>>> Supported Platforms:

    >>> FreeBSD [http://www.FreeBSD.org]

	- FreeBSD-3.3 + KAME IPv6/IPsec
	- FreeBSD-3.4 + KAME IPv6/IPsec
	- FreeBSD-3.3/3.4/4.0 (No IPsec support)
	- FreeBSD-4.1
	- FreeBSD-CAIRN 2.5 (with IPsec fixes)

    *** FreeBSD kernel options:

	You need to modify your kernel config file to include them if they
	are not enabled, then build and install a new kernel.

	pseudo-device gif 128
	  - to enable gif tunnel interface, minimum 32 recommended

	option MAX_GIF_NEST=2147483647
	  - to allow recursive tunnels

	option IPSEC
	option IPSEC_ESP
	  - to enable IPsec support (KAME or FreeBSD 4.1)

	> On FreeBSD 4.1 and later, you also need to add "MAX_GIF_NEST"
	  at the end of /usr/src/sys/conf/options, otherwise the kernel
	  won't compile.

    >>> Linux [http://www.kernel.org]

	- Linux 2.2.5  kernel (RedHat 6.0 or later) + NIST Cerberus (IPsec)
	- Linux 2.2.5  kernel (RedHat 6.0 or later) (No IPsec support)
	- Linux 2.2.12 kernel (RedHat 6.1) (No IPsec support)*
	- Linux 2.2.14 kernel (RedHat 6.2) + NIST Cerberus (IPsec)

    *** There's no NIST Cerberus patch for RedHat 6.1 (2.2.5) kernel code.
    *** You should also check if ipip.o is present at your module directory
	(usually /lib/modules/YOUR_KERNEL_NAME/ipv4/). If you not, you need to
	configure your kernel to set "IP: tunneling" to <M>, then compile &
	install a new kernel. This is to enable the IP-in-IP tunnel module.


    >>> For further information on other projects:

	- KAME: 		http://www.kame.net
	- CAIRN:		http://www.cairn.net
	- RedHat Linux: 	http://www.redhat.com
	- NIST Cerberus:	http://www.antd.nist.gov/itg/cerberus/

>>> Required Softwares:

    1. Standard Perl5 with the following additional modules:
        > Web site: http://www.cpan.org
	
	Net::SSLeay		(for OM, RD, and GUI components)
	Net::Netmask		(for OM, RD, and GUI components)
	CGI			(for GUI components)
	Mail::Sendmail		(for GUI components)
	File::CounterFile	(for GUI components)

    2. Apache-SSL		(for GUI components)
	> Web site: http://www.apache-ssl.org
	> Version: apache_1.39 + ssl_1.37 and above

    3. OpenSSL			(for OM, RD, and GUI components)
	> Web site: http://www.openssl.org
	> Version: 0.9.4 and above

    4. RSAref library		(USA residents only)

    5. DNS server: named or equivalent programs (for OM)

    6. Linux Only:
	> iproute2 => http://snafu.freedom.org/linux2.2/iproute-notes.html
	> Notes on RPMs: Most RPMs of the softwares required by XBone can be 
	  found at <http://rufus.w3.org/linux/RPM> except the followings:
	  > Net::SSLeay Perl module: Available at the XBone web site:
	    <http://www.isi.edu/xbone/software/linux>; OR,
	    you can install it from the source tarball as well.
	  > Apache-SSL rpm is available at the Rufus site, but it MAY or MAYNOT
	    work due to different configuration options. Here's a list of 
	    configuration options we used (they will affect the contents of
	    httpsd.conf or httpd.conf):
	    > In apache source directory:
	    % ./configure	--prefix=${PREFIX} \
				--with-layout=GNU \
				--sysconfdir=${PREFIX}/etc/apache \
				--includedir=${PREFIX}/include/apache \
				--localstatedir=/var \
				--datadir=${PREFIX}/www \
				--suexec-docroot=${PREFIX}/www/data \
				--proxycachedir=${PREFIX}/www/proxy \
				--libexecdir=${PREFIX}/libexec/apache \
				--without-confadjust \
				--enable-shared=remain \
				--enable-module=most \
				--enable-module=auth_db \
				--disable-module=auth_dbm
	    > Then proceed as normal installation.
	> IP tunnel module patch => http://www.isi.edu/xbone/software/linux
	* Note: This is no longer needed unless you disable TUN_ALIASING
		in /usr/local/xbone/lib/XB_Defs.pm. Please see XB_Defs.pm(5).



>>> Installation Methods:

    >>> FreeBSD Port:

	0. Update the FreeBSD port collection.

	   Before you start, make sure to update your port collections on ALL
	   the systems you plan to install X-Bone. Some of the FreeBSD ports
	   for our required software were committed into FreeBSD's official
	   port collection only recently (July 2000).

	   If ALL the required ports are available at the system, FreeBSD
	   port will verify the software dependency and install any missing
	   packages automatically.

	   See http://www.FreeBSD.org/ports/ on how to update your ports.

	1. Get X-Bone port.
	
	   If /usr/ports/net/xbone exists:

			% cd /usr/ports/net/xbone

	   If not, download xbone-port.tar.gz from the X-Bone web site at 
	   http://www.isi.edu/xbone/software/x-bone. Unpack the port.

			% cd /usr/tmp && tar xfz xbone-port.tar.gz
			% cd /usr/tmp/xbone

	2. Install X-Bone.

	   [RD]		% make install USA_RESIDENT=[YES|NO] OPTION=RD

	   [OM/GUI]	% make install USA_RESIDENT=[YES|NO] OPTION=OMGUI

	   Notes:
	   (1) RD vs. OMGUI: Read the "Overview" section above. You can only
	       do one of the two on a system.
	   (2) USA_RESIDENT: Specify YES if you reside in the USA. This will
	       build various components using the RSAref library. Specify "NO"
	       if you are outside USA.
	   (3) X-Bone port does _not_ work on FreeBSD-CAIRN 2.5.

    >>> Linux RedHat RPM:

	1. Install the required software packages listed in the "Required
	   Softwares" section above.

	   > RPM will check the software dependency, but will _NOT_ install the
	     missing ones automatically. You can use the RPM "--nodeps" option
	     to disable the dependency check if you want to install other rpms
	     later.

	2. Download the X-Bone RPM file from our web site:
	   http://www.isi.edu/xbone/software/xbone/linux.

	3. Install the X-Bone RPM file:
	   ****************************************************************
	   * Warning: DO NOT USE -U OPTION, see notes on upgrading below. *
	   ****************************************************************

	   		% rpm -ivv XBone-1.3-1.i386.rpm

	4. Run configuration scripts:

	   		% cd /usr/local/xbone/install

	   [RD] 	% make rpm-rd

	   [OM/GUI]	% make rpm-om SRC=/usr/local/xbone

    >>> From Source Tarball:

	1. Install the required software packages listed in the "Required
	   Softwares" section above.

	2. Download and unpack XBone-1.3.tar.gz from our web site:
	   http://www.isi.edu/xbone/software/xbone

			% cd /usr/tmp && tar xfz XBone-1.3.tar.gz
			% cd /usr/tmp/XBone-1.3/

	3. Install X-Bone:

	   [RD]		% make rd

	   [OM/GUI]	% make omgui

    >>> Upgrade From 1.2 to 1.3:

	The basic steps for upgrading:
	   > Backup host certificate files and /etc/Xbone_daemon.conf.
	   > Uninstall XBone 1.2.
	   > Install XBone 1.3.

	1. Uninstall XBone 1.2:
	   > For FreeBSD ports: (assuming XBone port is in /usr/tmp/xbone)
	     % cd /usr/tmp/xbone && make deinstall
	   > For Linux RPM:
	     % rpm -evv XBone-1.2-1
	   > From source tarball:
	     You can manually remove/backup the XBone files, or you can install
	     the new version over the old one.
	   
	   ********************************************************************
	   * Note: Uninstalling XBone-1.2 will also delete ALL EXISTING CONF, *
	   *       STATE FILES, and HOST CERTIFICATES. Make sure you back up  *
	   *       these files before uninstalling XBone.                     *
	   ********************************************************************

        2. Install XBone 1.3 as described above.

	3. Notes on RPM upgrade option (-U):
	   The upgrade option (-U) will _NOT_ work for upgrading XBone from
	   XBone-1.2-1.rpm to XBone-1.3-1.rpm; i.e., %rpm -U XBone-1.3-1.rpm
	   will fail if XBone-1.2-1.rpm was installed before.


>>> Uninstalling XBone-1.3:

    >>> FreeBSD ports:	% cd /_xbone_port_dir/
			% make deinstall

    >>> Linux RPM:	% rpm -evv XBone-1.3-1

    >>> Tarball:	You'll have to remove the XBone files manually. 
			Check FILELIST for XBone-related files & directories.

    *** /etc/xbone:
	The files under /etc/xbone will NOT be removed by RPM uninstallation.
	You can remove them manually after RPM finishes. We recommend that
	you back up at least the Certificate files for future use.
	In the FreeBSD ports deinstallation, a script is executed to ask for
	user confirmation before deleting /etc/xbone.


>>> Obtain Host and User Certificates:

    >>> X.509 Certificates are required for each host (OM & RD) and each user.
	This is necessary since X-Bone software *WILL* alter the configuration
	of your systems. X-Bone requires each host and user to authenticate
	themselves by presenting its X.509 Certificates.

    ***********************************************************************
    *  The X-Bone project maintains a Certification Authority (CA) that   *
    *  issues and signs X.509 certificates ONLY for collaborator of our   *
    *  project. If this is an independent installation, you will need     *
    *  to either setup your own certificatation authority (CA) (see the   *
    *  instructions in the OpenSSL package. (http://www.openssl.org)) or  *
    *  use a commercial service (e.g., Verisign).                         *
    ***********************************************************************

    >>> Altertively, certificates issued by any commercial CA (Verisign, etc.)
	will also work with X-Bone.

    >>> Please refer to REQUIREMENTS & SECURITY for more details.


>>> Routing Issues, MRTd & GateD:

    >>> Routing Issues: 

	Since X-Bone constructs overlays of different topologies (ring, line,
	& star), it's necessary for X-Bone to modify the kernel routing table
	on every host and router participating in overlays. Most routing
	softwares/daemons, including GateD (www.gated.org) and MRTd
	(www.mrtd.net), will delete the routes added through "route" command
	(i.e., not through the routing softwares). To get around this, X-Bone
	needs to issue static route add/delete through the routing softwares
	running on each host. 

    *** Dynamic routing for overlays is currently unsupported. 

    >>> MRTd: 

	The static route update through MRTd is supported both in FreeBSD
	and Linux. The versions tested were 2.1.2a & 2.2.2a. X-Bone will open
	a socket to the MRTd port (5674 by default). If your MRTd uses an
	alternative port, it must be specified either in /etc/mrtd.conf
	or in XB_Defs.pm ($XB_Defs::MRTD_PORT = _new_port_). 

	*** MRTd Crash Recovery:
	
	Note that, since X-Bone adds/deletes routes through the MRTd socket
	interface only, and does *NOT* update the MRTd configuration file
	(/etc/mrtd.conf), if MRTd crashes while X-Bone is running, all routes
	added by X-Bone will be deleted when you reboot MRTd! The solution
	is to terminate X-Bone RD if you find MRTd has crashed, restart MRTd
	first, then restart X-Bone RD. The overlays will be reconstructed by
	X-Bone RD error recovery function, and the overlay operation is back
	to normal. You only need to do this on the host whose MRTd has crashed.

	*** MRTd Password:

	If the MRTd access password is enabled, X-Bone will prompt the user
	for the password during RD startup.

    >>> GateD:
	
	Static route update through GateD is still in development.

    >>> Configuring Routing Softwares for X-Bone:

	X-Bone does NOT require the users to modify their mrtd.conf or 
	gated.conf before using X-Bone. The only requirement is that the 
	routing software (MRTd or GateD) must be started *BEFORE* you run 
	X-Bone RD. 

	For information on obtaining/installing/configuring MRTd and GateD,
	please check their web sites:

	  MRTd:  www.mrtd.net
	  GateD: www.gated.org


>>> Known Problems

    >>> IPsec & Traceroute:

	1. FreeBSD 3.4+KAME will not respond to traceroute when encryption 
	   (IPsec ESP) is enabled in overlays.

	   Solution: It's related to the way KAME treats ICMP errors. The 
	   following patch to netinet/ip_icmp.c (* in the kame directory *)
	   will fix it:
	   <http://www.isi.edu/xbone/software/patches/ip_icmp.c.patch>

	2. FreeBSD 3.4+KAME (with ip_icmp.c.patch applied)  & FreeBSD 4.x
	   respond to traceroute with the wrong addresses when IPsec is
	   enabled.

	   Solution: Please refer to the KAME bug report database: 
	     <http://orange.kame.net/dev/query-pr.cgi?pr=296>,
	   and KAME snap user mailing list archive: 
	     <ftp://ftp.kame.net/pub/mail-list/snap-users/3543>

	3. For some implementations of traceroute, it is necessary to use
	   the "-s source_addr" option to get the correct results on overlays.
	   (This applies to both overlays with or without IPsec enabled.)


>>> Information & Bug Report

    >>> Information, installation problems about OTHER software packages:

	Please contact the maintainers or organizations regarding other
	software packages. X-Bone uses all the required software components
	as-is. 

    >>> Please submit problem or bug reports to <xbone@isi.edu>.

    >>> For more information on the X-Bone programs, please read the man pages
	and other documentation of the X-Bone.

    >>> For more information of the X-Bone project, please visit our web site
        at http://www.isi.edu/xbone/ or email your question to xbone@isi.edu.


