Language:
Format:

Language:
Format:

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 the Database menu.
Create a new suffix as described in Section 2.1.1, “Creating Suffixes”.
Select the suffix, click Suffix Tasks, and select Create Database Link.
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 Create Database Link.

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 Control
For 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

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