
                         X-Bone and LDAP 
			 ---------------


BACKGROUND
----------

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)

All OpenLDAP-related X-Bone configuration files - template for the
configuration file, initial database to be loaded, LDAP ACL file, and
scripts to handle LDAP functions (install/uninstall, add/delete/show
database) - are located in /usr/local/etc/xbone/openldap 

SERVERS
--------

OpenLDAP Server organization: 


                   ldap.xbone.net
                +------------------+
                |Global LDAP Server| 
                +------------------+
                     /         \           ...........
                    /           \
+------------------------+ +-----------------------+
|    a.example.com/      | |      \ x.rack.com     |
|  +-----------------+   | |  +-----------------+  |
|  |Local LDAP Server|   | |  |Local LDAP Server|  |
|  +-----------------+   | |  +-----------------+  |
|        ^               | |            ^          |
|        |               | |            |          |
|        V               | |            V          |
|    +-----------+       | |      +-----------+    | ....
|    |Node Daemon|       | |      |Node Daemon|    |
|    +-----------+       | |      +-----------+    |
|      b.example.com     | |        y.rack.com     |
|                        | |                       |
|  Domain: example.com   | |   Domain: rack.com    |
+------------------------+ +-----------------------+

        Site 1                      Site 2



DATABASE
--------

The basic trees are shown in:

   /usr/local/etc/xbone/openldap/xbone-ldap-local.ldif
   /usr/local/etc/xbone/openldap/xbone-ldap-global.ldif

                     xbone
                      |
               +------+--------------+
               |                     |
              local               global 
               |                     |
+------+---+---+-----+------+        |
Users CA  Pvt  Reg  ACL    Conf      |
          Reg                        |
                                     |
                                     |
                            +--------+-------+
                            CA   Registry  ACL
                      

Expansions for the abbreviations used above: 

"Local" part of the tree which is complete and part of 
the tree are replicated across the global network. 

Users:  ou=Users,ou=local,ou=xbone
        User configuration is stored here 

ACL:    ou=acl,ou=local,ou=xbone
        Shared ACLs within a given site (that can 
        exported to other deployment sites)

Reg:    ou=registry,ou=local,ou=xbone
        Host registry (entries are exported to  
        other deployment sites) 

PvtReg: ou=privateregistry,ou=local,ou=xbone
        Host registry (entries not exported to 
        other deployment sites) 

Conf:   ou=config,ou=local,ou=xbone
        Host configurations (not exported to other 
        deployment sites) 

CA:     ou=ca,ou=local,ou=xbone
        Shared certificate authorities (exported to 
        other deployment sites) 

"Global" part of the tree which contains shared data from other
sites. 

ACL:      ou=acl,ou=global,ou=xbone

          Imported ACLs 

Registry: ou=registry,ou=global,ou=xbone

          Imported host entries 

CA:       ou=ca,ou=global,ou=xbone

          Imported certificate authorities 

Preconfigured Users: 

  cn=Manager,ou=Users,ou=local,ou=xbone 
  
  Has root access to all entries in the database 

  cn=XBoneUser,ou=Users,ou=local,ou=xbone

  User name specified by Node Daemon to read host configuration and
  write into registry.

  cn=SyncUser,ou=Users,ou=local,ou=xbone

  User name specified by slapd OpenLDAP server to synchronize with the
  global LDAP server at ldap.xbone.net

  cn=ReplicationUser,ou=Users,ou=local,ou=xbone

  User name specified by slurpd OpenLDAP server to push data into the 
  global OpenLDAP server at ldap.xbone.net 

  cn=xbone.net,ou=ca,ou=local,ou=xbone

  Default X-Bone CA certificiate (somewhat redundant) included in the
  database.

PRECEDENCE
----------

The precedence for resolving conflicts between settings specified in
various ways is given below:

    command line > xbone.conf > 
            ldap config > default parameters (XB_Params) 

SECURITY 
---------

All communication between LDAP clients (embedded in Node Daemons) 
and LDAP servers uses SSL. Passwords are used in addition to the 
SSL. Passwords can be easily decoded from the distribution unless
they are modified after installation. 

INSTALL
-------

1. Install 

  OpenLDAP must be installed in the usual fashion. 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 \
                        --build=i386-portbld-freebsd4.10 
          $ make install 

    Slapd and slurpd must be run with the following arguments: 

          slapd -h ldaps://<hostname>
          slurpd -t /var/db/openldap-xbone-slurpd

    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. 

    Make sure that NTP is running on your machine.  Otherwise you
    might find that the timestamps are skewed and you cannot get the
    ldap servers to sync up.


2. Make sure that the ldap client settings in $HOME/.ldaprc are
   set appropriately. Example settings shown below.

    $cat ~/.ldaprc 
    #
    # LDAP Defaults
    #
    
    TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv2
    TLS_REQCERT   demand
    TLS_CACERT    /usr/local/etc/xbone/cert/CAcert.pem
    TLS_CAPATH    /usr/local/etc/xbone/cert
    TLS_CERT      /usr/local/etc/xbone/cert/<HOSTNAME-CERT-FILENAME>
    TLS_KEY       /usr/local/etc/xbone/cert/<HOSTNAME-KEY-FILENAME>


REFERENCES
----------
[1] Adam Williams, LDAP Tutorial. 
    ftp://kalamazoolinux.org/pub/pdf/ldapv3.pdf
[2] OpenLDAP website. http://www.openldap.org 

