Show Table of Contents



2.4. Configuring Cascading Chaining
The database link can be configured to point to another database link, creating a cascading chaining operation. A cascading chain occurs any time more than one hop is required to access all of the data in a directory tree.
2.4.1. Overview of Cascading Chaining
Cascading chaining occurs when more than one hop is required for the directory to process a client application's request.

The client application sends a modify request to Server 1. Server one contains a database link that forwards the operation to Server 2, which contains another database link. The database link on Server 2 forwards the operations to server three, which contains the data the clients wants to modify in a database. Two hops are required to access the piece of data the client want to modify.
During a normal operation request, a client binds to the server, and then any ACIs applying to that client are evaluated. With cascading chaining, the client bind request is evaluated on Server 1, but the ACIs applying to the client are evaluated only after the request has been chained to the destination server, in the above example Server 2.
For example, on Server A, a directory tree is split:

The root suffix
dc=example,dc=com
and
the ou=people
and ou=groups
sub suffixes are stored on Server A. The l=europe,dc=example,dc=com
and ou=groups
suffixes are stored in on Server B, and the ou=people
branch of the l=europe,dc=example,dc=com
suffix is stored on Server C.
With cascading configured on servers A, B, and C, a client request targeted at the
ou=people,l=europe,dc=example,dc=com
entry would be routed by the directory as follows:

