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

                              $Revision: 1.77 $
                        $Date: 2005/04/26 04:35:16 $
===============================================================================

Index:
	Overview
	    Installation Types: Node Daemon and GUI 

	Global X-Bone 

	Supported Platforms

	Required Softwares

	Installing X-Bone
	    FreeBSD Port
	    RedHat Linux RPM
	    From the Tarball

	Starting X-Bone

	Uninstalling X-Bone

	Obtain Host & User Certificates

	Backward Compatibility

	Known Problems 

	Information & Bug Report

===============================================================================
	
>>> Overview: Types of Installations: Node Daemon or GUI 

    There are two types of installations for X-Bone: Node Daemon and
    GUI. Both will install the full source code of X-Bone, but the
    configuration steps and the software dependency are quite
    different as shown here.

    >>> Node Daemon Only: -> multiple instances per network

	Install the X-Bone Node Daemon on the hosts you choose to
	participate in overlays either as end systems (hosts), as
	intermediate systems (routers), both or as overlay managers
	("meta" nodes). It will install the X-Bone source code, X-Bone
	configuration file, and the DNS client configuration file
	(resolv.conf).

    >>> GUI: 

	Install the X-Bone GUI files on the host which will be the
	control center of overlay deployment and management
	center. This option will require the user to configure 
	the Apache web server on that host. 

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

	- Install the Overlay Manager (Node daemon configured as a
	meta node) and X-Bone GUI. 

	- Install Node Daemon in host or router roles on the remaining
	9 PCs.

	This setting will let you construct overlays of up to 9 nodes.

	- Start Node Daemon configured as meta node, the web server
	and DNS server (typically named).  
	
	- Start Node Daemon on each Node Daemon host.

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

