2.3. Creating and Maintaining Database Links
2.3.1. Creating a New Database Link
- 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
2.3.1.1. Creating a New Database Link Using the Console
- In the Directory Server Console, select the Configuration tab.
- Create a new suffix as described in Section 2.1.1, “Creating Suffixes”.Deselect the Create associated database automatically check box. It is simpler to configure a database link on a suffix without a database associated with it because having both a database and database link requires custom distribution functions to distribute directory data.
- In the left pane, right-click the new suffix, and select New Database Link from the pop-up menu.
- Fill in the database link name. The name can be a combination of alphanumeric characters, dashes (
-
), and underscores (_
). No other characters, like spaces, are allowed. - Set the radio button for the appropriate method for authentication.There are four authentication methods:
- Simple means that the server connects over the standard port with no encryption. The only required information is the bind DN and password for the user as whom the server connects to the remote server.
- Server TLS/SSL Certificate uses the local server's TLS certificate to authenticate to the remote server. A certificate must be installed on the local server for certificate-based authentication, and the remote server must have certificate mapping configured so that it can map the subject DN in the local server's certificate to the corresponding user entry.Configuring TLS and certificate mapping is described in Section 9.4, “Enabling TLS”.
Note
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. - SASL/DIGEST-MD5 requires only the bind DN and password to authenticate.
- SASL/GSSAPI requires the local server to have a Kerberos keytab (as in Section 9.10.2.2, “About the KDC Server and Keytabs”), and the remote server to have a SASL mapping to map the local server's principal to the real user entry (as in Section 9.9.3.1, “Configuring SASL Identity Mapping from the Console”).
- In the Remote Server Information section, select the connection type for the local server to use to connect to the remote server. There are three options:
- Use LDAP. This sets a standard, unencrypted connection.
- Use TLS/SSL. This uses a secure connection over the server's secure LDAPS port, such as
636
. This setting is required to use TLS/TLS.When using TLS, make sure that the remote server's port number is set to its secure port. - Use Start TLS. This uses Start TLS to establish a secure connection over the server's standard port.
Note
If secure binds are required for simple password authentication (Section 19.11.1, “Requiring Secure Binds”), then any chaining operations will fail unless they occur over a secure connection. Using a secure connection (TLS and Start TLS connections or SASL authentication) is recommended, anyway. - In the Remote Server Information section, fill in the name (host name, IPv4 address, or IPv6 address) and port number for the remote server.For any failover servers, fill in the host name and port number, and click thebutton. A failover server is a backup server, so that if the primary remote server fails, the database link contacts the first server in the failover servers list and cycles through the list until a server is accessed.

Note
2.3.1.2. Creating a Database Link from the Command Line
- Use the
ldapmodify
command-line utility to create a new database link. The new instance must be located in thecn=chaining database,cn=plugins,cn=config
entry.# ldapmodify
-a
-D "cn=Directory Manager" -W -p 389 -h server.example.com -x - Specify the configuration information for the database link:
dn: cn=examplelink,cn=chaining database,cn=plugins,cn=config changetype: add objectclass: top objectclass: extensibleObject objectclass: nsBackendInstance nsslapd-suffix: ou=people,dc=example,dc=com suffix being chained nsfarmserverurl: ldap://people.example.com:389/ LDAP URL to remote server nsMultiplexorBindDN: cn=proxy admin,cn=config bind DN nsMultiplexorCredentials: secret bind password cn: examplelink
Note
cn=default instance config,cn=chaining database,cn=plugins,cn=config
entry. These configuration attributes apply to all database links at creation time. Changes to the default configuration only affect new database links. The default configuration attributes on existing database links cannot be changed.
cn=
database_link, cn=chaining database,cn=plugins,cn=config
. For more information about configuration attributes, see the Red Hat Directory Server Configuration, Command, and File Reference.
2.3.1.2.1. Providing Suffix Information
nsslapd-suffix
attribute to define the suffix managed by the database link. For example, for the database link to point to the people information for a remote site of the company, enter the following suffix information:
nsslapd-suffix: l=Zanzibar,ou=people,dc=example,dc=com
cn=
database_link, cn=chaining database,cn=plugins,cn=config
entry.
Note
nsslapd-nsslapd-suffix
attribute are applied only after the server containing the database link is restarted.
2.3.1.2.2. Providing Bind Credentials
anonymous
.
- On the remote server:
- Create an administrative user 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 step 1 on the subtree chained to by the database link.For more information on configuring ACIs, see Chapter 18, Managing Access Control
- On the server containing the database link, use
ldapmodify
to provide a user DN for the database link in thensMultiplexorBindDN
attribute of thecn=
database_link,cn=chaining database,cn=plugins,cn=config
entry.Warning
ThensMultiplexorBindDN
cannot be that of the Directory Manager.Useldapmodify
to provide a user password for the database link in thensMultiplexorCredentials
attribute of thecn=
database_link,cn=chaining database,cn=plugins,cn=config
entry.