First, the client binds to Server A and chains to Server B using Database Link 1. Then Server B chains to the target database on Server C using Database Link 2 to access the data in the
ou=people,l=europe,dc=example,dc=com
branch. Because at least two hops are required for the directory to service the client request, this is considered a cascading chain.
2.4.2. Configuring Cascading Chaining Using the Console
- Select the Configuration tab. Expand the Data folder in the left pane, and select the suffix, then the database link.
- Click the Limits and Controls tab in the right navigation pane.
- Select the Check local ACI check box to enable the evaluation of local ACIs on the intermediate database links involved in the cascading chain. Selecting this check box may require adding the appropriate local ACIs to the database link.
- Enter the maximum number of times a database link can point to another database link in the Maximum hops field.By default, the maximum is ten hops. After ten hops, a loop is detected by the server, and an error is returned to the client application.
2.4.3. Configuring Cascading Chaining from the Command Line
To configure a cascade of database links through the command line:
- Point one database link to the URL of the server containing the intermediate database link.To create a cascading chain, the
nsFarmServerURL
attribute of one database link must contain the URL of the server containing another database link. Suppose the database link on the server calledexample1.com
points to a database link on the server calledafrica.example.com
. For example, thecn=
database_link,cn=chaining database,cn=plugins,cn=config
entry of the database link on Server 1 would contain the following:nsFarmServerURL: ldap://africa.example.com:389/
- Configure the intermediate database link or links (in the example, Server 2) to transmit the Proxy Authorization Control.By default, a database link does not transmit the Proxy Authorization Control. However, when one database link contacts another, this control is used to transmit information needed by the final destination server. The intermediate database link needs to transmit this control. To configure the database link to transmit the proxy authorization control, add the following to the
cn=config,cn=chaining database,cn=plugins,cn=config
entry of the intermediate database link:nsTransmittedControls: 2.16.840.1.113730.3.4.12
The OID value represents the Proxy Authorization Control. For more information about chaining LDAP controls, see Section 2.3.2.2, “Chaining LDAP Controls”. - Create a proxy administrative user ACI on all intermediate database links.The ACI must exist on the server that contains the intermediate database link that checks the rights of the first database link before translating the request to another server. For example, if Server 2 does not check the credentials of Server 1, then anyone could bind as
anonymous
and pass a proxy authorization control allowing them more administrative privileges than appropriate. The proxy ACI prevents this security breach.- Create a database, if one does not already exist, on the server containing the intermediate database link. This database will contain the admin user entry and the ACI. For information about creating a database, see Section 2.2.1, “Creating Databases”.
- Create an entry that corresponds to the administrative user in the database.
- Create an ACI for the administrative user that targets the appropriate suffix. This ensures the administrator has access only to the suffix of the database link. For example:
aci: (targetattr = "*")(version 3.0; acl "Proxied authorization for database links"; allow (proxy) userdn = "ldap:///cn=proxy admin,cn=config";)
This ACI is like the ACI created on the remote server when configuring simple chaining.
Warning
Carefully examine access controls when enabling chaining to avoid giving access to restricted areas of the directory. For example, if a default proxy ACI is created on a branch, the users that connect through the database link will be able to see all entries below the branch. There may be cases when not all of the subtrees should be viewed by a user. To avoid a security hole, create an additional ACI to restrict access to the subtree. - Enable local ACI evaluation on all intermediate database links.To confirm that the proxy administrative ACI is used, enable evaluation of local ACIs on all intermediate database links involved in chaining. Add the following attribute to the
cn=
database_link,cn=chaining database,cn=plugins,cn=config
entry of each intermediate database link:nsCheckLocalACI: on
Setting this attribute toon
in thecn=default instance config,cn=chaining database,cn=plugins,cn=config
entry means that all new database link instances will have thensCheckLocalACI
attribute set toon
in theircn=
database_link,cn=chaining database,cn=plugins,cn=config
entry. - Create client ACIs on all intermediate database links and the final destination database.Because local ACI evaluation is enabled, the appropriate client application ACIs must be created on all intermediate database links, as well as the final destination database. To do this on the intermediate database links, first create a database that contains a suffix that represents a root suffix of the final destination suffix.For example, if a client request made to the
c=africa,ou=people,dc=example,dc=com
suffix is chained to a remote server, all intermediate database links need to contain a database associated with thedc=example,dc=com
suffix.Add any client ACIs to this superior suffix entry. For example:aci: (targetattr = "*")(version 3.0; acl "Client authentication for database link users"; allow (all) userdn = "ldap:///uid=* ,cn=config";)
This ACI allows client applications that have auid
in thecn=config
entry of Server 1 to perform any type of operation on the data below theou=people,dc=example,dc=com
suffix on server three.
2.4.4. Detecting Loops
An LDAP control included with Directory Server prevents loops. When first attempting to chain, the server sets this control to be the maximum number of hops, or chaining connections, allowed. Each subsequent server decrements the count. If a server receives a count of
0
, it determines that a loop has been detected and notifies the client application.
The number of hops allowed is defined using the
nsHopLimit
attribute. If not specified, the default value is 10
.
To use the control, add the following OID to the
nsTransmittedControl
attribute in the cn=config,cn=chaining database,cn=plugins,cn=config
entry:
nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12
If the control is not present in the configuration file of each database link, loop detection will not be implemented.
2.4.5. Summary of Cascading Chaining Configuration Attributes
The following describes the attributes used to configure intermediate database links in a cascading chain:
nsFarmServerURL
- URL of the server containing the next database link in the cascading chain.
nsTransmittedControls
- Enter the following OIDs to the database links involved in the cascading chain:
nsTransmittedControls: 2.16.840.1.113730.3.4.12 nsTransmittedControls: 1.3.6.1.4.1.1466.29539.12
aci
- This attribute must contain the following ACI:
aci: (targetattr = "*")(version 3.0; acl "Proxied authorization for database links"; allow (proxy) userdn = "ldap:///cn=proxy admin,cn=config";)
nsCheckLocalACI
- To enable evaluation of local ACIs on all database links involved in chaining, turn local ACI evaluation on, as follows:
nsCheckLocalACI: on
2.4.6. Cascading Chaining Configuration Example
To create a cascading chain involving three servers as in the diagram below, the chaining components must be configured on all three servers.

