Symas OpenLDAP Knowledge Base

Referrals and Chaining

Chaining instructs the server to redirect writes aimed at a replica/slave/consumer to the appropriate master(s)/producer(s), while Referrals instruct the client to direct writes to any specified server. This can be accomplished by adding the chaining overlay and referral to the slapd.conf on the replica/slave/consumer or by adding a referral entry in the directory itself.

Referral Entry (rarely used)

  1. Add an entry to the directory

     "dn: ou=RemoteUsers,ou=system", 
     "objectClass: top", 
     "objectClass: referral", 
     "objectClass: extensibleObject", 
     "ou: RemoteUsers", 
     "ref: ldap://master1:10389/ou=users,ou=system", 
     "ref: ldap://master2:10389/ou=users,dc=example,dc=com", 
     "ref: ldap://master3:10389/ou=users,ou=system", 

This method allows you to specify multiple ldap servers (not necessarily in the same master cluster) with appropriate credentials to enable writes so the client can send writes to the correct server.

These object classes are mandatory:

    "objectClass: referral", 
    "objectClass: extensibleObject", 

The extensibleObject objectClass is special in that it allows us to include any attribute in this entry. We use it here to gain the ou attribute.

However, once the entry is created, it can be difficult to modify. Any ldapsearch or modify commands must include -M (enables Manage DSA IT control allowing you to override the server referral) to change the actual referral entry.

Apache Directory Studio has a checkbox that allows an override of the referral to modify the Entry.

    type filter text 
    > Connection 
    Network Parameter Authentication Edit Options 
    Base DN 
    Get base DNS from Root DSE 
    Fetch Base DNS 
    Base DN: 
    Aliases Dereferencing 
    Count Limit: Finding Base DN 
    Time Limit (s): Search 
    Use ManageDsaIT control while browsing 
    Referrals Handling 
    Follow Referrals manually 
    Follow Referrals 
    Ignore Referrals 
    Fetch subentries while browsing (requires additional search request) 
    paged Search page Size: 1 00 Scroll Mode 

Chaining Overlay (more common)

Add the following to the global portion of the slapd.conf file on the replica/slave/consumer above any directory entry

    overlay chain 
    chain-uri "ldap://<master1>" 
    chain-idassert-bind        bindmethod="simple" 
    chain-tls start 
    chain-return-error TRUE 

Add the following to the syncrepl section on the replica/slave/consumer

    updateref "ldap://<master1>" 

The chaining overlay allows writes sent to a replica/slave/consumer to be passed by the server to the specified master.