>>> Global X-Bone 
        
	Global X-Bone uses LDAP to achieve replication of the CAs
	(Certificate Authorities), ACL (Access Control List) and
	registry information. The X-Bone specific LDAP configuration
	(configuration file, initial database, access control)
	includes settings for replication in the configuration and the
	administrator can use the control panel to install and
	uninstall the same. 

        The user-visible GX-Bone settings are at two places:

	   (1) Node Daemon configuration [One per host]
	   (2) OpenLDAP server configuration [One per site]

	[Per Host] If the node daemon configuration (on command
	line/configuration file/in LDAP) specifies
	the "ldap scope" variable as "local" or is unspecified, then
	the daemon registers itself in the private registry that is
	not replicated. If the scope is global, the host registers
	itself is registry subtree that is replicated (depends on the
	per-site setting).

	[Per Site] If the "replica" item in the X-Bone specific LDAP
	configuration file
	(/usr/local/etc/xbone/openldap/xbone-slapd.conf included in
	/usr/local/etc/openldap/slapd.conf) is commented out or
	absent, then also Global X-Bone is disabled. 

	Both these settings are orthogonal giving the administrator of
	a single host and an administrator of a X-Bone deployment site
	control over level of participation in Global X-Bone.
	
	A single GUI, the Node Daemon Control Panel can be used to set
	the per-host and per-site LDAP properties. The user has to
	simply set the "scope" in Node Daemon Control Panel on the
	LDAP page as "global" and save this configuration. If the host
	also serves as a LDAP server, then this setting will be used
	(requires saving the configuration first) while installing
	X-Bone specific OpenLDAP configuration (click "Related
	Software" on the panel).

>>> Supported Platforms:

    Platforms	Versions	IPsec	IPv4/v6      		Notes
    ==========================================================================
     FreeBSD    4.7 - 	        Yes	Yes/Yes    
    --------------------------------------------------------------------------
     Fedora     Core 3+         Yes     Yes/No                  Kernel 2.6.0+
     Linux       -		
    --------------------------------------------------------------------------
     Info:
	FreeBSD: http://www.freebsd.org
	RedHat:  http://www.redhat.com
	Fedora:  http://fedora.redhat.com
	Linux:   http://www.kernel.org

	Linux kernel 2.5.47 (Redhat 9.0) and kernel 2.4.18+ (Redhat 8.0) 
	should work but has not been tested. 

    ==========================================================================

>>> Required Software:

    See REQUIREMENTS. 


>>> Installing X-Bone:

    Summary: 
       1. Install perl modules identified in REQUIREMENTS
       2. Obtain host (one for each host) and user certificates 
       3. Install OpenLDAP 2.2.23 or above [optional]
       4. Obtain the xbone and/or xbone-gui port/rpm/tar 
       5. Generate XBone/XBone-GUI configuration using the 
          control panel 
       6. Optionally use the control panel to install xbone-specific
          openldap/apache configuration 
       7. In case of errors look at REQUIREMENTS and FAQ. 

    >>> FreeBSD Port:

	0. Update the FreeBSD port collection <http://www.FreeBSD.org/ports>.
	   Uninstall previous versions of X-Bone. Be sure to backup your old
	   certificate/key files, X-Bone configuration and state files.

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

			% cd /usr/ports/net/xbone

	   Check if PORTVERSION is 3.2 in Makefile, or get the latest version
	   from the X-Bone web site: <http://www.isi.edu/xbone/software/xbone>
	   and unpack the port: 
			% cd /tmp && tar xfz xbone-3.2-port.tar.gz
			% cd /tmp/xbone-3.2-port 
			% make install 
	
           Similarly check for X-Bone GUI port:

	   Get X-Bone GUI port. 

	   If /usr/ports/net/xbone-gui exists:

	   		%cd /usr/ports/net/xbone-gui 
        
	   Check if PORTVERSION is 3.2 in Makefile, or get the latest version
	   from the X-Bone web site: <http://www.isi.edu/xbone/software/xbone>
	   and unpack the port: 

			% cd /tmp && tar xfz xbone-gui-3.2-port.tar.gz
			% cd /tmp/xbone-gui-3.2-port 
			% make install 


           
	   Both can be installed on the same machine. 
           
    >>> RedHat Linux RPM:

	0. Install the required software packages listed above. RPM
 	   will not automatically install the dependencies.

	   Uninstall previous versions of X-Bone. Be sure to backup
	   your old certificate/key files, X-Bone configuration and
           state files. 

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

	2. Install the X-Bone RPM file: (use --nodep if necessary)
	   [Node Daemon] 	% rpm -ivv <distribution>-XBone-3.2-1.i386.rpm
	   [GUI        ] 	% rpm -ivv <distribution>-XBone-GUI-3.2-1.i386.rpm


    >>> From Source Tarball:

	1. Install the required software packages listed in the "Required
	   Softwares" section above.
	   Uninstall the previous versions of X-Bone.

	2. Download and unpack XBone-3.2.tar.gz from our web site:
	   http://www.isi.edu/xbone/software/xbone
			% cd /tmp && tar xfz XBone-3.2.tar.gz
			% cd /tmp/XBone-3.2/

	3. Install X-Bone in /foo/bar: 
	   [Node Daemon]	% make node    PREFIX=/foo/bar
	   [GUI]        	% make gui     PREFIX=/foo/bar
	   
	   * Although this allows non-root users to install X-Bone in a
	     customized location, configuring and running X-Bone still
	     require root priviledge.

>>> Starting X-Bone: [must be root]

   >>> Generic post install processing: 

	   [Node Daemon]  	Run xb-node-control
				or edit /usr/local/etc/xbone/xbone.conf

                                [For Global X-Bone, enable LDAP and 
                                 select LDAP scope to be "global"] 


	   [GUI        ]	Run xb-gui-control
				or edit /usr/local/etc/xbone/xbone-gui.conf
                                to update the key and certificate paths. 

          Check the firewall configuration:

	  Ports: 

	  [GUI        ]  8000 (tcp), 8001 (tcp) 
		         if xbone default http configuration is used

          [Node Daemon] 265 (tcp & udp), 2165 (tcp)

	     Linux: Use system-config-securitylevel
	     FreeBSD: Use ipfw and ip6fw 

	  Other privileges 
	     Linux: Privilege to load shared object files
                    check 
		    http://fedora.redhat.com/docs/selinux-apache-fc3/
             FreeBSD: None

    >>> On GUI host:

	1. Check the following:	(Refer to REQUIREMENTS for details.)
	   - Apache-SSL Setup [Apache is able to run, mod perl is installed]
	   - X-Bone host certificate & key files in /usr/local/etc/xbone/cert/

        2. Install X-Bone specific Apache configuration: 

	   % xb-gui-control [For automatic installation] 
           or use the following as a starting point:
            /usr/local/etc/xbone/apache/xbone-apache.conf.template 

        3. (Re)start Apache
	   
           % apachectl startssl 
   
    >>>	On Name server:

	1. (Re)start name server
	% named
	(you can skip this step if you do not want dynamic dns support 
	 in xbone overlay. Check REQUIREMENTS for more details)

    >>>	On OpenLDAP server: 

        1. Install and enable OpenLDAP [see REQUIREMENTS] 

        2. Install X-Bone specific OpenLDAP configuration
          
           % xb-node-control 
             
           Select "Base" and if "LDAP" set the parameter including
           the nature of this installation (local/global)
  
           After "save", click on "Related Software" and install
           OpenLDAP X-Bone database 

	3. (Re)start LDAP server

   	   % /usr/local/libexec/slapd -h ldaps://<server-name> 
        or % /usr/local/etc/rc.d/slapd.sh start [FreeBSD]

        4. (Re)start the SLURPD server if Global X-Bone is enabled 
          
           % /usr/local/libexec/slurpd -t /var/db/openldap-xbone-slurpd 
        or % /usr/local/etc/rc.d/slurpd.sh start [FreeBSD]

    >>> On Node Daemon hosts:

        1. Generate the configuration files: 

            % xb-node-control 

	   Optionally this panel will generate a OpenLDAP LDIF 
           input file that should be loaded into the LDAP server. 
           Use X-Bone provided application for the purpose

           % xb-ldap-config add <LDAP-Server> <LDIF-filename> 
           
           [Ask xbone@isi.edu if you dont know what password to 
            use] 

	2. Start Node Daemon:
	   % xb-node-daemon 
        
        3. To start the node daemon automatically, copy and edit 
           /usr/local/etc/xbone/xbone.sh.sample to 
           /usr/local/etc/rc.d/xbone.sh. 

    >>> On nodes with Quagga installed 
        
	1. Make sure that Quagga has been compiled with root 
	   privileges to be able to be add multicast addresses
	   to interfaces [See REQUIREMENTS]

	2. Copy sample Zebra/Quagga configuration files from 
	   /usr/local/etc/xbone/routing/ into appropriate 
	   directory (BSD: /usr/local/etc/quagga and Linux: 
	   /etc/quagga). 

	3. Edit files with the correct hostname 

    >>> User:

	Start a web browser and open http://${GUI_Hostname}:8000/


               
>>> Uninstalling XBone:

    >>> FreeBSD:	% pkg_delete XBone-<Version>
    >>> Linux RPM:	% rpm -evv XBone-<Version>-1
    >>> Tarball:	Remove the XBone files manually. 

    *** /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 and Key files for future use.

>>> Obtain Host and User Certificates:

    >>> X.509 Certificates are required for each host (OM & Node
        Daemon) 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).                         *
    ***********************************************************************

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

    >>> Due to the new support for S/MIME authentication, the
    >>> certificates obtained prior to X-Bone 1.3.x will NOT work IF
    >>> the key is passphrase- protected. If that's the case,
    >>> regenerate your key file WITHOUT passphrase protection.

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


