===============================================================================
                            X-BONE 3.2 REQUIREMENTS
		           http://www.isi.edu/xbone/
                                 xbone@isi.edu

                               $Revision: 1.37 $
                          $Date: 2005/04/27 20:59:42 $
===============================================================================

	>>> This document contains detailed information on the <<<
	>>> requirements of the X-Bone program.                <<<

Index:
	List of Required Software
	    - for the impatient

	Detailed Information
	    - Platforms
	    - Perl 
	    - Apache-SSL Web Server
	    - User Front-End
	    - Security Issues & X.509 Certificates
	    - DNS Setup

	Information

-------------------------------------------------------------------------------
List of Required Software for X-Bone
-------------------------------------------------------------------------------

1. Perl 5.8.0 or above
   
   Perl modules supporting various functionalities are required. They
   are listed below. 
	  
2. OpenSSL 0.9.5a or above	(Node Daemon and GUI)

3. Apache-SSL: apache_2.0.46 or above	        (GUI)

4. DNS server (named): bind 9.2.2 or above	(if DNS is enabled)

5. Linux Only: iproute2 	                (Node Daemon)
               nistnet                          (Node Daemon if QoS is enabled)
               ipsec-tools                      (Node Daemon if IPsec is 
					 	 enabled)

6. Quagga 0.98.3 or above                       (Node Daemon if Dynamic 
						 Routing is enabled, compiled
						 with user=root)

7. OpenLDAP 2.2.23 or above 			(one instance per site)

8. Firefox versions that support XML and XSLT. This distribution has
   been tested with Firefox 1.0.
    
*  Note: Only the immediate requirements for X-Bone were listed. Each package
   may have additional software dependencies not shown. Please check each
   individual software for details.

-------------------------------------------------------------------------------
Detailed Information
-------------------------------------------------------------------------------

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

	Only FreeBSD versions 4.11 and 5.3 have been tested but this software
	should work on earlier versions.

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

  > Kernel Requirements

    The only kernel requirements of X-Bone is the capability to process
    recursive IP-in-IP tunneling. You need to reconfigure and recompile
    your kernel if options to support recursive IP-IP tunneling aren't
    enabled. 
    
    FreeBSD FreeBSD releases 4.x and 5.x, and Linux 2.4.18+ all
    support kernel-level IP-IP tunnels. A minumum of 32 tunnel
    interfaces is recommended. On FreeBSD 4.4 and above, and Linux,
    which support dynamically create and delete tunnel interfaces on
    demand, the maximum number of tunnel interfaces is limited by the
    kernel.
     
    On FreeBSD 4.7+ sysctl "net.link.gif.max_nesting" can be used to 
    control the number of levels IP-IP encapsulations. It must be 
    set to atleast 2. On linux, the number of tunnels if limited by 
    the memory resources. 

    IPsec capabilities also require kernel support, but it is optional.
    X-Bone will automatically detect the presence of kernel IPsec support
    and choose only IPsec-capable hosts/routers when IPsec is required.
    X-Bone supports IPsec on the following platforms: FreeBSD 4.x and 5.x,  
    Linux Kernel 2.6.x.

  > Kernel configuration options for FreeBSD:

    > To enable IP-IP tunneling (gif tunnel interfaces):
	pseudo-device gif	# FreeBSD 4.x, 5.x 

    > To enable IPsec support:
	option IPSEC		# 
	option IPSEC_ESP	# 

  > Kernel options for Linux:

    > To enable support for IP-IP tunneling as a loadable module (ipip.o):
	Networking options --> "IP: tunneling" --> <M>
    


