=============================================================================== X-BONE RELEASE 3.0 INSTALLATION INSTRUCTIONS http://www.isi.edu/xbone/ xbone@isi.edu $Revision: 1.6 $ $Date: 2004/02/06 19:47:43 $ =============================================================================== Index: Overview Installation Types: Node Daemon and GUI 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-SSL web server on that host. There are however sample configuration to help the user. >>> 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. >>> Supported Platforms: Platforms Versions IPsec IPv4/v6 Notes ========================================================================== FreeBSD 4.7 - Yes Yes/Yes -------------------------------------------------------------------------- RedHat 8.0 - No Yes/No Kernel 2.4.18+ Linux - Yes Yes/No Kernel 2.5.47+ -------------------------------------------------------------------------- Info: FreeBSD: http://www.freebsd.org RedHat: http://www.redhat.com Linux: http://www.kernel.org ========================================================================== See REQUIREMENTS for installation instructions. >>> Required Software: See REQUIREMENTS. >>> Installing X-Bone: Summary: 1. Install perl modules identified in REQUIREMENTS 2. Obtain host and user certificates 3. Obtain the xbone port or xbone-gui port/rpm/tar 4. Follow the instructions and answer the questions that are asked during installation. 5. In case of errors look at REQUIREMENTS and FAQ. >>> FreeBSD Port: 0. Update the FreeBSD port collection . 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.0 in Makefile, or get the latest version from the X-Bone web site: and unpack the port: % cd /tmp && tar xfz xbone-3.0-port.tar.gz % cd /tmp/xbone-3.0-port % make install Similarly check for X-Bone GUI port: % cd /usr/ports/net/xbone-gui Check if PORTVERSION is 3.0 in Makefile, or get the latest version from the X-Bone web site: and unpack the port: % cd /tmp && tar xfz xbone-gui-3.0-port.tar.gz % cd /tmp/xbone-gui-3.0-port % make install Use the sample configuration files from /usr/local/www/xbone/apache-conf to configure the apache server. Make sure you run httpd with command line directive "-D SSL" and apachectl with "startssl" Both can be installed on the same machine. To automatically start the node daemon at machine boot time, copy /usr/local/etc/xbone/xbone.sh.sample script into /usr/local/etc/rc.d/ directory and edit it as appropriate. >>> 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 XBone-3.0-1.i386.rpm [GUI ] % rpm -ivv XBone-GUI-3.0-1.i386.rpm 3. Post install processing: [Node Daemon] Run xb-config [GUI ] Edit /usr/local/www/xbone/lib/XB_Params.pm to update the key and certificate paths. In case of GUI, use the sample configuration files from /usr/local/www/xbone/apache-conf to configure the apache server. Make sure you run apachectl with command line directive startssl (httpd -D SSL). >>> 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.0.tar.gz from our web site: http://www.isi.edu/xbone/software/xbone % cd /tmp && tar xfz XBone-3.0.tar.gz % cd /tmp/XBone-3.0/ 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] >>> On GUI host: 1. Check the following: (Refer to REQUIREMENTS for details.) - Apache-SSL Setup - Set up the keys - X-Bone host certificate & key files in /usr/local/etc/xbone/cert/ - Update the "node_cert" and "node_key" in /usr/local/www/lib/XB_Params.pm 2. (Re)start Apache % httpd -D SSL OR % apachectl -D SSL (re)start % named >>> On Node Daemon hosts: 1. Check the following: ($PREFIX=/usr/local) - X-Bone daemon conf: $PREFIX/etc/xbone/xbone.conf class= host, router, node, or meta. - X-Bone host certificate & key files in $PREFIX/etc/xbone/conf - /etc/resolv.conf points to nameserver - Check $PREFIX/etc/xbone/xbone.conf for o paths to keys and certificates o ovl_manager = o addresses (v4/v6 for control and app ) o daemon_type - what kind of node is this? o ipproto is defined and set to "ipv4" or "ipv6" as the need may be. o access control rules exist for all users 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. >>> User: Start a web browser and open . >>> Uninstalling XBone: >>> FreeBSD: % pkg_delete XBone- >>> Linux RPM: % rpm -evv XBone--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.0 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. >>> 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 . >>> 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.