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 the Directory Topology," in the Red Hat Directory Server Deployment Guide. Section 20.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 four piece of 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 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.

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 the Add button. 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.

The new database link is listed under the suffix, in place of the database.

Note

The Console provides a checklist of information that needs to be present on the remote server for the database link to bind successfully. To view this checklist, click the new database link, and click the Authentication tab. The checklist is in the Remote server checklist box.

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 the cn=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

Default configuration attributes are contained in the 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.

Each database link contains its own specific configuration information, which is stored with the database link entry itself, 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

Use the 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

The suffix information is stored in the cn=database_link, cn=chaining database,cn=plugins,cn=config entry.

Note

After creating the database link, any alterations to the nsslapd-nsslapd-suffix attribute are applied only after the server containing the database link is restarted.

2.3.1.2.2. Providing 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.

Providing bind credentials involves the following steps:

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 the nsMultiplexorBindDN attribute of the cn=database_link,cn=chaining database,cn=plugins,cn=config entry.
Warning
The nsMultiplexorBindDN cannot be that of the Directory Manager.
Use ldapmodify to provide a user password for the database link in the nsMultiplexorCredentials attribute of the cn=database_link,cn=chaining database,cn=plugins,cn=config entry.

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 as defined in the 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

Server B must contain a user entry corresponding to the 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

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.

2.3.1.2.3. Providing an 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://server:port, where the server can be a host name, IPv4 address, or IPv6 address.

The URL of the remote server using the 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

Do not forget to use the trailing slash (/) at the end of the URL.

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:

nsFarmServerURL: 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.

2.3.1.2.4. Providing a List of Failover Servers

There can be additional LDAP URLs for servers included to use in the case of failure. Add alternate servers to the nsFarmServerURL attribute, separated by spaces.

nsFarmServerURL: ldap://example.com us.example.com:389 africa.example.com:1000/

In this sample LDAP URL, the database link first contacts the server 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

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 Start TLS, which is a secure connection over a standard port

Note

Ultimately, there are two connection settings. The TLS option signifies that both of the servers are configured to run and accept connections over TLS, but there is no separate configuration attribute for enforcing TLS.

The connection type is identified in the 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.

For example, to use Start TLS:

nsUseStartTLS: on

For example, to use a standard connection or TLS connection:

nsUseStartTLS: off

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 the nsMultiplexorBindDN and nsMultiplexorCredentials 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 the nsUseStartTLS attribute must be set to on.
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 and nsMultiplexorCredentials 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

SASL connections can be established over standard connections or TLS connections.

For example:

nsBindMechanism: EXTERNAL

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”. For example:

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

The following table lists the attributes available for configuring a database link. Some of these attributes were discussed in the earlier sections. All instance attributes are defined in the cn=database_link, cn=chaining database,cn=plugins,cn=config entry.

Values defined for a specific database link take precedence over the global attribute value.

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.

For further details, see the parameter descriptions in the Red Hat Directory Server Configuration, Command, and File Reference.

2.3.1.2.7. Database Link Configuration Example

Suppose a server within the 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, the nsslapd-suffix attribute contains the suffix on Server B to which to chain from Server A. The nsFarmServerURL 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. The cn attribute contains the same suffix specified in the nsslapd-suffix attribute of the database link. The nsslapd-backend attribute contains the name of the database link. The nsslapd-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 the l=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

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