>>> Backward Compatibility

    >>> XBone 3.xx is incompatible with any previous XBone releases.

>>> Known Problems

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

    2.  If you use IP addresses from RFC 1918 for XBone overlays, 
	traceroute would be very slow since it attempts to do reverse 
	DNS lookup on those overlay addresses. 

	Solution: Use "-n" option to print hop addresses numerically 
	rather than doing reverse DNS lookup on each gateway (which 
	would fail anyway.)

    3.  After a period of inactivity (~ 15 minutes), some Node Daemons
	will not reply to the first multicast request ("Overlay
	Creation" or "Discover Available Daemons").

	This is due to the ARP implementation of FreeBSD. When an ARP 
	request is issued, FreeBSD will cache only the "last" IP packet
	of a group of packets sent to the requested destination address.
	Because the X-Bone UDP reply message with S/MINE signature usually
	consists of 3 IP fregments, only the last fregment will be sent.
	
	Solution: Issue the command again.

    4.  Firewall issue:

	XBone uses private IP addresses (RFC 1918) in the overlays. If
	your firewall setting blocks those addresses, you can still 
	create and delete overlays, but all traffic within overlays will
	be blocked by the firewall. 

	Dynamically punch holes in the firewall when creating overlay is
	currently under investigation. 

    5.  Traceroute on IPsec'd IPv6 overlays fails
	
	The ICMP messages that are supposed to be generated are not
	being generated when ipsec is enabled.

	This is a FreeBSD issue. Look at message 8272 on snap-users 
	mailing list at http://www.kame.net.

	(KAME-snap 8272) Re: traceroute6  fails when ipsec enabled

	Jun-ichiro Itojun 	
        >the real cause of problem is that we maintain M_DECRYPTED by
	> 1-bit flag. we have been investigating how to solve the
	> problem (i.e. maintain more detailed information on
	> decryption), but have not implemented any solution yet.

    6. xbone deinstall does not remove IO-Socket-Multicast6 module

	X-Bone had to be patched up because there was no module for
	IPv6 Multicast. While the files get deleted properly, the 
	clean up the package database is not complete. This patch 
	(and resulting package errors) will be removed in the next 
	release. 

    7. NistNET (QoS support on linux) untested

       NistNet has compilation issues on Fedora Core 3 and does not
       appear to be officially supported. IPTables seems to have an
       appropriate experimental extension but has not been explored. 


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


