Date: 08-15-2024

Chaining versus Referrals

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)

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 
o 
Follow Referrals 
automatically 
o 
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>.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/" 

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