===============================================================================
                    X-BONE 3.2 Frequently Asked Questions
                         http://www.isi.edu/xbone/  
                               xbone@isi.edu

                              $Revision: 1.33 $
                         $Date: 2005/04/26 03:03:13 $
===============================================================================

*** Note: This is a preliminary version of the X-Bone FAQ. A more extensive
          (and better organized) version will be updated at the X-Bone web
	  site: http://www.isi.edu/xbone.

Please also see "Known Problems" section in INSTALL. 

INSTALLATION 
============

> Install of the rpm throw the following error:
  "which: no perl5 in (/sbin:/bin:/usr/sbin:/usr/bin:/usr/X11R6/bin)"
  > The installation script is unable to find perl5. Create a
    link from perl5 (in /usr/local/bin) to perl5.8.xx

> Install of the rpm throw the following error:
  "Can't locate xxx.pm in @INC (..." 
  > Go to CPAN (http://www.cpan.org) and search for this module. Download
    and install this module.

> Do we need to patch and/or recompile the kernel source code in 
  order to use XBone?
  > Not for XBone itself. Current versions of FreeBSD and Linux
    support almost all of the required functionality. We defer
    support for features on specific platforms when the default 
    kernel cannot support it. 

> Installation unsuccessful. There is some issue with Multicast6.
  > Multicast6 depends on perl 5.6 and above. Make sure that 
    /usr/bin/perl has the version of perl5 

> Installation unsuccessful. There is some issue with ports
  > Some ports on which X-Bone depends have been moved to different
    locations. Make sure that the ports tree is upto date.

> Installation was successful. Why can't I find xb-node-daemon? 
  > May be there is a bug. 

    xb-node-daemon should have been installed in /usr/local/bin. Does
    that file (it is actually a symbolic link) exist? Is /usr/local/bin/ is 
    included in the shell path? 

    if the answer for both the above is true, then can you please provide us
    (xbone@isi.edu) with 
       1. Version of the X-Bone you installed 
       2. xbone-install.log 
          (on freebsd, this file is in 
          <temp-dir>/xbone-<version-number>-port/work/XBone-<version-number>/)
       3. Directory contents of 
             (i)   /usr/local/xbone 
             (ii)  /usr/local/xbone/programs 
             (iii) /usr/local/etc/xbone/
             (iv)  /usr/local/etc/xbone/cert/

> Why can't I start xb-node-daemon? 
  > The Node Daemon requires many perl modules, please check to make 
    sure that all are installed. The perl error messages will give you
    idea of what is missing. 
  > Check the certficates paths
  > Check to make sure that if the daemon_type is set to "node" or "router" 
    the appropriate sysctl is set enabling routing. 

> Why can't I see the GUI? 
  > If the error is "connection refused" then likely the apache server
    is not running. 
  > If the error is "-12227", then it is likely you do not have user 
    certificate. Obtain one from http://www.xbone.net
  > If the error is "Internal error", then Apache is unable to run the 
    X-Bone GUI perl scripts. This could be because the dependent perl
    modules are missing or because the certificates are
    missing/corrupt. check /var/log/httpd-error.log

> Why does discover command not return a particular node that is running
  just fine? 
  > There could be many reasons. Do check to see if you default firewall
    rules block the packets. On Linux use "iptables -L"  and on FreeBSD
    use "ipfw show" to see the firewall rules. 

> Why do I see errors such as: 
   
   slapadd: could not add entry dn="ou=Users,ou=xbone" \
   (line=20): txn_aborted! DB_KEYEXIST: Key/data pair \
   already exists (-30996)

   > You might have called init or install repeatedly. This 
     is a warning that can be mostly ignored. 

> Why do I see errors such as: 

   ldap_initialize( ldaps://<hostname> )
   Enter LDAP Password:
   ldap_bind: Can't contact LDAP server (-1)

   > Look at ~/.ldaprc Make sure it has entries as shown in 
     xbone/doc/xbone-ldap.txt 

CAPABILITIES and RUNTIME
========================

> The Node Daemon exits saying something about addrserver
  > You might have reinstalled/updated the xbone installation. Remove 
    the old state file (/var/xbone/xbone.state) and restart the 
    server

> How can I clean up the state of the Node Daemon
  > There are three places where state is present - routing table, 
    tunnel interfaces, and X-Bone state file (/var/xbone/xbone.state). 
    Delete all tunnel interfaces and route entries with addresses in 
    the 172.26/16 and 172.27/16 range and remove the state file.

> I want to cleanup the state. I rebooted my machines but the tunnels
  and routes keep coming back. 
  > X-Bone Node Daemon has persistent state stored in the state file
    (/var/xbone/xbone.state). When the node daemon is started, the 
    daemon tries to restore the state i.e., create routes and tunnels. 
    If you are sure that you want clean the slate completely, then 
    delete the state file before starting the node daemon (assuming
    that you have deleted all route and tunnel entries). 

> Can we disable DNS for XBone?
  > Yes. You can set "dns = no" in xbone.conf configuration file. It
    is also controllable on a per-overlay basis. You can choose NOT to
    run a DNS name server for XBone, but you will have to uncheck the
    "Use DNS" box when creating overlays.

> Can we disable the use of SSL (and the host/user X.509 certificates) in 
  XBone?
  > No, since X-Bone program WILL ALTER the existing network configurations
    (interfaces & routing tables) which requires root access to all the hosts
    participating in XBone operations.

> Can a Resource Daemon accept commands from multiple Overlay Managers?
  > Yes, but you need to include all OM hostnames in the "OverlayManagers"
    entry of /usr/local/etc/xbone/xbone.conf. Add one or more lines of
    type 
        ovl_manager = www.xbone.net 
    
> Can we run multiple Overlay Managers in the same network?
  > Yes, but you need to specify different IP address blocks on different
    OM's or there will be address conflicts between overlays. Please see
    the man page of OM (xb-node-daemon(8)) for details on how to set
    IP address blocks for each OM in the command line.

> Can we run multiple instances of Resource Daemon on the same host?
  > Yes. They would need to be run with different configuration files
    and part of different overlays. You can specify the configuration
    file from the command line. 

> Can we visit a node more than once on the same overlays?
  > No, but it's on our TODO list. :)

> Can we use XBone without IPsec support?
  > Yes. On hosts without IPsec capability or if you prefer, you can
    still construct overlays but without IPsec support. You can
    enable/disable ipsec by enabling/disabling by specifying

            IPsec = no
    in the configuration file (/usr/local/etc/xbone/xbone.conf).

> Can we use XBone without QoS support?
  > Yes. On hosts without QoS (DummyNet/iproute) capability or if you
    prefer, you can still construct overlays but without QoS
    support. You can enable/disable QoS by enabling/disabling by
    specifying

            qos = no

    in the configuration file (/usr/local/etc/xbone/xbone.conf).    

> How can I cleanup old state of the node-daemon ? 
 > Unless you have modified the state file path in xbone.conf or
   XB_Params, the state file is /var/xbone/xbone/state. Note that 
   all the old tunnel and routing related information is lost 
   if the state file is removed.    
 
> Can we use XBone without Dynamic Routing support?
 > Yes. On hosts without Dynamic Routing capability or if you prefer,
   you can still construct overlays but without Dynamic Rouing support.
   You can enable Dynamic Routing by specifying
	    
	    routing = dynamic 
   
   or disable Dynamic Routing by specifying
	   
	    routing = static

   in the configuration file (/usr/local/etc/xbone/xbone.conf).
	

> How do I know if an overlay is still up?
  > You can verify an active overlay through the following means:
    (1) X-Bone "Overlay Status Monitoring" page in the X-Bone main menu,
    (2) You can ping other hosts within the same overlays using "ping"
	command in any of the overlay hosts/routers,
    (3) You can use "traceroute" command within the overlay to check the
	overlay topology. 
    (*) Note that due to the mechanism used by traceroute, it only works in 
	overlays *WITHOUT* IPsec.
    (*) In some implementations of ping and traceroute, you need to use "-s"
	option to specify the source IP address to be the overlay address
	of the host for both ping and traceroute to work correctly.
    (4) Generally speaking, any software monitoring IP networks could be used
	to monitor overlays provided that the source IP addresses can be set
	to the overlay addresses.

> Where are the debugging information for X-Bone?
  > The Node Daemons generate a lot of information on the terminal,
    the same info will also be written to /var/log/xbone.log. Look at
    the xb-node-daemon(8) man page for various debug options. They 
    can all be specified in the configuration file. Use the 
    
         log_mask = "debug1 debug2 ..." 

    option in the configuration file. 

> Why do reverse DNS lookups for overlay names fail?
  > Assuming your DNS setup is correct, you are probably using
    non-routable networks (e.g., 10.0.0.0) for overlay
    addresses. Reverse lookups only work for routable (real)
    addresses.

> Do reverse name lookups have to work to use X-Bone? 
  > Yes. They are necessary. Look at files in xbone/install and
    xbone/doc for instructions on how to set up the DNS.

> Why do traceroutes and/or pings in the overlay fail? Why does traceroute
  display a route that leaves the overlay?
  > Assuming the overlay was deployed correctly, pings and or
    traceroutes inside the overlay may fail due to bugs in the
    ping/traceroute programs: On some systems, ping/traceroute fails
    to correctly set the source address for packets it
    generates. Solution: Explicitly specify the correct source address
    through a command line argument.

> Why cant I see the xbone webpage? 
   > Check the following:
       1. httpsd is being run 
       2. httpsd is able to find the document root (typically 
	   /usr/local/www/xbone/) 
       3. httpsd is able to find the certificates at the appropriate
	  locations (as specified in the configuration file)
       4. Virtual host name (look for <somehostname>:443 in httpsd.conf)
	  is correctly specified as the localhost host name
       5. error log is not showing any other errors 

> Why cant I discover Linux node daemons? 
  > The default fedora core installation firewall settings block
    access to X-Bone ports (265 and 2165). Allow TCP, UDP and 
    Multicast to X-Bone ports. 

> Why cant I see X-Bone GUI or the GUI shows errors on Linux Fedora Core 3 
  > It is possible that SELinux security setting are disabling the 
    loading of certain perl modules. Check this link for more 
    instructions:
         http://fedora.redhat.com/docs/selinux-apache-fc3/
  
> Discover is failing with a message about the server having crashed. 
  > This is a timing issue that we have observed from time to time. 
    Let us (xbone@isi.edu) know if you notice (upon enabling debugging)
    that the overlay manager is fine but the GUI is failing. 

> Dynamic routing is not working 
  > Could be for a couple of reasons: 
    (1) rip/zebra may not have the correct privileges. 
	Fix: quagga needs to be recompiled with user
	     set to root (and group set to wheel on BSD)
    (2) rip is running but fails with the setsocketopt 
	error "IP_ADD_MEMBERSHIP failed" with "Address
	reuse" 
	Problem: Aliases that X-Bone creates for the tunnels
		 result in lo0 being added to the multicast 
		 interface list
        Action: write to xbone@isi.edu because this is a bug          

> Where can I find info not listed here?
  (1) X-Bone web site: <http://www.isi.edu/xbone> 
      (including a longer version of FAQ)
  (2) X-Bone documentation comes with this installation.
  (3) Email xbone@isi.edu.
