5.2 Distributing the Directory

The scenarios presented thus far have all assumed that the entire directory consists of a single partition on one server. In the real world, this may not always suffice. There are many reasons (which I touched on in Chapter 2) for splitting a directory into two or more partitions, which may reside on multiple servers.

Let's assume that, according to Figure 5-2, the top level of your directory server (dc=plainjoe,dc=org) is maintained by one department, and the server containing host information (ou=hosts,dc=plainjoe,dc=org) is managed by another. How can these two directories be combined into one logical DIT?

Figure 5-2. Two separate directory partitions held by different servers

The definition for the ou=hosts partition held by the second server is very similar to the database section we have been using so far. The main changes are to the suffix served by the backend (ou=hosts,dc=plainjoe,dc=org) and the directory in which the BerkeleyDB files are stored (/var/ldap/hosts/). The rootdn (cn=Manager,ou=hosts,dc=plainjoe,dc=org) must also be updated due to the requirement that it must exist within the partition's naming context.

#######################################################
## Partition on second server holding ou=hosts
database        bdb
      
## Define the root suffix you serve.
suffix          "ou=hosts,dc=plainjoe,dc=org"
      
## Define a root DN for superuser privileges.
rootdn          "cn=Manager,ou=hosts,dc=plainjoe,dc=org"
      
## Define the password used with rootdn. This is the Base64-encoded MD5 hash of
## "secret."
rootpw          {SSHA}2aksIaicAvwc+DhCrXUFlhgWsbBJPLxy
      
## Directory containing the database files
directory       /var/ldap/hosts
      
## Files should be created rw for the owner **only**.
mode            0600
      
## Indexes to maintain
index           objectClass     eq
index           cn              pres,eq
      
## db tuning parameters; cache 2,000 entries in memory
cachesize       2000
      
# Simple ACL granting read access to the world
access to * 
     by * read

Chapter 2 described a distributed directory implemented by superior knowledge references (referrals) that point from the root of a subtree to the server of the larger directory, and subordinate knowledge references (references) that point from a node in the larger directory to the subtree, or partition, to which it should be attached. In terms of Figure 5-2, these knowledge references would link the dc=plainjoe,dc=org partition to ou=hosts,dc=plainjoe,dc=org, as shown in Figure 5-3.

Figure 5-3. Connecting the two partitions using a referral and a reference

These connecting links allow a client to request a search that starts at any node in the directory and continues down through the directory tree, traversing all the directory's partitions. In this case, the search reference URI is returned to the client, which then has the option of continuing the search using the new server and the new base suffix.

The slapd.conf for the server holding the ou=hosts tree possesses a global section identical to your existing server, with one exception. OpenLDAP uses the referral global parameter to define an LDAP URI for the server's superior knowledge reference. This feature is implemented as a global, server-wide parameter as opposed to a database-specific directive because a superior knowledge reference refers the client to a server that has knowledge that the server receiving the request does not possess. Normally, this superior server would be higher in the directory tree, but OpenLDAP does not enforce this rule. If the ou=hosts partition is held by a server separate from one containing the top-level naming context, the referral parameter would look similar to the following:

## slapd.conf for ou=hosts (ldap2.plainjoe.org)
##
## <Preceding portion of global section omitted>
##  . . . 
## Define the URL (only host:port) for the host that clients should contact in the
## event that you cannot service their requests.  
referral     ldap://master.plainjoe.org:389/

Subordinate knowledge references are implemented as entries within the directory itself. These entries use the referral structural object class defined in RFC 3296. This class contains a single required attribute named ref, which holds the LDAP URI for the root of the subtree. So to connect the top-level partition in Figure 5-3 to the people organizational unit, you must create the referral entry to the directory. Assuming that the ou=hosts naming context is held by a server named ldap2.plainjoe.org, this ldapadd example reads the new entry from standard input:

$ ldapadd -H ldap://localhost/ -D "cn=Manager,dc=plainjoe,dc=org" \
> -w secret -x << EOR
> dn: ou=hosts,dc=plainjoe,dc=org
> ou: people 
> objectClass: extensibleObject
> objectClass: referral
> ref: ldap://ldap2.plainjoe.org/ou=hosts,dc=plainjoe,dc=org
> EOR
adding new entry "ou=hosts,dc=plainjoe,dc=org"

The OpenLDAP server implements the ManagerDSAIT LDAP control defined in the RFC 3088. This control enables a client to access the actual attribute values (including the ref attribute) in a referral entry without having the server return the referral itself. If a need arises to update a referral entry, enable this control by using the -M (or -MM) command-line option to ldapmodify.

Next, create a sample in the ou=hosts tree ldap2.plainjoe.org for later use:

$ ldapadd -H ldap://ldap2.plainjoe.org/ \
> -D "cn=Manager,ou=hosts,dc=plainjoe,dc=org" \
> -w secret -x << EOR
> dn: ou=hosts,dc=plainjoe,dc=org
> objectclass: organizationalUnit
> ou: hosts
> description: Container for host information in plainjoe.org domain
> EOR
adding new entry "ou=hosts,dc=plainjoe,dc=org"

The next section will show you how to handle these search references when querying the directory using ldapsearch.