nsMultiplexorBindDN
attribute and a user password as defined in the nsMultiplexorCredentials
attribute. In this example, Server A uses the following bind credentials:
nsMultiplexorBindDN: cn=proxy admin,cn=config nsMultiplexorCredentials: secret

nsMultiplexorBindDN
, and set the proxy authentication rights for this user. To set the proxy authorization correctly, set the proxy ACI as any other ACI.
Warning
Note
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.
2.3.1.2.3. Providing an LDAP URL
ldap://
server:port, where the server can be a host name, IPv4 address, or IPv6 address.
nsFarmServerURL
attribute is set in the cn=
database_link, cn=chaining database,cn=plugins,cn=config
entry of the configuration file.
nsFarmServerURL: ldap://example.com:389/
Note
nsFarmServerURL: ldaps://africa.example.com:636/
Note
2.3.1.2.4. Providing a List of Failover Servers
nsFarmServerURL
attribute, separated by spaces.
nsFarmServerURL: ldap://example.com us.example.com:389 africa.example.com:1000/
example.com
on the standard port to service an operation. If it does not respond, the database link then contacts the server us.example.com
on port 389
. If this server fails, it then contacts africa.example.com
on port 1000
.
2.3.1.2.5. Using Different Bind Mechanisms
- Over the standard LDAP port
- Over a dedicated LDAPS port
- Using Start TLS, which is a secure connection over a standard port
Note
nsUseStartTLS
attribute. When this is on
, then the server initiates a Start TLS connect over the standard port. If this is off
, then the server either uses the LDAP port or the LDAPS port, depending on what is configured for the remote server in the nsFarmServerURL
attribute.
nsUseStartTLS: on
nsUseStartTLS: off
- empty. If there is no bind mechanism set, then the server performs simple authentication and requires the
nsMultiplexorBindDN
andnsMultiplexorCredentials
attributes to give the bind information. - 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.9, “Setting up SASL Identity Mapping”.
Note
nsBindMechanism: EXTERNAL
Note
ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=config,cn=chaining database,cn=plugins,cn=config changetype: modify add: nsActiveChainingComponents nsActiveChainingComponents: cn=password policy,cn=components,cn=config - add: nsActiveChainingComponents nsActiveChainingComponents: cn=sasl,cn=components,cn=config ^D
2.3.1.2.6. Summary of Database Link Configuration Attributes
cn=
database_link, cn=chaining database,cn=plugins,cn=config
entry.
Table 2.1. Database Link Configuration Attributes
Attributes | Value |
---|---|
nsTransmittedControls [†] | Gives the OID of LDAP controls forwarded by the database link to the remote data server. |
nsslapd-suffix | The suffix managed by the database link. Any changes to this attribute after the entry has been created take effect only after the server containing the database link is restarted. |
nsslapd-timelimit | Default search time limit for the database link, given in seconds. The default value is 3600 seconds. |
nsslapd-sizelimit | Default size limit for the database link, given in number of entries. The default value is 2000 entries. |
nsFarmServerURL | Gives the LDAP URL of the remote server (or farm server) that contains the data. This attribute can contain optional servers for failover, separated by spaces. If using cascading chaining, this URL can point to another database link. |
nsUseStartTLS | Sets whether to use Start TLS to establish a secure connection over a standard port. The default is off , which is used for both simple (standard) connections and TLS connections. |
nsBindMechanism | Sets the authentication method to use to authenticate (bind) to the remote server. If you set an empty value, simple bind is used (LDAP_SASL_SIMPLE). |
nsMultiplexorBindDN | DN of the administrative entry used to communicate with the remote server. The term multiplexor in the name of the attribute means the server which contains the database link and communicates with the remote server. This bind DN cannot be the Directory Manager. If this attribute is not specified, the database link binds as anonymous . |
nsMultiplexorCredentials | Password for the administrative user, given in plain text. If no password is provided, it means that users can bind as anonymous . The password is encrypted in the configuration file. |
nsCheckLocalACI | Reserved for advanced use only. Controls whether ACIs are evaluated on the database link as well as the remote data server. Takes the values on or off . Changes to this attribute occur only after the server has been restarted. The default value is off . |
nsProxiedAuthorization | Reserved for advanced use only. Disables proxied authorization. A value of off means proxied authorization is disabled. The default value is on . |
nsActiveChainingComponents[†] | Lists the components using chaining. A component is any functional unit in the server. The value of this attribute in the database link instance overrides the value in the global configuration attribute. To disable chaining on a particular database instance, use the value none . The default policy is not to allow chaining. For more information, see Section 2.3.2.1, “Chaining Component Operations”. |
nsReferralOnScopedSearch | Controls whether referrals are returned by scoped searches. This attribute is for optimizing the directory because returning referrals in response to scoped searches is more efficient. Takes the values on or off . The default value is off . |
nsHopLimit | Maximum number of times a request can be forwarded from one database link to another. The default value is 10 . |
[†]
Can be both a global and instance attribute. This global configuration attribute is located in the cn=config,cn=chaining database,cn=plugins,cn=config entry. The global attributes are dynamic, meaning any changes made to them automatically take effect on all instances of the database link within the directory.
|
2.3.1.2.7. Database Link Configuration Example
us.example.com
domain contains the subtree l=Walla Walla,ou=people,dc=example,dc=com
on a database and that operation requests for the l=Zanzibar,ou=people,dc=example,dc=com
subtree should be chained to a different server in the africa.example.com
domain.