2.4.6.1. Configuring Server One
- Run
ldapmodify
and specify the configuration information for the database link, DBLink1, on Server 1:# ldapmodify
-a
-D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=DBLink1,cn=chaining database,cn=plugins,cn=config changetype: add objectclass: top objectclass: extensibleObject objectclass: nsBackendInstance nsslapd-suffix: c=africa,ou=people,dc=example,dc=com nsfarmserverurl: ldap://africa.example.com:389/ nsMultiplexorBindDN: cn=server1 proxy admin,cn=config nsMultiplexorCredentials: secret cn: DBLink1 nsCheckLocalACI:off dn: cn="c=africa,ou=people,dc=example,dc=com",cn=mapping tree,cn=config changetype: add objectclass: nsMappingTree nsslapd-state: backend nsslapd-backend: DBLink1 nsslapd-parent-suffix: ou=people,dc=example,dc=com cn: c=africa,ou=people,dc=example,dc=comThe first section creates the entry associated withDBLink1
. The second section creates a new suffix, allowing the server to direct requests made to the database link to the correct server. ThensCheckLocalACI
attribute does not need to be configured to check local ACIs, as this is only required on the database link,DBLink2
, on Server 2. - To implement loop detection, to specify the OID of the loop detection control in the
nsTransmittedControl
attribute stored incn=config,cn=chaining database,cn=plugins,cn=config
entry on Server 1.dn: cn=config,cn=chaining database,cn=plugins,cn=config changetype: modify add: nsTransmittedControl nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12
As thensTransmittedControl
attribute is usually configured by default with the loop detection control OID1.3.6.1.4.1.1466.29539.12
value, it is wise to check beforehand whether it already exists. If it does exist, this step is not necessary.
2.4.6.2. Configuring Server Two
- Create a proxy administrative user on Server 2. This administrative user will be used to allow Server 1 to bind and authenticate to Server 2. It is useful to choose a proxy administrative user name which is specific to Server 1, as it is the proxy administrative user which will allow server one to bind to Server 2. Create the proxy administrative user, as follows:
dn: cn=server1 proxy admin,cn=config objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: server1 proxy admin sn: server1 proxy admin userPassword: secret description: Entry for use by database links
Warning
Do not use the Directory Manager or Administrator ID user as the proxy administrative user on the remote server. This creates a security hole. - Configure the database link,
DBLink2
, on Server 2:dn: cn=DBLink2,cn=chaining database,cn=plugins,cn=config objectclass: top objectclass: extensibleObject objectclass: nsBackendInstance nsslapd-suffix: l=Zanzibar,c=africa,ou=people,dc=example,dc=com nsfarmserverurl: ldap://zanz.africa.example.com:389/ nsMultiplexorBindDN: cn=server2 proxy admin,cn=config nsMultiplexorCredentials: secret cn: DBLink2 nsCheckLocalACI:on dn: cn="l=Zanzibar,c=africa,ou=people,dc=example,dc=com",cn=mapping tree,cn=config objectclass: top objectclass: extensibleObject objectclass: nsMappingTree nsslapd-state: backend nsslapd-backend: DBLink2 nsslapd-parent-suffix: c=africa,ou=people,dc=example,dc=com cn: l=Zanzibar,c=africa,ou=people,dc=example,dc=com
Since database link DBLink2 is the intermediate database link in the cascading chaining configuration, set thensCheckLocalACI
attribute toon
to allow the server to check whether it should allow the client and proxy administrative user access to the database link. - The database link on Server 2 must be configured to transmit the proxy authorization control and the loop detection control. To implement the proxy authorization control and the loop detection control, specify both corresponding OIDs. Add the following information to the
cn=config,cn=chaining database,cn=plugins,cn=config
entry on Server 2:dn: cn=config,cn=chaining database,cn=plugins,cn=config changetype: modify add: nsTransmittedControl nsTransmittedControl: 2.16.840.1.113730.3.4.12 nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12
nsTransmittedControl: 2.16.840.1.113730.3.4.12
is the OID for the proxy authorization control.nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12
is the or the loop detection control.Check beforehand whether the loop detection control is already configured, and adapt the above command accordingly. - Configure the ACIs. On Server 2, ensure that a suffix exists above the
l=Zanzibar,c=africa,ou=people,dc=example,dc=com
suffix, so that the following actions are possible:- Add the database link suffix
- Add a local proxy authorization ACI to allow Server 1 to connect using the proxy authorization administrative user created on Server 2
- Add a local client ACI so the client operation succeeds on Server 2, and it can be forwarded to server three. This local ACI is needed because local ACI checking is turned on for the
DBLink2
database link.
Both ACIs will be placed on the database that contains thec=africa,ou=people,dc=example,dc=com
suffix.Note
To create these ACIs, the database corresponding to thec=africa,ou=people,dc=example,dc=com
suffix must already exist to hold the entry. This database needs to be associated with a suffix above the suffix specified in thensslapd-suffix
attribute of each database link. That is, the suffix on the final destination server should be a sub suffix of the suffix specified on the intermediate server.- Add the local proxy authorization ACI to the
c=africa,ou=people,dc=example,dc=com
entry:aci:(targetattr="*")(target="l=Zanzibar,c=africa,ou=people,dc=example,dc=com") (version 3.0; acl "Proxied authorization for database links"; allow (proxy) userdn = "ldap:///cn=server1 proxy admin,cn=config";)
- Then add the local client ACI that will allow the client operation to succeed on Server 2, given that ACI checking is turned on. This ACI is the same as the ACI created on the destination server to provide access to the
l=Zanzibar,c=africa,ou=people,dc=example,dc=com
branch. All users withinc=us,ou=people,dc=example,dc=com
may need to have update access to the entries inl=Zanzibar,c=africa,ou=people,dc=example,dc=com
on server three. Create the following ACI on Server 2 on thec=africa,ou=people,dc=example,dc=com
suffix to allow this:aci:(targetattr="*")(target="l=Zanzibar,c=africa,ou=people,dc=example,dc=com") (version 3.0; acl "Client authorization for database links"; allow (all) userdn = "ldap:///uid=*,c=us,ou=people,dc=example,dc=com";)
This ACI allows clients that have a UID inc=us,ou=people,dc=example,dc=com
on Server 1 to perform any type of operation on thel=Zanzibar,c=africa,ou=people,dc=example,dc=com
suffix tree on server three. If there are users on Server 2 under a different suffix that will require additional rights on server three, it may be necessary to add additional client ACIs on Server 2.
2.4.6.3. Configuring Server Three
- Create an administrative user on server three for Server 2 to use for proxy authorization:
dn: cn=server2 proxy admin,cn=config objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: server2 proxy admin sn: server2 proxy admin userPassword: secret description: Entry for use by database links
- Then add the same local proxy authorization ACI to server three as on Server 2. Add the following proxy authorization ACI to the
l=Zanzibar,ou=people,dc=example,dc=com
entry:aci: (targetattr = "*")(version 3.0; acl "Proxied authorization for database links"; allow (proxy) userdn = "ldap:///cn=server2 proxy admin,cn=config";)
This ACI gives the Server 2 proxy admin read-only access to the data contained on the remote server, server three, within thel=Zanzibar,ou=people,dc=example,dc=com
subtree only. - Create a local client ACI on the
l=Zanzibar,ou=people,dc=example,dc=com
subtree that corresponds to the original client application. Use the same ACI as the one created for the client on Server 2:aci: (targetattr ="*")(target="l=Zanzibar,c=africa,ou=people,dc=example,dc=com") (version 3.0; acl "Client authentication for database link users"; allow (all) userdn = "ldap:///uid=*,c=us,ou=people,dc=example,dc=com";)
The cascading chaining configuration is now set up. This cascading configuration allows a user to bind to Server 1 and modify information in the
l=Zanzibar,c=africa,ou=people,dc=example,dc=com
branch on server three. Depending on your security needs, it may be necessary to provide more detailed access control.