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, refer to the chapter "Designing the Directory Topology," in the Directory Server Deployment Guide. Section 15.7, “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.
  • 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 13.5.1, “Requiring Secure Binds”), then any chaining operations will fail unless they occur over a secure connection. Using a secure connection (SSL/TLS and Start TLS connections or SASL authentication) is recommended, anyway.

2.3.1.1. Creating a New Database Link Using the Console

  1. In the Directory Server Console, select the Configuration tab.
  2. Create a new suffix as described in Section 2.1.1, “Creating Suffixes”.
    Deselect the Create associated database automatically checkbox. 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.
  3. In the left pane, right-click the new suffix, and select New Database Link from the pop-up menu.
  4. 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.
  5. 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 SSL 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 SSL and certificate mapping is described in Section 14.2, “Using TLS/SSL”.

      NOTE

      When the database link and remote server are configured to communicate using SSL, this does not mean that the client application making the operation request must also communicate using SSL. 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 14.3.4.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 14.3.5.1, “Configuring SASL Identity Mapping from the Console”).
  6. 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/SSL.
      When using SSL/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 13.5.1, “Requiring Secure Binds”), then any chaining operations will fail unless they occur over a secure connection. Using a secure connection (SSL/TLS and Start TLS connections or SASL authentication) is recommended, anyway.
  7. In the Remote Server Information section, fill in the name and port number for the remote server.
    For any failover servers, fill in the hostname 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

  1. Use the ldapmodify command-line utility to create a new database link from the command line. The new instance must be located in the cn=chaining database,cn=plugins,cn=config entry. 
    /usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com
  2. Specify the configuration information for the database link: 
    dn: cn=examplelink,cn=chaining database,cn=plugins,cn=config 
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

If secure binds are required for simple password authentication (Section 13.5.1, “Requiring Secure Binds”), then any chaining operations will fail unless they occur over a secure connection. Using a secure connection (SSL/TLS and Start TLS connections or SASL authentication) is recommended, anyway.
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, refer to the Directory Server Configuration and Command-Line Tool 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:
  1. On the remote server:
  2. 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 via 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 12, Managing Access Control. For more information about the proxy authentication control, refer to the LDAP C-SDK documentation at http://www.mozilla.org/directory.

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://hostname:port.
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 SSL, 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

SSL has to be enabled on the local Directory Server and the remote Directory Server to be chained over SSL. For more information on enabling SSL, see Section 14.2.1, “Enabling TLS/SSL: Summary of Steps”.
When the database link and remote server are configured to communicate using SSL, this does not mean that the client application making the operation request must also communicate using SSL. 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 TLS/SSL port
  • Using Start TLS, which is a secure connection over a standard port

NOTE

If secure binds are required for simple password authentication (Section 13.5.1, “Requiring Secure Binds”), then any chaining operations will fail unless they occur over a secure connection. Using a secure connection (SSL/TLS and Start TLS connections or SASL authentication) is recommended, anyway.
Ultimately, there are two connection settings. The TLS/SSL option signifies that both of the servers are configured to run and accept connections over TLS/SSL, but there is no separate configuration attribute for enforcing TLS/SSL.
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 TLS/SSL 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/SSL 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 SSL 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 Section 14.2.10.2, “Mapping DNs to Certificates”.
  • 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 14.3, “Using SASL”.

NOTE

SASL connections can be established over standard connections or SSL/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: 
/usr/lib64/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com

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.2. 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/SSL connections.
nsBindMethod Sets the authentication method to use to authenticate (bind) to the remote server. The default, if this attribute is not given, is to authenticate using a simple bind, requiring the nsMultiplexorBindDN and nsMultiplexorCredentials attributes for the bind information.
null; this is a simple bind.
EXTERNAL (certificate-based); certificate mapping must be enabled for this.
DIGEST-MD5 (SASL); this, like a simple bind, requires the bind DN and password.
GSSAPI (SASL); this requires the keytab to be configured on the local server and SASL identity mapping on the remote server.
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
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.
  1. Run ldapmodify[2] to add a database link to Server A: 
    /usr/lib64/mozldap/ldapmodify -a -D "cn=directory manager" -w secret -p 389 -h server.example.com
  2. Specify the configuration information for the database link: 
    dn: cn=DBLink1,cn=chaining database,cn=plugins,cn=config 
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.
  3. 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.
  4. 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 table lists 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:

Table 2.3. Components Allowed to Chain

Component Name Description Permissions
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. 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. 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. 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 username 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. 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. 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. Read, write, 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 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. Read, write, 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 12.1.4, “ACI Limitations”.
2.3.2.1.1. Chaining Component Operations Using the Console
  1. In the Directory Server Console, select the Configuration tab.
  2. Expand Data in the left pane, and click Database Link Settings.
  3. Select the Settings tab in the right window.
  4. Click the Add button in the Components allowed to chain section.
  5. Select the component to chain from the list, and click OK.
  6. Restart the server in order for the change to take effect.
After allowing the component to chain, 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.1.2. Chaining Component Operations from the Command Line
  1. Specify components to include in chaining using the nsActiveChainingComponents attribute in the cn=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 Table 2.3, “Components Allowed to Chain” for a list of the components which can be chained.
  2. Restart the server for the change to take effect. 
    service dirsrv restart instance
  3. 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

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.
  • Simple paged results. This control breaks entry results into smaller pages, where the user specifies the page size. This is similar to VLV indexes for results, only without maintaining an index.
  • 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

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.
2.3.2.2.1. Chaining LDAP Controls Using the Console
  1. In the Directory Server Console, select the Configuration tab.
  2. Expand the Data folder in the left pane, and click Database Link Settings.
  3. Select the Settings tab in the right window.
  4. Click the Add button in the LDAP Controls forwarded by the database link section to add an LDAP control to the list.
  5. Select the OID of a control to add to the list, and click OK.
2.3.2.2.2. Chaining LDAP Controls from the Command Line
To chain controls, alter the controls that the database link forwards by changing the 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
In addition, if clients of the Directory Server create their own controls and their operations should be chained to remote servers, add the OID of the custom control to the nsTransmittedControls attribute.
The LDAP controls which can be chained and their OIDs are listed in the following table:

Table 2.4. 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
Simple paged results 1.2.840.113556.1.4.319
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

For more information about LDAP controls, refer to the LDAP C-SDK documentation at http://www.mozilla.org/directory.

2.3.3. Maintaining Database Links

All of the information for the database link for the connection to the remote server.
  1. In the Directory Server Console, select the Configuration tab.
  2. In the left pane, expand the Data folder, and select the database link under the suffix.
  3. In the right navigation pane, click the Authentication tab.
  4. Change the connection information.
    • The LDAP URL for the remote server.[2]
    • The bind DN and password used by the database link to bind to the remote server.

2.3.4. Configuring Database Link Defaults

Configuring the default settings for database links defines the settings used for cascading chaining (the number of hops allowed for a client request), the connection rules for the remote server, and how the server responds to client requests.
  1. Select the Configuration tab.
  2. Expand the Data folder in the left pane, and click Database Link Settings. Open the Default Creation Parameters tab.
  3. Fill in the new configuration parameters.

NOTE

Changes made to the default settings of a database link are not applied retroactively. Only the database links created after changes are made to the default settings will reflect the changes.

2.3.5. Deleting Database Links

To delete a database link, right-click the database link, and select Delete from the pop-up menu. Confirm the delete when prompted.
  1. In the Directory Server Console, select the Configuration tab.
  2. Under Data in the left navigation pane, open the suffix and select the database link to delete.
  3. Right-click the database link, and select Delete from the menu.

2.3.6. 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 via 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.
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 may refer to remote users.
  • ACIs must be located with any role definitions they use and with any users intended to have those roles.
  • ACIs that refer 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.

[2] Unlike the standard LDAP URL format, the URL of the remote server does not specify a suffix. It has the form ldap://hostname:port/.