=============================================================================== 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 . 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: 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: 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 -XBone-3.2-1.i386.rpm [GUI ] % rpm -ivv -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:// 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 [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- >>> 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.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 . >>> 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.