- Run
ldapmodify
to add a database link to Server A:# ldapmodify
-a
-D "cn=Directory Manager" -W -p 389 -h server.example.com -x - Specify the configuration information for the database link:
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=proxy admin,cn=config nsMultiplexorCredentials: secret cn: DBLink1 dn: cn="c=africa,ou=people,dc=example,dc=com",cn=mapping tree,cn=config objectclass: top objectclass: extensibleObject 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=com
In the first entry, thensslapd-suffix
attribute contains the suffix on Server B to which to chain from Server A. ThensFarmServerURL
attribute contains the LDAP URL of Server B.The second entry creates a new suffix, allowing the server to route requests made to the new database link. Thecn
attribute contains the same suffix specified in thensslapd-suffix
attribute of the database link. Thensslapd-backend
attribute contains the name of the database link. Thensslapd-parent-suffix
attribute specifies the parent of this new suffix,ou=people,dc=example,dc=com
. - Create an administrative user on Server B, as follows:
dn: cn=proxy admin,cn=config objectclass: person objectclass: organizationalPerson objectclass: inetOrgPerson cn: proxy admin sn: proxy admin userPassword: secret description: Entry for use by database links
Warning
Do not use the Directory Manager user as the proxy administrative user on the remote server. This creates a security hole. - Add the following proxy authorization ACI to the
l=Zanzibar,ou=people,dc=example,dc=com
entry on Server B:aci: (targetattr = "*")(version 3.0; acl "Proxied authorization for database links"; allow (proxy) userdn = "ldap:///cn=proxy admin,cn=config";)
This ACI gives the proxy admin user read-only access to the data contained on the remote server within thel=Zanzibar,ou=people,dc=example,dc=com
subtree only.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.6, “Database Links and Access Control Evaluation”.
2.3.2. Configuring the Chaining Policy
2.3.2.1. Chaining Component Operations
- 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
- Roles plug-in
- Password policy component
- Replication plug-ins
- Referential Integrity plug-in
2.3.2.1.1. Chaining Component Operations Using the Console
- In the Directory Server Console, select the Configuration tab.
- Expand Data in the left pane, and click Database Link Settings.
- Select the Settings tab in the right window.
- Click the Components allowed to chain section.button in the
- Select the component to chain from the list, and click.
- Restart the server in order for the change to take effect.
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 from the Command Line
- Specify components to include in chaining using the
nsActiveChainingComponents
attribute in thecn=config,cn=chaining database,cn=plugins,cn=config
entry of the configuration file.For example, to allow the referential integrity component to chain operations, add the following to the database link configuration file:nsActiveChainingComponents: 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 server for the change to take effect.
# systemctl restart dirsrv@instance_name
- Create an ACI in the suffix on the remote server to which the operation will be chained. For example, this creates an ACI for the Referential Integrity plug-in:
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
- 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 tracks back over references in entry attributes in a search and pulls specified attribute information from the referenced entry and returns it 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.4, “Detecting Loops”.
Note
2.3.2.2.1. Chaining LDAP Controls Using the Console
- In the Directory Server Console, select the Configuration tab.
- Expand the Data folder in the left pane, and click Database Link Settings.
- Select the Settings tab in the right window.
- Click the LDAP Controls forwarded by the database link section to add an LDAP control to the list.button in the
- Select the OID of a control to add to the list, and click.
2.3.2.2.2. Chaining LDAP Controls from the Command Line
nsTransmittedControls
attribute of the cn=config,cn=chaining database,cn=plugins,cn=config
entry. For example, to forward the virtual list view control, add the following to the database link entry in the configuration file:
nsTransmittedControls: 2.16.840.1.113730.3.4.9
nsTransmittedControls
attribute.
Table 2.2. LDAP Controls and Their OIDs
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.3. Maintaining Database Links
- In the Directory Server Console, select the Configuration tab.
- In the left pane, expand the Data folder, and select the database link under the suffix.
- In the right navigation pane, click the Authentication tab.
- Change the connection information.
- The LDAP URL for the remote server.[]
- The bind DN and password used by the database link to bind to the remote server.
2.3.4. Configuring Database Link Defaults
- Select the Configuration tab.
- Expand the Data folder in the left pane, and click Database Link Settings. Open the Default Creation Parameters tab.
- Fill in the new configuration parameters.
Note
2.3.5. Deleting Database Links
- In the Directory Server Console, select the Configuration tab.
- Under Data in the left navigation pane, open the suffix and select the database link to delete.
- Right-click the database link, and select Delete from the menu.
2.3.6. Database Links and Access Control Evaluation
- 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.
- 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.
- 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
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.
ldap://
server:port/
, where server can be the host name, IPv4 address, or IPv6 address.