>>> Perl Versions & Modules

    All X-Bone code is written in Perl, and has been tested extensively
    with Perl_5.8.0 (Earlier/later versions of Perl 5 may or may not work. 
    Perl 4 will *not* work.) 

    NOTE: 1. There should be an executable called perl5 for the install 
    to go through. 2. /etc/make.conf should point to the latest perl 
    version 3. perl -v and perl5 -v should return the latest version

    The source code of all required Perl modules can be found at CPAN web
    site <http://www.cpan.org/>. Or you can install them from FreeBSD's ports
    directory or packages (ftp://ftp.freebsd.org/pub/FreeBSD/ports/packages),
    or find the RPMs for Linux systems.

    You might find the script 

         http://www.isi.edu/xbone/software/perl-module-install.sh-3.2.txt

    useful. 

    The following is a list of required Perl modules along with the
    correspoding FreeBSD ports and Linux rpms. Instructions for
    installation are given below.


      Module        Requirement	FreeBSD Port              	Linux RPM
      ==============================================================
      AppConfig		ND/GUI	devel/p5-AppConfig	perl-AppConfig
      CGI		ND/GUI	www/p5-CGI.pm		perl-5.8.0	
      CGI::Carp		ND/GUI	www/p5-CGI.pm		perl-5.8.0
      Config, 		ND/GUI	lang/perl5.8		perl-5.8.0
      Data::Dumper 	ND/GUI	lang/perl5.8		perl-5.8.0
      Fcntl,		ND/GUI	lang/perl5.8		perl-5.8.0
      File::Copy, 	ND/GUI	lang/perl5.8		perl-5.8.0
      FileHandle, 	ND/GUI	lang/perl5.8		perl-5.8.0
      FindBin, 		ND/GUI	lang/perl5.8		perl-5.8.0
      Getopt::Long, 	ND/GUI	lang/perl5.8		perl-5.8.0
      Graph::Base,	ND/GUI	math/p5-Graph		perl-Graph
      Graph::Undirected ND/GUI	math/p5-Graph		perl-Graph
      IO::Select, 	ND/GUI	lang/perl5.8		perl-5.8.0
      IO::Socket, 	ND/GUI	lang/perl5.8		perl-5.8.0
      Socket6, 		ND/GUI	net/p5-Socket6		perl-Socket6
      IO::Socket::Multicast ND	net/p5-IO-Socket-Multicast 
                                           perl-IO-Socket-Multicast
      IO::Socket::SSL, 	ND/GUI	net/p5-IO-Socket-SSL	perl-IO-Socket-SSL
      IO::Socket::SSLv6 ND/GUI	X-Bone*			X-Bone*
      IPC::Open3, 	ND/GUI	lang/perl5.8		perl-5.8.0
      LWP::Simple,	ND/GUI	www/p5-libwww 		perl-libwww
      Net::DNS, 	    ND	dns/p5-Net-DNS		perl-Net-DNS
      Net::IP, 		ND/GUI	net/p5-Net-IP		perl-Net-IP
      Net::Netmask, 	ND/GUI	net/p5-Net-Netmask	perl-Net-Netmask
      Net::Ping, 	    ND	net/p5-Net-Ping		perl-5.8.0
      Net::hostent,	ND/GUI	lang/perl5.8		perl-5.8.0
      NetAddr::IP, 	ND/GUI	net/p5-NetAddr-IP	perl-NetAddr-IP
      POSIX, 		ND/GUI	lang/perl5.8		perl-5.8.0
      Parallel::ForkManager ND	devel/p5-Parallel-ForkManager
  						perl-Parallel-ForkManager
      Parse::RecDescent	ND/GUI	devel/p5-Parse-RecDescent 
                                                    perl-Parse-RecDescent
      Socket, 		ND/GUI	lang/perl5.8		perl-5.8.0
      Socket6, 		ND/GUI	X-Bone*			X-Bone*
      Sys::Syslog, 	ND/GUI	lang/perl5.8		perl-5.8.0
      Tie::File, 	    ND	lang/perl5.8		perl-5.8.0
      Time::Local,	    ND	lang/perl5.8		perl-5.8.0
      XML::LibXML, 	ND/GUI	textproc/p5-XML-LibXML	perl-libxml-perl
      XML::Simple, 	ND/GUI	textproc/p5-XML-Simple	perl-XML-LibXML
      IO::Socket::Multicast6ND	X-Bone*			X-Bone*
      Net::SSLeay	ND/GUI	security/p5-Net-SSLeay	perl-Net-SSLeay
      IO::Socket::INET6 ND/GUI	net/p5-IO-Socket-INET6	perl-IO-Socket-INET6
      File::CounterFile	   GUI	misc/p5-File-CounterFileperl-File-CounterFile
      Mail::SendMail 	   GUI	mail/p5-Mail-Sendmail	perl-Mail-SendMail
      Text::ParseWords 	   GUI	lang/perl5.8		perl-5.8.0
      Net::SSH::Perl	    ND	net/p5-Net-SSH-Perl	perl-Net-SSH-Perl
      Net::LDAP	    	    ND	net/p5-perl-ldap	perl-ldap
      (choose cipher = DES when installing Net::SSH::Perl module)
      Tk		ND/GUI  x11-toolkits/p5-Tk		perl-Tk
      Tk::Getopt	ND/GUI  x11-toolkits/p5-Tk-Getopt  	perl-Tk-Getopt
      Tk::TableMatrix	ND/GUI  x11-toolkits/p5-Tk-TableMatrix	perl-Tk-TableMatrix

      *X-Bone 
      ------      

      Note that IO::Socket::Multicast6 and IO::Socket::SSLv6 are not
      available (either the right version or the module itself) in the
      standard location: CPAN. They are distributed with X-Bone and 
      there should NOT be installed.

      Installation Instructions
      -------------------------

         FreeBSD (from ports directory): 

	 1. Obtain the latest ports tree (ports.tar.gz) from 
	    http://www.freebsd.org/ports. 
             % cd /usr
             % tar zcvf ports-old.tar.gz ports
             % rm -rf ports
             % tar zxvf /tmp/ports.tar.gz 
	 2. Suppose the port to be installed is X (e.g, mail/p5-Mail-SendMail)
   	    then  do the following:
                % cd /usr/ports/X 
                % make install

     	 Some of these modules have their own dependencies. Please
      	 read the documentations of each individual package for
      	 details.
	
	 FreeBSD (from packages): 

         1. Save the package in a local directory (called say X.tgz) 
         2. Execute 
             % pkg_add X.tgz 

         Linux: 

         1. Search for the RPM with the name specified in the Linux column
         2. Assuming that the rpm is X.rpm, install it as 
              % rpm -i X.rpm 
         3. Repeat for all the RPMs. 


>>> OpenSSL
	
	X-Bone requires 0.9.5a version or above including 
	CA handling scripts (e.g., c_rehash)

	FreeBSD: 
	
	    Install port security/openssl

        Linux: 
	
           Install the following rpms on Fedora Core 3: 

             > openssl-0.9.7a-40.i386.rpm   
             > openssl-perl-0.9.7a-40.i386.rpm 


>>> Apache-SSL Web Server

    Only Apache2 is supported by X-Bone. Install Apache2 in 
    the standard way. (e.g., FreeBSD port - www/apache2 )

    1. Apache must be run with SSL enabled. 
    
        FreeBSD: 

	    Add the following lines to /etc/rc.conf.local:

            apache2_enable="YES"
            apache2ssl_enable="YES"
        
        Linux: 

            Execute the system configuration service: 

             bash# system-config-services

    
    X-Bone specific Apache configuration is stored in
    /usr/local/etc/xbone/apache/xbone-apache.conf and symbolically
    linked from appropriate include directory of Apache 
    (FreeBSD: /usr/local/etc/apache2/Includes and 
     Linux: /etc/httpd/conf.d/)

    /usr/local/bin/xb-apache-config is used to install/uninstall X-Bone, 
    in the background. The installed X-Bone is available at
    http://<hostname>:8000. To run X-Bone GUI on non-standard
    ports, edit the above mentioned the configuration file. 

    2. Make sure that the keys and certificates identified in the ssl.conf
       exist and have read permissions. Also do a sanity check to 
       make sure that hostnames, directories etc. are correctly set.
	
    3. Make sure that SSLOptions includes 

	 "+StdEnvVars +CompatEnvVars +ExportCertData" 

    4. On Iinux, check the path to the mime.types and other files. 
	
    5. Install modperl2 
      
	 FreeBSD:  Install port www/mod_perl2 
	 Linux:	   Install rpm mod_perl-1.99_16-3.i386.rpm   
  
    6. Check the security and firewall settings: 

         FreeBSD: ipfw show [ipv4 firewall]
                  ip6fw show [ipv6 firewall]
  
         Linux: iptables -L [list firewall rules]
                /etc/selinux/config 
                [Instructions at
                   http://fedora.redhat.com/docs/selinux-apache-fc3/]

    7. Start Apache: 
     
	     $apachectl startssl
        or   $/usr/local/etc/rc.d/apache2.sh restart 
        or   $/etc/rc.d/init.d/httpd restart 

    -------------------------------------

>>> USER FRONT-END

    Any SSL-capable web client should be usable as a user frontend to
    X-Bone. However, only version 1.0 version of Firefox has been
    extensively tested with X-Bone.


>>> SECURITY ISSUES AND X.509 CERTIFICATES

    Please consult SECURITY for a more detailed discussion of the X-Bone
    security model.

    In short, X-Bone security is based on third-party trust, where (1)
    users and Node Daemons authenticate themselves to each other, and
    (2) Node Daemons and RDs authenticate themselves to each
    other. User credentials are passed to the RDs by an Node Daemon
    for ACL checks; however, this still presumes trust that the
    credential and the requested configuration transaction belong
    together. These two components of a request cannot be atomic if
    the user's front-end agent and the Node Daemon are separate
    entities. Lack of atomicity requires delegated trust. The X-Bone
    security mechanisms are based on X.509 certificates. SSL is used
    as a secure communication channel whenever peers need to exchange
    information.

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

    The following certificates are needed to run an X-Bone system:
    Note: ${HOST} is the canonical fully-qualified domain name of the host

    ***********************************************************************
    * WARNING - make sure your keys are sufficiently protected.           *
    *   *cert.* files are public keys, 644 is sufficient                  *
    *   *key.* files are private keys, 600 is recommended                 *
    * These protections must be set when the keys are installed;          *
    * they are NOT set by the X-Bone installation package.                *
    ***********************************************************************

    1. Users: 
      - certificate for X-Bone frontend (web browser)
      - usually stored by the browser
      - Certificate can be obtained from http://www.xbone.net

    2. Node Daemon/GUI:
      - host keypair (two files, key and certificate)
      - /usr/local/etc/xbone/cert/${HOST}.cert.pem
      - /usr/local/etc/xbone/cert/${HOST}.key.pem
      - Certificates needed for both xb-node-daemon.pl & Apache-SSL server
      - Look at sample httpd/ssl configuration files to specify
	the cert/key files 
      - Cerficates for X-Bone can be specified in xbone.conf/xbone-gui.conf
      - Certificates can be obtained from http://www.xbone.net

    3. CA Certificate:
      - certificate of your chosen CA (the one your certificates are
         signed by) 

      - for Node Daemon, RD, and web server/GUI:
         /usr/local/etc/xbone/cert/CAcert.pem

      * Rename the CA Certificate to CAcert.pem if it's not.

>>> DNS Setup

    X-Bone creates overlays with private DNS names useful only to the
    nodes in the overlays. So each node in the overlay could use
    virtual FQDN like "host-1.line.xbone.overlay" instead of having to
    memorize the private IP addresses used.  To facilitate this,
    X-Bone requires at least one DNS server running named (part of
    Berkeley Internet Name Domain (BIND) Version 9.x). The named must
    be configured to accept dynamic DNS updates and the X-Bone
    configuration should set "dns" variable in the configuration
    file. This host will serve all DNS queries of X-Bone overlays.
    All clients (X-Bone RD nodes) must point their resolver to the
    X-Bone DNS server first.

    1.  DNS clients (hosts running X-Bone Node Daemon)

	The resolver configuration files on the client hosts must be
	changed to direct the DNS requests to the X-Bone name servers.

	Example: /etc/resolv.conf

	    Original resolv.conf		New resolv.conf
	  ===================================================================
	    search	your.domain		search     your.domain
	    nameserver	NS1_ip_addr		nameserver XBone_NS1_ip_addr
	    nameserver	NS2_ip_addr		nameserver NS1_ip_addr
	    nameserver	NS3_ip_addr		nameserver NS2_ip_addr
	    					nameserver NS3_ip_addr
	
	  * XBone_NS1_ip_addr is the IP address of the X-Bone DNS server.
	
	  This will cause DNS lookups to go to the X-Bone DNS server first.
	    - DNS queries for active X-Bone overlays:
	        Succeed at XBone_NS1_ip_addr, and return.
	    - Regular (non-X-Bone) DNS queries:
	        Failed at XBone_NS1_ip_addr, the resolver then queries
		the original nameservers (NS*_ip_addr) in resolv.conf.

    2.  DNS server (named)

	There must be at least one (max. two) name server (system
	running named) to serve the overlay domain you choose. You can
	configure an existing name server or start a new name server
	for the X-Bone overlays. In both cases, you need to modify the
	named.conf file and add the forward and reverse zone (for both
	ipv4 and ipv6) files.
	
	The named must be configured to accept dynamic DNS updates
	from the Node Daemon.  A sample named.conf is provided at
	/usr/local/etc/xbone/named_conf/named.conf.xbone.
	
	***** Check to make sure that the forward and reverse DNS
	***** entries work for all physical hosts. 

	***** Detailed instructions for the setting up the DNS can be
	***** found in xbone/doc/dynamic_dns.txt .

      > named.conf:
	It's in /etc/namedb for FreeBSD, /etc for RedHat Linux.
	Add the following zone entries in named.conf:

		zone "xbone.overlay" {
			type master;
			file "xbone/xbone-forward.zone";
			allow-update {key "key-test";};
		};
		zone "26.172.IN-ADDR.ARPA" {
			type master;
			file "xbone/xbone-reverse.zone";
			allow-update {key "key-test";};
		};
		zone "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.c.e.f.IP6.INT" {
			type master;
			file "xbone/xbone-reverse6.zone";
			allow-update {key "key-test";};	
		};


      > Forward and reverse zone files:	
        Copy the forward and reverse zone files to the location specified
	in the "directory" option in named.conf. The zone files are given in
	/usr/local/etc/xbone/named_conf/xbone. 

	Example: If directory option in named.conf is "/etc/namedb",
		 % cp -R /usr/local/etc/xbone/named_conf/xbone /etc/namedb

		 Default zone file directory: /etc/namedb for FreeBSD,
		 			      /var/named for RedHat Linux.


      * Currently, the X-Bone setup will install and configure the DNS
        server on the same host as Node Daemon/GUI. You can change the
	default DNS server by changing $XB_Defs::DNS_SERVER in
	xbone/lib/XB_Params.pm. 
      
       Check $PREFIX/xbone/doc/dynamic_dns.txt for more details.

>>> OpenLDAP Service Configuration
	
    LDAP can be used to store X-Bone Node Daemon configuration 
    and advertise the presence of Node Daemons. The LDAP servers
    of various X-Bone installations are linked up using replication to
    allow for automatic distribution of ACLs, CAs and host
    advertisements (also called Global X-Bone Testbed or GXBone)

    OpenLDAP must be installed in the normal way. X-Bone requires 
    atleast version 2.2.23 

       FreeBSD: 
            
          Install ports net/openldap22-server and net/openldap22-client.

          $ cd /usr/ports/net/openldap22-server
          $ make install

       Linux: 

          Obtain the latest 2.2.x (x >= 23) source from OpenLDAP website 
          (http://www.openldap.org). After untarring, 

	  $ export  LDFLAGS=" -L/usr/local/lib -rpath=/usr/local/lib"
	  $ export CPPFLAGS="-I/usr/local/include/db42 -D_THREAD_SAFE \
                             -I/usr/local/include"
	  $ ./configure --with-threads=posix  --with-tls=openssl  \
                        --enable-dynamic --without-cyrus-sasl \
                        --localstatedir=/var/db  --enable-ldbm  \
                        --enable-crypt  --enable-lmpasswd  --enable-ldap \
                        --enable-meta  --enable-rewrite  --enable-null \
                        --enable-monitor --enable-bdb \
                        --with-ldbm-api=berkeley  --enable-hdb \
                        --enable-wrappers --prefix=/usr/local 

          $ make install 

    Once OpenLDAP is installed, the X-Bone database has to be initialized. The 
    X-Bone Node Control application can simplify the process. 

          $ xb-node-control 
 
          Click on "Related Software" and "Install" for OpenLDAP. 

    Alternatively, run to install/initialize LDAP database and load 
    more LDIF (LDAP Input Format) file. 

          $ xb-ldap-config 

    You can generate LDIF files containing configuration using 

          $ xb-node-control 

    with LDAP enabled. 

>>> Quagga 

    X-Bone supports Quagga/Zebra version 0.98.3 and above. This support
    is experimental.

    Quagga must be compiled with user/group settings that has the 
    privileges to set multicast addresses on interfaces. This typically
    means root user.

        > FreeBSD 
	 
	 % cd /usr/ports/net/quagga
	 % make ENABLE_USER=root ENABLE_GROUP=wheel install

         *** Quagga seems to munge root username and directory 
	     in /etc/passwd. Make sure they are in order to 
	     avoid surprises. use 'vipw"

       > Linux

         Install from the tar.gz that can be obtained from Quagga
	 main site http://www.quagga.net

	 % tar zxvf quagga-0.xxx.xx.tar.gz 
	 % cd quagga-0.xxx.xx
	 % ./configure --enable-user=root --enable-group=root --sysconfdir=/etc/quagga
         %  make install 


>>> INFORMATION & BUG REPORT

    Please submit your problem or bug report 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.


--
 LocalWords:  ip iti snad ncsl nist gov cerberus cpan org Sendmail usr
 LocalWords: CounterFile README Node Daemons RDs Verisign cert pem
 LocalWords: symlinked lib CAcert resolv conf isc 
