Chapter 3 Creating Your Directory Tree

The directory tree consists of all of the entries in your server, as identified by their distinguished name (DN). The hierarchical nature of the DN creates branches and leaves which structure the data in the tree. In order to manage the directory tree, it is defined administratively in terms of suffixes, subsuffixes, and chained suffixes. Directory Server Console provides the controls for creating and administering all of these elements, or you may use command-line tools.

Creating Suffixes

You can create both root suffixes and subsuffixes using either Directory Server Console or the command line.

Creating a New Root Suffix Using the Console

On the top-level Configuration tab of Directory Server Console, right-click on the Data node, and select New Suffix from the pop-up menu.

Alternatively, you may select the Data node and choose New Suffix from the Object menu.

The "New Suffix" dialog box is displayed.

Enter a unique suffix name in the Suffix DN field. The name must use the distinguished name format consisting of one or more attribute-value pairs separated by commas.

By convention, root suffixes use domain-component (dc) naming attributes. For example, you might enter dc=example,dc=org for a new suffix DN.



Note	Suffix names contain attribute-value pairs in the DN format, but are treated as a single string. Therefore, all spaces are significant and are part of the suffix name.

By default, the location of database files for this suffix is chosen automatically by the server. Also by default, the suffix will maintain only the system indexes, no attributes will be encrypted, and replication will not be configured.

To modify any of the defaults, click the Options button to display the new suffix options:

The name of the database is also the name of the directory containing database files. The default database name is the value of the first naming attribute in the suffix DN, possibly with a number appended for uniqueness. To use a different name, select the Use Custom radio button and enter a new, unique database name.

Database names may only contain ASCII (7-bit) alphanumeric characters, hyphens (-), and underscores (_). For example, you might name the new database example_2.

You may also choose the location of the directory containing database files. By default it is a subdirectory of the following path:

ServerRoot/slapd-serverID/db

Enter a new path or click Browse to find a new location for the database directory. The new path must be accessible on the directory server host.

To speed up the configuration of your new suffix, you may choose to clone an existing suffix. Select the Clone Suffix Configuration and choose the suffix you wish to clone from the drop-down menu. Then select any of the following configurations to clone:

Clone index configuration - The new suffix will maintain the same indexes on the same attributes as the cloned suffix.

Clone attribute encryption configuration - The new suffix will enable encryption for the same list of attributes and the same encryption schemes as in the cloned suffix.

Clone replication configuration - The new suffix will be the same replica type as the cloned suffix, all replication agreements will be duplicated if it is a supplier, and replication will be enabled.

Click OK when you have configured all of the new suffix options. The new suffix dialog will show all the options you chose.

Click OK in the new suffix dialog to create the new root suffix.

The root suffix appears automatically under the Data branch. See Managing Suffixes, to further configure the new suffix.

A new root suffix does not contain any entries, not even an entry for the suffix DN. Consequently, it will not be accessible in the directory nor visible in the Directory tab of the console until it has been initialized and given the appropriate access permissions.

If you will initialize the suffix from an LDIF file you may skip the remaining steps. However, be sure the root entry in your LDIF file contains the access control instructions (ACIs) required by your deployment.

Select the top-level Directory tab of the console. The new suffix is not yet visible in the directory tree.

Only the directory manager has the right to create the top entry of a suffix. If you are not logged in as the directory manager, do so now by selecting the Console>Log in as New User menu item. Enter the DN and password of the directory manager to log in. By default, the directory manager DN is cn=Directory Manager.

Right-click on the root node of the directory tree, the one containing the server hostname and port. Select the New Root Object item from the pop-up menu and select the DN of the new root suffix.

Alternatively, select the root node of the directory tree and then choose the New Root Object item from the Object menu.

In the New Object dialog that is displayed, select a single object class for the root object. This object class will determine what other attributes may be added to the root entry.

By convention, root objects for suffix DNs containing dc naming attributes belong to the domain object class. Usually, root objects are simple objects and contain little data.

Click OK in the New Object dialog when you have selected the object class.

The console now displays the generic editor for the new root object. The set of default ACIs is automatically added to the new object. See Default ACIs for additional information. Add and edit any attribute values necessary for your topology, including any modifications to the set of ACIs.

When you have edited the entry, click OK in the Generic Editor to create the root object of the new suffix.

The new suffix now appears in the directory tree and can be managed through the console, according to the rights given by the ACIs.

Creating a New Subsuffix Using the Console

The following procedure describes how to create a new subsuffix under an already existing root or subsuffix:

On the top-level Configuration tab of Directory Server Console, expand the Data node and any suffix node to display the parent suffix.

Right-click on the parent suffix node, and select New Subsuffix from the pop-up menu.

Alternatively, you may select the parent suffix node and choose New Subsuffix from the Object menu.

The "New Subsuffix" dialog box is displayed.

Enter a unique name in the Subsuffix RDNs field. The name must be in the relative distinguished name format consisting of one or more attribute-value pairs separated by commas, for example ou=Contractors.

The line below the text box shows the complete DN of this subsuffix, consisting of the parent suffix DN appended to the RDNs.



Note	Subsuffix names contain attribute-value pairs in the RDN format, but are treated as a single string. Therefore, all spaces are significant and are part of the suffix DN.

To modify any of the defaults, click the Options button to display the new suffix options:

The name of the database is also the name of the directory containing database files. The default database name is the value of the first naming attribute in the RDN, possibly with a number appended for uniqueness. To use a different name, select the Use Custom radio button and enter a new, unique database name.

Database names may only contain ASCII (7-bit) alphanumeric characters, hyphens (-), and underscores (_). For example, you might name the new database temps-US.

You may also choose the location of the directory containing database files. By default it is a subdirectory of the following path:

ServerRoot/slapd-serverID/db

Enter a new path or click Browse to find a new location for the database directory. The new path must be accessible by the directory server application.

To speed up the configuration of your new subsuffix, you may choose to clone an existing suffix, either its parent or any other suffix. Select the Clone Suffix Configuration and choose the suffix you wish to clone from the drop-down menu. Then select any of the following configurations to clone:

Clone index configuration - The new suffix will maintain the same indexes on the same attributes as the cloned suffix.

Clone attribute encryption configuration - The new suffix will enable encryption for the same list of attributes and the same encryption schemes as in the cloned suffix.

Click OK when you have configured all of the new suffix options. The new subsuffix dialog will show all the options you chose.

Click OK in the new subsuffix dialog to create the subsuffix.

The subsuffix appears automatically under its parent suffix in the Configuration tab. See Managing Suffixes, to further configure the new suffix.

A new subsuffix does not contain any entries, not even an entry for the RDN. Consequently, it will not be accessible in the directory nor visible in the Directory tab of the console until it has been initialized and given the appropriate access permissions.

If you initialize the suffix from an LDIF file you may skip the remaining steps. However, be sure the parent suffix and the new entries in your LDIF file contain the access control instructions (ACIs) required by your deployment.

On the top-level Directory tab of the console, expand the directory tree to display the parent of the subsuffix. The new subsuffix will not be visible yet.

Only the directory manager has the right to create the top entry of a suffix and subsuffix (ACI.) If you are not logged in as the directory manager, do so now by selecting the Console>Log in as New User menu item. Enter the DN and password of the directory manager to log in. By default, the directory manager DN is cn=Directory Manager.

Right-click on the parent of the subsuffix, and select the New item from the pop-up menu. In the list of new objects, select the type of object that corresponds to the RDN of the subsuffix. For example, choose the OrganizationalUnit item if you created the ou=Contractors subsuffix. If the object class of your subsuffix is not listed, select Other and choose it from list in the New Object dialog that is displayed. Alternatively, select the parent of the subsuffix and then choose the New item from the Object menu.

