Previous     Contents     Index     DocHome     Next     
iPlanet Directory Server 5.1 Administrator's Guide



Chapter 3   Configuring Directory Databases


Your directory is made up of databases over which you can distribute your directory tree. This chapter describes how to create suffixes, the branch points for your directory tree, and how to create the databases associated with each suffix. This chapter also describes how to create database links to reference databases on remote servers and how to use referrals to point clients to external sources of directory data.

This chapter includes the following sections:

For conceptual information on distributing your directory data, refer to the iPlanet Directory Server Deployment Guide.



Creating and Maintaining Suffixes


You can store different pieces of your directory tree in different databases, and then distribute these databases across multiple servers. Your directory tree contains branch points called nodes. These nodes can either be associated with databases or not. You create nodes using the Directory tab in the Directory Server Console, where you freely edit the entries that appear in your directory tree.

A suffix is a node of your directory tree associated with a particular database. You create these special nodes using the Database tab on the Directory Server Console. For example, a simple directory tree might appear as follows:



The ou=people suffix and all the entries and nodes below it might be stored in one database, the ou=groups suffix on another database, and the ou=contractors suffix on yet another database.

This section describes creating suffixes on your directory server and associating them with databases. This section contains procedures for the following:


Creating Suffixes

You can create both root and sub suffixes to organize the contents of your directory tree. A root suffix is the parent of a sub suffix. It can be part of a larger tree you have designed for your directory server. A sub suffix is a branch underneath a root suffix. The data for root and sub suffixes are contained by databases.

Your directory might contain more than one root suffix. For example, an ISP might host several websites, one for siroe.com and one for i-zed.com. The ISP would create two root suffixes, one corresponding to the dc=siroe,dc=com naming context and one corresponding to the dc=i-zed,dc=com naming context. The directory tree appears as follows:



You can also create root suffixes to exclude portions of your directory tree from search operations. For example, siroe.com Corporation might want to exclude their European office from a search on the general siroe.com Corporation directory. To do this, they create two root suffixes. One root suffix corresponds to the general siroe.com Corporation directory tree, dc=siroe,dc=com, and one root suffix corresponds to the European branch of their directory tree, l=europe,dc=siroe,dc=com. From a client application's perspective, the directory tree looks as follows:



Searches performed by client applications on the dc=siroe,dc=com branch of siroe.com Corporation's directory will not return entries from the l=europe,dc=siroe,dc=com branch of the directory, as it is a separate root suffix.

If siroe.com Corporation decides that they want to include the entries in the European branch of their directory tree in general searches, they would make the European branch a sub suffix of the general branch. To do this, they create a root suffix siroe.com Corporation, dc=siroe,dc=com, and then create a sub suffix beneath it for their European directory entries, l=europe,dc=siroe,dc=com. From a client application's perspective, the directory tree would appear as follows:



This section describes creating root and sub suffixes for your directory using either the Directory Server Console or the command line. This section contains the following procedures:


Creating a New Root Suffix Using the Console

The following procedure describes creating a suffix and associating it with a database:

  1. On the Directory Server Console, select the Configuration tab.

  2. Right-click Data in the left navigation pane and select New Root Suffix from the pop-up menu.

    The "Create new root suffix" dialog box is displayed.

  3. Enter a unique suffix name in the "New suffix" field.

    The suffix should be named according to domain-component (dc) naming conventions. For example, you might enter a new suffix name of dc=siroe,dc=com.

  4. The "Create associated database automatically" checkbox is selected by default if you want to create the database in the current directory at the same time as the new root suffix.

    Deselect this checkbox if you want to create the database for the new root suffix in a different directory or at a later time. The new root suffix will be disabled until you create its database.

  5. If you selected the "Create associated database automatically" checkbox in Step 4, enter a unique name for the new database in the "Database name" field.

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

  6. Click OK to create the new root suffix.

    The root suffix appears automatically under the Data branch in the left navigation pane.


Creating a New Sub-Suffix Using the Console

The following procedure describes creating a sub-suffix under an already existing root or sub-suffix:

  1. On the Directory Server Console, select the Configuration tab.

  2. Under the Data in the left navigation pane, select the suffix under which you want to add a new sub suffix. Right-click the suffix and select New Sub-Suffix from the pop-up menu.

    The "Create new sub-suffix" dialog box is displayed.

  3. Enter a unique suffix name in the "New suffix" field.

    The suffix should follow the naming conventions of its root suffix. The root suffix is automatically added to the name. For example, if you are creating the sub-suffix ou=groups under the dc=siroe,dc=com root suffix, the console automatically names it ou=groups,dc=siroe,dc=com.

  4. The "Create associated database automatically" checkbox is selected by default if you want to create the database in the current directory at the same time as the new root suffix.

    Deselect this checkbox if you want to create the database for the new sub-suffix in a different directory or at a later time. The new suffix will be disabled until you create its database.

  5. If you selected the "Create associated database automatically" checkbox in Step 4, enter a unique name for the new database in the "Database name" field.

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

  6. Click OK to create the new sub-suffix.

    The new suffix appears automatically under its root suffix in the Data tree in the left navigation pane.


Creating Root and Sub Suffixes From the Command Line

Use the ldapmodify command-line utility to add new suffixes to your directory configuration file. The suffix configuration information is stored in the cn=mapping tree,cn=config entry.


Note Avoid creating entries under the cn=config entry in the dse.ldif file. The cn=config entry in the simple, flat dse.ldif configuration file is not stored in the same highly scalable database as regular entries. As a result, if many entries, and particularly entries that are likely to be updated frequently, are stored under cn=config, performance will probably suffer.

However, although we recommend you do not store simple user entries under cn=config for performance reasons, it can be useful to store special user entries such as the Directory Manager entry or Replication Manager (supplier bind DN) entry under cn=config, as this allows you to centralize configuration information.


For example, you want to add a new root suffix to the configuration file using the ldapmodify utility. Run ldapmodify as follows:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password

The ldapmodify utility binds to the server and prepares it to add an entry to the configuration file.

Next, you create the root suffix entry for siroe.com Corporation as follows:

dn: cn="dc=siroe,dc=com",cn=mapping tree,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsMappingTree
nsslapd-state: backend
nsslapd-backend: UserData
cn: dc=siroe,dc=com

To create a sub suffix for groups under this root suffix, you would do an ldapmodify operation to add the following entry:

dn: cn="ou=groups,dc=siroe,dc=com",cn=mapping tree,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsMappingTree
nsslapd-state: backend
nsslapd-backend: GroupData
nsslapd-parent-suffix: "dc=siroe,dc=com"
cn: ou=groups,dc=siroe,dc=com


Note If you want to maintain your suffixes using the Directory Server Console, you will need to respect the same spacing you use to name the root and sub suffixes via the command line.

For example, if you name a root suffix ou=groups  ,dc=siroe,dc=com (with two spaces after groups), any sub suffixes you create under this root will need to specify two spaces after ou=groups as well.


The following table describes the attributes used to configure a suffix entry:


Table 3-1    Suffix Attributes

Attribute Name

Value

dn  

Defines the DN for the suffix. The DN is contained in quotes. The value you enter takes the following form: cn="dc=domain,dc=com",cn=mapping tree,
 cn=config

This attribute is required.  

cn  

Defines the relative DN (RDN) of the entry.

This attribute is required.  

objectclass  

Tells the server that the entry is root or sub suffix entry. It always takes the value nsMappingTree.

This attribute is required.  

nsslapd-state  

Determines how the suffix handles operations. This attribute takes the following values:

  • backend: the backend (database) is used to process all operations.

  • disabled: the database is not available for processing operations. The server returns a "No such search object" error in response to requests made by client applications.

  • referral: a referral is returned for requests made to this suffix.

  • referral on update: the database is used for all operations except update requests, which receive a referral.

The default value is disabled.  

nsslapd-referral  

Defines the LDAP URL of the referral to be returned by the suffix. This attribute can be multi valued, with one referral per value. This attribute is required when the value of the nsslapd-state attribute is referral or referral on update.  

nsslapd-backend  

Gives the name of the database or database link used to process requests. This attribute can be multi valued, with one database or database link per value. Refer to "Creating and Maintaining Database Links" for more information about database links.

This attribute is required when the value of the nsslapd-state attribute is set to backend or referral on update.  

nsslapd-distribution-plugin  

Specifies the shared library to be used with the custom distribution function. This attribute is required only when you have specified more than one database in the nsslapd-backend attribute.

Refer to "Creating and Maintaining Databases" for more information about the custom distribution function.  

nsslapd-distribution-funct  

Specifies the name of your custom distribution function. This attribute is required only when you specify more than one database in the nsslapd-backend attribute.

