2.3. Creating and Maintaining Database Links
Chaining means that a server contacts other servers on behalf of a client application and then returns the combined results. Chaining is implemented through a database link, which points to data stored remotely. When a client application requests data from a database link, the database link retrieves the data from the remote database and returns it to the client.
For more general information about chaining, see the chapter "Designing Directory Topology," in the Red Hat Directory Server Deployment Guide. Section 21.8, “Monitoring Database Link Activity” covers how to monitor database link activity.
2.3.1. Creating a New Database Link
The basic database link configuration requires the following information:
- Suffix information. A suffix is created in the directory tree that is managed by the database link, not a regular database. This suffix corresponds to the suffix on the remote server that contains the data.
- Bind credentials. When the database link binds to a remote server, it impersonates a user, and this specifies the DN and the credentials for each database link to use to bind with remote servers.
- LDAP URL. This supplies the LDAP URL of the remote server to which the database link connects. The URL consists of the protocol (ldap or ldaps), the host name or IP address (IPv4 or IPv6) for the server, and the port.
- List of failover servers. This supplies a list of alternative servers for the database link to contact in the event of a failure. This configuration item is optional.
Note
If secure binds are required for simple password authentication (Section 20.12.1, “Requiring Secure Binds”), then any chaining operations will fail unless they occur over a secure connection. Using a secure connection (TLS and STARTTLS connections or SASL authentication) is recommended, anyway.
2.3.1.1. Creating a New Database Link Using the Command Line
To create a new database link, use the
dsconf chaining link-create
command. For example:
# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining link-create --suffix="ou=Customers,dc=example,dc=com" --server-url="ldap://remote_server.example.com:389" --bind-mech="" --bind-dn="cn=proxy_user,cn=config" --bind-pw="password" "example_chain_name"
This creates a database link named
example_chain_name
for the ou=Customers,dc=example,dc=com
. The link refers to the server ldap://remote_server.example.com:389
and uses the specified bind DN and password to authenticate. Because the --bind-mech
is set empty, the link uses simple authentication.
Note
To grant the proxy_user the rights to access data, you must create the proxy ACI entry in the
dc=example,dc=com
suffix on remote server. How to do so, refer to the section Section 2.3.1.4, “Additional Information on Required Settings When Creating a Database Link”
To display additional settings you can set when you create the database link, see:
# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining link-create --help
For further details, see Section 2.3.1.4, “Additional Information on Required Settings When Creating a Database Link”.
2.3.1.2. Creating a New Database Link Using the Web Console
To create a new database link:
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Create a new suffix as described in Section 2.1.1, “Creating Suffixes”.
- Select the suffix, click Create Database Link., and select
- Fill the fields with the details about the connection to the remote server. For example:For further details, see Section 2.3.1.4, “Additional Information on Required Settings When Creating a Database Link”.
- Click.
2.3.1.3. Managing the Default Configuration for New Database Links
With the
dsconf chaining
command you can manage the default configuration of database links.
To display the current default values, see:
# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining config-get-def
To change new database links configuration, use
dsconf chaining config-set-def
command. For example, to set response-delay
parameter to 30
, run:
# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining config-set-def --response-delay 30
The example command sets the default response timeout for all chaining connections. You can overwrite the response timeout for a specific chaining link if you use
dsconf instance chaining link-set
command.
To see the list of all parameters you can set, run:
# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining config-set-def --help
2.3.1.4. Additional Information on Required Settings When Creating a Database Link
Suffix Information
The suffix defines the suffix that is managed by the database link.
Bind Credentials
For a request from a client application to be chained to a remote server, special bind credentials can be supplied for the client application. This gives the remote server the proxied authorization rights needed to chain operations. Without bind credentials, the database link binds to the remote server as
anonymous
.
For example, a client application sends a request to Server A. Server A contains a database link that chains the request to a database on Server B.

The database link on Server A binds to Server B using a special user and password:

Server B must contain a user entry and set the proxy authentication rights for this user. To set the proxy authorization correctly, set the proxy ACI as any other ACI.
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 using 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.
For more information on ACIs, see Chapter 18, Managing Access Control.
Note
When a database link is used by a client application to create or modify entries, the attributes
creatorsName
and modifiersName
do not reflect the real creator or modifier of the entries. These attributes contain the name of the administrative user granted proxied authorization rights on the remote data server.
Providing bind credentials involves the following steps on the remote server:
- Create an administrative user, such as
cn=proxy_user,cn=config
, for the database link. For information on adding entries, see Chapter 3, Managing Directory Entries. - Provide proxy access rights for the administrative user created in the previous step on the subtree chained to by the database link. For more information on configuring ACIs, see Chapter 18, Managing Access ControlFor example, the following ACI grants read-only access to the
cn=proxy_admin,cn=config
user to access data contained on the remote server only within the subtree where the ACI is set.aci: (targetattr = "*")(version 3.0; acl "Proxied authorization for database links"; allow (proxy) userdn = "ldap:///cn=proxy_admin ,cn=config";)
Note
When a user binds to a database link, the user's identity is sent to the remote server. Access controls are always evaluated on the remote server. For the user to modify or write data successfully to the remote server, set up the correct access controls on the remote server. For more information about how access controls are evaluated in the context of chained operations, see Section 2.3.3, “Database Links and Access Control Evaluation”.
LDAP URL
On the server containing the database link, identify the remote server that the database link connects with using an LDAP URL. Unlike the standard LDAP URL format, the URL of the remote server does not specify a suffix. It takes the form
ldap://host_name:port
.
For the database link to connect to the remote server using LDAP over TLS, the LDAP URL of the remote server uses the protocol LDAPS instead of LDAP in the URL and points to the secure port of the server. For example
ldaps://africa.example.com:636/
Note
TLS has to be enabled on the local Directory Server and the remote Directory Server to be chained over TLS. For more information on enabling TLS, see Section 9.4, “Enabling TLS”.
When the database link and remote server are configured to communicate using TLS, this does not mean that the client application making the operation request must also communicate using TLS. The client can bind using a normal port.
Bind Mechanisms
The local server can connect to the remote server using several different connection types and authentication mechanisms.
There are three ways that the local server can connect to the remote server:
- Over the standard LDAP port
- Over a dedicated LDAPS port
- Using STARTTLS, which is a secure connection over a standard port
Note
If secure binds are required for simple password authentication (Section 20.12.1, “Requiring Secure Binds”), then any chaining operations will fail unless they occur over a secure connection. Using a secure connection (TLS and STARTTLS connections or SASL authentication) is recommended, anyway.
There are four different methods which the local server can use to authenticate to the farm server.
- empty: If there is no bind mechanism set, then the server performs simple authentication and requires a bind DN and password.
- EXTERNAL: This uses an TLS certificate to authenticate the farm server to the remote server. Either the farm server URL must be set to the secure URL (
ldaps
) or thensUseStartTLS
attribute must be set toon
.Additionally, the remote server must be configured to map the farm server's certificate to its bind identity, as described in the certmap.conf section in the Red Hat Directory Server Configuration, Command, and File Reference. - DIGEST-MD5: This uses SASL authentication with DIGEST-MD5 encryption. As with simple authentication, this requires the
nsMultiplexorBindDN
andnsMultiplexorCredentials
attributes to give the bind information. - GSSAPI: This uses Kerberos-based authentication over SASL.The farm server must be configured with a Kerberos keytab, and the remote server must have a defined SASL mapping for the farm server's bind identity. Setting up Kerberos keytabs and SASL mappings is described in Section 9.10, “Setting up SASL Identity Mapping”.
Note
SASL connections can be established over standard connections or TLS connections.
Note
If SASL is used, then the local server must also be configured to chain the SASL and password policy components. Add the components for the database link configuration, as described in Section 2.3.2, “Configuring the Chaining Policy”.
2.3.2. Configuring the Chaining Policy
These procedures describe configuring how Directory Server chains requests made by client applications to Directory Servers that contain database links. This chaining policy applies to all database links created on Directory Server.
2.3.2.1. Chaining Component Operations
A component is any functional unit in the server that uses internal operations. For example, plug-ins are considered to be components, as are functions in the front-end. However, a plug-in may actually be comprised of multiple components (for example, the ACI plug-in).
Some components send internal LDAP requests to the server, expecting to access local data only. For such components, control the chaining policy so that the components can complete their operations successfully. One example is the certificate verification function. Chaining the LDAP request made by the function to check certificates implies that the remote server is trusted. If the remote server is not trusted, then there is a security problem.
By default, all internal operations are not chained and no components are allowed to chain, although this can be overridden.
Additionally, an ACI must be created on the remote server to allow the specified plug-in to perform its operations on the remote server. The ACI must exist in the suffix assigned to the database link.
The following lists the component names, the potential side-effects of allowing them to chain internal operations, and the permissions they need in the ACI on the remote server:
- ACI plug-in
- This plug-in implements access control. Operations used to retrieve and update ACI attributes are not chained because it is not safe to mix local and remote ACI attributes. However, requests used to retrieve user entries may be chained by setting the chaining components attribute:
nsActiveChainingComponents: cn=ACI Plugin,cn=plugins,cn=config
Permissions: Read, search, and compare - Resource limit component
- This component sets server limits depending on the user bind DN. Resource limits can be applied on remote users if the resource limitation component is allowed to chain. To chain resource limit component operations, add the chaining component attribute:
nsActiveChainingComponents: cn=resource limits,cn=components,cn=config
Permissions: Read, search, and compare - Certificate-based authentication checking component
- This component is used when the external bind method is used. It retrieves the user certificate from the database on the remote server. Allowing this component to chain means certificate-based authentication can work with a database link. To chain this component's operations, add the chaining component attribute:
nsActiveChainingComponents: cn=certificate-based authentication,cn=components,cn=config
Permissions: Read, search, and compare - Password policy component
- This component is used to allow SASL binds to the remote server. Some forms of SASL authentication require authenticating with a user name and password. Enabling the password policy allows the server to verify and implement the specific authentication method requested and to apply the appropriate password policies. To chain this component's operations, add the chaining component attribute:
nsActiveChainingComponents: cn=password policy,cn=components,cn=config
Permissions: Read, search, and compare - SASL component
- This component is used to allow SASL binds to the remote server. To chain this component's operations, add the chaining component attribute:
nsActiveChainingComponents: cn=password policy,cn=components,cn=config
Permissions: Read, search, and compare - Referential Integrity plug-in
- This plug-in ensures that updates made to attributes containing DNs are propagated to all entries that contain pointers to the attribute. For example, when an entry that is a member of a group is deleted, the entry is automatically removed from the group. Using this plug-in with chaining helps simplify the management of static groups when the group members are remote to the static group definition. To chain this component's operations, add the chaining component attribute:
nsActiveChainingComponents: cn=referential integrity postoperation,cn=plugins,cn=config
Permissions: Read, search, and compare - Attribute Uniqueness plug-in
- This plug-in checks that all the values for a specified attribute are unique (no duplicates). If this plug-in is chained, it confirms that attribute values are unique even on attributes changed through a database link. To chain this component's operations, add the chaining component attribute:
nsActiveChainingComponents: cn=attribute uniqueness,cn=plugins,cn=config
Permissions: Read, search, and compare - Roles component
- This component chains the roles and roles assignments for the entries in a database. Chaining this component maintains the roles even on chained databases. To chain this component's operations, add the chaining component attribute:
nsActiveChainingComponents: cn=roles,cn=components,cn=config
Permissions: Read, search, and compare
Note
The following components cannot be chained:
- Roles plug-in
- Password policy component
- Replication plug-ins
- Referential Integrity plug-in
When enabling the Referential Integrity plug-in on servers issuing chaining requests, be sure to analyze performance, resource, and time needs as well as integrity needs. Integrity checks can be time-consuming and draining on memory and CPU. For further information on the limitations surrounding ACIs and chaining, see Section 18.5, “Limitations of ACIs”.
2.3.2.1.1. Chaining Component Operations Using the Command Line
To add a component allowed to chain:
- Specify the components to include in chaining. For example, to configure that the referential integrity component can chain operations:
# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining config-set \ --add-comp="cn=referential integrity postoperation,cn=components,cn=config"
See Section 2.3.2.1, “Chaining Component Operations” for a list of the components which can be chained. - Restart the instance:
# dsctl instance_name restart
- Create an ACI in the suffix on the remote server to which the operation will be chained. For example, to create an ACI for the Referential Integrity plug-in:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h remoteserver.example.com -x dn: ou=People,dc=example,dc=com changetype: modify add: aci aci: (targetattr = "*")(target="ldap:///ou=customers,l=us,dc=example,dc=com") (version 3.0; acl "RefInt Access for chaining"; allow (read,write,search,compare) userdn = "ldap:///cn=referential integrity postoperation,cn=plugins,cn=config";)
2.3.2.1.2. Chaining Component Operations Using the Web Console
To add a component allowed to chain:
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open thetab.
- In the navigation on the left, select theentry.
- Click the Components to Chain field.button below the
- Select the component, and click.
- Create an ACI in the suffix on the remote server to which the operation will be chained. For example, to create an ACI for the Referential Integrity plug-in:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h remoteserver.example.com -x dn: ou=People,dc=example,dc=com changetype: modify add: aci aci: (targetattr = "*")(target="ldap:///ou=customers,l=us,dc=example,dc=com") (version 3.0; acl "RefInt Access for chaining"; allow (read,write,search,compare) userdn = "ldap:///cn=referential integrity postoperation,cn=plugins,cn=config";)
2.3.2.2. Chaining LDAP Controls
It is possible to not chain operation requests made by LDAP controls. By default, requests made by the following controls are forwarded to the remote server by the database link:
- Virtual List View (VLV). This control provides lists of parts of entries rather than returning all entry information.
- Server-side sorting. This control sorts entries according to their attribute values, usually using a specific matching rule.
- Dereferencing. This control pulls specified attribute information from the referenced entry and returns this information with the rest of the search results.
- Managed DSA. This controls returns smart referrals as entries, rather than following the referral, so the smart referral itself can be changed or deleted.
- Loop detection. This control keeps track of the number of times the server chains with another server. When the count reaches the configured number, a loop is detected, and the client application is notified. For more information about using this control, see Section 2.4.3, “Detecting Loops”.
Note
Server-side sorting and VLV controls are supported only when a client application request is made to a single database. Database links cannot support these controls when a client application makes a request to multiple databases.
The LDAP controls which can be chained and their OIDs are listed in the following table:
Control Name | OID |
---|---|
Virtual list view (VLV) | 2.16.840.1.113730.3.4.9 |
Server-side sorting | 1.2.840.113556.1.4.473 |
Managed DSA | 2.16.840.1.113730.3.4.2 |
Loop detection | 1.3.6.1.4.1.1466.29539.12 |
Dereferencing searches | 1.3.6.1.4.1.4203.666.5.16 |
2.3.2.2.1. Chaining LDAP Controls Using the Command Line
To chain LDAP controls, use the
dsconf chaining config-set --add-control
command. For example, to forward the virtual list view control:
# dsconf -D "cn=Directory Manager" ldap://server.example.com chaining \ config-set --add-control="2.16.840.1.113730.3.4.9"
If clients of Directory Server create their own controls and their operations should be chained to remote servers, add the object identifier (OID) of the custom control.
For a list of LDAP controls that can be chained and their OIDs, see Table 2.1, “LDAP Controls and Their OIDs”.
2.3.2.2.2. Chaining LDAP Controls Using the Web Console
To chain LDAP controls using the web console:
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu.
- Select theentry.
- Click the Forwarded LDAP Controls field.button below the
- Select the LDAP control and click.If clients of Directory Server create their own controls and their operations should be chained to remote servers, add the object identifier (OID) of the custom control.For a list of LDAP controls that can be chained and their OIDs, see Table 2.1, “LDAP Controls and Their OIDs”.
- Click.
2.3.3. Database Links and Access Control Evaluation
When a user binds to a server containing a database link, the database link sends the user's identity to the remote server. Access controls are always evaluated on the remote server. Every LDAP operation evaluated on the remote server uses the original identity of the client application passed using the proxied authorization control. Operations succeed on the remote server only if the user has the correct access controls on the subtree contained on the remote server. This requires adding the usual access controls to the remote server with a few restrictions:
- Not all types of access control can be used.For example, role-based or filter-based ACIs need access to the user entry. Because the data are accessed through database links, only the data in the proxy control can be verified. Consider designing the directory in a way that ensures the user entry is located in the same database as the user's data.
- All access controls based on the IP address or DNS domain of the client may not work since the original domain of the client is lost during chaining. The remote server views the client application as being at the same IP address and in the same DNS domain as the database link.
Note
Directory Server supports both IPv4 and IPv6 IP addresses.
The following restrictions apply to the ACIs used with database links:
- ACIs must be located with any groups they use. If the groups are dynamic, all users in the group must be located with the ACI and the group. If the group is static, it links to remote users.
- ACIs must be located with any role definitions they use and with any users intended to have those roles.
- ACIs that link to values of a user's entry (for example,
userattr
subject rules) will work if the user is remote.
Though access controls are always evaluated on the remote server, they can also be evaluated on both the server containing the database link and the remote server. This poses several limitations:
- During access control evaluation, contents of user entries are not necessarily available (for example, if the access control is evaluated on the server containing the database link and the entry is located on a remote server).For performance reasons, clients cannot do remote inquiries and evaluate access controls.
- The database link does not necessarily have access to the entries being modified by the client application.When performing a modify operation, the database link does not have access to the full entry stored on the remote server. If performing a delete operation, the database link is only aware of the entry's DN. If an access control specifies a particular attribute, then a delete operation will fail when being conducted through a database link.
Note
By default, access controls set on the server containing the database link are not evaluated. To override this default, use the
nsCheckLocalACI
attribute in the cn=
database_link, cn=chaining database,cn=plugins,cn=config
entry. However, evaluating access controls on the server containing the database link is not recommended except with cascading chaining.