The chain overlay provides basic chaining capability to the underlying database.
What is chaining? It indicates the capability of a DSA to follow referrals on behalf of the client, so that distributed systems are viewed as a single virtual DSA by clients that are otherwise unable to "chase" (i.e. follow) referrals by themselves.
The chain overlay is built on top of the ldap backend; it is compiled by default when --enable-ldap.
In order to demonstrate how this overlay works, we shall discuss a typical scenario which might be one master server and three Syncrepl slaves.
On each replica, add this near the top of the file (global), before any database definitions:
overlay chain
chain-uri "ldap://ldapmaster.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 this below your syncrepl statement:
updateref "ldap://ldapmaster.example.com/"
The chain-tls statement enables TLS from the slave to the ldap master. The DITs are exactly the same between these machines, therefore whatever user bound to the slave will also exist on the master. If that DN does not have update privileges on the master, nothing will happen.
You will need to restart the slave after these changes. Then, if you are using loglevel 256, you can monitor an ldapmodify on the slave and the master.
Now start an ldapmodify on the slave and watch the logs. You should expect something like:
Sep 6 09:27:25 slave1 slapd[29274]: conn=11 fd=31 ACCEPT from IP=143.199.102.216:45181 (IP=143.199.102.216:389)
Sep 6 09:27:25 slave1 slapd[29274]: conn=11 op=0 STARTTLS
Sep 6 09:27:25 slave1 slapd[29274]: conn=11 op=0 RESULT oid= err=0 text=
Sep 6 09:27:25 slave1 slapd[29274]: conn=11 fd=31 TLS established tls_ssf=256 ssf=256
Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=1 BIND dn="uid=user1,ou=people,dc=example,dc=com" method=128
Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=1 BIND dn="uid=user1,ou=People,dc=example,dc=com" mech=SIMPLE ssf=0
Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=1 RESULT tag=97 err=0 text=
Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=2 MOD dn="uid=user1,ou=People,dc=example,dc=com"
Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=2 MOD attr=mail
Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=2 RESULT tag=103 err=0 text=
Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=3 UNBIND
Sep 6 09:27:28 slave1 slapd[29274]: conn=11 fd=31 closed
Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: LDAP_RES_SEARCH_ENTRY(LDAP_SYNC_MODIFY)
Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: be_search (0)
Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: uid=user1,ou=People,dc=example,dc=com
Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: be_modify (0)
And on the master you will see this:
Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 PROXYAUTHZ dn="uid=user1,ou=people,dc=example,dc=com"
Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 MOD dn="uid=user1,ou=People,dc=example,dc=com"
Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 MOD attr=mail
Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 RESULT tag=103 err=0 text=
Note: You can clearly see the PROXYAUTHZ line on the master, indicating the proper identity assertion for the update on the master. Also note the slave immediately receiving the Syncrepl update from the master.
By default, if chaining fails, the original referral is returned to the client under the assumption that the client might want to try and follow the referral.
With the following directive however, if the chaining fails at the provider side, the actual error is returned to the client.
chain-return-error TRUE