Refer to "Creating and Maintaining Databases" for more information about the custom distribution function.  

nsslapd-parent-suffix  

Provides the DN of the parent entry for a sub suffix. By default, this attribute is not present, which means that the suffix is regarded as a root suffix.

For example, you want to create a sub suffix o=sales,dc=siroe,dc=com under the root suffix dc=siroe,dc=com. Add the following value to the nsslapd-parent-suffix attribute of the sub suffix:
nsslapd-parent-suffix: "dc=siroe,dc=com"  


Maintaining Suffixes

This section describes the following procedures:


Using Referrals in a Suffix

Referrals can 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 when the database associated with the suffix is taken off-line for maintenance.

For more information on referrals in general, refer to iPlanet Directory Server Deployment Guide.

To set referrals in a suffix:

  1. On the Directory Server Console, select the Configuration tab.

  2. Under Data in the left pane, click the suffix to which you want to add a referral.

  3. Click the Suffix Settings tab. Select the Use Referrals radio button.

  4. Click the Referrals tab. Enter an LDAP URL in the "Enter a new referral" field or click Construct to be guided through the creation of an LDAP URL.

    For more information about the structure of LDAP URLs, refer to Appendix C, "LDAP URLs."

  5. Click Add to add the referral to the list.

    You can enter multiple referrals. The directory will return the entire list of referrals in response to requests from client applications.

  6. Click Save.


Enabling Referrals Only During Update Operations

You may want to configure your directory to redirect update and write requests made by client applications to a read-only database.

For example, you can enable referrals for update operations when you have a local copy of the directory data that you do not own. You want the data to be available for searches but not for updates. You do this by enabling referrals only during update requests. When a client application asks to update an entry, the client is referred to the server that owns the data, where the modification request can proceed.

To enable referrals only during update operations:

  1. On the Directory Server Console select the Configuration tab.

  2. Under Data in the left pane, click the suffix to which you want to add a referral.

  3. Click the Suffix Settings tab. Select the "Use Referrals on Update" radio button.

  4. Click the Referrals tab. Enter an LDAP URL in the "Enter a new referral" field or click Construct to be guided through the creation of an LDAP URL.

    For more information about the structure of LDAP URLs, refer to Appendix C, "LDAP URLs."

  5. Click Add to add the referral to the list.

    You can enter multiple referrals. The directory will return the entire list of referrals in response to requests from client applications.

  6. Click Save.


Disabling a Suffix

Sometime you may need to take down a database for maintenance, but the data the database contains is not replicated. Rather than returning a referral, you can disable the suffix responsible for the database.

Once you disable a suffix, the contents of the database related to the suffix are invisible to client applications when they perform LDAP operations such as search, add, and modify.

To disable a suffix:

  1. On the Directory Server Console select the Configuration tab.

  2. Under Data in the left navigation pane, click the suffix you want to disable.

  3. Click the Suffix Setting tab. Deselect the "Enable this suffix" checkbox.

    A red dot appears on the Suffix Setting tab to alert you to changes that need to be saved.

  4. Click Save.

    The suffix is no longer enabled.


Deleting a Suffix

The following procedure describes deleting a suffix:


Caution

When you delete a suffix, you also delete all database entries and replication information associated with that suffix.


  1. On the Directory Server Console select the Configuration tab.

  2. Under Data in the left navigation pane, select the suffix you want to delete.

  3. Select "Delete..." from the Object menu.

    You can also right-click the suffix and select "Delete..." from the pop-up menu.

  4. Select "Delete this suffix and all of its sub suffixes" if you want to remove all the suffix and every suffix below it.

    Select "Delete this suffix only" if you want to remove only this particular suffix, not its sub suffixes.

  5. Click OK to delete the suffix.

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



Creating and Maintaining Databases

After you create suffixes for organizing your directory data, you create databases to contain your directory data. Databases are used to store your directory data.

This section contains information about creating databases to contain your directory data, deleting databases, and making databases temporarily read-only.


Creating Databases

iPlanet Directory Server 5.0 supports the use of multiple databases over which you can distribute your directory tree. There are two ways you can distribute your data across multiple databases:

  • One database per suffix.

    The data for each suffix is contained in a separate database. For example, your directory tree appears as follows:



    You add three databases to store the data contained in your separate suffixes as follows:



    This division of the tree corresponds to three databases as follows:



    Database one contains the data for ou=people plus the data for dc=siroe,dc=com, so that clients can conduct searches based at dc=siroe,dc=com. Database two contains the data for ou=groups, and database three contains the data for ou=contractors.

  • Multiple databases for one suffix.

    For example, suppose the number of entries in the ou=people branch of your directory tree is so large that you need two databases to store them. In this case, the data contained by ou=people could be distributed across two databases. This is illustrated as follows:



    Database one contains people with names from A-K and database two contains people with names from L-Z. Database three contains the ou=groups data, and database four contains the ou=contractors data.

    You need to use the custom distribution plug-in to distribute data from a single suffix across multiple databases. Contact iPlanet Professional Services for information on how to create distribution logic for your directory server. For more information about Professional Services, go to http://www.iplanet.com/services/.


Creating a New Database for an Existing Suffix Using the Console