The console now displays the custom or generic editor for the new object. Add and edit any attribute values necessary for your topology, including any modifications to the set of ACIs.

When you have edited the entry, click OK in the Editor to create the entry for the new subsuffix.

The new subsuffix now appears in the directory tree and can be managed through the console, according to the rights given by the ACIs.

Creating Suffixes From the Command Line

You may also use the ldapmodify command-line utility to create suffixes in your directory. Because root suffixes and subsuffixes are managed internally in the same way by the server, the procedure for creating them from the command line is nearly the same.

Although "cn=Directory Manager" is used in the following examples, the configuration entries can be created by any administrative user. However, the top entry of the suffix must be created by the directory manager.

Create the suffix configuration entry under cn=mapping tree,cn=config with the following command for a root suffix:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password
dn: cn="suffixDN",cn=mapping tree,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsMappingTree
cn: suffixDN
nsslapd-state: backend
nsslapd-backend: databaseName
^D

For a subsuffix, use the same command with an additional attribute:
nsslapd-parent-suffix: "parentSuffixDN"

The suffixDN is the full DN of the new suffix. For a root suffix, the convention is to use the domain-component (dc) naming attribute, for example, dc=example,dc=org. In the case of a subsuffix, the suffixDN includes the RDN of the subsuffix and the DN of its parent suffix, for example ou=Contractors,dc=example,dc=com.

The databaseName is a name for the internally managed database associated with this suffix. The name must be unique among the databaseNames of all suffixes, and by convention it is the value of the first naming component of the suffixDN. The databaseName is also the name of the directory containing database files for the suffix, and therefore should contain only ASCII (7-bit) alphanumeric characters, hyphens (-), and underscores (_).

For a subsuffix, the parentSuffixDN is the exact DN of the parent suffix.

Create the database configuration entry with the following command:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password
dn: cn=databaseName,cn=ldbm database,cn=plugins,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsBackendInstance
cn: databaseName
nsslapd-suffix: suffixDN
^D

where databaseName and suffixDN must have the same value as those used in the previous step.

When this entry is added to the directory, the database module of the server will automatically create the database files in the following directory:

ServerRoot/slapd-serverID/db/databaseName

To make the server create the database files in another location, create the database configuration entry with the following attribute:

nsslapd-directory: path/databaseName

The server will automatically create a directory named databaseName in the give location to hold the database files.

Create the base entry of the root suffix or subsuffix.

For example, the base entry of the dc=example,dc=org root suffix can be created with the following command:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password
dn: dc=example,dc=org
objectclass: top
objectclass: domain
dc: example
^D

You must include the first naming attribute of the DN and its value. You must also include all attributes that are required by the schema of the base entry's object class. By convention, root suffix DNs using domain-components (dc) have the domain object class, which does not require any other attributes.

You should also add access control instructions (ACI) attributes to a root suffix to enforce your access policy. The following are the aci attribute values you may add to allow anonymous reading, secure self-modification, and full administrator access:

aci: (targetattr != "userPassword") (version 3.0; acl
"Anonymous access";
allow (read, search, compare)userdn = "ldap:///anyone";)
aci: (targetattr != "nsroledn || aci || nsLookThroughLimit ||
nsSizeLimit || nsTimeLimit || nsIdleTimeout ||
passwordPolicySubentry || passwordExpirationTime ||
passwordExpWarned || passwordRetryCount || retryCountResetTime
|| accountUnlockTime || passwordHistory ||
passwordAllowChangeTime")(version 3.0; acl "Allow self entry
modification except for nsroledn, aci, resource limit
attributes, passwordPolicySubentry and password policy state
attributes"; allow (write)userdn ="ldap:///self";)
aci: (targetattr = "*")(version 3.0; acl
"Configuration Administrator";
allow (all) userdn = "ldap:///uid=admin,ou=Administrators,
ou=TopologyManagement, o=NetscapeRoot";)
aci: (targetattr ="*")(version 3.0;acl
"Configuration Administrators Group";
allow (all) (groupdn =
"ldap:///cn=Configuration Administrators, ou=Groups,
ou=TopologyManagement, o=NetscapeRoot");)

As an example of a subsuffix, the base entry for ou=Contractors,dc=example,dc=com can be created with the following command:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password
dn: ou=Contractors,dc=example,dc=com
objectclass: top
objectclass: organizationalUnit
description: base of separate subsuffix for contractor identities
^D

You must include the naming attributes of the DN and their values. You must also include all attributes that are required by the schema of the base entry's object class, and you may add any others that are allowed. A subsuffix will have the access control defined by ACIs on its parent, provided the scope of those ACIs includes the new subsuffix. To define a different access policy on the subsuffix, specify your aci attributes when you create the base entry.

Managing Suffixes

Creating suffixes allows you to manage all of their contents together. This section explains how to manage access to the suffix, including disabling all operations, making the suffix read only and creating suffix-level referrals.

Many other directory administration tasks are configured at the suffix-level, but covered in separate chapters of this book:

Importing Data.

Exporting Data.

Managing Indexes.

Encrypting Attribute Values.

Managing Replication.

Disabling or Enabling a Suffix

Sometime you may need to make a suffix unavailable for maintenance, or make its contents unavailable for security reasons. Disabling a suffix prevents the server from reading or writing the contents of the suffix in response to any client operations that try to access the suffix. If you have a default referral defined, that referral will be returned when clients attempt to access a disabled suffix.

Disabling or Enabling a Suffix Using the Console

On the top-level Configuration tab of Directory Server Console, expand the Data node and select the suffix you wish to disable.

In the right panel, select the Settings tab. By default, all suffixes are enabled when they are created.

If you have enabled replication for this suffix, you will see a note informing you that the contents of this tab may be updated automatically. Disabling a suffix that is replicated will also interrupt replication to this suffix. As long as replication is not interrupted longer than the recover settings, the replication mechanism will resume updates to this replica when the suffix is enabled again. The replication recovery settings are the purge delay of this consumer replica and the maximum size and age of its supplier's change log (see Advanced Consumer Configuration).

Deselect the "Enable access to this suffix" checkbox to disable the suffix, or select the checkbox to enable it.

Click Save to apply the change and immediately disable or enable the suffix.

Optionally, you may set the global default referral that will be returned for all operations on this suffix while it is disabled. This setting is located on the Network tab of root node of the top-level Configuration tab. For more information, see Setting a Default Referral Using the Console.

Disabling or Enabling a Suffix From the Command Line

Edit the nsslapd-state attribute in the suffix's configuration entry with the following command:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn="suffixDN",cn=mapping tree,cn=config
changetype: modify
replace: nsslapd-state
nsslapd-state: disabled or backend
^D

where suffixDN is the full string of the suffix DN as it was defined, including any spaces. Set the nsslapd-state attribute to the value disabled to disable the suffix and to the value backend to enable full access.

The suffix will be disabled immediately when the command is successful.

Optionally, you may set the global default referral that will be returned for all operations on this suffix while it is disabled. For more information, see Setting a Default Referral From the Command Line.

Setting Access Permissions and Referrals

If you wish to limit access to a suffix without disabling it completely, you may modify the access permissions to allow read-only access. In this case you must define a referral to another server for write operations. You may also deny both read and write access and define a referral for all operations on the suffix.

Referrals can also be used to temporarily point a client application to a different server. For example, you might add a referral to a suffix so that the suffix points to a different server while backing up the contents of the suffix.

The replication mechanism relies on write permissions and referrals to configure the suffix for replication. Enabling replication, promoting a replica, or demoting a replica will modify the referral settings.

Setting Access Permissions and Referrals Using the Console


Caution	If the suffix is replicated, modifying the referrals may affect the replicated behavior of this suffix.

On the top-level Configuration tab of the Directory Server console, expand the Data node and select the suffix where you wish to set a referral.

In the right panel, select the Settings tab. You will only be able to set permissions and referrals if the chained suffix is enabled. If you have enabled replication for this suffix, you will see a note informing you that the contents of this tab may be updated automatically.

Select one of the following radio buttons to set the response to any write operation on entries in this suffix:

Process write and read requests - This radio button is selected by default and represents the normal behavior of a suffix. Referrals may be defined, but they will not be returned.

Process read requests and return a referral for write requests - Select this radio button if you wish to make your suffix read-only and enter one or more LDAP URLs in the list to be returned as referrals for write requests.

Return a referral for both read and write requests - Select this radio button if you wish to deny both read and write access. This behavior is similar to disabling access to the suffix, except that the referrals may be defined specifically for this suffix instead of using the global default referral.

Edit the list of referrals with the Add and Remove buttons. Clicking the Add button will display a dialog for creating an LDAP URL of a new referral. You may create a referral to the DN of any branch in the remote server. For more information about the structure of LDAP URLs, refer to the`Directory Server Administration Reference.

You can enter multiple referrals. The directory will return all referrals in this list in response to requests from client applications.

Click Save to apply you changes and immediately begin enforcing the new permissions and referral settings.

Setting Access Permissions and Referrals From the Command Line

Referrals are labeled URLs, that is, an LDAP URL possibly followed by a space character and a label. Because space characters are significant, any space characters in the URL part of the referral must be escaped using %20.

In the following command, suffixDN is the full string of the suffix DN as it was defined, including any spaces. LDAPURL is a valid URL containing the hostname, port number and DN of the target, for example:

Edit the suffix's configuration entry with the following command:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn="suffixDN",cn=mapping tree,cn=config
changetype: modify
replace: nsslapd-state
nsslapd-state: referral on update or referral
-
add: nsslapd-referral
nsslapd-referral: LDAPURL
^D

You may repeat the last change statement to add any number of LDAP URLs to the nsslapd-referral attribute.

When the value of nsslapd-state is referral on update, the suffix is read-only and all LDAP URLs will be returned as referrals for write operations. When the value is referral, both read and write operations are denied and the referrals are returned for any request.

The suffix will become read-only or inaccessible and ready to return referrals immediately after the command is successful.

Deleting a Suffix

Deleting a suffix removes its entire branch from the directory. You may delete a parent suffix and keep its subsuffixes in the directory as new root suffixes.

Deleting a Suffix Using the Console


Caution	When you delete a suffix, you permanently remove all of its entries from the directory and remove all configuration of the suffix, including its replication configuration.

On the Configuration tab of Directory Server Console, expand the Data node.

Right-click on the suffix you wish to remove, and select Delete from the pop-up menu.

Alternatively, you may select the suffix node and choose Delete from the Object menu.

A confirmation dialog appears to inform you that all suffix entries will be removed from the directory.

In addition for a parent suffix, you have the choice of recursively deleting all of its subsuffixes. Select "Delete this suffix and all of its subsuffixes" if you want to remove the entire branch. Otherwise, select "Delete this suffix only" if you want to remove only this particular suffix, and keep its subsuffixes in the directory.

Click OK to delete the suffix.

A progress dialog box is displayed that tells you the steps being completed by the console.

Deleting a Suffix From the Command Line

To delete a suffix from the command line, use the ldapdelete command to remove its configuration entries from the directory.

If you wish to delete an entire branch containing subsuffixes, you must find the subsuffixes of the deleted parent and repeat the procedure for each of them and their possible subsuffixes.

Remove the suffix configuration entry using the following command:

ldapdelete -h host -p port -D "cn=Directory Manager" -w password \
-v 'cn="suffixDN",cn=mapping tree,cn=config'

This command removes the suffix from the server, starting with the base entry at the suffixDN. Now the suffix is no longer visible nor accessible in the directory. The -v option specifies verbose output mode: additional information about the delete operation is displayed.

Remove the corresponding database configuration entry located in cn=databaseName,cn=ldbm database,cn=plugins,cn=config and all entries below it. To do this recursive delete, use the ldapsubtdel command from the download the Directory Server Resource Kit (DSRK). This software is available at the following location: http://wwws.sun.com/software/download/.

% ./ldapsubtdel -h hostname -p port -D "cn=Directory Manager" -w - -b "ou=test,dc=example,dc=com" -r -v

Enter bind password: password

Processing subtree ou=test,dc=example,dc=com

Deleting entry uid=test0,ou=test,dc=example,dc=com

Deleting entry uid=test1,ou=test,dc=example,dc=com

Deleting entry uid=test2,ou=test,dc=example,dc=com

Deleting entry uid=test3,ou=test,dc=example,dc=com

[...]

Deleting entry ou=test,dc=example,dc=com

Successfully deleted subtree ou=test,dc=example,dc=com

This output shows all of the index configuration entries that were associated with the database and that needed to be removed. When the database configuration is entirely deleted, the server will remove all database files and directories associated with this suffix.

Creating Chained Suffixes

Both root suffixes and subsuffixes may be chained to another server, and both procedures may be performed through the console or from the command line.

However, before you create any chained suffixes, you should create a proxy identity on the remote server. The local server will use the proxy identity to bind to the remote server when forwarding an operation through the chained suffix.

If you are configuring many chained suffixes with identical parameters, you should also set default values for the chaining parameters of new chained suffixes. At any time before or after creating chained suffixes, you may also set the chaining policy for LDAP controls and server components, as described in Configuring the Chaining Policy.

Creating a Proxy Identity

The proxy identity is a user on the remote server that the local server will use to bind and forward the chained operation. For security reasons you should never use the Directory Manager or the Administrative user (admin) for proxying.

Creating a Proxy Identity Using the Console

This procedure applies to the Directory Server Console connected to the remote server that is the target of a chained suffix.

On the top-level Directory tab of Directory Server Console, expand the directory tree.

Right-click on the cn=config entry and select New>User from the pop-up menu. Alternatively, select the cn=config entry and choose the New>User item from the Object menu.

Fill in the fields of the Create New User dialog with values to describe the proxy identity, for example:

First Name:          proxy
Last Name:          host1
Common Name:          host1 chaining proxy
User ID:          host1_proxy
Password:          password
Confirm Password:          password

where host1 is the name of the server containing the chained suffix. You should use a different proxy identity for each server that has a suffix chained to this server.

Click OK to save this new proxy identity.

Creating a Proxy Identity From the Command Line

This procedure uses host1 and host2 to refer to the local server containing the chained suffix and the remote server that is the target of a chained suffix, respectively.

Use the following command to create the proxy identity on host2:

ldapmodify -a -h host2 -p port2 -D "cn=Directory Manager" -w password2
dn: uid=host1_proxy,cn=config
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetorgperson
uid: host1_proxy
cn: host1 chaining proxy
sn: host1
userpassword: password
description: proxy entry to be used for chaining from host1
^D



Caution	You should perform the ldapmodify command through an encrypted port to avoid sending a clear password.

Setting Default Chaining Parameters

Chaining parameters determine how the server connects to a chained server and processes operations on that chained suffix. These parameters are configured on each chained suffix. Directory Server provides default values that are used every time a chained suffix is created. You may edit these default values to specify the chaining parameters on all new chained suffixes.

Every new chained suffix created after you modify the default parameters will have the values you specify. However, once a suffix is created you may only modify the parameters as described in Managing Chained Suffixes.

The attributes and default values for the chaining parameters are described below. Refer to the Directory Server Administration Reference for a description of allowed values:

Client Return Parameters

nsReferralOnScopedSearch - When on by default, clients searches with a scope entirely within the chained suffix will receive a referral to the remote server. This avoids transmitting the search results twice. When set to off, you should set the size and time limit parameters to avoid long searches on chained suffixes.

nsslapd-sizelimit - This parameter determines the number of entries that will be returned in response to the chained search operation. The default size limit is 2000 entries. Set this parameter to a low value if you wish to limit broad searches involving the chained suffix. In any case, the operation will be limited by any size settings on the remote server.

nsslapd-timelimit - This parameter controls the length of time for chained operation. The default time limit is 3600 seconds (one hour). Set this parameter to a low value if you wish to limit the time allowed for operations on the chained suffix. In any case, the operation will be limited by any time settings on the remote server.

Cascading Chaining Parameters

nsCheckLocalACI - In single-level chaining, the local server does not check the access rights of the bound user on the chained suffix because that is the responsibility of the remote server. Therefore, the default value is off. However, intermediate servers in a cascading chain must set this parameter to on in order to check and limit the access rights of the proxy DN used by the server that is forwarding the chained operation.

nsHopLimit - Loop detection relies on this parameter to define the maximum number of hops allowed. Any chained operation that reaches this number of hops will not be forwarded but instead abandoned under the assumption there is an accidental loop in the cascading topology.

Connection Management Parameters

nsOperationConnectionsLimit - Maximum number of simultaneous LDAP operation connections that the chained suffix can establish with the remote server. The default value is 10 connections.

nsBindConnectionsLimit - The maximum number of simultaneous bind connections that the chained suffix can establish with the remote server. The default value is 3 connections.

nsConcurrentBindLimit - Maximum number of simultaneous bind operations per LDAP connection. The default value is 10 outstanding bind operations per connection.

nsBindRetryLimit - Number of times a chained suffix attempts to rebind to the remote server upon error. A value of 0 indicates that the chained suffix will try to bind only once. The default value is 3 attempts.

nsConcurrentOperationsLimit - Maximum number of simultaneous operations per LDAP connection. The default value is 10 operations per connection.

nsBindTimeout - Amount of time, in seconds, before the bind attempts to the chained suffix will time out. The default value is 15 seconds.

nsAbandonedSearchCheckInterval - Number of seconds before the server checks to see if an operation has been abandoned. The default value is 2 seconds.

nsConnectionLife - How long a connection made between the chained suffix and remote server remains open so that it may be reused. It is faster to keep the connections open, but it uses more resources. For example, if you are using a dial-up connection you may want to limit the connection time. By default, connections are unlimited, which is defined by the value 0.

Error Detection Parameters

nsmaxresponsedelay - Maximum amount of time a remote server may take to respond to the initiation of an LDAP request for a chained operation. This period is given in seconds. After this delay, the local server will test the connection. The default delay period is 60 seconds.

nsmaxtestresponsedelay - Duration of the test to check whether the remote server is responding. The test is a simple search request for an entry which does not exist. This period is given in seconds. If no response is received during the test delay, the chained suffix assumes the remote server is down. The default test response delay period is 15 seconds.

Setting Default Chaining Parameters Using the Console

On the top-level Directory tab of the Directory Server console, expand the directory tree and select the following entry: cn=default instance config,cn=chaining database,cn=plugins,cn=config.

Double click this entry or select the Object>Edit with Generic Editor menu item. Modify the values of the desired attributes from the list above.

Click Save in the Generic Editor dialog, and the changes will take effect immediately.

Setting Default Chaining Parameters From the Command Line

Use the ldapmodify command to edit the entry cn=default instance config,cn=chaining database,cn=plugins,cn=config. All attributes of this entry become the default values of the parameters in a new chained suffix.

For example, the following command will increase the default size limit to 5000 entries and decrease the default time limit to 10 minutes in new chained suffixes:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn=default instance config,cn=chaining database,
cn=plugins,cn=config
changetype: modify
replace: nsslapd-sizelimit
nsslapd-sizelimit: 5000
-
replace: nsslapd-timelimit
nsslapd-timelimit: 600
^D

Modifications to this entry will take effect immediately.

Creating Chained Suffixes Using the Console

The following procedure is nearly identical for creating chained root suffixes and chained subsuffixes:

Select the Configuration tab of Directory Server Console.

For a chained root suffix, right-click on the Data node, and select New Chained Suffix from the pop-up menu. Alternatively, you may select the Data node and choose New Chained Suffix from the Object menu.

For a chained subsuffix, expand the Data node and any suffix node to display the parent suffix. Right-click on the parent suffix node, and select New Chained Subsuffix from the pop-up menu. Alternatively, you may select the parent suffix node and choose New Chained Subsuffix from the Object menu.

The "New Chained (Sub)Suffix" dialog is displayed.

Enter the DN of the entry on the remote server to which you want to chain. The remote entry does not necessarily have to be the base entry of a remote suffix:

For a root suffix, enter the full DN of the remote entry in the Suffix DN field. You may enter any DN that is an entry in the remote directory tree. That entry will be the base of the chained root suffix and everything below it will be available through the chained suffix.

For a subsuffix, enter the subsuffix RDNs of the entry that will be chained. That entry will be the base of the chained subsuffix. The complete subsuffix name that appears below the text field must be an entry that exists in the remote server.

Enter the hostname of the remote server containing the suffix data, including the domain if necessary.

Enter the port number for accessing the remote server and select the checkbox if this is the secure port. When using a secure port, the chaining operation will be encrypted over SSL. For more information, refer to Chaining Using SSL.

The text at the bottom of the dialog will show the full URL of the remote server.

Enter the bind DN and password of the proxy identity on the remote server. The local server will use this DN as a proxy when accessing contents of the suffix on the remote server. For example, use the uid=host1_proxy,cn=config DN defined in Creating a Proxy Identity.

You cannot use the DN of the Directory Manager on the remote server. Operations performed through the chained suffix will use this proxy identity in the creatorsName and modifiersName attributes. You may omit the proxy DN, in which case the local server will bind anonymously when accessing the remote server.

Click OK to create the chained suffix. The new suffix will appear in the configuration tree with the icon for chaining.

Click on the new chained suffix to select it, and select the Remote Server tab in the right-hand panel.

Optionally, you may define one or more failover servers for this chained suffix. If the server cannot contact the remote server, it will try each of the failover servers in the order defined until one of them responds. Failover servers must contain the same suffix that is being chained and allow the same bind DN for proxying.

To define failover servers, enter more hostname and port number pairs, separated by spaces in the Remote Server URL field. This field has the following format:

ldap[s]://hostname[:port][ hostname[:port]].../

At the bottom of the Remote Servers tab, the text box displays the ACI needed to allow the proxied operation through chaining. You must add this ACI to the entry with the suffixDN on the remote server. If you defined any failover servers, you should add the ACI to all of them. Use the Copy ACI button to copy the ACI text to your system's clipboard for pasting.

Once this ACI is added to the base entry on the remote server, the chained suffix will be visible in the directory tree of the local server.



Caution	You may need to define other ACIs on the same entry to restrict access to the remote server that is now exposed through chaining. See Access Control Through Chained Suffixes.

If you have configured the chaining policy for server components, you must also add ACIs that will allow those components to access the remote server. For example, if you allow the referential integrity plug-in to chain, you must add the following ACI to the base entry whose DN was given in Step 2:

aci: (targetattr "*")
(target="ldap:///suffixDN")
(version 3.0; acl "RefInt Access for chaining"; allow
(read,write,search,compare) userdn = "ldap:///cn=referential
integrity postoperation,cn=plugins,cn=config";)

Creating Chained Suffixes From the Command Line

You may also use the ldapmodify command-line utility to create chained suffixes in your directory. Because chained root suffixes and chained subsuffixes are managed internally in the same way by the server, the procedure for creating them from the command line is nearly the same.

Create the chained suffix entry under cn=mapping tree,cn=config with the following command for a chained root suffix:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password
dn: cn=suffixDN,cn=mapping tree,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsMappingTree
cn: suffixDN
nsslapd-state: backend
nsslapd-backend: databaseName
^D

For a chained subsuffix, use the same command with an additional attribute:
nsslapd-parent-suffix: parentSuffixDN

In the case of a chained subsuffix, the suffixDN is the RDN of the subsuffix and the DN of its parent suffix, for example l=Europe,dc=example,dc=com. The suffixDN must be the DN of an entry available through the remote server, but it does not necessarily have to be the base entry of a remote suffix.

Suffix names are in the DN format but are treated as a single string. Therefore, all spaces are significant and are part of the suffix name. In order for the server to access the remote entry, the suffixDN string must respect the same spacing used in the remote suffixes.

The databaseName is used by the chaining plug-in component to identify this chained suffix. The name must be unique among the databaseNames of all suffixes, and by convention it is the value of the first naming component of the suffixDN. Unlike a local suffix, chained suffixes do not have any database files on the local server.

For a subsuffix, the parentSuffixDN is the exact DN of the parent suffix. The parent may be either a local suffix or a chained suffix.

Create the chaining configuration entry with the following command:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password
dn: cn=databaseName,cn=chaining database,cn=plugins,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsBackendInstance
cn: databaseName
nsslapd-suffix: suffixDN
nsfarmserverurl: LDAPURL
nsmultiplexorbinddn: proxyDN
nsmultiplexorcredentials: ProxyPassword
^D

where databaseName and suffixDN must have the same value as those used in the previous step. The LDAPURL is the URL of the remote server, but it does not include any suffix information. The URL may include failover servers listed in the following format:

ldap[s]://hostname[:port][ hostname[:port]].../

All remote servers listed in the LDAP URL must contain the suffixDN. For information about specifying a secure port, refer to Chaining Using SSL.

The proxyDN is the DN of the proxy identity on the remote server. The local server will use this DN as a proxy when accessing contents of the suffix on the remote server. Operations performed through the chained suffix will use this proxy identity in the creatorsName and modifiersName attributes. If no proxy DN is specified, the local server will bind anonymously when accessing the remote server.

The ProxyPassword is the non-encrypted value of the password for the proxy DN. The password will be encrypted when it is stored in the configuration file. For example:

nsmultiplexorbinddn: uid=host1_proxy,cn=config
nsmultiplexorcredentials: secret



Caution	You should perform the ldapmodify command through an encrypted port to avoid sending a clear password.

The new entry will automatically include all of the chaining parameters with the default values defined in cn=default instance config,cn=chaining database,cn=plugins,cn=config. You may override any of these values by setting the attributes with different values when you create the chaining configuration entry. See Setting Default Chaining Parameters for the list of attributes for which you may define values.

Use the following command to create an ACI on the remote entry. This ACI is needed to allow the proxied operation through chaining. For more information on ACIs, refer to Chapter 6, "Managing Access Control."

ldapmodify -h host2 -p port2 -D "cn=Directory Manager" -w password2
dn: suffixDN
changetype: modify
add: aci
aci: (targetattr=*)(target = "ldap:///suffixDN")(version 3.0;acl
"Allows use of admin for chaining"; allow (proxy)
(userdn="ldap:///proxyDN");)
^D



Caution	You may need to define other ACIs on the same entry to restrict access to the remote server that is now exposed through this server. See Access Control Through Chained Suffixes.

If you have configured the chaining policy for sever components, you must also add ACIs that will allow those components to access the remote server. For example, if you allow the referential integrity plug-in to chain, you must add the following ACI to the base entry with the suffixDN:

The following commands give an example of creating a chained subsuffix. Note that commas in the suffixDN must be escaped with a backslash (\) only when they appear in the naming attribute in the DN.

ldapmodify -a -h host1 -p port1 -D "cn=Directory Manager" -w password1
dn: cn=l=Europe\,dc=example\,dc=com,cn=mapping tree,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsMappingTree
cn: l=Europe,dc=example,dc=com
nsslapd-state: backend
nsslapd-backend: Europe
nsslapd-parent-suffix: dc=example,dc=com

dn: cn=Europe,cn=chaining database,cn=plugins,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsBackendInstance
cn: Europe
nsslapd-suffix: l=Europe,dc=example,dc=com
nsfarmserverurl: ldap://host2:port2/
nsmultiplexorbinddn: uid=host1_proxy,cn=config
nsmultiplexorcredentials: proxyPassword
^D

ldapmodify -h host2 -p port2 -D "cn=Directory Manager" -w password2
dn: l=Europe,dc=example,dc=com
changetype: modify
changetype: modify
aci: (targetattr=*)(target =
"ldap:///l=Europe,dc=example,dc=com")(version 3.0;acl
"Allows use of admin for chaining"; allow (proxy)
(userdn="ldap:///uid=host1_proxy,cn=config");)
^D

Access Control Through Chained Suffixes

When an authenticated user accesses a chained suffix, the server 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 means that you need to add the usual access controls to the remote server with a few restrictions:

You cannot use all types of access control.

All access controls based on the IP address or DNS domain of the client may not work, as the original domain of the client is lost during chaining.

The following restrictions apply to the ACIs you create to use with chained suffixes:

ACIs must be located on the same server as the 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 on the same server as 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 users are remote.

Though access controls are always evaluated on the remote server, you can also choose to have them evaluated on both the server containing the chained suffix 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 chained suffix and the entry is located on a remote server).

For performance reasons, clients cannot do remote inquiries and evaluate access controls.

The chained suffix does not necessarily have access to the entries being modified by the client application.

When performing a modify operation, the chained suffix does not have access to the full entry stored on the remote server. If performing a delete operation, the chained suffix 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 chained suffix.

By default, access controls set on the server containing the chained suffix are not evaluated. To override this default, use the nsCheckLocalACI attribute in the cn=databaseName,cn=chaining database,cn=plugins,cn=config entry. However, evaluating access controls on the server containing the chained suffix is not recommended unless using cascading chaining. For more information, see Configuring Cascading Chaining.

Chaining Using SSL

You can configure the server to communicate with the remote server using SSL when performing an operation on a chained suffix. Using SSL with chaining involves the following steps:

Enable SSL on the remote server.

Enable SSL on the server that contains the chained suffix.

For more information on enabling SSL, refer to Chapter 11, "Managing Authentication and Encryption."

Specify SSL and the secure port of the remote server in the procedure for creating or modifying a chained suffix.

When using the console, select the secure port checkbox in the chained suffix creation or configuration procedures. See Creating Chained Suffixes Using the Console or Modifying the Chaining Policy Using the Console.

When using the command-line procedures, specify an LDAPS URL and the secure port of the remote server, for example: ldaps://example.com:636/. See Creating Chained Suffixes From the Command Line or Modifying the Chaining Policy From the Command Line.

When you configure the chained suffix and remote server to communicate using SSL, this does not mean that the client application making the operation request must also communicate using SSL. The client may use either port of either the LDAP or DSML protocol.

Managing Chained Suffixes

This section describes how to update and delete existing chained suffixes and control the chaining mechanism.

Configuring the Chaining Policy

The chaining policy of the server determines which LDAP controls will be propagated to chained servers and which server components are allowed to access chained suffixes. You should be aware of these settings and their influence on operations involving chained suffixes. The chaining policy applies to all chained suffixes on the server.

The default settings are intended to allow the transparent completion of normal operations. However, if your operations involve LDAP controls, or you are using server components such as the referential integrity plug-in, you should ensure the chaining policy is configured for your needs.

It is best to configure the chaining policy before creating any chained suffixes, so that the policy will be applied as soon as chained suffixes are enabled. However, you may also modify the policy at any later time.

Chaining Policy of LDAP Controls

LDAP controls are sent by clients as part of a request to modify the operation or its results in some way. The server chaining policy determines which controls the server will forward to a chained suffix along with the operation. By default, the following controls are forwarded to the remote server of a chained suffix:

Table 3-1 LDAP Controls Allowed to Chain by Default
OID of the Control	Name and Description of the Control
1.2.840.113556.1.4.473	Server side sorting - Associated with a search to sort the resulting entries according to their attribute values.1
1.3.6.1.4.1.1466.29539.12	Chaining loop detection - Tracks of the number of times the server chains with another server. When the count reaches a number you configure, the operation is abandoned, and the client application is notified. For more information, see Transmitting LDAP Controls for Cascading.
2.16.840.1.113730.3.4.2	Managed DSA for smart referrals - Returns smart referrals as entries rather than following the referral. This allows you to change or delete the smart referral itself.
2.16.840.1.113730.3.4.9	Virtual list view (VLV) - Provides partial results to a search rather than returning all resulting entries at once.1

1Server side sorting and VLV controls are supported through chaining only when the scope of the search is a single suffix. Chained suffixes cannot support VLV controls when a client application makes a request to multiple suffixes.

The following table lists the other LDAP controls you may allow to chain by configuring the chaining policy:

Table 3-2 LDAP Controls That May be Chained
OID of the Control	Name and Description of the Control
1.3.6.1.4.1.42.2.27.9.5.2	Get effective rights request - Asks the server to return information about access rights and ACIs relating to the entries and attributes in the result.
2.16.840.1.113730.3.4.12	Proxied authorization (old specification) - Allows the client to assume another identity for the duration of a request.1
2.16.840.1.113730.3.4.14	Search on specific database- Used with search operations to specify that the search must be done on the database which is named in the control.
2.16.840.1.113730.3.4.16	Authentication identity request control - Allows the client to request the bind DN or the userAuthID established during the connection bind. For example, when using SASL External and SSL, it allows the client to know the DN of the entry needed to get the certificate.
2.16.840.1.113730.3.4.17	Real attribute only request - Indicates that the server should return only attributes that are truly contained in the entries returned and that it does not need to resolve virtual attributes.
2.16.840.1.113730.3.4.18	Proxied authorization (new specification) - Allows the client to assume another identity for the duration of a request.1
2.16.840.1.113730.3.4.19	Virtual attributes only request - Indicates that the server should return only attributes generated by the roles and class of service features.

1Applications may use either control for proxied authorization. You should have the same chaining policy for both of these OIDs. For more information, see Transmitting LDAP Controls for Cascading.

Chaining Policy of Server Components

A component is any feature or functional unit of the server that uses internal operations. For example, plug-ins are considered to be components. To perform their task, most components must access the directory contents, either the configuration data or the user data stored in the directory.

By default, no server components are allowed to chain. You must explicitly allow chaining if you want them to access chained suffixes. The components that may access chained data are listed by their DN below.

As described in Creating Chained Suffixes Using the Console, you must grant certain rights in an ACI on the remote server to allow chaining. When chaining server components, you must allow search, read, and compare in this ACI so that the server components may perform these operations. In addition, certain components require write permission on the remote server, as explained in the list:

cn=ACL Plugin,cn=plugins,cn=config - The ACL plug-in implements the access control feature. 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 access user entries may be chained. For further information on the limitations surrounding ACIs and chaining see ACI Limitations.

cn=old plugin,cn=plugins,cn=config - This plug-in represents all Directory Server 4.x plug-ins and whether or not they are allowed to chain. The 4.x plug-ins share the same chaining policy. You may need to set ACIs on the remote server depending upon the operations performed by the 4.x plug-ins.

cn=resource limits,cn=components,cn=config - This component sets resource usage limits based on the user bind DN. You can enforce resource limits on users whose identity is stored in a chained suffix when this component is allowed to chain.

cn=certificate-based authentication,cn=components,cn=config - This component is used when the SASL-external bind method is used. It retrieves the user certificate from the remote server.



Caution	Allowing certificate-based authentication from chained suffixes may create a security hole. If other suffixes are chained to remote servers that are not trusted, a certificate on an untrusted server could be used for authentication.

cn=referential integrity postoperation,cn=plugins,cn=config - This plug-in ensures that the removal of an entry is propagated to other entries that might have referenced its DN, such as lists of group members. Using this plug-in with chaining helps simplify the management of static groups when the group members are located in chained suffixes. When this plug-in accesses chained suffixes, it requires write permission on the remote server.

cn=uid uniqueness,cn=plugins,cn=config - The UID uniqueness plug-in ensures that all new values of a specified attribute are unique on the server. Allowing this plug-in to chain will ensure uniqueness in the entire directory tree.



Note	The following components cannot be chained: Roles plug-in Password policy component Replication plug-ins

Modifying the Chaining Policy Using the Console

On the Configuration tab of Directory Server Console, select the Data node, and in the right-hand panel, select the Chaining tab.

Select one or more LDAP controls from the right-hand list and click Add to allow them to chain. Create the list of controls that you allow to chain by using the Add and Delete buttons.

LDAP controls are listed by their OID. See Chaining Policy of LDAP Controls, for the name and description of each control.

Server components allowed to chain are listed in the bottom of the same tab. Select one or more component names from the right-hand list and click Add to allow them to chain. Create the list of components that you allow to chain by using the Add and Delete buttons.

See Chaining Policy of Server Components for a description of each component.

Click Save to save your chaining policy.

Restart the server in order for the changes to take affect.

Modifying the Chaining Policy From the Command Line

The cn=config,cn=chaining database,cn=plugins,cn=config entry contains the attributes for the chaining policy configuration. Use the ldapmodify command to edit this entry:

Modify the multivalued nsTransmittedControls attribute so that it contains the OIDs of all LDAP controls you allow to chain. Refer to the Chaining Policy of LDAP Controls for the OID of all controls that may be chained.

For example, the following command adds the effective rights control to the list of chained controls:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn=config,cn=chaining database,cn=plugins,cn=config
changetype: modify
add: nsTransmittedControls
nsTransmittedControls: 1.3.6.1.4.1.42.2.27.9.5.2
^D

If your client applications use custom controls and you wish to allow them to chain, you may also add their OID to the nsTransmittedControls attribute.

Modify the multivalued nsActiveChainingComponents attribute so that it contains the DNs of all server components you allow to chain. Refer to the Chaining Policy of Server Components for a description of each component.

For example, the following command adds the referential integrity component to the list of chained components:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn=config,cn=chaining database,cn=plugins,cn=config
changetype: modify
add: nsActiveChainingComponents
nsActiveChainingComponents: cn=referential integrity
postoperation,cn=components,cn=config
^D

Once you have modified the chaining policy configuration entry, you must restart the server for your changes to take affect.

Disabling or Enabling a Chained Suffix

Sometime you may need to make a chained suffix unavailable for maintenance or for security reasons. Disabling a suffix prevents the server from contacting the remote server in response to any client operations that try to access the suffix. If you have a default referral defined, that referral will be returned when clients attempt to access a disabled suffix.

Disabling or Enabling a Chained Suffix Using the Console

On the top-level Configuration tab of Directory Server Console, expand the Data node and select the chained suffix you wish to disable.

In the right panel, select the Settings tab. By default, all chained suffixes are enabled when they are created.

Deselect the "Enable access to this suffix" checkbox to disable the suffix, or select the checkbox to enable it.

Click Save to apply the change and immediately disable or enable the suffix.

Disabling or Enabling a Suffix From the Command Line

Edit the nsslapd-state attribute in the chained suffix entry with the following command:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn=suffixDN,cn=mapping tree,cn=config
changetype: modify
replace: nsslapd-state
nsslapd-state: disabled or backend
^D

where suffixDN is the full string of the suffix DN as it was defined, including any spaces or backslashes (\) to escape commas in the value. Set the nsslapd-state attribute to the value disabled to disable the suffix and to the value backend to enable full access.

The suffix will be disabled immediately when the command is successful.

Setting Access Permissions and Referrals

If you want to limit access to a chained suffix without disabling it completely, you can modify the access permissions to allow read-only access. In this case you must define a referral to another server for write operations. You can also deny both read and write access and define a referral for all operations on the suffix.

Setting Access Permissions and Referrals Using the Console

On the top-level Configuration tab of Directory Server Console, expand the Data node and select the chained suffix where you wish to set a referral.

In the right panel, select the Settings tab. You will only be able to set permissions and referrals if the chained suffix is enabled.

Select one of the following radio buttons to set the response to any write operation on entries in this suffix:

Process write and read requests - This radio button is selected by default and represents the normal behavior. Both read and write operations will be forwarded to the remote server and the results will be returned to the client. Referrals may be defined, but they will not be returned to clients.

Process read requests and return a referral for write requests - The server will forward only read requests and return their results to the client. Enter one or more LDAP URLs in the list to be returned as referrals for write requests.

Return a referral for both read and write requests - Enter one or more LDAP URLs in the list to be returned as referrals for all operations. This behavior is similar to disabling access to the suffix, except that the referrals may be defined specifically for this suffix instead of using the global default referral.

You can enter multiple referrals. The directory will return all referrals in this list in response to requests from client applications.

Click Save to apply you changes and immediately begin enforcing the new permissions and referral settings.

Setting Access Permissions and Referrals Using the Console

In the following command, suffixDN is the full string of the chained suffix as it was defined, including any spaces. LDAPURL is a valid URL containing the hostname, port number and DN of the target, for example:

Edit the chained suffix entry with the following command:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn=suffixDN,cn=mapping tree,cn=config
changetype: modify
replace: nsslapd-state
nsslapd-state: referral on update or referral
-
add: nsslapd-referral
nsslapd-referral: LDAPURL
^D

You may repeat the last change statement to add any number of LDAP URLs to the nsslapd-referral attribute.

The suffix will become read-only or inaccessible and ready to return referrals immediately after the command is successful.

Modifying the Chaining Parameters

Once you have defined a chained suffix, you may modify the parameters that control chaining. You may specify how to access the remote server, change the DN used for proxying, or even change the remote server. You may also modify performance parameters that control how the server establishes and maintains connections to chained servers.

Modifying the Chaining Parameters Using the Console

On the top-level Configuration tab of Directory Server Console, expand the Data node and select the chained suffix you wish to modify.

In the right panel, select the Remote Server tab.

To change the name or port of the remote server, modify the Remote Server(s) URL field. The URL contains the hostname and optional port number of on or more remote servers in the following format:

ldap[s]://hostname[:port][ hostname[:port]].../

The URL it does not include any suffix information. For information about specifying a secure port, refer to Chaining Using SSL. The servers in URL will be contacted in the order listed when the first one fails to respond to a chained request. All remote servers listed in the LDAP URL must contain the suffixDN that is the base entry of the chained suffix.

To change the DN of the proxy user, enter a new value in the Bind DN field. Enter and confirm the corresponding password for this DN in the Password fields.

The proxyDN is the DN of a user on the remote server. The local server will use this DN as a proxy when accessing contents of the suffix on the remote server. Operations performed through the chained suffix will use this proxy identity in the creatorsName and modifiersName attributes. If no proxy DN is specified, the local server will bind anonymously when accessing the remote server.

The text box at the bottom of the tab shows the ACIs required to allow chaining of this suffix. If you changed the remote server URL, you must add the ACI to the entry with the suffixDN on the new remote server or servers. If you modified the proxy DN, you should update the ACI on all chained servers. Use the Copy ACI button to copy the ACI text to your system's clipboard for pasting.

Select the Limits & Controls tab to configure the parameters for chained requests. The cascading chaining parameters are described in Configuring Cascading Chaining.

Set the Control Client Return parameters to limit the size and time of a chained operation:

Return Referral on Scoped Search - A search whose scope is entirely within the chained suffix is inefficient because the results are transmitted twice. By default, the server will instead return a referral to the chained server, forcing the client to perform the search directly on the chained server. If you deselect this option, you should set the following parameters to limit the size of results that will be chained.

Size Limit or No Size Limit - This parameter determines the number of entries that will be returned in response to the chained search operation. The default size limit is 2000 entries. Set this parameter to a low value if you wish to limit broad searches involving the chained suffix. In any case, the operation will be limited by any size settings on the remote server.

Time Limit or No Time Limit - This parameter controls the length of time for chained operations. The default time limit is 3600 seconds (one hour). Set this parameter to a low value if you wish to limit the time allowed for operations on the chained suffix. In any case, the operation will be limited by any time settings on the remote server.

Set the Connection Management parameters to control how the server manages the network connection and the binding with the remote server:

Maximum LDAP connection(s). Maximum number of simultaneous LDAP operation connections that the chained suffix can establish with the remote server. The default value is 10 connections.

Maximum bind connection(s). The maximum number of simultaneous bind connections that the chained suffix can establish with the remote server. The default value is 3 connections.

Maximum binds per connection. Maximum number of simultaneous bind operations per LDAP connection. The default value is 10 outstanding bind operations per connection.

Maximum bind retries. Number of times a chained suffix attempts to rebind to the remote server upon error. A value of 0 indicates that the chained suffix will try to bind only once. The default value is 3 attempts.

Maximum operations per connection. Maximum number of simultaneous operations per LDAP connection. The default value is 10 operations per connection.

Bind timeout or No bind timeout. Amount of time, in seconds, before the bind attempts to the chained suffix will time out. The default value is 15 seconds.

Timeout before abandon or No Timeout. Number of seconds before the server checks to see if an operation has been abandoned. The default value is 2 seconds.

Connection lifetime or Unlimited. How long a connection made between the chained suffix and remote server remains open so that it may be reused. It is faster to keep the connections open, but it uses more resources. For example, if you are using a dial-up connection you may want to limit the connection time. By default, connections are unlimited.

The error detection parameters are not available through the console. See Modifying the Chaining Parameters From the Command Line.

Click Save when you have finished setting your chaining parameters.

Modifying the Chaining Parameters From the Command Line

From the command line, you may set all of the same parameters as when using the console, and you may also configure the additional parameters described in Error Detection Parameters:

Edit the chaining configuration entry corresponding to the suffix you wish to modify with the following command:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn=databaseName,cn=chaining database,cn=plugins,cn=config
changetype: modify
replace: attributeName
attributeName: attributeValue
-
replace: attributeName2
attributeName2: attributeValue2
...
^D

The possible attribute names and values are described in the following steps. You may include several change statements in the command to change any number of parameters at once.

Modify the nsfarmserverURL attribute to change the name or port of the remote server. The value is a URL containing the hostname and optional port number of on or more remote servers in the following format:

ldap[s]://hostname[:port][ hostname[:port]].../

Modify the nsmultiplexorBindDN and nsmultiplexorCredentials attributes to change the DN used for proxy access to the remote server.

The local server will use this DN as a proxy when accessing contents of the suffix on the remote server. Operations performed through the chained suffix will use this proxy identity in the creatorsName and modifiersName attributes. If no proxy DN is specified, the local server will bind anonymously when accessing the remote server.

If you modify the proxy DN or its credentials, you must create the corresponding ACI on the remote server. This ACI is needed to allow the proxied operation through chaining:

Set any of the attributes described in Setting Default Chaining Parameters to control the connection and operation handling on the remote server. The cascading parameters are further described in Configuring Cascading Chaining.

Optimizing Thread Usage

You may also set the number of threads used globally by the server to take into account the thread resources used for chaining. Chained operations may take significantly longer because they must be forwarded to the remote server, but their threads are idle while the remote server processes the operation. If your chained servers add significant delays, you should increase the number of threads so that more are available to process local operations in the meantime.

By default, the number of threads used by the server is 30. However, when using chained suffixes, you can improve performance by increasing the number of threads available for processing operations. The number of threads you need depends on the number of chained suffixes, the number and types of operations on them, and the average time needed to process the operations on the remote server.

In general you should increase the number of threads by 5 to 10 per chained suffix, assuming the chained suffix is the target of the same number of operations as local suffixes.

Setting Thread Resources Using the Console

On the top-level Configuration tab of Directory Server Console, click on the Performance node and select the Miscellaneous tab in the right-hand panel.

Enter a new value for the Max number of threads field.

Click OK to save your changes, and confirm the message that you will need to restart the server for the changes to take effect.

Restart the directory server to use the new number of threads.

Setting Thread Resources From the Command Line

Edit the global configuration entry to modify the number of threads with the following command:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn=config
changetype: modify
replace: nsslapd-threadnumber
nsslapd-threadnumber: newThreadNumber
^D

Restart the directory server to use the new number of threads.

Deleting a Chained Suffix

Deleting a chained suffix will make it inaccessible through the local directory tree, but it will not delete the entries or suffix on the chained server. You may delete a parent suffix and keep its subsuffixes in the directory as new root suffixes.

Deleting a Chained Suffix Using the Console

On the Configuration tab of Directory Server Console, expand the Data node.

Right-click on the suffix you wish to remove, and select Delete from the pop-up menu.

Alternatively, you may select the suffix node and choose Delete from the Object menu.

A confirmation dialog appears to inform you that entries accessible through this chained suffix will not be removed from the remote directory.

Click OK to delete the suffix.

A progress dialog box is displayed that tells you the steps being completed by the console.

Deleting a Suffix From the Command Line

To delete a suffix from the command line, use the ldapdelete command to remove its configuration entries from the directory.

If you wish to delete an entire branch containing subsuffixes, you must find the subsuffixes of the deleted parent and repeat the procedure for each of them and their possible subsuffixes.

Remove the suffix configuration entry using the following command:

ldapdelete -h host -p port -D "cn=Directory Manager" -w password
cn=suffixDN,cn=mapping tree,cn=config

This command makes the chained suffix and its remote entries no longer visible in the directory.

Remove the corresponding database configuration entry located in cn=databaseName,cn=chaining database,cn=plugins,cn=config and the monitor entry below it:

ldapdelete -h host -p port -D "cn=Directory Manager" -w password
cn=monitor,cn=dbName,cn=chaining database,cn=plugins,cn=config
cn=dbName,cn=chaining database,cn=plugins,cn=config

Configuring Cascading Chaining

In cascading chaining, a subtree being chained from one server may itself be a chained suffix or contain chained subsuffixes. When an operation involves the chained suffix in the one server, it will be forwarded to the intermediate server that will contact a third server, and so on. A cascading chain occurs any time more than one hop between servers is required to access all of the data in a directory tree.

For example, the following diagram show how access to the entry ou=People,l=Europe,dc=example,dc=com is chained from Server A to Server B and finally to Server C. Server A contains a root suffix dc=example,dc=com, and a chained subsuffix to Server B for the branch l=Europe,dc=example,dc=com. Server B contains the entry l=Europe,dc=example,dc=com, but the branch ou=People,l=Europe,dc=example,dc=com is a chained subsuffix to Server C. Server C actually contains the entry ou=People,l=Europe,dc=example,dc=com

Setting the Cascading Parameters

All servers should configure loop detection so that any accidental loop in the chaining topology will be detected. If loop detection is not enabled, servers in a loop will forward an operation around and around until it overloads them.

All intermediate chained suffixes should be configured to evaluate local ACIs which is usually not done on the first level of a chained suffix.

Setting the Cascading Parameters Using the Console

On the top-level Configuration tab of Directory Server Console, expand the Data node and select the chained suffix you wish to modify.

In the right panel, select the Limits & Controls tab where the Cascading Chaining parameters may be modified.

On all intermediate servers in a cascading chain, select the checkbox to check local ACIs.

During single level chaining, this checkbox is not selected because a user's access rights are not evaluated on the first server but rather on the second server through the proxy. However, on the intermediate server of a cascading chain, you must enable ACI checking to allow perform access control before forwarding the operation again.

On all servers in a cascading chain, set the maximum number of hops that allows all chaining operations in your topology. Every time the same operation is forwarded to another chained suffix counts as a hop, and a chained suffix will not forward the operation any more if this limit is reached.

You should set a number greater than the number of hops in your longest cascading chain. Any operation that reaches the limit will be aborted because the servers will assume it is an accidental loop in your topology.

You must also set the chaining configuration to allow the loop detection control, as described in Transmitting LDAP Controls for Cascading.

Click Save when you have finished setting the cascading parameters.

Setting the Cascading Parameters From the Command Line

On all intermediate servers, edit the chaining configuration entry for the cascading suffix with the following command:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn=databaseName,cn=chaining database,cn=plugins,cn=config
changetype: modify
replace: nsCheckLocalACI
nsCheckLocalACI: on
-
changetype: modify
replace: nsHopLimit
nsHopLimit: maximumHops
^D

You should set the maximumHops greater than the number of hops in your longest cascading chain. Any operation that reaches the limit will be aborted because the servers will assume it is an accidental loop in your topology. You must also set the chaining configuration to allow the loop detection control, as described in Transmitting LDAP Controls for Cascading.

On all other servers in a cascading chain, edit the chaining configuration entry for the cascading suffix with the following command:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn=databaseName,cn=chaining database,cn=plugins,cn=config
replace: nsHopLimit
nsHopLimit: maximumHops
^D

where maximumHops has the same definition as in the previous step.

Transmitting LDAP Controls for Cascading

By default, a chained suffix does not transmit the Proxy Authorization control. However, when one chained suffix contacts another, this control is needed to transmit the user identification required for access control on the remote server. The intermediate chained suffixes must allow this control to chain.

Recently, a second protocol was defined for the Proxy Authorization control. Because different server versions may use either control, you should configure all cascading servers to allow both the old and the new Proxy Authorization control to chain.

The Loop Detection control is also needed to prevent loops during cascading chaining. By default it is allow to be forwarded with chained operations, but you should verify this configuration. If a server does not allow this control to chain, any loop involving that server will not be detected.

Previous Contents Index Next
Sun Java(TM) System Directory Server 5.2 2005Q1 Administration Guide