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

                               $Revision: 1.4 $
                          $Date: 2000/10/27 22:31:59 $
===============================================================================

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

Index:
	PLATFORMS
	PERL
	APACHE-SSL WEB SERVER
	USER FRONT-END
	SECURITY ISSUES AND X.509 CERTIFICATES
	DNS SETUP

	Information


-------------------------------------------------------------------------------
		  DETAILED INSTALLATION INSTRUCTIONS
-------------------------------------------------------------------------------

>>> PLATFORMS

Currently, X-Bone supports the following platforms:
  
  - FreeBSD-CAIRN 2.5	  http://www.cairn.net/
  - FreeBSD-3.3/4 + KAME  http://www.kame.net/   
  - FreeBSD-3.3/4 	  (no IPsec support)
  - FreeBSD-4.0		  (no IPsec support)
  - FreeBSD-4.1.x
  - Linux 2.2.5 kernel	  (Redhat 6.0) with NIST Cerberus
  - Linux 2.2.5 kernel	  (Redhat 6.0) (no IPsec support)
  - Linux 2.2.12 kernel	  (Redhat 6.1) (no IPsec support)
  - Linux 2.2.14 kernel   (Redhat 6.2) with NIST Cerberus

X-Bone uses IPIP tunnel interfaces. You may need to
reconfigure/recompile your kernel if it does not include several (we
recommend at least 32) such interfaces, since each X-Bone link
requires *two* tunneling devices. Thus, a host with 32 tunnel devices
supports 16 X-Bone links (which is not much, consider the example of a
center router in a star topology, for example.)

On all platforms except Linux, X-Bone can use user-level IPIP tunnels
based on tun devices and the X-Bone ip-tun daemon. However, both
CAIRN-2.5, FreeBSD-3.3/4 + KAME , and FreeBSD 4.* platforms support 
kernel-level IPIP tunnels, which are preferred (see below). If you wish
to use tun-based tunnels, you must reconfigure you kernel to include IP
firewall and divert socket support, as well as a number of tun devices.

On FreeBSD-3.3/4 + KAME and FreeBSD 4.x systems, X-Bone can use both gif
interfaces (kernel-level IPIP tunnels) or tun interfaces combined with 
X-Bone ip-tun daemons (user-level IPIP tunnels). Using gif interfaces is
preferred on these platforms; you may need to reconfigure your kernel to
support a number of them.

For CAIRN-2.5 systems, both iti interfaces (kernel-level IPIP tunnels)
or tun interfaces combined with X-Bone ip-tun daemons (user-level IPIP
tunnels) are supported by X-Bone. Using iti interfaces is preferred on
this platform, as CAIRN supports dynamic on-the-fly-creation of iti
interfaces, so a kernel recompilation is not necessary.

For vanilla FreeBSD-3.3/3.4 systems, your only option are tun
interfaces combined with X-Bone ip-tun daemons (user-level IPIP
tunnels). You must reconfigure you kernel to include IP firewall and
divert socket support, as well as a number of tun devices.

If you want IPsec, you also need to apply the NIST Cerberus patch from 
http://snad.ncsl.nist.gov/cerberus. Please note that there is no NIST
Cerberus IPsec patch for the 2.2.12 kernel yet. So there is no IPsec
support for X-Bone on Linux Redhat 6.1. Please see the NIST web site for
details.



>>> PERL

All X-Bone code is written in Perl, and has been tested extensively
with Perl_5.005. (Earlier/later versions of Perl 5 may or may not
work. Perl 4 will *not* work.) If you have FreeBSD-3.3-RELEASE or
later, Perl_5.005 should already be installed on your machine.

It is recommended that you use the FreeBSD port-style installation to
automatically check dependencies and install the missing modules. (All
these modules are available from CPAN at http://www.cpan.org/ if you
prefer to install them manually.)

The following is a list of required Perl modules:

  Overlay Manager (OM) & Resource Daemon (RD):
    Net::SSLeay
    Net::Netmask

  User Interface (GUI): 
    CGI
    Mail::Sendmail
    File::CounterFile
    Net::SSLeay
    Net::Netmask

Note: Some of these modules have their own dependencies. Please read
      the documentations of each individual package for details.

Note: The current code includes a 'prefix' to set the search path for
      perl packages, which includes references to directories local to
      ISI (/home/xbone/perl* and the like). If you install X-Bone
      using the FreeBSD port or Linux RPM, this will not matter to you
      as all required packages will be installed locally on each
      machine. However, if you wish to install those packages under a
      shared directory, you can modify this section of the code to
      include your shared path instead of /home/xbone/perl*.

      (Perl has a default INC directory list; this is configured at
      install time, and may already refer to your shared area - print
      @INC to see)



>>> APACHE-SSL WEB SERVER

