12. Constructing a Distributed Directory Service

For many sites, running one or more slapd(8) that hold an entire subtree of data is sufficient. But often it is desirable to have one slapd refer to other directory services for a certain part of the tree (which may or may not be running slapd).

slapd supports subordinate and superior knowledge information. Subordinate knowledge information is held in referral objects (RFC3296).

12.1. Subordinate Knowledge Information

Subordinate knowledge information may be provided to delegate a subtree. Subordinate knowledge information is maintained in the directory as a special referral object at the delegate point. The referral object acts as a delegation point, gluing two services together. This mechanism allows for hierarchical directory services to be constructed.

A referral object has a structural object class of referral and has the same Distinguished Name as the delegated subtree. Generally, the referral object will also provide the auxiliary object class extensibleObject. This allows the entry to contain appropriate Relative Distinguished Name values. This is best demonstrated by example.

If the server a.example.net holds dc=example,dc=net and wished to delegate the subtree ou=subtree,dc=example,dc=net to another server b.example.net, the following named referral object would be added to a.example.net:

        dn: dc=subtree,dc=example,dc=net
        objectClass: referral
        objectClass: extensibleObject
        dc: subtree
        ref: ldap://b.example.net/dc=subtree,dc=example,dc=net

The server uses this information to generate referrals and search continuations to subordinate servers.

For those familiar with X.500, a named referral object is similar to an X.500 knowledge reference held in a subr DSE.

12.2. Superior Knowledge Information

Superior knowledge information may be specified using the referral directive. The value is a list of URIs referring to superior directory services. For servers without immediate superiors, such as for a.example.net in the example above, the server can be configured to use a directory service with global knowledge, such as the OpenLDAP Root Service (http://www.openldap.org/faq/index.cgi?file=393).

        referral        ldap://root.openldap.org/

However, as a.example.net is the immediate superior to b.example.net, b.example.net would be configured as follows:

        referral        ldap://a.example.net/

The server uses this information to generate referrals for operations acting upon entries not within or subordinate to any of the naming contexts held by the server.

For those familiar with X.500, this use of the ref attribute is similar to an X.500 knowledge reference held in a Supr DSE.

12.3. The ManageDsaIT Control

Adding, modifying, and deleting referral objects is generally done using ldapmodify(1) or similar tools which support the ManageDsaIT control. The ManageDsaIT control informs the server that you intend to manage the referral object as a regular entry. This keeps the server from sending a referral result for requests which interrogate or update referral objects.

The ManageDsaIT control should not be specified when managing regular entries.

The -M option of ldapmodify(1) (and other tools) enables ManageDsaIT. For example:

        ldapmodify -M -f referral.ldif -x -D "cn=Manager,dc=example,dc=net" -W

or with ldapsearch(1):

        ldapsearch -M -b "dc=example,dc=net" -x "(objectclass=referral)" '*' ref

Note: the ref attribute is operational and must be explicitly requested when desired in search results.