Date: 08-15-2024

Chaining redirects write operation requests (ADD, DEL, MOD, MODDN) sent to a replica (slave,  consumer) to a specific master (producer.) Referrals instruct the client to direct writes to any specified server. These features are enabled by: 

• adding the chaining overlay and/or referral stanzas to the slapd.conf on the replica 
• adding the appropriate entries in cn=config
• can also be activated by adding a referral entry in the directory itself

Chaining is normal in clusters which have replicas of the master database and do not support replication to other servers (they consume replication but do not produce it). If a write is sent to a replica and is processed, the change will only be on that server which is a data integrity failure. All replicas should use the chaining overlay to ensure that all writes are forwarded to an appropriate master server.

Referrals, on the other hand, require that the client LDAP application be written with logic to handle referral responses … to chase referrals. Such applications were more common in the early use of LDAP but are relatively rare today. 

Chaining Overlay

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>.example.com"
chain-idassert-bind bindmethod="simple"
binddn="cn=Manager,dc=example,dc=com"
credentials="<secret>"
mode="self"
chain-tls start
chain-return-error TRUE

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

updateref "ldap://<master1>.example.com/" 

Referral Entry (rarely used)

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.

Mandatory Object Classes

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 
Connection 
Network Parameter Authentication Edit Options 
Base DN 
Get base DNS from Root DSE 
Fetch Base DNS 
Base DN: 
Limits 
Aliases Dereferencing 
Count Limit: Finding Base DN 
Time Limit (s): Search 
Controls 
Use ManageDsaIT control while browsing 
Referrals Handling 
Follow Referrals manually 

Follow Referrals 
automatically 

Ignore Referrals 
Fetch subentries while browsing (requires additional search request) 
paged Search page Size: 1 00 Scroll Mode