The Apache-SSL web server is needed for the GUI part of X-Bone. The
corresponding HTML files and CGI scripts will be installed in
/usr/local/www. It is strongly recommended that you back your original
files up if the system already has Apache installed and running. The
supported version is Apache_1.39+SSL_1.37. (Earlier/later versions may
work as well but are not supported.)

The port installation procedure will check if Apache-SSL is installed
or install it automatically.



>>> USER FRONT-END

Any SSL-capable web client should be usable as a user frontend to
X-Bone. However, only version 4.X of Netscape Navigator 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 OMs authenticate themselves to each other, and (2) OMs and
RDs authenticate themselves to each other. User credentials are passed
to the RDs by an OM 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 OM 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

2. OM:
    - host keypair (two files, key and certificate)
    - /etc/xbone/cert/${HOST}.cert.pem
    - /etc/xbone/cert/${HOST}.key.pem
    - usually the same keypair as GUI

3. GUI:
    - host keypair (two files, key and certificate)
    - /etc/xbone/cert/${HOST}.cert.pem
    - /etc/xbone/cert/${HOST}.key.pem
    - usually the same keypair as OM 

4. RD
    - host keypair (two files, key and certificate)
    - /etc/xbone/cert/${HOST}.cert.pem
    - /etc/xbone/cert/${HOST}.key.pem

5. CA Certificate:
    - certificate of your chosen CA (the one your certificates are signed by)
    - for OM, RD, and web server/GUI: /etc/xbone/CAcert.pem
    * Rename the CA Certificate to CAcert.pem if it's not.

Note: At this time, the GUI and OM components *must* be run on the
same system, since communication between the two is not yet secured.
Thus, the same key pair is needed in both locations (2 & 3).



>>> DNS SETUP

#- UPDATE --------------------------------------------------------------
  Starting with X-Bone 1.3 release, the user has the option to turn off
  the DNS feature on a per-overlay basis. You can choose not to setup a
  DNS server for X-Bone *IF* you uncheck the "use DNS" box for ALL
  requests to create overlays. Failure to do so without a DNS server
  would cause errors.
#-----------------------------------------------------------------------

At least one DNS server must be set up use X-Bone. The following
description assumes the resolver configuration file is in
/etc/resolv.conf and the DNS server is named (part of the Berkeley
Internet Name Domain (BIND) Version 8.x <http://www.isc.org/>). If
your DNS server and resolver configuration are different, please read
the following description and consult your DNS setup documentation for
the exact procedures.

    >>> DNS clients (hosts running regular X-Bone RD)

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

	If your system did not have a resolver configuration file
	before the installation, a file named "resolv.conf" will be
	created for you with the sole entry point to your X-Bone name
	server.

	If your system already has a resolv.conf, one "name-server"
	entry will be added to the top of the file. This will cause
	DNS lookups to be redirected to the X-Bone DNS server first.
	If the name to look up does not belong to any of the currently
	configured X-Bone overlays, the lookup will fail and your
	resolver will then go to your original DNS name server(s). If
	the X-Bone DNS server entry is not the first one in
	resolv.conf, depending on how the first name server of
	resolv.conf is configured, the X-Bone DNS server might *never*
	be queried and the overlay name lookup would never succeed.

    >>> Name 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. We will outline the two cases below:

      > Setup new name servers:

	1. The following 3 files are required:
	   - named.conf: consists of two zone entries for your domain and 
			reverse domain lookup which point to the following
 			two files respectively.
	   - xbone zone file
	   - xbone reverse zone file

	2. "Root" entry in named.conf: 
	   Comment out the entry for root (zone ".") if this name
	   server will ONLY serve the overlay DNS queries. (Other
	   general queries will fail.) Enable root entry if this name
	   server will also serve other non- overlay DNS queries.

	3. A Perl script will be executed during X-Bone installation to
	   configure a new name server.

      > Use existing name server:

	Please contact your system administrator to manually configure
	named for your chosen overlay domains.
	****************************************************************
	* DO NOT USE THE PERL SCRIPT PROVIDED.                         *
	* IT MAY DESTROY YOUR DNS HIERARCHY IF NOT APPLIED CORRECTLY.  * 
	****************************************************************

    >>> DNS-RD:

	A special version of the RD must run on the system where
	named runs. This RD receives DNS update requests from OM,
	updates the named files, then notifies named to reload the
	configurations. Currently, this special RD can not act as
	either host nor router for the overlays.

Note:	Currently, the X-Bone setup will install and configure the
	DNS server on the same host as OM/GUI, and configure the DNS
	client for each RD hosts. The affected files will be backed
	up during the process. See INSTALL for installation details.



>>> 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 OMs RDs Verisign cert pem symlinked lib CAcert
 LocalWords:  resolv conf isc LocalWords