The following procedure describes adding a database to a suffix you have already created:

  1. In the iPlanet Directory Server Console, select the Configuration tab.

  2. In the left pane, expand Data then click the suffix to which you want to add the new database.

  3. Right-click the suffix and select New Database from the pop-up menu.

    The "Create New Database" dialog box is displayed.

  4. In the "Create New Database" dialog box, enter a unique name for the database.

    This value cannot contain commas, tabs, an equals sign (=), asterisk (*), backslash (\), forward slash (/), plus sign (+), quote (`), double quote ("), or a question mark (?). For example, you might name the new database siroe2.

  5. In the "Create database in" field, enter the path to the directory where you want to store the new database. You can also click Browse to locate a directory on your local machine.

    By default, the directory stores the new database in the following directory:

    /var/ds5/slapd-serverID/db

  6. Click OK. Click Yes in the confirmation dialog to create the new database.


    Note To see the new suffix in the Directory tab, you first need to create a root entry associated with the suffix. Refer to "Creating Directory Entries," on page 43.



Creating a New Database for a Single Suffix From the Command Line

Use the ldapmodify command-line utility to add a new database to your directory configuration file. The database configuration information is stored in the cn=ldbm database,cn=plugins,cn=config entry.

For example, you want to add a new database to the server siroe1. Add a new entry to the configuration file by performing an ldapmodify as follows:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password

The ldapmodify utility binds to the server and prepares it to add an entry to the configuration file.

Next, you create the entry for the new database as follows:

dn: cn=UserData,cn=ldbm database,cn=plugins,cn=config
objectclass: extensibleObject
objectclass: nsBackendInstance
nsslapd-suffix: ou=people,dc=siroe,dc=com

The entry added corresponds to a database named UserData that contains the data for the root or sub suffix ou=people,dc=siroe,dc=com.

To create a root or sub suffix from the command line, refer to "Creating Root and Sub Suffixes From the Command Line". The database name, given in the DN attribute, must correspond with the value in the nsslapd-backend attribute of the suffix entry.


Adding Multiple Databases for a Single Suffix

You can distribute a single suffix across multiple databases. However, to distribute the suffix you need to create a custom distribution function to extend the directory. For more information on creating a custom distribution function, contact iPlanet Professional Services. For more information about Professional Services, go to http://www.iplanet.com/services/l.


Note Once you have distributed entries, you cannot redistribute them. The following restrictions apply:

  • You cannot change your distribution function once you have deployed entry distribution.

  • You cannot use the LDAP modrDN operation to rename entries if that would cause them to be distributed into a different database.

  • You cannot replicate distributed local databases.

  • You cannot use the ldapmodify operation to change entries if that would cause them to be distributed into a different database.

Violating these restrictions prevents iPlanet Directory Server from correctly locating and returning entries.


Once iPlanet Professional Services has helped you create a custom distribution logic plug-in, you need to add it to your directory. The following procedures describe adding distribution logic to a suffix in your directory.


Adding the Custom Distribution Function to a Suffix

The distribution logic is a function declared in a suffix. This function is called for every operation reaching this suffix, including subtree search operations that start above the suffix. You can insert a distribution function into a suffix using both the console and the command line.

For information about creating your own custom distribution logic, contact iPlanet Professional Services.


Adding Custom Distribution Using the Console

  1. On the Directory Server Console, select the Configuration tab.

  2. Expand Data in the left navigation pane. Select the suffix to which you want to apply your distribution function.

  3. Select the Databases tab in the right window.

  4. Click Add to associate additional databases with the suffix.

    The "Database List" dialog box is displayed. Select a database from the list and click OK.

  5. Enter the path to your distribution library in the "Distribution library" field, or click Browse to locate a distribution library on your local machine.

  6. Enter the name of your distribution function in the "Function name" field.

  7. Click Save to save your changes.


Adding Custom Distribution From the Command Line
Use the ldapmodify command-line utility to add the following attributes to the suffix entry itself:

nsslapd-backend: Database1
nsslapd-backend: Database2
nsslapd-backend: Database3
nsslapd-distribution-plugin: /full/name/of/a/shared/library
nsslapd-distribution-funct: distribution-function-name

The nsslapd-backend attribute specifies all of the databases associated with this suffix. The nsslapd-distribution-plugin attribute specifies the name of the library that your plug-in uses. The nsslapd-distribution-funct attribute provides the name of the distribution function itself.

For more information about using the ldapmodify command-line utility, refer to "Adding and Modifying Entries Using ldapmodify," on page 53.


Maintaining Directory Databases

This section describes jobs associated with maintaining your directory databases. It includes the following procedures:


Placing a Database in Read-Only Mode

When a database is in read-only mode, you cannot create, modify, or delete any entries. For example, you must put a database in read-only mode if you are manually initializing a consumer.

If your directory server manages multiple databases, you can place all of them into read-only mode at the same time by placing your entire server in read-only mode. For more information, see "Placing the Entire Directory Server in Read-Only Mode," on page 37.

This section includes procedures for the following:


Making a Database Read-Only Using the Console
To place a database in read-only mode from the Server Console:

  1. On the iPlanet Directory Server Console select the Configuration tab.

  2. Expand Data in the left pane. Expand the Suffix containing the database you want to put in read-only mode.

  3. Select the database you want to put into read-only mode.

  4. Select the Database Settings tab in the right pane.

  5. Select the "Database is read-only" checkbox.

  6. Click Save.


Making a Database Read-Only From the Command Line
If you want to manually place a database into read-only mode, you must change the read-only attribute, nsslapd-readonly, to on. To do so, use the ldapmodify command-line utility. The nsslapd-readonly attribute for a particular database is located in the cn=database_name,cn=ldbm database,cn=plugins,cn=config entry (where database_name is the name of the database).


Note By default, the name of the database created at installation time is userRoot.



Deleting a Database

The following procedure describes deleting a directory database using the Directory Server Console. Deleting a database deletes the configuration information and entries for that database only, not the physical database itself.

  1. On the iPlanet Directory Server Console, select the Configuration tab.

  2. In the left navigation pane, locate the database you want to delete and select it.

  3. From the Object menu, select Delete.

    You can also right-click the database and select Delete from the pop-up menu.

    The Deleting Database confirmation dialog box is displayed.

  4. Click Yes to confirm that you want to delete the database.

    A progress dialog box appears telling you the steps the directory server completes during the deletion.

    Once deleted, the database no longer appears in the right pane.



Creating and Maintaining Database Links

Chaining is a method by which a server contacts other servers on behalf of a client application and then returns the combined results. This method is implemented through the database link. A database link 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.

The following sections describe how to create and configure a database link. For more general information about chaining, refer to "Designing the Directory Topology" in iPlanet Directory Server Deployment Guide.

You can create and configure a database link using Directory Server Console or the command line. The following sections describe the procedures for creating and maintaining a database link:

For information about monitoring the activity of your database links, refer to "Monitoring Database Link Activity," on page 412.


Configuring the Chaining Policy

These procedures describe configuring how your directory server chains requests made by client applications to directory servers that contain database links. This chaining policy applies to all database links you create on your directory server.

This section contains the following information:


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, you need to control the chaining policy so that the components can complete their operations successfully. For example, consider the certificate verification function. If you chain the LDAP request made by the function to check certificates, it implies that you trust the remote server. If the remote server is not trusted, then you have a security problem.

By default, all internal operations are not chained. However, you can override this default by specifying components that you want to chain using the console or the command line. By default, no components are allowed to chain.

You must also create an ACI on the remote server to allow the plug-in you specify to perform its operations on the remote server. You create the ACI 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 you create on the remote server:


Table 3-2    Components Allowed to Chain

Component Name

Description

Permissions

ACI plug-in  

This 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 retrieve user entries may be chained. Specify the following value in nsActiveChainingComponents attribute:

nsActiveChainingComponents: cn=ACI
 Plugin,cn=plugins,cn=config  

Read, search, and compare  

4.0 plug-ins  

This component name represents all Directory Server 4.0 plug-ins. The 4.0 plug-ins share the same chaining policy. Specify the following in the nsActiveChainingComponents attribute:

nsActiveChainingComponents: cn=old
 plugin,cn=plugins,cn=config  

Depends upon the 4.0 plug-in you are allowing to chain  

Resource limit component  

This component sets server limits depending on the user bind DN. You can apply resource limits on remote users if the resource limitation component is allowed to chain. To chain this component's operations, specify the following:

nsActiveChainingComponents: cn=resource
 limits,cn=components,cn=config  

Read, search, and compare  

Certificate-based authentication checking component  

This component is used when the SASL-external bind method is used. It retrieves the user certificate from the database on the remote server. If you allow this component to chain, certificate-based authentication can work with a database link. To chain this component's operations, specify the following:

nsActiveChainingComponents:
 cn=certificate-based
 authentication,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, if you delete an entry that is a member of a group, 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, specify the following:

nsActiveChainingComponents:
 cn=referential integrity
 postoperation,cn=plugins,cn=config  

Read, write, search, and compare  

UID uniqueness plug-in  

This plug-in checks that all the values for a specified uid attribute are unique (no duplicates). If you allow this plug-in to chain, it confirms that the uid attribute values are unique even on attributes changed through a database link. To chain this component's operations, specify the following:

nsActiveChainingComponents: cn=uid
 uniqueness,cn=plugins,cn=config  

Read, search, and compare  


Note You cannot chain the following components:

  • Roles plug-in

  • Password policy component

  • Replication plug-ins

For further information on the limitations surrounding ACIs and chaining see "ACI Limitations" on page 190.


Once you have modified the component you allow to chain, you must restart the server in order for the modification to take affect.

The following sections describe how to specify components you want to allow to chain using the console and from the command line.


Chaining Component Operations Using the Console

  1. On 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. To add a component to the "Components allowed to chain" list, click Add.

    The "Select Components to Add" dialog box displays. Select a component from the list and click OK.

  4. To delete a component from the list, select it and click Delete.

  5. After making modifications to the components list, a red dot appears on the tab and the field name turns gray. Click Save to save your changes.

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

After allowing the component to chain, you must create an ACI in the suffix on the remote server to which the operation will be chained. For example, you would create the following ACI for the referential integrity plug-in:

aci: (targetattr  "*")(target="ldap:///ou=customers,l=us,dc=siroe,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";)


Chaining Component Operations From the Command Line
You can specify components you want 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, if you want to allow the referential integrity component to chain operations, you add the following to your database link configuration file:

nsActiveChainingComponents: cn=referential integrity postoperation,
 cn=components,cn=config

Refer to Table 3-2 for a list of the components you can allow to chain.

Once you have modified the nsActiveChainingComponents attribute, you must restart the server for your change to take affect.

After allowing the component to chain, you must create an ACI in the suffix on the remote server to which the operation will be chained. For example, you would create the following ACI for the referential integrity component:

aci: (targetattr  "*")(target="ldap:///ou=customers,l=us,dc=siroe,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";)


Chaining LDAP Controls

You can choose 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:

  • Managed DSA - This controls returns smart referrals as entries rather than following the referral. This allows you to change or delete the smart referral itself.

  • Loop detection - This control keeps track of the number of times the server chains with another server. When the count reaches a number you configure, a loop is detected and the client application is notified.

    For more information about using this control, refer to "Detecting Loops".

  • Server side sorting - This control sorts entries according to their attribute values.

  • Virtual list view (VLV) - This control provides lists containing partial results rather than returning all entries in the search results once.


    Note Server side sorting and VLV controls are supported through chaining only when the scope of the search is a single database. Database links cannot support VLV controls when a client application makes a request to multiple databases.


The following sections describe how to alter the controls that the database link forwards using the console and from command line.


Chaining LDAP Controls Using the Console

  1. On 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. To add an LDAP control to the list, click Add.

    The "Select control OIDs to add" dialog box displays. Select the OID of a control you want to add to the list and click OK.

  4. To delete a control from the list, select it from the "LDAP controls forwarded to the remote server" list and click Delete.

  5. After making modifications to the components list, a red dot appears on the tab and the components field name turns gray. Click Save to save your changes.


Chaining LDAP Controls From the Command Line
You can 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, you add the following to your database link entry in the configuration file:

nsTransmittedControls: 2.16.840.1.113730.3.4.9

In addition, if clients of your directory server create their own controls and you want their operations to be chained to remote servers, you need to add the OID of the custom control to the nsTransmittedControls attribute.

The LDAP controls you can chain and their OIDs are listed in the following table:


Table 3-3    LDAP Controls and Their OIDs

Control Name

OID

Virtual list view (VLV)  

2.16.840.1.113730.3.4.9  

Server side sorting  

1.2.840.113556.1.4.473  

Managed DSA  

2.16.840.1.113730.3.4.2  

Loop detection  

1.3.6.1.4.1.1466.29539.12  

For more information about LDAP controls, refer to the LDAP C-SDK documentation on http://docs.iplanet.com/docs/manuals/directory.html.


Creating a New Database Link

The basic configuration of your database link involves providing the following information:

Suffix information. You create a suffix in your 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. You need to specify the DN and the credentials you want each database link to use to bind with remote servers.

LDAP URL. You provide the LDAP URL of the remote server to which the database link connects.

List of failover servers. You can provide a list of alternative servers for the database link to contact in the event of a failure. This configuration item is optional.


Note This option must not be used in the case of a secure link using SSL.


The following sections describe creating a new database link from the Directory Server Console as well as the command line.


Creating a New Database Link Using the Console

To create a new database link using the Directory Server Console:

  1. On the iPlanet Directory Server Console, select the Configuration tab

  2. Right-click Data in the left navigation pane and select New Root Suffix or New Sub Suffix from the pop-up menu.

    A "Create New Suffix" dialog box is displayed.

  3. Enter the name of the suffix on the remote server to which you want to chain in the "New suffix" field.

    The suffix must be named according to dc naming conventions. For example, you might enter a new suffix name of dc=siroe,dc=com.

  4. Deselect the "Create associated database automatically" checkbox.

    You deselect the checkbox because you cannot add a database link to a suffix that is associated with a database. This suffix is used only by the database link.

  5. Click OK to create the new suffix.

    The suffix appears automatically under the Data branch in the left navigation pane.

  6. In the left pane, right-click the suffix you just created and select "New Database Link" from the pop-up menu.

    The Create New Database Link dialog box is displayed.

  7. Enter the name of the new database link in the "Database link name" field.

    Use only ASCII (7-bit) characters for naming the database link. This value cannot contain commas, tabs, an equals sign (=), asterisk (*), backslash (\), forward slash (/), plus sign (+), quote (`), double quote ("), or a question mark (?). For example, you might name the new database link siroelink1.

  8. Enter the DN used by the database link to bind to the remote server in the "Bind DN" field.

    For example, you might enter cn=dblink in the "Bind DN" field.

  9. Enter the password used by the database link to bind to the remote server in the "Password" field.

  10. Select the "Use a secure LDAP connection between servers" checkbox if you want the database link to use SSL to communicate to the remote server.

  11. Enter the name of the remote server in the "Remote server" field. Enter the server port number used for the bind in the "Remote server port" field. The default port number is 389.

  12. Enter the name of a failover server in the "Failover Server(s)" field and specify a port number in the "Port" field. The default port number is 389. Click Add to add the failover server to the list.

    You can specify multiple failover servers. If the primary remote server fails, the database link contacts the first server in the Failover Servers list. If it fails, it contacts the next in the list and so on.

  13. Click OK to create the new database link. Click OK to dismiss the success dialog box that appears after the database link has been created.

    Your new database link appears under the suffix in the left navigation pane.


    Tip The console provides you with a checklist of information that needs to be present on the remote server for your database link to successfully bind. To view this checklist, click your new database link and click the Authentication tab. The checklist appears in the "Remote server checklist" box.



Creating a Database Link From the Command Line

Use the ldapmodify command-line utility to create a new database link from the command line.

Your new instance must be located in the cn=chaining database,cn=plugins, cn=config entry.

Default configuration attributes are contained in the cn=default 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. You cannot change the default configuration attributes on existing database links.

Each database link contains its own specific configuration information, which is stored with the database link entry itself, cn=database_link_name,cn=chaining database,cn=plugins,cn=config. For more information about configuration attributes, refer to the iPlanet Directory Server Configuration, Command, and File Reference.

This section contains the following procedures for configuring a database link from the command line:


Providing Suffix Information
Use the nsslapd-suffix attribute to define the suffix managed by your database link. For example, if you want your database link to point to the people information for a remote site of your company, you would enter the following suffix information:

nsslapd-suffix: l=Zanzibar,ou=people,dc=siroe,dc=com

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


Note After creation time, any alterations you make to the nsslapd-suffix attribute occur only after you have restarted the server containing the database link.



Providing Bind Credentials
For a request from a client application to be chained to a remote server, you can provide special bind credentials for the client application. This gives the remote server the proxied authorization rights needed to chain operations. If you do not specify bind credentials, the database link binds to the remote server as anonymous.

Providing bind credentials involves the following steps:

  1. On the remote server, you need to do the following:

    1. Create an administrative user for the database link.

      For information on adding entries, see "Creating Directory Entries," on page 41.

    2. Provide proxy access rights for the administrative user created in step 1 on the subtree chained to by the database link.

      For more information on configuring ACI's, refer to "Managing Access Control," on page 187.

  2. On the server containing the database like, you need to do the following:

    1. Use ldapmodify to provide a user DN for the database link in the nsMultiplexorBindDN attribute of the cn=database_link_name,cn=chaining database,cn=plugins,cn=config entry.


      Caution

      		The nsMultiplexorBindDN cannot be that of the Directory Manager.


    2. Use ldapmodify to provide a user password for the database link in the nsMultiplexorCredentials attribute of the cn=database_link_name,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 you must set the proxy authentication rights for this user. To set the proxy authorization right, you need to set the "proxy" ACI as you would any other ACI.


Caution

Carefully examine access controls when enabling chaining to avoid giving access to restricted areas of your directory. For example, if you create a default proxy ACI 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 you do not want all of the subtrees to be viewed by a user. To avoid a security hole, you may need to create an additional ACI to restrict access to the subtree.


For more information on ACIs, refer to "Managing Access Control," on page 187. For more information about the proxy authentication control, refer to the C-SDK documentation at http://developer.iplanet.com/docs/manuals/directory.html.


Note When a database link is used by a client application to create or modify entries, the attributes creatorsName and modifiersName do not reflect the real creator or modifier of the entries. These attributes contain the name of the administrative user granted proxied authorization rights on the remote data server.



Providing an LDAP URL
On the server containing your database link, you have to 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 following form:

ldap://servername:portnumber/

You specify the URL of the remote server using the nsFarmServerURL attribute in the cn=database_link_name,cn=chaining database,cn=plugins,cn=config entry of the configuration file. For example, the nsFarmServerURL might appear as follows:

nsFarmServerURL: ldap://siroe.com:389/

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

If you want to the database link to connect to the remote server using LDAP over SSL, the LDAP URL of the remote server takes the following form:

ldaps://servername:portnumber/

For more information about chaining and SSL, refer to "Chaining Using SSL".


Providing a List of Failover Servers
You can include additional LDAP URLs for servers to use in the case of failure. To do so, add alternate servers to the nsFarmServerURL attribute, separated by spaces. For example, you might enter the following:

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

In this sample LDAP URL, the database link first contacts the server siroe.com on the standard port to service an operation. If it does not respond, the database link then contacts the server us.siroe.com on port 389. If this server fails, it then contacts africa.siroe.com on port 1000.


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.

Attributes marked with an asterisk (*) can be both global or instance attributes. All instance attributes are defined in the cn=database_link_name,cn=chaining database,cn=plugins,cn=config entry.

The two global configuration attributes are located in the cn=config,cn=chaining database,cn=plugins,cn=config entry. The global attributes are dynamic, meaning any changes you make to them will automatically take effect on all instances of the database link within your directory.

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


Table 3-4    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 you make to this attribute after the entry has been created take effect only after you restart the server containing the database link.  

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.  

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. Allows you to disable 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 to not allow chaining. Refer to "Chaining Component Operations" for more information.  

nsReferralOnScopedSearch  

Controls whether or not referrals are returned by scoped searches. This attribute is for optimizing your 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.  


Database Link Configuration Example
Suppose you have a server within the us.siroe.com domain that contains the subtree l=Walla Walla,ou=people,dc=siroe,dc=com on a database and that you want to chain operation requests for l=Zanzibar,ou=people,dc=siroe,dc=com to a different server in the africa.siroe.com domain. This operation is illustrated in the following diagram:



First, use the ldapmodify command-line utility to add a database link to server A:

ldapmodify -a -h us.siroe.com -p port \
          -D "cn=Directory Manager" -w password

Then 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: l=Zanzibar,ou=people,dc=siroe,dc=com
nsfarmserverurl: ldap://africa.siroe.com:389/
nsmultiplexorbinddn: cn=proxy admin,cn=config
nsmultiplexorcredentials: secret
cn: DBLink1

dn: cn="l=Zanzibar,ou=people,dc=siroe,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=siroe,dc=com"
cn: l=Zanzibar,ou=people,dc=siroe,dc=com

In the first section, the nsslapd-suffix attribute contains the suffix on server B that you want to chain to from server A. The nsFarmServerURL attribute contains the LDAP URL of server B.

The second section 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 nssalpd-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=siroe,dc=com.

Next, you 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


Caution

Do not use the Directory Manager user as the proxy administrative user on the remote server. This creates a security hole.


Add the following proxy authorization ACI to the l=Zanzibar,
ou=people,dc=siroe,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=siroe,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 successfully modify or write data to the remote server, you need to 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, refer to "Database Links and Access Control Evaluation".



Chaining Using SSL

You can configure your database links to communicate with the remote server using SSL. Using SSL to chain involves the following steps:

When you configure the database link 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 can bind using a normal port.


Maintaining Database Links

This section describe how to update and delete existing database links. It contains the following procedures:


Updating Remote Server Authentication Information

To update the bind DN and password used by the database link to connect to the remote server:

  1. On the iPlanet Directory Server Console, select the Configuration tab.

  2. In the left pane, expand Data and locate the database link you want to update under one of the suffixes. Select the database link.

  3. In the right navigation pane, click the Authentication tab.

  4. To update the remote server information, enter a new LDAP URL in the "Remote Server URL" field.

    Unlike the standard LDAP URL format, the URL of the remote server does not specify a suffix. It takes the following form:

    ldap://servername:portnumber/

  5. Update the bind DN used by the database link to bind with the remote server by entering a new DN in the "Database link bind DN" field.

  6. Update the password used by the database link to bind with the remote server by entering a new password in the "Database link password" field. Confirm the password by retyping it in the "Confirm database link password" field.

    The remote server checklist box lists the administrative user entry, suffix, and ACI that need to exist on the remote server for the database link to successfully bind.

  7. Click Save to save your changes.


Deleting Database Links

To delete a database link:

  1. On the iPlanet Directory Server Console select the Configuration tab.

  2. In the left navigation pane, locate the database link you want to delete and select it.

  3. From the Object menu, select Delete.

    You can also right-click the database link and select Delete from the pop-up menu.

    The Deleting Database Link confirmation dialog box is displayed.

  4. Click Yes to confirm that you want to delete the database link.

    A progress dialog box appears telling you the steps the directory server completes during the deletion.

    Once deleted, the database link no longer appears in the right pane.


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

    For example, role based or filter based ACIs need access to the user entry. Because you are accessing the data via database links, only the data in the proxy control can be verified. Consider designing your 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, as 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 you create to use 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 users is 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 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_name,cn=chaining database,cn=plugins,cn=config entry. However, evaluating access controls on the server containing the database link is not recommended unless using cascading chaining.



Advanced Feature: Tuning Database Link Performance

The following sections provide information on tuning the performance of your database links through connection and thread management. It contains the following parts:


Managing Connections to the Remote Server

Each database link maintains a pool of connections to a remote server. You can configure the connections to optimize resources for your directory.

You can change the connection attributes using the Directory Server Console or through the command line.


Managing Connections to the Remote Server Using the Console

  1. On the Directory Server Console, select the Configuration tab.

  2. Expand the Data folder in the left pane and locate the database link you want to change. Click the database link, then click the Limits and Controls tab in the right navigation pane.

  3. In the Connection Management section, make changes to any of the following fields:

    Maximum TCP connection(s). The maximum number of TCP connections that the database link establishes with the remote server. The default value is 3 connections.

    Bind timeout. Amount of time, in seconds, before the database link's bind attempt times out. The default value is 15 seconds.

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

    Time out before abandon (sec). Number of seconds before the server checks to see if a timed out connection should be abandoned. The default value is 2 seconds.

    Maximum LDAP connection(s). Maximum number of LDAP connections that the database link establishes with the remote server. The default value is 10 connections.

    Maximum bind retries. Number of times a database link attempts to bind to the remote server. A value of 0 indicates that the database link will try to bind only once. The default value is 3 attempts.

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

    Connection lifetime (sec). How long a connection made between the database link and remote server remains open. You can keep connections between the database link and the remote server open for an unspecified time, or you can close them after a specific period of time.

    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.

    A value of 0 indicates there is no limit. By default, the value is set to 0.

  4. Click Save to save your changes.


Managing Connections to the Remote Server From the Command Line
Use ldapmodify to add connection attributes to your database link entry.

The default connection management attributes are stored in the following entry: cn=default instance config, cn=chaining database,cn=plugins,cn=config.

The connection management attributes for a specific database link are stored in the following entry: cn=database_link_name,cn=chaining database,cn=plugins,cn=config, where database_link_name is the name of the database link. The connection management attributes specified in this entry take precedence over the attributes specified in the cn=default instance config entry.

The following table lists the attributes associated with connection management:


Table 3-5    Database Link Connection Management Attributes 

Attribute Name

Description

nsOperationConnectionsLimit  

Maximum number of LDAP connections that the database link establishes with the remote server. The default value is 10 connections per database link instance.  

nsBindConnectionsLimit  

Maximum number of TCP connections that the database link establishes with the remote server. The default value is 3 connections.  

nsConcurrentOperationsLimit  

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

nsConcurrentBindLimit  

Maximum number of outstanding bind operations per TCP connection. The default value is 10 outstanding bind operations.  

nsBindRetryLimit  

Number of times a database link attempts to bind to the remote server. A value of zero (0) indicates that the database link will try to bind only once. The default value is 3 attempts.  

nsConnectionLife  

Connection lifetime, in seconds. You can keep connections between the database link and the remote server open for an unspecified time, or you can close them after a specific period of time.

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.

A value of 0 indicates there is no limit. By default, the value is set to 0. When the value is 0 and you provide a list of failover servers in the nsFarmServerURL attribute, the "main" server is never contacted after failover to the alternate server.

The default value is 0 seconds.  

nsBindTimeout  

Amount of time, in seconds, before the bind attempt times out. The default value is 15 seconds.  

nsAbandonedSearchCheckInterval  

Number of seconds that pass before the server checks for abandoned operations. The default value is 2 seconds.  

For the list of database link configuration attributes, refer to "Database Link Configuration Attributes".


Detecting Errors During Normal Processing

You can help protect server performance by detecting errors during the normal chaining operation between the database link and the remote server. The database link has two attributes which work together to determine if the remote server is no longer responding.

The first attribute, nsMaxResponseDelay, sets a maximum duration for an LDAP operation to complete. If the operation takes more than the amount of time specified in this attribute, the database link's server suspects that the remote server is no longer online.

Once the nsMaxResponseDelay period has been met, the database link pings the remote server. During the ping, the database link issues another LDAP request, a simple search request for an object that does not exist in the remote server. The duration of the ping is set using the nsMaxTestResponseDelay.

If the remote server does not respond before the nsMaxResponseDelay period has passed, then an error is returned and the connection is flagged as down. All connections between the database link and remote server will be blocked for 30 seconds, protecting your server from a performance degradation. After 30 seconds, operation requests made by the database link to the remote server continue as normal.

Both attributes are stored in the cn=config,cn=chaining database,cn=plugins,cn=config entry. The following table describes the attributes in more detail:


Table 3-6    Database Link Processing Error Detection Parameters

Attribute Name

Description

nsMaxResponseDelay  

Maximum amount of time it can take a remote server to respond to an LDAP operation request made by a database link before an error is suspected.This period is given in seconds. The default delay period is 60 seconds.

Once this delay period has been met, the database link tests the connection with the remote server.  

nsMaxTestResponseDelay  

Duration of the test issued by the database link to check whether the remote server is responding. If a response from the remote server is not returned before this period has passed, the database link assumes the remote server is down and the connection is not used for subsequent operations.

This period is given in seconds. The default test response delay period is 15 seconds.  


Managing Threaded Operations

Generally, iPlanet Directory Server performs best using a limited number of threads for processing operations. A limited number of threads can generally process operations very quickly, preventing the queue of operations waiting for a free thread from growing too long.

However, the database link forwards operations to remote servers for processing. The database link contacts the remote server, forwards the operation, waits for the result, and then sends the result back to the client application. The entire operation can take much longer than a local operation.

While the database link waits for results from the remote server, it can process additional operations. By default, the number of threads used by the server is 20. However, when using database links, you can improve performance by increasing the number of threads available for processing operations. While the local CPU waits for a response from a remote server, it can process other operations rather than stand idle.

To change the number of threads used for processing operations, change the nsslapd-threadnumber global configuration attribute in the cn=config entry. The default thread number is 20. For example, you can increase the thread number to 50 to improve performance. After changing the thread number, restart the server to implement your changes.


Advanced Feature: Configuring Cascading Chaining

You can configure your database link to point to another database link, creating a cascading chaining operation. A cascading chain occurs any time more than one hop is required to access all of the data in a directory tree.

The section contains the following topics:


Overview of Cascading Chaining

Cascading chaining occurs when more than one hop is required for the directory to process a client application's request.

For example, consider the following scenario:



The client application sends a modify request to server one. Server one contains a database link that forwards the operation to server two, which contains another database link. The database link on server two forwards the operations to server three, which contains the data the clients wants to modify in a database. Two hops are required to access the piece of data the client want to modify.

During a normal operation request, a client binds to the server and then any ACIs applying to that client are evaluated. With cascading chaining, the client bind request is evaluated on server one, but the ACIs applying to the client are evaluated only after the request has been chained to the destination server, in the above example server two.

Consider the following example scenario. On server A, a directory tree is split as follows:



The root suffix dc=siroe,dc=com, the ou=people and ou=groups sub suffixes are stored on Server A. The l=europe,dc=siroe,dc=com and ou=groups suffixes are stored in on Server B, and the ou=people branch of the l=europe,dc=siroe,dc=com suffix is stored on Server C.

With cascading configured on servers A, B, and C, a client request targeted at the ou=people,l=europe,dc=siroe,dc=com entry would be routed by the directory as follows:



First the client binds to Server A and chains to Server B using Database Link 1. Then Server B chains to the target database on Server C using Database Link 2 to access the data in the ou=people,l=europe,dc=siroe,dc=com branch. Because at least two hops are required for the directory to service the client request, this is considered a cascading chain.


Configuring Cascading Chaining Defaults Using the Console

To set cascading chaining defaults for all database links in your directory server:

  1. On the Directory Server Console, select the Configuration tab.

  2. Expand the Data folder in the left pane and click Database Link Settings. Click the Default Creation Parameters tab.

  3. Select the "Check local ACI" checkbox if you want to enable the evaluation of local ACIs on the intermediate database links involved in cascading chaining. If you select this checkbox, you will need to add the appropriate local ACIs to a database on the servers that contain intermediate database links.

    This is an advanced feature. For more information, refer to "Enabling Local ACI Evaluation".

  4. Enter the maximum number of times a database link can point to another database link in the "Maximum hops" field.

    By default, the maximum is 10 hops. After 10 hops, a loop is detected by the server and an error is returned to the client application.

  5. Click Save to save your changes.


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



Configuring Cascading Chaining Using the Console

To configure cascading chaining for a particular set of database links, do the following:

  1. On the Directory Server Console, select the Configuration tab.

  2. Expand the Data folder in the left pane and locate the database link you want to include in a cascading chain. Click the database link, then click the Limits and Controls tab in the right navigation pane.

  3. Select the "Check local ACI" checkbox if you want to enable the evaluation of local ACIs on the intermediate database links involved in the cascading chain. If you select this checkbox, you may need to add the appropriate local ACIs to the database link.

    This is an advanced feature. For more information, refer to "Enabling Local ACI Evaluation".

  4. Enter the maximum number of times a database link can point to another database link in the "Maximum hops" field.

    By default, the maximum is 10 hops. After 10 hops, a loop is detected by the server and an error is returned to the client application.

  5. Click Save to save your changes.


Configuring Cascading Chaining From the Command Line

Configuring a cascade of database links through the command line involves the following steps:

  • Pointing one database link to the URL of the server containing the intermediate database link.

  • Configuring the intermediate database link or links (in the example, server two) to transmit the Proxy Authorization Control.

  • Creating a proxy administrative user ACI on all intermediate database links. To do so, you will need to create a database on each server that contains an intermediate database link.

  • Enabling local ACI evaluation on all intermediate database links.

  • Creating client ACIs on all intermediate database links and the final destination database.

This section covers the following topics:


Pointing to Another Database Link
To create a cascading chain, the nsFarmServerURL attribute of one database link must contain the URL of the server containing another database link. For example, suppose the database link on the server called siroe1.com points to a database link on the server called africa.siroe.com. The cn=database_link_name,cn=chaining database, cn=plugins,cn=config entry of the database link on server one would contain the following:

nsFarmServerURL: ldap://africa.siroe.com:389


Transmitting the Proxy Authorization Control
By default, a database link does not transmit the Proxy Authorization Control. However, when one database link contacts another, this control is used to transmit information needed by the final destination server. The intermediate database link needs to transmit this control. To configure the database link to transmit the proxy authorization control, add the following to the cn=config,cn=chaining database,cn=plugins,cn=config entry of the intermediate database link:

nsTransmittedControls: 2.16.840.1.113730.3.4.12

The OID value represents the Proxy Authorization Control. For more information about chaining LDAP controls, refer to "Chaining LDAP Controls".


Creating the Proxy Administrative User ACI
You need to create an ACI on the server that contains the intermediate database link that checks the rights of the first database link before translating the request to another server. For example, if server two does not check the credentials of server one, then anyone could bind as anonymous and pass a proxy authorization control allowing them more administrative privileges than appropriate.

To prevent this security hole, you need to create an ACI on the server which contains the intermediate database link. To create an ACI, you need to do the following:

  1. Create a database, if one does not already exist, on the server containing the intermediate database link. This database will contain the admin user entry and the ACI. For information about creating a database, see "Creating Databases".

  2. Create an entry that corresponds to the administrative user in the database.

  3. Create an ACI for the administrative user that targets the appropriate suffix. This ensures the administrator has access only to the suffix of the database link. Add the following ACI to the administrative user's entry:

    aci: (targetattr = "*")(version 3.0; acl "Proxied authorization  for database links"; allow (proxy) userdn = "ldap:///cn=proxy  admin,cn=config";)

    This ACI is like the ACI you create on the remote server when configuring simple chaining.


    Caution

    		Carefully examine access controls when enabling chaining to avoid giving access to restricted areas of your directory. For example, if you create a default proxy ACI 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 you do not want all of the subtrees to be viewed by a user. To avoid a security hole, you may need to create an additional ACI to restrict access to the subtree.



Enabling Local ACI Evaluation
To confirm that the proxy administrative ACI is used, you need to enable evaluation of local ACIs on all intermediate database links involved in chaining. To do this, add the following attribute to the cn=database_link_name,cn=chaining database,cn=plugins,cn=config entry of each intermediate database link:

nsCheckLocalACI: on

Setting this attribute to on in the cn=default instance config,cn=chaining database,cn=plugins,cn=config entry means that all new database link instances will have the nsCheckLocalACI attribute set to on in their cn=database_link_name,cn=chaining database,cn=plugins,cn=config entry.


Creating Client ACIs
Because you have enabled local ACI evaluation, you need to create the appropriate client application ACIs on all intermediate database links as well as the final destination database.

To do this on the intermediate database links, you first need to create a database that contains a suffix that represents a root suffix of the final destination suffix.

For example, if you are chaining a client request made to the c=africa,ou=people,dc=siroe,dc=com suffix on a remote server, all intermediate database links need to contain a database associated with the dc=siroe,dc=com suffix.

You then need to add any client ACIs to this superior suffix entry. For example, you might add the following

aci: (targetattr = "*")(version 3.0; acl "Client authentication for  database link users"; allow (all) userdn = "ldap:///uid=*  ,cn=config";)

This ACI allows client applications that have a uid in the cn=config entry of server one to perform any type of operation on the data below the ou=people,dc=siroe,dc=com suffix on server three.


Detecting Loops
An LDAP control included with Directory Server prevents loops. When first attempting to chain, the server sets this control to be the maximum number of hops, or chaining connections, allowed. Each subsequent server decrements the count. If a server receives a count of 0 it determines that a loop has been detected and notifies the client application.

The number of hops allowed is defined using the nsHopLimit attribute. If not specified, the default value is 10.

To use the control, add the following OID to the nsTransmittedControl attribute in the cn=config,cn=chaining database,cn=plugins,cn=config entry:

nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12

If the control is not present in the configuration file of each database link, loop detection will not be implemented.


Summary of Cascading Chaining Configuration Attributes

The following table describes the attributes used to configure intermediate database links in a cascading chain:


Table 3-7    Cascading Chaining Configuration Attributes 

Attribute

Description

nsFarmServerURL  

URL of the server containing the next database link in the cascading chain.  

nsTransmittedControls  

Enter the following OIDs to the database links involved in the cascading chain:

nsTransmittedControls: 2.16.840.1.113730.3.4.12
nsTransmittedControls: 1.3.6.1.4.1.1466.29539.12

The first OID corresponds to the Proxy Authorization Control. The second OID corresponds to the Loop Detection Control.  

aci  

This attribute must contain the following ACI:

aci: (targetattr = "*")(version 3.0; acl  "Proxied authorization for database links";  allow (proxy) userdn = "ldap:///cn=proxy  admin,cn=config";)  

nsCheckLocalACI  

To enable evaluation of local ACIs on all database links involved in chaining, turn local ACI evaluation on as follows:

nsCheckLocalACI: on  


Cascading Chaining Configuration Example

To create a cascading chain involving three servers as in the diagram below, you have to configure the chaining components on all three servers. This section describes the configuration steps for creating a cascading chain involving three servers and is divided into the following sections:


Configuring Server One

First, use the ldapmodify command-line utility to add a database link to server one. Run the utility as follows:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password

Then specify the configuration information for the database link, DBLink1, on server one as follows:

dn: cn=DBLink1,cn=chaining database,cn=plugins,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsBackendInstance
nsslapd-suffix: l=Zanzibar,c=africa,ou=people,dc=siroe,dc=com
nsfarmserverurl: ldap://africa.siroe.com:389/
nsmultiplexorbinddn: cn=server1 proxy admin,cn=config
nsmultiplexorcredentials: secret
cn: DBLink1
nsCheckLocalACI:off

cn="l=Zanzibar,c=africa,ou=people,dc=siroe,dc=com",cn=mapping tree,cn=config
objectclass=nsMappingTree
nsslapd-state=backend
nsslapd-backend=DBLink1
nsslapd-suffix: l=Zanzibar,c=africa,ou=people,dc=siroe,dc=com
cn: l=Zanzibar,c=africa,ou=people,dc=siroe,dc=com

The first section creates the entry associated with DBLink1. The second section creates a new suffix, allowing the server to direct requests made to the database link to the correct server. You do not need to configure the nsCheckLocalACI attribute to check local ACIs, as this is only required on the database link, DBLink2, on server two.

Since you want to implement loop detection, you need to specify the OID of the loop detection control in the nsTransmittedControl attribute stored in cn=config,cn=chaining database,cn=plugins,cn=config entry on server one. You specify the OID as follows:

dn: cn=config,cn=chaining database,cn=plugins,cn=config
changeType: modify
add: nsTransmittedControl
nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12

As the nsTransmittedControl attribute is usually configured by default with the loop detection control OID 1.3.6.1.4.1.1466.29539.12 value, it is wise to check beforehand whether or not it already exists. If it does exist you do not need to perform this configuration step.


Configuring Server Two

Next, you create a proxy administrative user on server two. This administrative user will be used to allow server one to bind and authenticate to server two. Bear in mind that it is useful to choose a proxy administrative user name which is specific to server one as it is the proxy administrative user which will allow server one to bind to server two. You create the proxy administrative user as follows:

dn: cn=server1 proxy admin,cn=config
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: server1 proxy admin
sn: server1 proxy admin
userPassword: secret
description: Entry for use by database links


Caution

Do not use the Directory Manager or Administrator ID user as the proxy administrative user on the remote server. This creates a security hole.


Next, you configure the database link, DBLink2, on server two. Using ldapmodify, specify the configuration information for DBLink2 as follows:

dn: cn=DBLink2,cn=chaining database,cn=plugins,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsBackendInstance
nsslapd-suffix: l=Zanzibar,c=africa,ou=people,dc=siroe,dc=com
nsfarmserverurl: ldap://zanz.africa.siroe.com:389/
nsmultiplexorbinddn: cn=server2 proxy admin,cn=config
nsmultiplexorcredentials: secret
cn: DBLink2
nsCheckLocalACI:on

dn: cn="l=Zanzibar,c=africa,ou=people,dc=siroe,dc=com",cn=mapping tree,cn=config
objectclass: top
objectclass: extensibleObject
objectclass: nsMappingTree
nsslapd-state: backend
nsslapd-backend: DBLink2
nsslapd-parent-suffix:"c=africa,ou=people,dc=siroe,dc=com"
cn: l=Zanzibar,c=africa,ou=people,dc=siroe,dc=com

Since database link DBLink2 is the intermediate database link in your cascading chaining configuration, you need to set the nsCheckLocalACI to on, to allow the server to check whether or not it should allow the client and proxy administrative user access to the database link.

The database link on server two must be configured to transmit the proxy authorization control and the loop detection control. To implement the proxy authorization control and the loop detection control you need to specify both corresponding OIDs. Add the following information to the cn=config,cn=chaining database, cn=plugins,cn=config entry on server two:

dn: cn=config,cn=chaining database,cn=plugins,cn=config
changeType: modify
add: nsTransmittedControl
nsTransmittedControl: 2.16.840.1.113730.3.4.12
nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12

where nsTransmittedControl: 2.16.840.1.113730.3.4.12 is the OID for Proxy Authorization control and nsTransmittedControl: 1.3.6.1.4.1.1466.29539.12 is the OID for the loop detection control.

Again, remember to check beforehand whether or not the loop detection control is already configured, and adapt the above command accordingly.

The next step is to configure your ACIs. On server two you need to ensure that a suffix exists above the there is an existing suffix above the l=Zanzibar,c=africa,ou=people,dc=siroe,dc=com suffix to allow you to:

  • add the database link suffix

  • add a local proxy authorization ACI that will be used to allow server one to connect using the proxy authorization administrative user that will be created on server two, and

  • add a local client ACI that allows the client operation to succeed on server two, so that it can be forwarded to server three. This local ACI is needed because you have turned local ACI checking on for the DBLink2 database link.

Both ACIs will be placed on the database that contains the c=africa,ou=people,dc=siroe,dc=com suffix.


Note To create these ACIs it is assumed that the database corresponding to the c=africa,ou=people,dc=siroe,dc=com suffix already exists to hold the entry. This database needs to be associated with a suffix above the suffix specified in the nsslapd-suffix attribute of each database link. That is, the suffix on the final destination server should be a sub suffix of the suffix specified on the intermediate server.


Add the local proxy authorization ACI to the c=africa,ou=people,dc=siroe,dc=coml entry:

aci:(targetattr="*")(target="l=Zanzibar,c=africa,ou=people,
dc=siroe,dc=com")(version 3.0; acl "Proxied authorization for  database links"; allow (proxy) userdn = "ldap:///cn=server1 proxy  admin,cn=config";)

Then add the local client ACI that will allow the client operation to succeed on server two given that ACI checking is turned on. This ACI is the same as the ACI you will create on the destination server to provide access to the l=Zanzibar,c=africa,ou=people,dc=siroe,dc=com branch. You may decide that you want all users within c=us,ou=people,dc=siroe,dc=com to have update access to the entries in l=Zanzibar,c=africa,ou=people,dc=siroe,dc=com on server three. The following ACI is the ACI you would need to create on the c=africa,ou=people,dc=siroe,dc=com suffix on server two to allow this:

aci:(targetattr="*")(target="l=Zanzibar,c=africa,ou=people,
dc=siroe,dc=com")(version 3.0; acl "Client authorization for  database links"; allow (all) userdn = "ldap:///uid=*,c=us,ou=people,dc=siroe,dc=com";)

This ACI allows clients that have a uid in c=us,ou=people,dc=siroe,dc=com on server one to perform any type of operation on the l=Zanzibar,c=africa,ou=people,dc=siroe,dc=com suffix tree on server three. Should you have users on server two under a different suffix that will require additional rights on server three, you may need to add additional client ACIs on server two.


Configuring Server Three

The final configuration step in our cascading chaining example is to configure server three. First, you create an administrative user on server three for server two to use for proxy authorization:

dn: cn=server2 proxy admin,cn=config
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
cn: server2 proxy admin
sn: server2 proxy admin
userPassword: secret
description: Entry for use by database links

Then you need to add the same local proxy authorization ACI to server three as you did on server two. Add the following proxy authorization ACI to the l=Zanzibar,ou=people,dc=siroe,dc=com entry:

aci: (targetattr = "*")(version 3.0; acl "Proxied authorization for  database links"; allow (proxy) userdn = "ldap:///cn=server2 proxy  admin,cn=config";)

This ACI gives the server2 proxy admin read-only access to the data contained on the remote server, server three, within the l=Zanzibar,ou=people,dc=siroe,dc=com subtree only.

You then need to create an local client ACI on the l=Zanzibar,ou=people,dc=siroe,dc=com subtree that corresponds to the original client application. Use the same ACI as the one you created for the client on server two:

aci: (targetattr = "*")(target="l=Zanzibar,c=africa,ou=people,
 dc=siroe,dc=com")(version 3.0; acl "Client authentication for  database link users"; allow (all) userdn =
 "ldap:///uid=*,c=us,ou=people,dc=siroe,dc=com";)

Once you have completed all these steps your cascading chaining configuration is set up. This cascading configuration will allow you to bind to server one and modify information in the l=Zanzibar,c=africa,ou=people,dc=siroe,dc=com branch on server three. Depending on your security needs you may or may not want to provide more detailed access control.



Using Referrals


You can use referrals to tell client applications which server to contact for a specific piece of information. This redirection occurs when a client application requests a directory entry that does not exist on the local server or when a database has been taken offline for maintenance. This section contains the following information about referrals:

For conceptual information on how you can use referrals in your directory, see iPlanet Directory Server Deployment Guide.


Setting Default Referrals

Default referrals are returned to client applications that submit operations on a DN not contained within any of the suffixes maintained by your directory. The following procedures describes setting a default referral for your directory using the console and the command-line utilities.


Setting a Default Referral Using the Console

Set a default referral to your directory as follows:

  1. On the iPlanet Directory Server Console, select the Configuration tab.

  2. Select the top entry in the navigation tree in the left pane.

  3. Select the Settings tab in the right pane.

  4. Enter an LDAP URL in the "Referrals to" text box and click OK.

    For example:

    ldap://directory.siroe.com:389/dc=siroe,dc=com

    You can enter multiple referral URLs separated by spaces and in quotes as follows:

    "ldap://d1.siroe.com:389/dc=siroe,dc=com" "ldap://d2.siroe.com/"

For more information about LDAP URLs, refer to Appendix C, "LDAP URLs."


Setting a Default Referral From the Command Line

Use the ldapmodify command-line utility to add a default referral to the cn=config entry in your directory configuration file.

For example, to add a new default referral from your directory server, siroe.com, to a server named Zanzibar.com, add a new line to the cn=config entry. Run the ldapmodify utility as follows:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password

The ldapmodify utility binds to the server and prepares it to change an entry in the configuration file.

Next, you add the default referral to the Zanzibar.com server:

dn: cn=config
changetype: modify
replace: nsslapd-referral
nsslapd-referral: ldap://zanzibar.com/

Once you have added the default referral to the cn=config entry of your directory, the directory will return the default referral in response to requests made by client applications. You do not need to restart the server.


Creating Smart Referrals

Smart referrals allow you to map a directory entry or directory tree to a specific LDAP URL. Using smart referrals, you can refer client applications to a specific server or a specific entry on a specific server.

For example, a client application requests the following directory entry: uid=bjensen,ou=people,dc=siroe,dc=com. You return a smart referral to the client which points to the entry cn=Babs Jensen,o=people,l=europe,dc=siroe,dc=com on the server directory.europe.siroe.com.

The way the directory uses smart referrals conforms to the standard specified in RFC 2251 section 4.1.11. For more information, refer to the text of the RFC at http://www.ietf.org/rfc/rfc2251.txt.

The following procedures describe creating smart referrals using both the console and the command-line utilities.


Creating Smart Referrals Using the iPlanet Directory Server Console

  1. On the iPlanet Directory Server Console, select the Directory tab.

  2. Browse through the tree to locate the entry for which you want to add the referral.

  3. Right-click the entry and select Set Referrals from the drop-down menu.

    The Edit Referrals dialog box is displayed. If this is the first referral you are creating for the entry, the Referral List is empty.

  4. Check the Enable Referrals check box.

  5. Enter an LDAP URL in the "Enter a New Referral" field, or click Construct to display a dialog box that will help you create a correct URL.

    The elements of the URL include the host name and LDAP port number of the directory server that holds the referral entry, and the DN of the referral entry (target DN). This DN can be a suffix, a subtree, or a leaf entry.

  6. In the Edit Referrals dialog box, click Add to add the new LDAP URL to the list of referrals.

  7. Still in the Edit Referrals dialog box, click Authentication to display the dialog box that will prompt you for the credentials that the current server will use to bind to follow the referral to the remote server.

  8. Enter the DN and password of a user authorized to access the referral DN, and click OK to dismiss this dialog box.

  9. In the Edit Referrals dialog box, click OK to dismiss the window.

    In the navigation tree, you should see the referral subtree or entry in place of the original entry for which you created the referral. If you still see the original entry, it will have a warning icon next to it. This icon indicates that you have not performed Step 7, or that the bind DN and password that you provided are not authorized to access the referral DN.


Creating Smart Referrals From the Command Line

Use the ldapmodify command-line utility to create smart referrals from the command line.

To create a smart referral, create the relevant directory entry and add the Referral object class. This object class allows a single attribute, ref. The ref attribute is expected to contain an LDAP URL.

For example, add the following to return a smart referral for an existing entry, uid=bjensen:

dn: uid=bjensen,ou=people,dc=siroe,dc=com
objectclass: referral
ref: ldap://directory.europe.siroe.com/cn=babs%20jensen,ou=people,
 l=europe,dc=siroe,dc=com


Note Any information after a space in an LDAP URL is ignored by the server. For this reason, you must use %20 instead of spaces in any LDAP URL you intend to use as a referral.


To add the entry uid=ssarette,ou=people,dc=siroe,dc=com with a referral to directory.europe.siroe.com, you would include the following in your LDIF file before importing:

dn: uid=ssarette, ou=people, dc=siroe,dc=com
objectclass: top
objectclass: person
objectclass: organizationalperson
objectclass: inetOrgPerson
objectclass: referral
cn: somi sarette
sn: sarette
uid: ssarette
ref: ldap://directory.europe.siroe.com/cn=somi%20sarette,ou=people,
 l=europe,dc=siroe,dc=com

For more information on smart referrals, see iPlanet Directory Server Deployment Guide. For more information about the ldapmodify utility, refer to the iPlanet Directory Server Configuration, Command, and File Reference.


Creating Suffix Referrals

The following procedure describes creating a referral in a suffix. This means that the suffix processes operations using a referral rather than a database or database link. For more information about referrals, refer to iPlanet Directory Server Deployment Guide.


Caution

When a suffix is configured to return referrals, the ACIs contained by the database associated with the suffix are ignored.



Creating Suffix Referrals Using the Console

To create a suffix referral using the console:

  1. On the Directory Server Console select the Configuration tab.

  2. Under Data in the left pane, click the suffix to which you want to add a referral.

  3. On the Suffix Settings tab, select one of the following radio buttons:

    Use Referrals. This means that a referral will be returned when this suffix receives any request from a client application.

    Use Referral on Update. This means a referral will be returned when this suffix receives an update request from a client application. This option is used to redirect update and write requests made by client applications to a read-only database.

  4. Click the Referrals tab. Enter an LDAP URL in the "Enter a new referral" field or click Construct to be guided through the creation of an LDAP URL.

    For more information about the structure of LDAP URLs, refer to Appendix C, "LDAP URLs."

  5. Click Add to add the referral to the list.

    You can enter multiple referrals. The directory will return the entire list of referrals in response to requests from client applications.

  6. Click Save.


Creating Suffix Referrals From the Command Line

Use the ldapmodify command-line utility to add a suffix referral to an entry in your directory configuration file. The suffix referral information is added to the root or sub suffix entry under the cn=mapping tree,cn=config branch.

For example, to add a new suffix referral to the ou=people,dc=siroe,dc=com root suffix, you do an ldapmodify. Run ldapmodify as follows:

ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password

The ldapmodify utility binds to the server and prepares it to add information to the configuration file.

Next, you add a suffix referral to the ou=people,dc=siroe,dc=com root suffix as follows:

dn: cn="ou=people,dc=siroe,dc=com",cn=mapping tree,cn=config
objectclass: extensibleObject
objectclasss: nsmappingtree
nsslapd-state: referral
nsslapd-referral: ldap://zanzibar.com/

The nsslapd-state attribute is set to referral, meaning that a referral is returned for requests made to this suffix. The nsslapd-referral attribute contains the LDAP URL of the referral returned by the suffix, in this case a referral to the Zanzibar.com server.

You can also set the nsslapd-state attribute to referral on update. This means that the database is used for all operations except update requests. When a client application makes an update request to a suffix set to referral on update, the client receives a referral.

For more information about the suffix configuration attributes, refer to Table 3-1, "Suffix Attributes".


Previous     Contents     Index     DocHome     Next     
Copyright © 2002 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated February 26, 2002