test

Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide

Part I Directory Server Administration

Chapter 1 Directory Server Tools

Sun JavaTM System Directory Server Directory Server Enterprise Edition provides a browser interface and command-line tools for administering multiple servers, instances, and suffixes in a replicated environment. This chapter provides overview information about Directory Server administration tools.

This chapter covers the following topics:

Directory Server Administration Overview

Information about the Directory Server administration framework is provided in other guides in this documentation set.

Deciding When to Use DSCC and When to Use the Command Line

Directory Server Enterprise Edition provides two user interfaces for managing Directory Servers and Directory Proxy Servers: a browser interface, Directory Service Control Center (DSCC), and a command-line interface.

Determining Whether a Procedure Can Be Done Using DSCC

Most procedures in this guide can be performed using either the command line or DSCC. The procedures in this guide show how to use the command line to accomplish the procedure. In most cases DSCC can be used to perform the same task. If DSCC can be used for a particular procedure, a statement to that effect appears at the beginning of the procedure.

The DSCC online help provides detailed instructions on how to use DSCC to perform the procedures in this guide.

Cases Where Using DSCC Is Better

DSCC enables you to perform some operations and tasks more easily than you can perform them from the command line, as explained in the following sections. In general, any command that must be applied to several servers is best performed using DSCC.

Viewing Servers and Suffix Replication Status

DSCC displays tables that show all server instances that have been registered in DSCC, all suffixes that have been configured, and the status of each.

The servers table is on the Directory Servers tab and shows the operational status of the server. For a complete list of possible server states, see the Directory Server online help.

The suffixes table is on the Suffixes tab and shows replication status information, such as the number of entries and the number and age of any missing changes. For more information about the information displayed in this table, see the Directory Server online help.

Managing Groups of Servers

Server groups assist you in monitoring and configuring servers. You can create groups and assign servers to the groups. For example, you can group servers by geographical location, or by function. If you have a large number of servers, you can filter the servers shown on the Directory Servers tab so that only the servers in the group are shown. You can also copy the server configuration (for example index or cache settings) of one server to all other servers in a group. For instructions on how to set up and use a server group, see the Directory Server online help.

Copying Configuration Settings

DSCC enables you to copy the configuration settings of an existing server, suffix, or replication agreement to one or more other servers, suffixes, or replication agreements. For information about how to perform each of these tasks, see the Directory Server online help.

Configuring Replication

With DSCC, you can set up a replication topology quickly and easily. Simply create the server instances, then use the steps provided by DSCC to designate the role of each server. DSCC automatically creates the replication agreements for you. For more information about how to configure replication using DSCC, see the Directory Server online help.

Directory Service Control Center Interface

Directory Service Control Center (DSCC) is a user interface that enables you to manage Directory Servers and Directory Proxy Servers by using a browser.

To configure DSCC, see Configuring DSCC. For information about using DSCC, see the following sections.

Administration Users for DSCC

DSCC has a few administration logins.

ProcedureTo Access DSCC

If you experience any difficulty accessing DSCC, see To Troubleshoot Directory Service Control Center Access in Sun Java System Directory Server Enterprise Edition 6.2 Installation Guide.

  1. Ensure that DSCC has been correctly installed, as described in Software Installation in Sun Java System Directory Server Enterprise Edition 6.2 Installation Guide.

  2. If you have installed DSCC with the native package installation, follow these steps:

    1. Open a browser, and type the DSCC host URL in the following format:


      https://hostname:6789

      For example:


      https://host1:6789

      where hostname is the system on which you installed the DSCC software.

      The Sun Java Web Console default port is 6789.

      The following figure shows a Sun Java Web Console login window.

      Figure 1–1 Sun Java Web Console Login Window

      Sun Java Web Console login window.

    2. Log in to the Sun Java Web Console.

      • If this is the first time that you log in to Sun Java Web Console, log in as root on the system where you installed the DSCC software.

      • If this is a subsequent login, type your operating system user name and password. This user should have the privileges to start, stop, and manage Directory Server instances.

      When you log in, you see a list of applications.

    3. Select Directory Service Control Center (DSCC).

      The DSCC login window is displayed.

  3. If you have installed DSCC with a zip installation, follow these steps:

    1. Access DSCC directly in your preferred application server by typing the DSCC host URL. DSCC host URL can be any of the following depending on the configuration of your application server.


      https://hostname:6789

      or


      http://hostname:6789

    2. Initialize DSCC using the following command.


      $ install path/dscc6/bin/dsccsetup ads-create

  4. Log in to DSCC.

    If this is the first time that you log in to DSCC, you must set the Directory Service Manager password. On subsequent logins, use the password that you set on the first login.

    You are now logged into DSCC and at the Common Tasks tab.

    Figure 1–2 DSCC Common Tasks Tab

    Screen capture shows the DSCC Common Tasks tab.

  5. Navigate by using the tabs.

    • The Common Tasks tab contains shortcuts to commonly used windows and wizards.

    • The Directory Servers tab displays all Directory Servers managed by DSCC. To see more options for managing and configuring a particular server, click the server name.

    • The Proxy Servers tab displays all Directory Proxy Servers managed by DSCC. To see more options for managing and configuring a particular server, click the server name.

    Note –

    For instructions on how to perform tasks using DSCC, see the DSCConline help.

    Figure 1–3 List of Directory Servers On the Servers Sub Tab

    Screen capture showing a list of Directory Serverservers.

DSCC Tabs Description

Use the tabs in DSCC to navigate the interface.

Common Tasks Tab

The Common Tasks tab (see Figure 1–2) is the first interface that you see when opening DSCC. It contains links to commonly used administrative tasks, such as searching directory data, checking logs, and managing servers.

Directory Servers Tab

The Directory Servers tab (see Figure 1–3) lists all directory servers registered in DSCC. For each server, you can see the server status and instance path, which shows where the instance is located.

When you click a server name, you see another window with a different set of tabs that relate only to that server.

Proxy Servers Tab

The Proxy Servers tab lists all the directory proxy servers that are registered in DSCC. For each server, you can see the server status and the server instance path, which shows where the instance resides.

When you click a server name, you see another window with a different set of tabs that relate only to that server.

Server Groups Tab

The Server Groups tab enables you to assign servers to groups, to make server management easier. If you have numerous servers, you can use filters to display only the servers in a certain group. You can also copy the server configuration (for example index or cache settings) from one server to all other servers in a group.

Settings Tab

This tab displays DSCC port numbers and allows you to create and delete Directory Service Managers.

DSCC Online Help

The online help provides the following:

You can access help from most pages by clicking the Help button on the top right corner of the screen. From within a wizard, you can access help by clicking the Help tab. You can also access the online help from the Common Tasks tab.

Directory Server Command-Line Tools

Most tasks you perform on DSCC can be performed using command-line tools. These tools enable you to manage Directory Server directly from the command line, and to manage your server by using scripts.

The main directory server commands are dsadm and dsconf. You can use these commands to perform backups, export to LDIF, manage certificates, and so on. For information about these commands, see the dsadm(1M) and dsconf(1M) man pages.

This section contains the following information about Directory Server command-line tools:

Location of Directory Server Commands

The Directory Server command-line tools are contained in a default installation directory:


install-path/ds6/bin

The directory for your installation depends on your operating system. Installation paths for all operating systems are listed in Default Paths and Command Locations.

Setting Environment Variables for dsconf

The dsconf command requires some options that you can preset by using environment variables. If you do not specify an option when using the command, or do not set the environment variable, the default setting is used. You can configure environment variables for the following options:

-D user DN

User bind DN. Environment variable: LDAP_ADMIN_USER. Default: cn=Directory Manager.

-w password-file

Password file for the user bind DN. Environment variable: LDAP_ADMIN_PWF. Default: Prompt for password.

-h host

Host name. Environment variable: DIRSERV_HOST. Default: local host.

-p LDAP-port

LDAP port number. Environment variable: DIRSERV_PORT. Default: 389.

-e, --unsecured

Specifies that dsconf should open a clear connection by default. Environment variable: DIRSERV_UNSECURED. If this variable is not set, dsconf opens a secure connection by default.

For more details, see the dsconf(1M) man page.

Comparison of dsadm and dsconf

The following table shows a comparison of the dsadm and dsconf commands.

Table 1–1 Comparison of the dsadm and dsconf Commands

 

dsadm Command

dsconf Command

Description 

Administration commands that must be run directly on the local host. For example:

  • Starting and stopping the server

  • Creating a server instance

Administration commands that can be run from a remote host. For example:

  • Enabling replication

  • Setting cache size

Notes 

The server must be stopped (except for the dsadm stop and dsadm info commands).

The server is identified by the server instance path (instance-path).

You must have OS access permissions to the server instance path. 

The server must be running.  

The server is identified by host name (-h) port (-p) or LDAPS secure port (-P).

If you do not specify a port number, dsconf uses the default port (389 for LDAP).

You must have LDAP access permissions to configuration data, for example, as the user cn=admin,cn=Administrators,cn=config.  

Obtaining Help for Using dsadm and dsconf

For complete information about how to use the dsadm and dsconf commands, see the dsadm(1M) and dsconf(1M) man pages.

Modifying Configuration Properties by Using dsconf

Many of the dsconf subcommands enable you to view and modify configuration properties.

For more information about individual properties, see the man page for that property. The man pages are in Sun Java System Directory Server Enterprise Edition 6.2 Man Page Reference.

Setting Multi-Valued Properties With dsconf

Certain Directory Server properties can take multiple values. The syntax to specify these values is as follows:


$ dsconf set-container-prop -h host -p port container-name \
 property:value1 property:value2

For example, to set multiple encryption ciphers for a server, use the following command:


$ dsconf set-server-prop -h host1 -p 1389 ssl-cipher-family:SSL_RSA_WITH_RC4_128_MD5 \
 ssl-cipher-family:SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA

To add a value to a multi-valued property that already contains values, use the following syntax:


$ dsconf set-container-prop -h host -p port container-name property+:value

To remove a value from a multi-valued property that already contains values, use the following syntax:


$ dsconf set-container-prop -h host -p port container-name property-:value

For example, in the scenario described previously, to add the SHA encryption cipher to the list of ciphers, run this command:


$ dsconf set-server-prop -h host1 -p 1389 \
 ssl-cipher-family+:TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

To remove the MD5 cipher from the list, run this command:


$ dsconf set-server-prop -h host1 -p 1389 ssl-cipher-family-:SSL_RSA_WITH_RC4_128_MD5

Man Pages

The man pages provide descriptions of all commands and attributes used in Directory Server. In addition, the man pages show some useful examples of how to use the commands in deployment.

Legacy Tools

Legacy tools are included with the regular Directory Server tools for backwards compatibility. These tools are present but deprecated.

Chapter 2 Directory Server Instances and Suffixes

This chapter describes how to create and manage Directory Server instances and suffixes. Many other directory administration tasks are configured at the suffix level, but they are covered in other chapters in this book.

This chapter covers the following topics:

Quick Procedure for Creating Server Instances and Suffixes

This chapter contains detailed information about how to create server instances and suffixes. If you need to quickly create a Directory Server instance and suffix, and import some example data, see Server Instance Creation in Sun Java System Directory Server Enterprise Edition 6.2 Installation Guide.

Creating and Deleting a Directory Server Instance

This section shows how to create and delete a Directory Server instance.

ProcedureTo Create a Directory Server Instance

Before you can administer data, you must create a Directory Server instance by using command-line tools or the browser interface Directory Service Control Center (DSCC). In DSCC, a Directory Server instance is often referred to simply as a “Directory Server”.

When you create a Directory Server instance, the files and directories required for your Directory Server are created in the instance-path that you specify.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

If you use DSCC to create a new server instance, you can choose to copy some or all server configuration settings from an existing server.

  1. Create a new Directory Server instance and set the instance path.


    $ dsadm create instance-path

    You are prompted to set a password for the Directory Manager for this server.

    To specify a non-default port number for the server instance, or any other parameter, see the dsadm(1M) man page.

    For example, to create a new instance in the directory /local/ds, use this command:


    $ dsadm create /local/ds
Choose the Directory Manager password:
Confirm the Directory Manager password:
Use 'dsadm start /local/ds' to start the instance

  2. Check that the server instance has been created correctly.


    $ dsadm info instance-path

    For example: 


    $ dsadm info /local/ds1
Instance Path:         /local/ds1
Owner:                 user1(group1)
Non-secure port:       1389
Secure port:           1636
Bit format:            64-bit
State:                 Running
Server PID:            22555
DSCC url:              -
SMF application name:  -
Start at boot:         Disabled
Instance version:      D-A00

  3. (Optional) If you installed Directory Server using the Java Enterprise System installer or a native package installation, and your OS provides a service management solution, you can enable the server to be managed as a service, as shown in this table.

    Operating System 

    Command 

    Solaris 10 

    If you are operating in a Sun Cluster environment, use this command: 

    dsadm enable-service --type CLUSTER instance-path resource-group

    Otherwise:  

    dsadm enable-service --type SMF instance-path

    Solaris 9 

    If you are operating in a Sun Cluster environment, use this command: 

    dsadm enable-service --type CLUSTER instance-path resource_group

    Otherwise:  

    dsadm autostart instance-path

    Linux, HP-UX 

    dsadm autostart instance-path

    Windows 

    dsadm enable-service --type WIN_SERVICE instance-path

  4. Start Directory Server.


    $ dsadm start instance-path
    Note –

    The server is running but does not contain data or a suffix. Use dsconf to create a suffix.

  5. (Optional) Register the server instance using one of these methods:

    • Access the URL https://host:6789 and register the server through DSCC.

    • Use the command dsccreg add-server.

      For details, see the dsccreg(1M) man page.

  6. If you want to use a password policy and your Directory Server instance is standalone, or if it belongs to a replication topology that has already been migrated to DS6-only password policy mode, move the instance to that mode.


    $ dsconf pwd-compat -h host -p port to-DS6-migration-mode

## Beginning password policy compatibility changes .
## Password policy compatibility changes finished.

Task completed (slapd exit code: 0).
$ dsconf pwd-compat -h host -p port to-DS6-mode

## Beginning password policy compatibility changes .
## Password policy compatibility changes finished.

Task completed (slapd exit code: 0).

ProcedureTo Delete a Directory Server Instance

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Stop the Directory Server.


    $ dsadm stop instance-path

  2. If you have previously used DSCC to manage the server, use the command line to unregister the server.


    $ dsccreg remove-server /local/ds
Enter DSCC administrator's password:
/local/ds is an instance of DS
Enter password of "cn=Directory Manager" for /local/ds:
This operation will restart /local/ds.
Do you want to continue ? (y/n) y
Unregistering /local/ds from DSCC on localhost.
Connecting to /local/ds
Disabling DSCC access to /local/ds
Restarting /local/ds

    For details, see the dsccreg(1M) man page.

  3. (Optional) If you previously enabled the server instance in a service management solution, disable the server from being managed as a service.

    Operating System 

    Command 

    Solaris 10 

    If you are operating in a Sun Cluster environment, use this command: 

    dsadm disable-service --type CLUSTER instance-path

    Otherwise:  

    dsadm disable-service --type SMF instance-path

    Solaris 9 

    If you are operating in a Sun Cluster environment, use this command: 

    dsadm disable-service --type CLUSTER instance-path

    Otherwise:  

    dsadm autostart --off instance-path

    Linux, HP-UX 

    dsadm autostart --off instance-path

    Windows 

    dsadm disable-service --type WIN_SERVICE instance-path

  4. Delete the server instance.


    $ dsadm delete instance-path
    Caution – Caution –

    This command removes everything, including the database and the data.

    If the instance has been enabled as a service, or if the instance is started automatically at system startup, dsadm delete requires root access.

Starting, Stopping, and Restarting a Directory Server Instance

To start, stop or restart, the server from the command line, use the commands dsadm start, dsadm stop, and dsadm restart, respectively.

Note –

When you stop and restart a Directory Server instance with a large cache in memory configured to hold entries, the cache takes some time to refill. While the cache fills again, the instance responds more slowly.

These commands must be run by the same UID and GID that created the Directory Server, or run by root. For example, if Directory Server runs as user1 , you should run the start, stop, and restart utilities as user1.

Note –

On Solaris, role-based access control allows you to run Directory Server as a user other than root.

ProcedureTo Start, Stop, and Restart Directory Server

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help. However, this does not apply to the step for enabling and disabling service management. Enabling and disabling service management must be done at the command line when starting and stopping Directory Server.

  1. To start, stop, or restart Directory Server, do one of the following:

    • To start the server, type:


      $ dsadm start instance-path

      For example, to start a server with the instance path /local/ds, use this command:


      $ dsadm start /local/ds

    • To stop the server, type:


      $ dsadm stop instance-path

      For example:


      $ dsadm stop /local/ds

    • To restart the server, type:


      $ dsadm restart instance-path

      For example:


      $ dsadm restart /local/ds

Creating Suffixes

After you have created your Directory Server instance, you must create one or more suffixes for the server's Directory Information Tree (DIT). The DIT consists of all of the entries in your server, as identified by their distinguished names (DNs). The hierarchical nature of a DN creates branches and leaves that structure the data in the tree. The DIT is defined and managed administratively in terms of suffixes and sub-suffixes. DSCC provides controls for creating and administering all of these elements. Alternatively, you can use command-line tools.

For conceptual information about structuring directory data and about suffixes in general, refer to the Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide.

As explained in the following procedure, you can use the dsconf create-suffix command to create a suffix configuration in your directory. Because root suffixes and sub-suffixes are managed internally in the same way, the procedure for creating them from the command line is nearly the same. The procedure shows the dsconf create-suffix command used only with the required options. For more information about other options of this command, see the dsconf(1M) man page or run the following command:


$ dsconf create-suffix --help

The configuration entries can be created by any administration user. However, the top entry of the suffix must be created by the Directory Manager or as a Directory Administrator, such as cn=admin,cn=Administrators,cn=config.

ProcedureTo Create a Suffix

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

If you use DSCC to create a new suffix, you can choose to copy some or all suffix configuration settings from an existing suffix.

  1. Create the root suffix.

    Ensure that your server is running, then type this command:


    $ dsconf create-suffix -h host -p port suffix-DN

    where the suffix-DN is the full DN of the new suffix. For a root suffix, the convention is to use the domain-component (dc) naming attribute.

    For example, to create a suffix for the DN dc=example,dc=com , use this command:


    $ dsconf create-suffix -h host1 -p 1389 dc=example,dc=com

    This command creates the new suffix as follows:

    • The top level (or base) entry of the root suffix is created.

    • The configuration entries in cn=config for both the suffix and the database are created.

    • The default database name is based on the suffix DN.

    For information about the all of the suffixes, including the new suffix that has been created, use this command:


    $ dsconf list-suffixes -h host -p port -v

    The -v option displays verbose mode, which shows how many entries are on the suffix, and any replication information.

    Note –

    If you have more than one Directory Server instance, use the -h host name and -p port number options to specify which server instance the suffix should belong to.

    If you want to specify a non-default path for the database files, use the -L option. You can change the suffix database path at a later stage. To do this, use the command dsconf set-suffix-prop suffix-DN db-path:new-db-path, then stop the server, move the database files manually, and restart the server.

    To see all the options that you can use when creating suffixes, refer to the dsconf(1M) man page.

  2. If required, create the sub-suffix:


    $ dsconf create-suffix -h host -p port subSuffix-DN

    then attach the sub-suffix to the root suffix.


    $ dsconf set-suffix-prop -h host -p port subSuffix-DN parent-suffix-dn:parentSuffix-DN

    where parentSuffix-DN must have the same value as suffix-DN in the previous step. The suffix-DN for the sub-suffix includes the relative distinguished name (RDN) of the sub-suffix and the DN of its parent suffix.

    For example, to create the sub-suffix ou=Contractors,dc=example,dc=com, and to attach the sub-suffix to the root suffix, type:


    $ dsconf create-suffix -h host1 -p 1389 ou=Contractors,dc=example,dc=com
$ dsconf set-suffix-prop -h host1 -p 1389 ou=Contractors,dc=example,dc=com \
 parent-suffix-dn:dc=example,dc=com

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


    instance-path/db/database-name

    where database-name is the name automatically built from a part of the suffix. For example, in the previous example, the database-name would be Contractors

  3. (Optional) Initialize the suffix with data. See Initializing a Suffix.

Disabling or Enabling a Suffix

Sometimes, you might need to make a suffix unavailable for maintenance, or to make its contents unavailable for security reasons. The action of disabling a suffix prevents the server from reading or writing the contents of the suffix in response to any client operations. When you disable a suffix, you no longer have access to that suffix, and the referral mode is automatically set to disabled.

ProcedureTo Disable then Enable a Suffix

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Disable the suffix.


    $ dsconf set-suffix-prop -h host -p port suffix-DN enabled:off
    Note –

    You cannot disable a suffix on which replication is enabled because most properties of a replicated suffix are determined by the replication mechanism.

  2. Enable the suffix.


    $ dsconf set-suffix-prop -h host -p port suffix-DN enabled:on

Setting Referrals and Making a Suffix Read-Only

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

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

If your suffix is a consumer in a replicated environment, the replication mechanism determines the value of the referral setting. Although you can manually modify the referral setting, the referral will be overwritten at the next replication update. For information about setting replication referrals, see To Perform Advanced Consumer Configuration.

Referrals are labeled URLs, that is, an LDAP URL optionally followed by a space character and a label. For example:


ldap://phonebook.example.com:389/

Or: 


ldap://phonebook.example.com:389/ou=All%20People,dc=example,dc=com

Because space characters are significant, any space characters in the URL part of the referral must be escaped using %20.

ProcedureTo Set Referrals to Make a Suffix Read-Only

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Set the referral URL.


    $ dsconf set-suffix-prop -h host -p port suffix-DN referral-url:LDAP-URL

    where LDAP-URL is a valid URL containing the host name, port number, and DN of the target.

    For example:


    $ dsconf set-suffix-prop -h host1 -p 1389 dc=example,dc=com \
 referral-url:ldap://phonebook.example.com:389/

    You can specify any number of LDAP URLs.

  2. Set the referral mode in order to make the suffix read-only.


    $ dsconf set-suffix-prop -h host -p port suffix-DN referral-mode:only-on-write

    To make the suffix unavailable for both read and write operations, and to return referrals for all requests, set the referral-mode to enabled.

  3. As soon as the command is successful, the suffix is read-only or inaccessible and ready to return referrals.

  4. (Optional) When the suffix becomes available, disable the referrals to make the suffix read-write again.


    $ dsconf set-suffix-prop -h host -p port suffix-DN referral-mode:disabled

    When referrals are disabled, the suffix automatically becomes read-write, unless you have disabled the suffix itself by setting the enabled property of the suffix to off.

Deleting a Suffix

Deleting a suffix removes its entire branch from the DIT.

Note –

When you delete a suffix, you permanently remove all of its data entries from the directory. You also remove all suffix configuration information, including its replication configuration.

You cannot delete a parent suffix and keep its sub-suffixes in the DIT as new root suffixes. If you want to delete an entire branch that contains sub-suffixes, you must also delete the sub-suffixes of the deleted parent and their possible sub-suffixes.

ProcedureTo Delete a Suffix

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Remove the suffix configuration entry:


    $ dsconf delete-suffix -h host -p port [subSuffix-DN] suffix-DN

    This command removes the suffix from the server, starting with the base entry at the suffix-DN. The suffix is no longer visible or accessible in the directory.

Compacting a Suffix

Directory Server 6.2 supports the compaction of suffixes offline. Online compaction is not supported in this release. If storage space is available, compacting a suffix reduces the size of the database by reorganizing the database keys.

ProcedureTo Compact a Suffix Offline

Stop the server and backup your database before performing this task.

  1. Compact the required suffix.


    $ dsadm repack instance-path suffix-dn

    All .db3 files related to the specified suffix are compacted.

    If you run this command with the -b option, you can specify a back end database name, instead of a suffix DN. At least one suffix, or one back end must be specified.

Chapter 3 Directory Server Configuration

This chapter describes how to configure Directory Server. You can use the dsconf command (see the dsconf(1M) man page).

You can also use Directory Service Control Center (DSCC), which is the preferred method. DSCC makes additional checks during the configuration process, which can minimize errors. In addition, DSCC enables you to copy the configuration of one server instance to another server instance. For more information about using DSCC, see the DSCC online help.

Displaying the Configuration of Directory Server Instance

To display the configuration of Directory Server instance, run dsconf info. 


$ dsconf info -h host -p port
Instance path   :  instance path
Global State    :  read-write
Host Name       :  host
Port            :  port
Secure port     :  secure port
Total entries   :  20844

Suffixes        :  suffix-DN

Dest. Servers   :  host:port

On-Going Tasks  :  import
Finished Tasks  :  backup

The above output assumes that you have created suffixes, and replication agreements with the destination servers. It also displays the ongoing import operation and finished backup operation.

Modifying the Configuration Using DSCC

The recommended method for modifying the configuration is to use DSCC. This browser interface provides task-based controls to help you set up your configuration quickly and efficiently. Using DSCC, you can modify a configuration setting on one server and then copy that configuration setting to other servers. In addition, the DSCC interface manages the complexity and interdependence of the configuration for you. Detailed procedures for modifying the configuration using DSCC can be found in the DSCC online help.

Modifying the Configuration From the Command Line

You can automate configuration tasks by writing scripts that use command-line tools.

Modify the configuration through the command line by using the dsconf command. This command uses LDAP to modify the cn=config subtree. For more information about dsconf, see Directory Server Command-Line Tools.

For any tasks that you cannot perform using dsconf, use the ldapmodify command.

Note –

If you want to modify the server configuration properties by using the command dsconf set-server-prop, you need to know which properties you can modify and their default values. Use this command to display help on all properties:


$ dsconf help-properties -v

Search the property help for the item that you need. For example, on a UNIX platform, type the following to search for memory cache properties:


$ dsconf help-properties -v | grep cache

For more information about configuration entries in cn=config and for a complete description of all configuration entries and attributes, including the range of allowed values, see Sun Java System Directory Server Enterprise Edition 6.2 Reference.

Modifying the dse.ldif File

Directory Server stores all of its configuration information in this file:

instance-path/config/dse.ldif

Caution – Caution –

Modifying the configuration by editing the contents of the dse.ldif file directly is prone to error and is not recommended. However, if you choose to edit this file manually, stop the server before you edit the file and restart it after you have finished editing.

The dse.ldif file is in the LDAP Data Interchange Format (LDIF). LDIF is a textual representation of entries, attributes, and their values, and is a standard format described in RFC 2849 (http://www.ietf.org/rfc/rfc2849).

The Directory Server configuration in the dse.ldif file consists of the following:

Configuring Administration Users

Directory Server contains default administration users, the Directory Manager and the cn=admin,cn=Administrators,cn=config user. Both of these users have the same access rights, but cn=admin,cn=Administrators,cn=config is subject to ACIs.

This section explains how to create an administration user with root access, and how to configure the Directory Manager.

ProcedureTo Create an Administration User with Root Access

If you want to create a new administration user with the same rights as cn=admin,cn=Administrators,cn=config, create the new user in the group cn=Administrators,cn=config. All users in this group are subject to a global ACI that allows the same access as the Directory Manager.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Create a new administration user.

    For example, to create a new user cn=Admin24,cn=Administrators,cn=config, type:


    $ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=admin24,cn=Administrators,cn=config
changetype: add
objectclass: top
objectclass: person
userPassword: password
description: Administration user with the same access rights as Directory Manager.

    The -D and -w options give the bind DN and password, respectively, of a user with permissions to create this entry.

ProcedureTo Configure the Directory Manager

The Directory Manager is the privileged server administrator, comparable to the root user on UNIX systems. Access control does not apply to the Directory Manager.

For most administration tasks, you are not required to use the Directory Manager. Instead, you can use the user cn=admin,cn=Administrators,cn=config, or any other user that you create beneath cn=Administrators,cn=config. The only tasks that require the Directory Manager are changing the root ACI, and replication troubleshooting tasks, such as repairing replication and searching tombstones.

You can change the Directory Manager DN and password, as well as create a file from which the password can be automatically read.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Find the existing Directory Manager DN.


    $ dsconf get-server-prop -h host -p port root-dn
root-dn:cn=Directory Manager

  2. Modify the Directory Manager settings as required.

    • To modify the Directory Manager DN, type:


      $ dsconf set-server-prop -h host -p port root-pwd-file:new-root-dn-password-file

      Use quotes if there are spaces in the Directory Manager DN. For example:


      $ dsconf set-server-prop -h host1 -p 1389 root-dn:"cn=New Directory Manager"

    • To change the Directory Manager password, type:


      $ dsconf set-server-prop -h host -p port root-pwd:new-root-dn-password

      If for security reasons you do not want to pass the clear text password as a command-line argument, create a temporary file for setting the password.


      $ echo password > /tmp/pwd.txt

      This file is read once, and the password is stored for future use. Set the server root password file property.


      $ dsconf set-server-prop -h host -p port root-pwd-file:/tmp/pwd.txt

      This command prompts the server to read the password file. Remove the temporary password file after you have set the password file property.


      $ rm /tmp/pwd.txt

Protecting Configuration Information

The root Directory Server entry (the entry returned for a base object search with a zero-length DN "") and the subtrees below cn=config, cn=monitor, and cn=schema contain access control instructions (ACIs) that are automatically generated by Directory Server. These ACIs are used to determine user permissions to directory entries. These ACIs are sufficient for evaluation purposes. However, for any production deployment, you need to evaluate your access control requirements and design your own access controls.

If you want to hide the existence of one or more additional subtrees and protect your configuration information for security reasons, you must place additional ACIs on the DIT.

For more information about creating ACIs, see Chapter 6, Directory Server Access Control.

Configuring DSCC

This section provides the following information about configuring DSCC:

ProcedureTo Change the Common Agent Container Port Number

The default common agent container port number is 11162. The common agent container defines the DSCC agent port as jmxmp-connector-port. If for administrative reasons you need to use a different port number for the DSCC agent and common agent container, use the following procedure.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. As root, verify the existing port number for jmxmp-connector-port. 


    $ su 
Password: 
# cacaoadm list-params
...
jmxmp-connector-port=11162
...

  2. Change the DSCC agent port number.

    The common agent container must be stopped when changing the DSCC agent port number.


    # cacaoadm stop
# cacaoadm set-param jmxmp-connector-port=new-port
# cacaoadm start

    For the location of this command, see Command Locations.

  3. In DSCC, unregister your servers, and then reregister them using the new DSCC agent port number.

    In addition, when you create a new server, you must specify the non-default DSCC agent port number.

ProcedureTo Reset the Directory Service Manager Password

To reset the Directory Service Manager password, use DSCC, as described in this procedure.

  1. Access DSCC as described in To Access DSCC.

  2. Click the Settings tab, then choose Directory Service Managers.

  3. Click the name of the Directory Service Manager for which you want to change the password.

  4. In the properties screen, enter the new password.

    Confirm the new password by typing it again in the Confirm Password field. Click OK to save your changes.

ProcedureTo Extend the DSCC Session Automatic Timeout Delay

After a period of time, your DSCC session will time out, and you will be logged out of DSCC. Use this procedure to extend the timeout delay. Note that this procedure extends the timeout for DSCC and for all other applications in Sun Java Web Console.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. As root, extend the timeout delay.


    # wcadmin add -p -a ROOT session.timeout.value=mm

    where mm is the number of minutes before timeout.

    For example, to set the timeout to two hours, type:


    $ su
Password:
# wcadmin add -p -a ROOT session.timeout.value=120
Set 1 properties for the ROOT application.
# wcadmin list -p
Shared service properties (name, value):
    session.timeout.value  120
    ...

  2. Restart Sun Java Web Console.


    # smcwebserver restart
Shutting down Sun Java(TM) Web Console Version 3.0.2 ...
Starting Sun Java(TM) Web Console Version 3.0.2 ...
The console is running.

    For the location of these commands, see Command Locations.

Configuring Failover for DSCC

DSCC displays the servers that you have registered in DSCC.

If the machine on which you have installed DSCC fails, you can install DSCC on another machine and then reregister your servers. However, this can be time-consuming. If you want to have immediate access to your servers through DSCC, you can configure DSCC failover.

To configure DSCC failover, take the following considerations into account:

Troubleshooting DSCC

For information about troubleshooting DSCC, see To Troubleshoot Directory Service Control Center Access in Sun Java System Directory Server Enterprise Edition 6.2 Installation Guide.

Changing Directory Server Port Numbers

You can modify the LDAP port or the LDAPS secure port number of your user directory server by using DSCC or by using the dsconf set-server-prop command.

If you change a port number, be aware of the following:

If you change the port number by using the command line, be aware of the following:

ProcedureTo Modify a Port Number, Enable a Port, and Disable a Port

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Note –

Once you make your modifications, you must restart the server for the changes to take effect.

  1. Verify the existing settings for your port.


    $ dsconf get-server-prop -h host -p port port-type

    Where port-type is one of the following:

    ldap-port

    LDAP default port

    ldap-secure-port

    LDAPS secure port

    dsml-port

    DSML default port

    dsml-secure-port

    DSML secure port

    For example, to display the LDAPS secure port, type:


    $ dsconf get-server-prop -h host1 -p 2501 ldap-secure-port
Enter "cn=Directory Manager" password:
ldap-secure-port : 2511

    If the returned result is an integer, the port is enabled. If the returned result is disabled, the port is disabled.

    Note –

    You can also list the LDAP default port and LDAPS secure port using the dsadm

  2. If required, modify a port number or enable a port.


    $ dsconf set-server-prop -h host -p port port-type:new-port

    For example, to change the LDAP port number from 1389 to 1390, use this command:


    $ dsconf set-server-prop -h host1 -p 1389 ldap-port:1390

    To enable the DSML secure port on port number 2250, use this command:


    $ dsconf set-server-prop -h host1 -p 1389 dsml-secure-port:2250

  3. If required, disable a port.


    $ dsconf set-server-prop -h host -p port port-type:disabled

    For example, to disable the DSML secure port, use the command:


    $ dsconf set-server-prop -h host1 -p 1389 dsml-secure-port:disabled

Configuring DSML

In addition to processing requests in the Lightweight Directory Access Protocol (LDAP), Directory Server also responds to requests sent in the Directory Service Markup Language version 2 (DSMLv2). DSML is another way for a client to encode directory operations. The server processes DSML as any other request, with all of the same access control and security features. DSML processing allows many other types of clients to access your directory contents.

Directory Server supports the use of DSMLv2 over the Hypertext Transfer Protocol (HTTP/1.1) and uses the Simple Object Access Protocol (SOAP) version 1.1 as a programming protocol to transport the DSML content. For more information about these protocols and for examples of DSML requests, see Chapter 10, Directory Server DSMLv2, in Sun Java System Directory Server Enterprise Edition 6.2 Reference.

This section covers the following topics:

ProcedureTo Enable the DSML-over-HTTP Service

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Set the DSML mode to on.


    $ dsconf set-server-prop -h host -p port dsml-enabled:on

  2. Set the secure DSML port.


    $ dsconf set-server-prop -h host -p port dsml-secure-port:port

  3. Set the non—secure DSML port.


    $ dsconf set-server-prop -h host -p port dsml-port:port

    By default, this port is set to disabled

  4. Restart the server.


    $ dsadm restart instance-path
Next Steps

According to the parameters and attribute values you defined, DSML clients may use the following URLs to send requests to this server:

http://host:DSML-port/relative-URL

https://host:secure-DSML-port/relative-URL

Note –

The relative-URL can be read and set using the dsml-relative-root-url property.

ProcedureTo Disable the DSML-over-HTTP Service

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Set the DSML mode to off.


    $ dsconf set-server-prop -h host -p port dsml-enabled:off

  2. Set the secure DSML port to disabled.


    $ dsconf set-server-prop -h host -p port dsml-secure-port:disabled

  3. Restart the server.


    $ dsasm restart instance-path

ProcedureTo Configure DSML Security

You can configure the level of security that is required to accept DSML requests. To do this, you must configure DSML client authentication.

  1. Set the DSML client authentication mode. 


    $ dsconf set-server-prop -h host -p port dsml-client-auth-mode:dsml-mode

    By default the dsml-client-auth-mode property is set to client-cert-first.

    dsml-mode can be one of:

    • http-basic-only - This is the default value. The server uses the contents of the HTTP Authorization header to find a user name that can be mapped to an entry in the directory. This process and its configuration are encrypted through SSL but do not use client certification. This is described in DSML Identity Mapping.

    • client-cert-only - The server uses credentials from the client certificate to identify the client. With this value, all DSML clients must use the secure HTTPS port to send DSML requests and provide a certificate. The server checks that the client certificate matches an entry in the directory. See Chapter 5, Directory Server Security for more information.

    • client-cert-first - The server will attempt to authenticate clients first with a client certificate if one is provided. Otherwise, the server will authenticate clients using the contents of the Authorization header.

    If no certificate and no Authorization header is provided in the HTTP request, the server performs the DSML request with anonymous binding. Anonymous binding is also used in the following cases:

    • The client provides a valid Authorization header but no certificate when client-cert-only is specified.

    • The client provides a valid certificate but no Authorization header when http-basic-only is specified.

    Regardless of the client authentication method, if a certificate is provided but it cannot be matched to an entry, or if the HTTP Authorization header is specified but cannot be mapped to a user entry, the DSML request is rejected with error message 403: “Forbidden”.

DSML Identity Mapping

When performing basic authentication without a certificate, Directory Server uses a mechanism called identity mapping to determine the bind DN to use when accepting DSML requests. This mechanism extracts information from the Authorization header of the HTTP request to determine the identity to use for binding.

The default identity mapping for DSML/HTTP is given by the following entry in your server configuration.

dn: cn=default,cn=HTTP-BASIC,cn=identity mapping,cn=config
objectClass: top
objectClass: nsContainer
objectClass: dsIdentityMapping
cn: default
dsSearchBaseDN: ou=people
dsSearchFilter: (uid=${Authorization})

This configuration indicates that the server should use the HTTP user ID as the uid value for a DN stored in a Directory Server suffix. For example, if the HTTP user is bjensen, the server tries to execute the bind using the DN uid=bjensen,ou=people.

For the mapping to work properly you must therefore complete the value of dsSearchBaseDN. For example, you can change the value of dsSearchBaseDN to ou=people,dc=example,dc=com. Then if the HTTP user is bjensen, the server tries to execute the bind using the DN uid=bjensen,ou=people,dc=example,dc=com.

dn: cn=default,cn=HTTP-BASIC,cn=identity mapping,cn=config
objectClass: top
objectClass: nsContainer
objectClass: dsIdentityMapping
cn: default
dsSearchBaseDN: ou=people,dc=example,dc=com
dsSearchFilter: (uid=${Authorization})

Within the mapping entry attribute dsSearchFilter, you can use placeholders of the format ${header} where header is the name of an HTTP header.

The following are the most common headers used in DSML mappings.

${Authorization}

This string is replaced with the user name contained in an HTTP Authorization header. An authorization header contains both a username and its password, but only the user name is substituted in this placeholder.

${From}

This string is replaced with the email address that might be contained in an HTTP From header.

${host}

This string is replaced with the hostname and port number in the URL of the DSML request, which are those of the server.

To have DSML requests perform a different kind of identity mapping, define a new identity mapping for HTTP headers.

ProcedureTo Define a New Identity Mapping for HTTP Headers

  1. Edit the default DSML-over-HTTP identity mapping or create custom mappings for this protocol.

    The mapping entries must be located below the entry cn=HTTP-BASIC,cn=identity mapping,cn=config.

    Use the ldapmodify command to add this entry from the command line, as described in Adding Entries Using ldapmodify.

  2. Restart Directory Server for your new mappings to take effect.

    Custom mappings are evaluated first. If no custom mapping is successful, the default mapping is evaluated. If all mappings fail to determine the bind DN for the DSML request, the DSML request is forbidden and rejected (error 403).

Setting the Server as Read-Only

Each suffix in your directory can be placed in read-only mode independently and can return a specific referral if one is defined. Directory Server also provides a read-only mode for the server that applies to all suffixes and can return a global referral when one is defined.

The server read-only mode is designed to allow administrators to prevent modifications to the directory contents while performing tasks such as reindexing the suffixes. For this reason, server read-only mode does not apply to the following configuration branches:

These branches should be protected at all times by access control instructions (ACIs) against modifications by non-administration users, regardless of the read-only setting (see Chapter 6, Directory Server Access Control). Global read-only mode prevents update operations on all other suffixes in the directory, including update operations initiated by the Directory Manager.

Read-only mode also interrupts replication on a suffix if it is enabled. A master replica no longer has any changes to replicate, although it continues to replicate any changes that were made before read-only mode was enabled. A consumer replica does not receive updates until read-only mode is disabled. A master in a multi master replication environment does not have any changes to replicate and is not able to receive updates from the other masters.

ProcedureTo Enable or Disable the Server Read-Only Mode

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Enable the global read-only mode.


    $ dsconf set-server-prop -h host -p port read-write-mode:read-only

  2. When you are ready, disable the read-only mode.


    $ dsconf set-server-prop -h host -p port read-write-mode:read-write

Configuring Memory

This section provides information about managing different types of memory. For a description of the different types of cache and for information about cache tuning, see Chapter 5, Directory Server Data Caching, in Sun Java System Directory Server Enterprise Edition 6.2 Reference.

Priming Caches

To prime caches means to fill the caches with data so that subsequent Directory Server behavior reflects normal operational performance, rather than ramp-up performance. Priming caches is useful for arriving at reproducible results when benchmarking, and for measuring and analyzing potential optimizations.

If possible, do not actively prime the caches. Let the caches be primed by normal or typical client interaction with Directory Server before you measure performance.

Tools for priming database cache can be found at http://www.slamd.com.

ProcedureTo Modify Database Cache

Caution – Caution –

Modifying cache can severely impact server performance. Use caution when modifying cache.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Obtain the current database cache level.


    $ dsconf get-server-prop -h host -p port db-cache-size

  2. Change the database cache level.


    $ dsconf set-server-prop -h host -p port db-cache-size:size

    where size can be expressed in gigabytes (G), megabytes (M), kilobytes (k) or bytes (b). The size you specify must be supported by your machine.

ProcedureTo Monitor Database Cache

The default level of cache at installation is suited to a test environment, not a production environment. For tuning purposes, you might want to monitor the database cache for your server.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Monitor database cache.


    $ ldapsearch -h host -p port -D cn=admin,cn=Administrators,cn=config -w - \
 -b "cn=monitor,cn=ldbm database,cn=plugins,cn=config" "(objectclass=*)"

    If the database cache size is large enough and it has been primed, the hit ratio (dbcachehitratio) should be high. In addition, the number of pages that are read in (dbcachepagein) and the clean pages that are written out (dbcacheroevict) should be low. Here, “high” and “low” are relative to the deployment constraints.

ProcedureTo Monitor Entry Cache

For tuning purposes, you might want to check the entry cache for one or more suffixes. Use this procedure to view the entry cache levels.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Monitor entry cache.


    $ ldapsearch -h host -p port -D cn=admin,cn=Administrators,cn=config -w - \
 -b "cn=monitor,cn=db-name,cn=ldbm database,cn=plugins,cn=config" "(objectclass=*)"

    If the entry cache for a suffix is large enough to hold most of the entries in the suffix and if the cache is primed, the hit ratio (entrycachehitratio) should be high.

    If you have primed the cache, you will see that as the previously empty entry cache fills, entry cache size (currententrycachesize) approaches the maximum entry cache size (maxentrycachesize). Ideally, the size in entries (currententrycachecount) should be either equal to or very close to the total number of entries in the suffix (ldapentrycachecount).

ProcedureTo Modify Entry Cache

Caution – Caution –

Modifying cache can severely impact server performance. Use caution when modifying cache.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Obtain the current entry cache level.


    $ dsconf get-suffix-prop -h host -p port suffix-DN entry-cache-count entry-cache-size

  2. Change the entry cache count.


    $ dsconf set-suffix-prop -h host -p port suffix-DN entry-cache-count:integer

    where integer is the number of entries to be stored in the cache.

  3. Change the entry cache size.


    $ dsconf set-suffix-prop -h host -p port suffix-DN entry-cache-size:size

    where size is the cache size expressed in gigabytes (G), megabytes (M), kilobytes (k) or bytes (b). The size you specify must be supported by your machine.

ProcedureTo Configure Heap Memory Threshold

If you want to limit the amount of heap memory used by the nsslapd process, you can set threshold values for the dynamic memory footprint. You might set this threshold when Directory Server is running on a machine where resources are shared or sparse.

Note –

This threshold can only be set on Solaris and Linux platforms.

For information about memory sizing, see Directory Server and Memory in Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

Note –

By default, the heap-high-threshold-size and heap-low-threshold-size properties are undefined.

  1. Set the maximum heap high memory threshold.


    $ dsconf set-server-prop -h host -p port heap-high-threshold-size:value

    where value is either undefined or a memory size expressed in gigabytes (G), megabytes (M), kilobytes (k) or bytes (b). The size you specify must be supported by your machine.

    For recommendations on the values to use for heap-high-threshold-size , see the server(5dsconf) man page.

  2. Optionally, set the maximum heap low memory threshold . 


    $ dsconf set-server-prop -h host -p port heap-low-threshold-size:value

    where value is either undefined or a memory size expressed in gigabytes (G), megabytes (M), kilobytes (k) or bytes (b). The size you specify must be supported by your machine.

    For recommendations on the values to use for heap-low-threshold-size , see the server(5dsconf) man page.

Setting Resource Limits For Each Client Account

You can control search operation resource limits on the server for each client account. You set such limits in operational attributes on an account, and Directory Server then enforces them based on the account a client uses to bind to the directory.

The following limits can be set:

Note –

The Directory Manager can use unlimited resources by default.

The resource limits that you set on specific user accounts take precedence over the resource limits set in the server-wide configuration. This section provides information about setting resource limits for each account.

The examples given in this section set resource limits directly in the attributes of the entry. You can also set resource limits on account using the Class of Service (CoS) mechanism. The CoS mechanism generates computed attributes as an entry is retrieved for a client application. For more information about defining CoS, see Class of Service.

ProcedureTo Configure the Heap Memory Threshold

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Use the dsconf get-server-prop command to read the resource limit server properties.


    $ dsconf get-server-prop -h host -p port look-through-limit search-size-limit \
 search-time-limit idle-timeout
look-through-limit  :  5000  
search-size-limit   :  2000  
search-time-limit   :  3600
idle-timeout        :  none

    The output shows that searches look through a maximum of 5000 entries, return a maximum of 2000 entries, and use a maximum of one hour (3600 seconds) of server time to process the search.

  2. Change the look-through limit.


    $ dsconf set-server-prop -h host -p port look-through-limit:integer

    where integer is the maximum number of entries examined for a search operation.

  3. Change the search size limit.


    $ dsconf set-server-prop -h host -p port search-size-limit:integer

    where integer is the maximum number of entries returned by a search operation.

  4. Change the search time limit.


    $ dsconf set-server-prop -h host -p port serach-time-limit:integer

    where integer is the maximum time spent processing a search operation.

  5. Change the idle timeout.


    $ dsconf set-server-prop -h host -p port idle-timeout:integer

    where integer is the maximum time a client connection can remain idle before the connection is dropped.

Chapter 4 Directory Server Entries

This chapter discusses how to manage the data entries in your directory. It also describes how to set referrals and to encrypt attribute values.

When planning a directory deployment, you need to characterize the types of data that the directory will contain. Read the relevant chapters in the Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide before creating entries and modifying the default schema.

You cannot modify your directory unless the appropriate access control instructions (ACIs) have been defined. For further information, see Chapter 6, Directory Server Access Control.

This chapter covers the following topics:

Managing Entries

The best way to manage entries depends on the context:

Managing Entries Using DSCC

DSCC enables you to view all readable attributes of an entry and to edit its writable attributes. It also enables you to add and remove attributes, set multi-valued attributes, and manage the object classes of the entry. For more information about how to use DSCC to manage entries, see the DSCC online help. For more information about DSCC in general, see Directory Service Control Center Interface.

Managing Entries Using Directory Editor

Directory Editor is an easy-to-use directory editing tool that enables administrators and end-users to search, create and edit data. This data is in the form of users, groups, and containers.

Managing Entries Using ldapmodify and ldapdelete

The ldapmodify and ldapdelete command-line utilities provide full functionality for adding, editing, and deleting your directory contents. You can use these utilities to manage both the configuration entries of the server and the data in the user entries. The utilities can also be used to write scripts to perform bulk management of one or more directories.

The ldapmodify and ldapdelete commands are used in procedures throughout this book. The following sections describe the basic operations that you will need to perform procedures. For more information about the ldapmodify and ldapdelete commands, see Sun Java System Directory Server Enterprise Edition 6.2 Reference.

Input to the command-line utilities is always in LDIF, and it can be provided either directly from the command-line or through an input file. The following section provides information about LDIF input, and subsequent sections describe the LDIF input for each type of modification.

For information about formatting LDIF input correctly, see the Guidelines for Providing LDIF Input in Sun Java System Directory Server Enterprise Edition 6.2 Reference.

The following sections describe these basic operations:

Adding Entries Using ldapmodify

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

You can add one or more entries to the directory by using the -a option of ldapmodify. The following example creates a structural entry to contain users and then creates a user entry:


$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: ou=People,dc=example,dc=com
objectclass: top
objectclass: organizationalUnit
ou: People
description: Container for user entries

dn: uid=bjensen,ou=People,dc=example,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetorgPerson
uid: bjensen
givenName: Barbara
sn: Jensen
cn: Babs Jensen
telephoneNumber: (408) 555-3922
facsimileTelephoneNumber: (408) 555-4000
mail: bjensen@example.com
userPassword: secret

The -D and -w options give the bind DN and password, respectively, of a user with permissions to create these entries. The -a option indicates that all entries in the LDIF will be added. Then each entry is listed by its DN and its attribute values, with a blank line between each entry. The ldapmodify utility creates each entry after it is entered, and the utility reports any errors.

    By convention, the LDIF of an entry lists the following attributes:

  1. The DN of the entry.

  2. The list of object classes.

  3. The naming attribute (or attributes). This is the attribute used in the DN, and it is not necessarily one of the required attributes.

  4. The list of required attributes for all object classes.

  5. Any allowed attributes that you want to include.

When typing a value for the userPassword attribute, provide the clear text version of the password. The server will encrypt this value and store only the encrypted value. Be sure to limit read permissions to protect clear passwords that appear in LDIF files.

You can also use an alternate form of the LDIF that does not require the -a option on the command line. The advantage of this form is that you can combine entry addition statements and entry modification statements, as shown in the following example.


$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password: 
dn: ou=People,dc=example,dc=com
changetype: add
objectclass: top
objectclass: organizationalUnit
ou: People
description: Container for user entries

dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: add
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetorgPerson
uid: bjensen
givenName: Barbara
sn: Jensen
cn: Barbara Jensen
telephoneNumber: (408) 555-3922
facsimileTelephoneNumber: (408) 555-4000
mail: bjensen@example.com
userPassword: secret

The changetype: add keyword indicates that the entry with the given DN should be created with all of the subsequent attributes. All other options and LDIF conventions are the same as explained earlier in this section.

In both examples, you can use the -f filename option to read the LDIF from a file instead of from the terminal input. The LDIF file must contain the same format as used for the terminal input, depending upon your use of the -a option.

Modifying Entries Using ldapmodify

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Use the changetype: modify keyword to add, replace, or remove attributes and their values in an existing entry. When you specify changetype: modify, you must also provide one or more change operations to indicate how the entry is to be modified. The three possible LDIF change operations are shown in the following example:


dn: entryDN
changetype: modify
add: attribute 
attribute: value...
-
replace: attribute 
attribute: newValue...
-
delete: attribute 
[attribute: value]
...

Use a hyphen (-) on a line to separate operations on the same entry, and use a blank line to separate groups of operations on different entries. You can also give several attribute: value pairs for each operation.

Adding an Attribute Value

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

The following example shows how you can use the same add LDIF syntax to add values to existing multi-valued attribute and to attributes that do not yet exist:


$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
add: cn
cn: Babs Jensen
-
add: mobile
mobile: (408) 555-7844

This operation might fail and the server will return an error if any of the following are true:

Using the Binary Attribute Subtype

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

The attribute;binary subtype indicates that attribute values must be transported over LDAP as binary data, regardless of their actual syntax. This subtype is designed for complex syntax that does not have LDAP string representations, such as userCertificate. The binary subtype should not be used outside of this purpose.

When used with the ldapmodify command, appropriate subtypes can be added to attribute names in any of the LDIF statements.

To enter a binary value, you may type it directly in the LDIF text or read it from another file. The LDIF syntax for reading it from a file is shown in the following example:


$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
version: 1
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
add: userCertificate;binary
userCertificate;binary:< file:///local/cert-file

To use the :< syntax to specify a file name, you must begin the LDIF statement with the line version: 1. When ldapmodify processes this statement, it will set the attribute to the value that is read from the entire contents of the given file.

Adding an Attribute With a Language Subtype

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Language and pronunciation subtypes of attributes designate localized values. When you specify a language subtype for an attribute, the subtype is added to the attribute name as follows:


attribute;lang-CC

where attribute is an existing attribute type, and cc is the two-letter country code to designate the language. You may optionally add a pronunciation subtype to a language subtype to designate a phonetic equivalent for the localized value. In this case the attribute name is as follows:


attribute;lang-CC;phonetic

To perform an operation on an attribute with a subtype, you must explicitly match its subtype. For example, if you want to modify an attribute value that has the lang-fr language subtype, you must include lang-fr in the modify operation as follows:


$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
add: homePostalAddress;lang-fr
homePostalAddress;lang-fr: 34, rue de la Paix
Note –

If the attribute value contains non-ASCII characters, they must be UTF-8 encoded.

Modifying Attribute Values

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

The following example shows how to change the value of an attribute by using the replace syntax in LDIF:


$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
replace: sn
sn: Morris
-
replace: cn
cn: Barbara Morris
cn: Babs Morris

All current values of the specified attributes are removed, and all given values are added.

After changing an attribute value, you can use the ldapsearch command to verify the change.

Trailing Spaces in Attribute Values

When you modify an attribute value, do not unintentionally include trailing spaces at the end of the value. Trailing spaces might result in the value appearing in base-64 encoding (such as 34xy57eg).

If the attribute value ends with a trailing space, the trailing space is encoded as part of the attribute value. When you verify the change using DSCC or the ldapsearch command, the value you see might be plain text, but it might also appear as base-64 encoded text. This depends on which Directory Server client you use.

Deleting an Attribute Value

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

The following example shows how to delete an attribute entirely and to delete only one value of a multi valued attribute:


$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
delete: facsimileTelephoneNumber
-
delete: cn
cn: Babs Morris

When using the delete syntax without specifying an attribute: value pair, all values of the attribute are removed. If you specify an attribute: value pair, only that value is removed.

Modifying One Value of a Multi Valued Attribute

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

To modify one value of a multi valued attribute with the ldapmodify command, you must perform two operations as shown in the following example:


$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: modify
delete: mobile
mobile: (408) 555-7845
-
add: mobile
mobile: (408) 555-5487

Deleting Entries Using ldapdelete

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Use the ldapdelete command-line utility to delete entries from the directory. This utility binds to the directory server and deletes one or more entries based on their DN. You must provide a bind DN that has permission to delete the specified entries.

You cannot delete an entry that has children. The LDAP protocol forbids the situation where child entries would no longer have a parent. For example, you cannot delete an organizational unit entry unless you have first deleted all entries that belong to the organizational unit.

The following example shows only one entry in the organizational unit. This entry and then its parent entry can be deleted.


$ ldapdelete -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
uid=bjensen,ou=People,dc=example,dc=com
ou=People,dc=example,dc=com

Deleting Entries Using ldapmodify

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

When using the ldapmodify utility, you can also use the changetype: delete keywords to delete entries. All of the same limitations apply as when using ldapdelete, as described in the previous section. The advantage of using LDIF syntax for deleting entries is that you can perform a mix of operations in a single LDIF file.

The following example performs the same delete operations as the previous example:


$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: delete

dn: ou=People,dc=example,dc=com
changetype: delete

Searching Entries Using ldapsearch

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

You can use the ldapsearch command-line utility to locate and retrieve directory entries. Note that the ldapsearch utility is not the utility provided with the Solaris platform, but is part of the Directory Server Resource Kit.

For more information about using ldapsearch, common ldapsearch options, accepted formats, and examples, refer to Sun Java System Directory Server Enterprise Edition 6.2 Reference.

ProcedureTo Move or Rename an Entry Using ldapmodify

This procedure uses the modify DN operation. Before starting this operation, ensure that you are familiar with the section Guidelines and Limitations for Using the Modify DN Operation.

For parts of this procedure, you can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help. Other parts of the procedure can only be done using the command line.

Note –

When modifying the DNs of entries that are a uniquemember of a group, you must have the referential integrity plug-in enabled. Referential integrity ensures that the group members get adjusted when the entry is moved. For information about how to enable and configure the referential integrity plug-in, see To Configure the Referential Integrity Plug-In.

  1. If you are moving an entry from one parent to another, extend ACI rights on the parent entries.

    • On the current parent entry of the entry to be moved, ensure that the ACI allows the export operations by using the syntax allow (export ...)

    • On the future parent entry of the entry to be moved, ensure that the ACI allows the import operations. by using the syntax allow (import ...)

    For information about using ACIs, see Chapter 6, Directory Server Access Control.

  2. Ensure that the modify DN operation is enabled globally, or at least for the suffix or suffixes that will be affected by the move operation.

    To ensure compatibility with previous releases of Directory Server, the modify DN operation is not enabled by default.

    If you have already enabled the modify DN operation previously, go to the next step.

    To enable the modify DN operation globally for a server, use this command:


    $ dsconf set-server-prop -h host -p port moddn-enabled:on

  3. Run the ldapmodify command.

    This step uses the modify DN operation. Do one of the following:

    • Move the entry.

      For example, the following command moves the entry uid=bjensen from the subtree for contractors, ou=Contractors,dc=example,dc=com to the subtree for employees, ou=People,dc=example,dc=com:


      $ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: uid=bjensen,ou=Contractors,dc=example,dc=com
changetype: modrdn
newrdn: uid=bjensen
deleteoldrdn: 0
newsuperior: ou=People,dc=example,dc=com

    • Rename the entry.

      For example, the following command renames the entry uid=bbjensen to uid=bjensen:


      $ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: uid=bbjensen,ou=People,dc=example,dc=com
changetype: modrdn
newrdn: uid=bjensen
deleteoldrdn: 1

    Pay attention to the following attributes when writing the LDIF statement:

    • dn - Specifies the entry to rename or move.

    • changetype: modrdn - Specifies that a modify DN operation is to be used.

    • newrdn - Gives the new naming attribute.

    • deleteoldrdn - Indicates whether the previous naming attribute should be removed from the entry (1 is yes, 0 is no).

      Note that you cannot remove a naming attribute from the entry if that attribute is obligatory in the entry definition.

    • newsuperior - Specifies the new superior attribute of the entry.

    For information about the ldapmodify command and its options, see the ldapmodify(1) man page.

  4. If you encounter resource limit errors when moving or renaming subtrees that contain a large number of entries, increase the number of locks that can be used by the database.


    $ dsconf set-server-prop -h host -p port db-lock-count:value

    If you modify this property, you must restart the server for the change to take effect.

Guidelines and Limitations for Using the Modify DN Operation

When you use the modify DN operation, as described in the previous section, use the guidelines described in the following sections.

General Guidelines for Using the Modify DN Operation

Guidelines for Using the Modify DN Operation With Replication

Caution – Caution –

Using the modify DN operation without complying with the following requirements can break replication and bring down your directory service.

Setting Referrals

You can use referrals to tell client applications which server to contact if the information is not available locally. Referrals are pointers to a remote suffix or entry that Directory Server returns to the client, in place of a result. The client must then perform the operation again on the remote server named in the referral.

Redirection occurs in three cases:

In all cases, a referral is an LDAP URL that contains the host name, port number, and optionally a DN on another server. For example, ldap://east.example.com:389.

For conceptual information about how you can use referrals in your directory deployment, see the Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide.

The following sections describe the procedures for setting your directory’s default referrals and for creating and defining smart referrals.

Setting the Default Referrals

Default referrals are returned to client applications that submit operations on a DN that is not contained on a suffix maintained by your Directory Server. The server will return all referrals that are defined, but the order in which they are returned is not defined.

ProcedureTo Set a Default Referral

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Use the dsconf command-line utility to set one or more default referrals. 


    $ dsconf set-server-prop -h host -p port suffix-DN referral-url:referral-URL

    For example:


    $ dsconf set-server-prop -h host1 -p 1389 dc=example,dc=com \
 referral-url:ldap://east.example.com:1389

Setting Smart Referrals

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

Often, a smart referral points to an actual entry with the same DN on another server. However, you may define the smart referral to any entry on the same server or on a different server. For example, you can define the entry with the following DN to be a smart referral:


uid=bjensen,ou=People,dc=example,dc=com

The smart referral points to another entry on the server east.example.com:


cn=Babs Jensen,ou=Sales,o=east,dc=example,dc=com

The way the directory uses smart referrals conforms to the standard specified in section 4.1.10 of RFC 4511 (http://www.ietf.org/rfc/rfc4511.txt).

ProcedureTo Create and Modify a Smart Referral

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. To create a smart referral, create an entry with referral and extensibleObject object classes.

    The referral object class allows the ref attribute that is expected to contain an LDAP URL. The extensibleObject object class allows you to use any schema attribute as the naming attribute, in order to match the target entry.

    For example, to define the following entry to return a smart referral instead of the entry uid=bjensen, use this command:


    $ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: uid=bjensen,ou=People,dc=example,dc=com
objectclass: top
objectclass: extensibleObject
objectclass: referral
uid: bjensen
ref: ldap://east.example.com/cn=Babs%20Jensen,ou=Sales,o=east,dc=example,dc=com
    Note –

    Any information after a space in an LDAP URL is ignored by the server. Thus, you must use %20 instead of spaces in any LDAP URL that you intend to use as a referral. Other special characters must be escaped.

    After you have defined the smart referral, modifications to the uid=bjensen entry will actually be performed on the cn=Babs Jensen entry on the other server. The ldapmodify command will automatically follow the referral, for example:


    $ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: replace
replace: telephoneNumber
telephoneNumber: (408) 555-1234

  2. (Optional) To modify the smart referral entry, use the -M option of ldapmodify:


    $ ldapmodify -M -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: uid=bjensen,ou=People,dc=example,dc=com
changetype: replace
replace: ref
ref: ldap://east.example.com/cn=Babs%20Jensen,ou=Marketing,o=east,dc=example,dc=com

Checking Valid Attribute Syntax

Directory Server allows you to check the integrity of your attributes whenever you perform the following operations:

The checks ensure that the attribute values conform to IETF recommendations. All nonconforming attributes are rejected and logged in the errors log. The log messages include the connection and operation ID, if applicable.

By default, the server automatically checks the syntax of the previously mentioned operations. If you want to turn syntax checking off, use the following procedure.

Note –

Syntax checking is not the same as schema checking. For information about schema checking, see Managing Schema Checking.

ProcedureTo Turn Off Automatic Syntax Checking

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. To turn off automatic syntax checking, use this command:


    $ dsconf set-server-prop -h host -p port check-syntax-enabled:off

Tracking Modifications to Directory Entries

By default, the server maintains special attributes for newly created or modified entries, as specified in the LDAP v3 specification. These special attributes are stored on the entry in the suffix and include the following:

ProcedureTo Turn Off Entry Modification Tracking

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Caution – Caution –

Turning off entry modification tracking results in non-compliant data. As many applications rely on these attributes and as disabling this feature results in only minimal performance gains, we recommend that you do not turn off entry modification tracking.

  1. Turn off entry modification tracking for the server.


    $ dsconf set-server-prop -h host -p port suffix-DN mod-tracking-enabled:off

Encrypting Attribute Values

Attribute encryption protects sensitive data while it is stored in the directory. Attribute encryption allows you to specify that certain attributes of an entry are stored in an encrypted format. This prevents data from being readable while stored in database files, backup files, and exported LDIF files.

With this feature, attribute values are encrypted before they are stored in the Directory Server database, and decrypted back to their original value before being returned to the client. You must use access controls to prevent clients from accessing such attributes without permission, and SSL to encrypt the attribute values when in transit between the client and Directory Server. For an architectural overview of data security in general and attribute encryption in particular, see Sun Java System Directory Server Enterprise Edition 6.2 Reference.

Attribute encryption is active only when SSL is configured and enabled on the server. However, no attributes are encrypted by default. Attribute encryption is configured at the suffix level, which means that an attribute is encrypted in every entry in which it appears in the suffix. If you want to encrypt an attribute in an entire directory, you must enable encryption for that attribute in every suffix.

Caution – Caution –

Attribute encryption affects all data and index files associated with a suffix. If you modify the encryption configuration of an existing suffix, you must first export its contents, make the configuration change, and then re-import the contents. DSCC can help you perform these steps. For more information about using DSCC, see Directory Service Control Center Interface.

For additional security, when turning on encryption for any attribute, you should manually delete the database cache files and database log file that might still contain unencrypted values. The procedure for deleting these files is described in To Configure Attribute Encryption.

You should enable any encrypted attributes before loading or creating data in a new suffix.

If you choose to encrypt an attribute that some entries use as a naming attribute, values that appear in the DN will not be encrypted. Values that are stored in the entry will be encrypted.

Even though you can select the userPassword attribute for encryption, no real security benefit is realized unless the password needs to be stored in the clear. Such is the case for DIGEST-MD5 SASL authentication. If the password already has an encryption mechanism defined in the password policy, further encryption provides little additional security, but, it will impact the performance of every bind operation.

When in storage, encrypted attributes are prefaced with a cipher tag that indicates the encryption algorithm used. An encrypted attribute using the DES encryption algorithm would appear as follows:


{CKM_DES_CBC}3hakc&jla+=snda%

When importing data online with a view to encrypting it, you will already have provided the key database password to authenticate to the server and will not be prompted a second time. If you are importing data offline, Directory Server will prompt you for the password before it allows you to encrypt the data you are importing. When decrypting data (a more security-sensitive operation), Directory Server automatically prompts you for the key database password, regardless of whether the export operation is online or offline. This provides an additional security layer.

Note –

As long as the certificate or private key does not change, the server will continue to generate the same key. Thus, data can be transported (exported then imported) from one server instance to another, provided both server instances have used the same certificate.

Attribute Encryption and Performance

While attribute encryption offers increased data security, it does impact system performance. Think carefully about which attributes require encryption, and encrypt only those attributes that you consider to be particularly sensitive.

Because sensitive data can be accessed directly through index files, the index keys that correspond to the encrypted attributes must be encrypted to ensure that the attributes are fully protected. Given that indexing already has an impact on Directory Server performance (without the added cost of encrypting index keys), configure attribute encryption before data is imported or added to the database for the first time. This procedure will ensure that encrypted attributes are indexed as such from the outset.

Attribute Encryption Usage Considerations

Consider the following when implementing the attribute encryption feature:

ProcedureTo Configure Attribute Encryption

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. If the suffix on which you want to configure attribute encryption contains any entries whatsoever, you must first export the contents of that suffix to an LDIF file.

    If the suffix contains encrypted attributes and you plan to re-initialize the suffix using the exported LDIF file, you can leave the attributes encrypted in the exported LDIF .

  2. To enable encryption for an attribute, use this command:


    $ dsconf create-encrypted-attr -h host -p port suffix-DN attr-name cipher-name

    where cipher-name is one of the following:

    • des - DES block cipher

    • des3 - Triple-DES block cipher

    • rc2 - RC2 block cipher

    • rc4 - RC4 stream cipher

    For example:


    $ dsconf create-encrypted-attr -h host1 -p 1389 dc=example,dc=com uid rc4

  3. To return an encrypted attribute to its original state, use this command:


    $ dsconf delete-encrypted-attr -h host -p port suffix-DN attr-name

  4. If you have changed the configuration to encrypt one or more attributes, and these attributes had values before the import operation, clear the database cache and remove the log.

    Any unencrypted values will not be visible in the database cache and database log.

    Note –

    If you delete these files, you will lose some tracking information. In addition, after you delete these files, the server will be in recovery mode, and might take a long time to restart.

    To clear the database cache and remove the log:

    1. Stop Directory Server as described in Starting, Stopping, and Restarting a Directory Server Instance.

    2. As root or a user with administrator privileges, delete the database cache files from your file system.


      # rm instance-path/db/__db.*

    3. Delete the database log file from your file system.


      # rm instance-path/db/log.0000000001

    4. Restart Directory Server.

      The server will automatically create new database cache files. Performance of operations in this suffix might be slightly impacted until the cache is filled again.

  5. Initialize the suffix with an LDIF file as described in Initializing a Suffix.

    As the file is loaded and the corresponding indexes are created, all values of the specified attributes will be encrypted.

Chapter 5 Directory Server Security

Directory Server supports several mechanisms that provide secure and trusted communications over the network. LDAPS is the standard LDAP protocol that runs on top of the Secure Sockets Layer (SSL). LDAPS encrypts data and optionally uses certificates for authentication. When the term SSL is used in this chapter, it means the supported protocols SSL2, SSL3 and TLS 1.0.

Directory Server also supports the Start Transport Layer Security (Start TLS) extended operation to enable TLS on an LDAP connection that was originally not encrypted.

In addition, Directory Server supports the Generic Security Service API (GSSAPI) over the Simple Authentication and Security Layer (SASL). The GSSAPI allows you to use the Kerberos Version 5 security protocol on the Solaris Operating System (Solaris OS). An identity mapping mechanism then associates the Kerberos principal with an identity in the directory.

For additional security information, see the NSS web site at http://www.mozilla.org/projects/security/pki/nss/.

This chapter provides procedures for configuring security through SSL. For information about ACIs, see Chapter 6, Directory Server Access Control. For information about user access and passwords, see Chapter 7, Directory Server Password Policy.

This chapter covers the following topics:

Using SSL With Directory Server

The Secure Sockets Layer (SSL) provides encrypted communications and optional authentication between a Directory Server and its clients. SSL can be used over LDAP or with DSML-over-HTTP. SSL is enabled by default over LDAP, but if you are using DSML-over-HTTP, you can easily enable SSL. In addition, replication can be configured to use SSL for secure communications between servers.

Using SSL with simple authentication (bind DN and password) encrypts all data sent to and from the server. Encryption guarantees confidentiality and data integrity. Optionally, clients can use a certificate to authenticate to Directory Server or to a third-party security mechanism through the Simple Authentication and Security Layer (SASL). Certificate-based authentication uses public-key cryptography to prevent forgery and impersonation of either the client or the server.

Directory Server is capable of simultaneous SSL and non-SSL communications on separate ports. For security reasons, you can also restrict all communications to the LDAP secure port. Client authentication is also configurable. You can set client authentication to required or to allowed. This setting determines the level of security you enforce.

SSL enables support for the Start TLS extended operation that provides security on a regular LDAP connection. Clients can bind to the standard LDAP port and then use the Transport Layer Security protocol to secure the connection. The Start TLS operation allows more flexibility for clients, and can help simplify port allocation.

The encryption mechanisms provided by SSL are also used for attribute encryption. Enabling SSL allows you to configure attribute encryption on your suffixes, which protects data while it is stored in the directory. For more information, see Encrypting Attribute Values.

For additional security, you can set access control to directory contents through access control instructions (ACIs). ACIs require a specific authentication method and ensure that data can only be transmitted over a secure channel. Set the ACIs to compliment your use of SSL and certificates. For more information, see Chapter 6, Directory Server Access Control.

SSL is enabled by default over LDAP, and you can easily enable SSL for DSML-over-HTTP. In addition, there are some aspects of the SSL configuration that you might want to modify, as described in the following sections.

Managing Certificates

This section describes how to manage SSL certificates in Directory Server.

To run SSL on Directory Server, you must either use a self-signed certificate or a Public Key Infrastructure (PKI) solution.

The PKI solution involves an external Certificate Authority (CA). For a PKI solution, you need a CA-signed server certificate, which contains both a public key and a private key. This certificate is specific to one Directory Server. You also need a trusted CA certificate, which contains a public key. The trusted CA certificate ensures that all server certificates from your CA are trusted. This certificate is sometimes called a CA root key or root certificate.

Note –

If you are using certificates for test purposes, you probably want to use self-signed certificates. However, in production, using self-signed certificates is not very secure. In production, use trusted Certificate Authority (CA) certificates.

The procedures in this section use the dsadm and dsconf commands. For information about these commands, see the dsadm(1M)and dsconf(1M) man pages.

This section provides the following information about configuring certificates on Directory Server:

ProcedureTo View the Default Self-Signed Certificate

When a Directory Server instance is first created, it contains a default self-signed certificate. A self-signed certificate is a public and private key pair, where the public key is signed by the private key. A self-signed certificate is valid for three months.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. To view the default self-signed certificate, use this command:


    $ dsadm show-cert instance-path defaultCert

ProcedureTo Manage Self-Signed Certificates

When you create a Directory Server instance, a default self-signed certificate is automatically provided.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. To create a self-signed certificate with non-default settings, use this command:


    $ dsadm add-selfsign-cert instance-path cert-alias

    Where cert-alias is a name that you provide to identify your certificate.

    To see all the options for this command, see the dsadm(1M) man page or the command-line help:.


    $ dsadm add-selfsign-cert --help

  2. When your self-signed certificate expires, stop the server instance and renew the certificate.


    $ dsadm stop instance-path
$ dsadm renew-selfsign-cert instance-path cert-alias

  3. Restart the server instance.


    $ dsadm start instance-path

ProcedureTo Request a CA-Signed Server Certificate

This procedure explains how to request and install a CA-signed server certificate for use with Directory Server.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Generate a CA-signed server certificate request.


    $ dsadm request-cert [-W cert-pwd-file] {-S DN | --name name [--org org] \
  [--org-unit org-unit] [--city city] [--state state] [--country country]} \
  [-o output-file] [-F format] instance-path

    For example, to request a CA-signed server certificate for the Example company, use this command:


    $ dsadm request-cert --name host1 --org Example --org-unit Marketing \
 -o my_cert_request_file /local/ds

    In order to completely identify the server, Certificate Authorities might require all of the attributes that are shown in this example. For a description of each attribute, see the dsadm(1M) man page.

    When you request a certificate by using dsadm request-cert, the resulting certificate request is a binary certificate request unless you specify ASCII as output format. If you specify ASCII, the resulting certificate request is a PKCS #10 certificate request in PEM format. PEM is the Privacy Enhanced Mail format specified by RFCs 1421 through 1424 (http://www.ietf.org/rfc/rfc1421.txt) and is used to represent a base64-encoded certificate request in US-ASCII characters. The content of the request looks similar to the following example:


    -----BEGIN NEW CERTIFICATE REQUEST-----
MIIBrjCCARcCAQAwbjELMAkGA1UBhMCVXMxEzARBgNVBAgTCkNBElGT1JOSUExLD
AqBgVBAoTI25ldHNjYXBlIGNvb11bmljYXRpb25zIGNvcnBvcmF0aWuMRwwGgYDV
QQDExNtZWxsb24umV0c2NhcGUuY29tMIGfMA0GCSqGSIb3DQEBAUAA4GNADCBiQK
BgCwAbskGh6SKYOgHy+UCSLnm3ok3X3u83Us7u0EfgSLR0f+K41eNqqWRftGR83e
mqPLDOf0ZLTLjVGJaHJn4l1gG+JDf/n/zMyahxtV7+T8GOFFigFfuxJaxMjr2j7I
vELlxQ4IfZgwqCm4qQecv3G+N9YdbjveMVXW0v4XwIDAQABAAwDQYJKoZIhvcNAQ
EEBQADgYEAZyZAm8UmP9PQYwNy4Pmypk79t2nvzKbwKVb97G+MT/gw1pLRsuBoKi
nMfLgKp1Q38K5Py2VGW1E47/rhm3yVQrIiwV+Z8Lcc=
-----END NEW CERTIFICATE REQUEST-----

  2. Transmit the certificate request to your Certificate Authority, according to its procedures.

    The process for obtaining your Certificate Authority certificate depends on the certificate authority that you use. Some commercial CAs provide a website that allows you to automatically download the certificate. Other CAs will send it to you in email upon request.

    After you have sent your request, you must wait for the CA to respond with your certificate. Response time for your request varies. For example, if your CA is internal to your company, the CA might only take a day or two to respond to your request. If your selected CA is external to your company, the CA could take several weeks to respond to your request.

  3. Save the certificate that you receive from the Certificate Authority.

    Back up your certificates in a safe location. If you ever lose the certificates, you can reinstall them by using your backup file. You can save them in text files. The PKCS #11 certificate in PEM format looks similar to the following example:


    -----BEGIN CERTIFICATE-----
MIICjCCAZugAwIBAgICCEEwDQYJKoZIhKqvcNAQFBQAwfDELMAkGA1UEBhMCVVMx
IzAhBgNVBAoGlBhbG9a2FWaWxsZGwSBXaWRnZXRzLCBJbmMuMR0wGwYDVQQLExRX
aWRnZXQgTW3FrZXJzICdSJyBVczEpMCcGAx1UEAxgVGVzdCBUXN0IFRlc3QgVGVz
dCBUZXN0IFlc3QgQ0EswHhcNOTgwMzEyMDIzMzUWhcNOTgwMzI2MDIzMpzU3WjBP
MQswCYDDVQQGEwJVUzEoMCYGA1UEChMfTmV0c2NhcGUgRGlyZN0b3J5VIFB1Ymxp
Y2F0aW9uczEWMB4QGA1UEAxMNZHVgh49dq2tLNvbjTBaMA0GCSqGSIb3DQEBAQUA
A0kAMEYkCQCksMR/aLGdfp4m0OiGgijG5KgOsyRNvwGYW7kfW+8mmijDtZaRjYNj
jcgpF3VnlbxbclX9LVjjNLC5737XZdAgEDozYwpNDARBglghkgBhvhCEAQEEBAMC
APAwHkwYDVR0jBBgwFAU67URjwCaGqZHUpSpdLxlzwJKiMwDQYJKoZIhQvcNAQEF
BQADgYEAJ+BfVem3vBOPBveNdLGfjlb9hucgmaMcQa9FA/db8qimKT/ue9UGOJqL
bwbMKBBopsDn56p2yV3PLIsBgrcuSoBCuFFnxBnqSiTS7YiYgCWqWaUA0ExJFmD6
6hBLseqkSWulk+hXHN7L/NrViO+7zNtKcaZLlFPf7d7j2MgX4Bo=
-----END CERTIFICATE-----

ProcedureTo Add the CA-Signed Server Certificate and the Trusted CA Certificate

This procedure explains how to install the CA-signed server certificate and trusted CA certificates for use with Directory Server.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Add the CA-signed server certificate.


    $ dsadm add-cert --ca instance-path cert-alias cert-file

    Where cert-alias is a name that you provide to identify your certificate, and cert-file is the text file that contains the PKCS #11 certificate in PEM format.

    For example, to install a CA-signed server certificate, you might use a command similar to this:


    $ dsadm add-cert --ca /local/ds server-cert /local/safeplace/serv-cert-file

    The certificate is now installed, but is not yet trusted. To trust the CA-signed server certificate, you must install the Certificate Authority certificate.

  2. Add the trusted Certificate Authority certificate.


    $ dsadm add-cert --ca -C instance-path cert-alias cert-file

    The -C option indicates that the certificate is a trusted Certificate Authority certificate.

    For example, to install a trusted certificate from a Certificate Authority, you might use this command:


    $ dsadm add-cert --ca -C /local/ds CA-cert /local/safeplace/ca-cert-file

  3. (Optional) Verify your installed certificates.

    • To list all server certificates and to display their validity dates and aliases, type:


      $ dsadm list-certs instance-path

      For example:


      $ dsadm list-certs /local/ds1
Enter the certificate database password:
Alias       Valid from Expires on Self-   Issued by          Issued to
                                  signed?                                     
----------- ---------- ---------- ------- -----------------  -----------------
serverCert  2000/11/10 2011/02/10 n       CN=CA-Signed Cert, CN=Test Cert,
            18:13      18:13              OU=CA,O=com        dc=example,dc=com
defaultCert 2006/05/18 2006/08/18 y       CN=host1,CN=DS,    Same as issuer
            16:28      16:28              dc=example,dc=com
2 certificates found

      By default, an instance of Directory Proxy Server contains a default server certificate called defaultCert. The text Same as issuer indicates that the default certificate is a self-signed server certificate.

    • To list trusted CA certificates, type:


      $ dsadm list-certs -C instance-path

      For example: 


      $ dsadm list-certs -C /local/ds1
Enter the certificate database password:
Alias   Valid from Expires on Self-   Issued by           Issued to
                              signed?                                   
------- ---------- ---------- ------- -----------------   --------------
CA-cert 2000/11/10 2011/02/10 y       CN=Trusted CA Cert, Same as issuer
        18:12      18:12              OU=CA,O=com
1 certificate found

    • To view the details of a certificate, including the certificate expiration date, type:


      $ dsadm show-cert instance-path cert-alias

      For example, to view a server certificate, type:


      $ dsadm show-cert /local/ds1 "Server-Cert"
Enter the certificate database password:
Certificate:
    Data:
        Version: 3 (0x2)
        Serial Number: 2 (0x2)
        Signature Algorithm: PKCS #1 MD5 With RSA Encryption
        Issuer:
            "CN=Server-Cert,O=Sun,C=US"
        Validity:
            Not Before: Fri Nov 10 18:12:20 2000
            Not After : Thu Feb 10 18:12:20 2011
        Subject:
            "CN=CA Server Cert,OU=ICNC,O=Sun,C=FR"
        Subject Public Key Info:
            Public Key Algorithm: PKCS #1 RSA Encryption
            RSA Public Key:
                Modulus:
                    bd:76:fc:29:ca:06:45:df:cd:1b:f1:ce:bb:cc:3a:f7:
                    77:63:5a:82:69:56:5f:3d:3a:1c:02:98:72:44:36:e4:
                    68:8c:22:2b:f0:a2:cb:15:7a:c4:c6:44:0d:97:2d:13:
                    b7:e3:bf:4e:be:b5:6a:df:ce:c4:c3:a4:8a:1d:fa:cf:
                    99:dc:4a:17:61:e0:37:2b:7f:90:cb:31:02:97:e4:30:
                    93:5d:91:f7:ef:b0:5a:c7:d4:de:d8:0e:b8:06:06:23:
                    ed:5f:33:f3:f8:7e:09:c5:de:a5:32:2a:1b:6a:75:c5:
                    0b:e3:a5:f2:7a:df:3e:3d:93:bf:ca:1f:d9:8d:24:ed
                Exponent: 65537 (0x10001)
    Signature Algorithm: PKCS #1 MD5 With RSA Encryption
    Signature:
        85:92:42:1e:e3:04:4d:e5:a8:79:12:7d:72:c0:bf:45:
        ea:c8:f8:af:f5:95:f0:f5:83:23:15:0b:02:73:82:24:
        3d:de:1e:95:04:fb:b5:08:17:04:1c:9d:9c:9b:bd:c7:
        e6:57:6c:64:38:8b:df:a2:67:f0:39:f9:70:e9:07:1f:
        33:48:ea:2c:18:1d:f0:30:d8:ca:e1:29:ec:be:a3:43:
        6f:df:03:d5:43:94:8f:ec:ea:9a:02:82:99:5a:54:c9:
        e4:1f:8c:ae:e2:e8:3d:50:20:46:e2:c8:44:a6:32:4e:
        51:48:15:d6:44:8c:e6:d2:0d:5f:77:9b:62:80:1e:30
    Fingerprint (MD5):
        D9:FB:74:9F:C3:EC:5A:89:8F:2C:37:47:2F:1B:D8:8F
    Fingerprint (SHA1):
        2E:CA:B8:BE:B6:A0:8C:84:0D:62:57:85:C6:73:14:DE:67:4E:09:56

    Certificate Trust Flags:
        SSL Flags:
            Valid CA
            Trusted CA
            User
            Trusted Client CA
        Email Flags:
            User
        Object Signing Flags:
            User

ProcedureTo Renew an Expired CA-Signed Server Certificate

When your CA-signed server certificate (public key and private key) expires, renew it by using this procedure.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Obtain an updated CA-signed server certificate from your Certificate Authority.

  2. When you receive the updated certificate, stop the server instance and install the certificate.


    $ dsadm stop instance-path
$ dsadm renew-cert instance-path cert-alias cert-file

  3. Restart the server instance.


    $ dsadm start instance-path

ProcedureTo Export and Import a CA-Signed Server Certificate

In some cases you might want to export the public and private keys of a certificate so that you can later import the certificate. For example, you might want the certificate to be used by another server.

The commands in this procedure can be used with certificates that contain wild cards, for example "cn=*,o=example".

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Export the certificate.


    $ dsadm export-cert [-o output-file] instance-path cert-alias

    For example:


    $ dsadm export-cert -o /tmp/first-certificate /local/ds1 "First Certificate"
$ dsadm export-cert -o /tmp/first-ca-server-certificate /local/ds1/ defaultCert
Choose the PKCS#12 file password:
Confirm the PKCS#12 file password:
$ ls /tmp
first-ca-server-certificate

  2. Import the certificate.


    $ dsadm import-cert instance-path cert-file

    For example, to import the certificate to a server instance on host1:


    $ dsadm import-cert -h host1 /local/ds2 /tmp/first-ca-server-certificate
Enter the PKCS#12 file password:

  3. (Optional) If you have imported the certificate to a server, configure the server to use the imported certificate.


    $ dsconf set-server-prop -e -h host -p port -w - ssl-rsa-cert-name:server-cert

Configuring the Certificate Database Password

By default, Directory Server manages the SSL certificate database password internally through a stored password. When managing certificates, the user does not need to type a certificate password or specify the password file. This option is not very secure because the password is only hidden, not encrypted.

However, if you want to have more control over the use of certificates, you can configure the server so that the user is prompted for a password on the command line. In this case, the user must type the certificate database password for all dsadm subcommands except autostart, backup, disable-service, enable-service, info, reindex, restore, and stop. The certificate database is located in the directory instance-path/alias.

ProcedureTo Configure the Server So the User is Prompted for a Certificate Password

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Stop the server.


    $ dsadm stop instance-path

  2. Set the password prompt flag to on.


    $ dsadm set-flags instance-path cert-pwd-prompt=on

    You are asked to choose a new certificate password.

  3. Start the server.


    $ dsadm start instance-path

Backing Up and Restoring the Certificate Database for Directory Server

When you back up an instance of Directory Server, you back up the Directory Server configuration and the certificates. The backed up certificates are stored in the archive-path/alias directory.

For information about how to back up and restore Directory Server, see To Make a Backup for Disaster Recovery.

Configuring SSL Communication

This section contains procedures related to disabling and enabling SSL.

Disabling Non Secure Communication

When a server instance is created, both an LDAP clear port and a secure LDAP port (LDAPS) are created by default. However, there might be situations where you want to disable non-SSL communications so that the server communicates only through SSL.

The SSL connection is enabled with a default self-signed certificate. If you want to, you can install your own certificates. For instructions on managing certificates and disabling SSL after the server has been started, see Chapter 5, Directory Server Security. For an overview of certificates, certificate databases, and obtaining a CA-signed server certificate, see Sun Java System Directory Server Enterprise Edition 6.2 Reference.

ProcedureTo Disable the LDAP Clear Port

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Disable the LDAP clear port.

    To disable the non secure point, you must bind to the LDAP secure port. This example shows a bind to the default LDAP secure port, 1636, on the host server host1.


    $ dsconf set-server-prop -h host1 -P 1636 ldap-port:disabled

  2. Restart the server for the change to take effect.


    $ dsadm restart /local/ds

    You can now no longer bind on the non secure port 1389.

Choosing Encryption Ciphers

A cipher is the algorithm used to encrypt and decrypt data. Generally speaking, the more bits that a cipher uses during encryption, the stronger or more secure the encryption is. Ciphers for SSL are also identified by the type of message authentication used. Message authentication is another algorithm that computes a checksum that guarantees data integrity.

When a client initiates an SSL connection with a server, the client and server must agree on a cipher to use to encrypt information. In any two-way encryption process, both parties must use the same cipher. The cipher used depends upon the current order of the cipher list kept by the server. The server chooses the first cipher presented by the client that matches a cipher in its list. The default cipher value for Directory Server is all, which means all known secure ciphers supported by the underlying SSL library. However, you can modify this value to only accept certain ciphers.

For more information about the ciphers that are available with Directory Server, see Sun Java System Directory Server Enterprise Edition 6.2 Reference.

ProcedureTo Choose an Encryption Cipher

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Make sure that SSL is enabled for your server.

    See Configuring SSL Communication.

  2. View the available SSL ciphers.


    $ dsconf get-server-prop -h host -p port ssl-supported-ciphers
ssl-supported-ciphers  :  TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
ssl-supported-ciphers  :  TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
ssl-supported-ciphers  :  TLS_DHE_RSA_WITH_AES_256_CBC_SHA
ssl-supported-ciphers  :  TLS_DHE_DSS_WITH_AES_256_CBC_SHA 
...

  3. (Optional) If you want to keep a copy of non-encrypted data, export the data before setting the SSL ciphers.

    See Exporting to LDIF.

  4. Set the SSL ciphers.


    $ dsconf set-server-prop -h host -p port ssl-cipher-family:cipher

    For example, to set the cipher family to SSL_RSA_WITH_RC4_128_MD5 and SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA, type:


    $ dsconf set-server-prop -h host1 -P 1636 ssl-cipher-family:SSL_RSA_WITH_RC4_128_MD5 \
 ssl-cipher-family:SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
Enter "cn=Directory Manager" password:  
Before setting SSL configuration, export Directory Server data. 
Do you want to continue [y/n] ? y
Directory Server must be restarted for changes to take effect.

  5. (Optional) Add an SSL cipher to an existing list.

    If you already have a list of ciphers specified, and you want to add a cipher, use this command:


    $ dsconf set-server-prop -h host -p port ssl-cipher-family+:cipher

    For example, to add the SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA cipher, type:


    $ dsconf set-server-prop -h host1 -P 1636 \
 ssl-cipher-family+:SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA

  6. Restart the server for the changes to take effect.


    $ dsadm restart /local/ds

Configuring Credential Levels and Authentication Methods

The security model that is applied to clients is defined through a combination of the credential level and the authentication method.

Directory Server supports the following credential levels:

Client authentication is a mechanism for the server to verify the identity of the client.

Client authentication can be performed in one of the following ways:

This section provides the following information about configuring the two SASL mechanisms on Directory Server.

For more information about configuring security, see Configuring LDAP Clients to Use Security.

Setting SASL Encryption Levels in Directory Server

Before configuring the SASL mechanism, you must specify whether you require encryption or not. Requirements for SASL encryption are set by the maximum and minimum Strength Security Factor (SSF).

The attributes dsSaslMinSSF(5dsat) and dsSaslMaxSSF(5dsat) represent the encryption key length, and they are stored in cn=SASL, cn=security, cn=config.

The server allows any level of encryption, including no encryption. This means that Directory Server accepts dsSaslMinSSF and dsSaslMaxSSF values greater than 256. However, no SASL mechanisms currently support an SSF greater than 128. Directory Server negotiates these values down to the highest SSF possible (128). Therefore, the highest actual SSF might be less than the configured maximum, depending on the underlying mechanisms available.

SASL security factor authentication depends two main items: the minimum and maximum factors requested by the server and client applications, and the available encryption mechanisms, which are provided by the underlying security components. In summary, the server and client attempt to use the highest available security factor that is less than or equal to the maximum factors set on both, but greater than or equal to the minimum factors on both.

The default minimum SASL security factor for Directory Server, dsSaslMinSSF, is 0, meaning no protection. The actual minimum depends on the client setting, unless you change the minimum for Directory Server. In practice, you should set the minimum to the lowest level that you actually want the server and client to use. If the server and client fail to negotiate a mechanism that meets the minimum requirements, the connection is not established.

ProcedureTo Require SASL Encryption

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. To require SASL encryption, set the dsSaslMinSSF value to the minimum encryption required. 


    $ ldapmodify -h host -p port -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: cn=SASL, cn=security, cn=config
changetype: modify
replace: dsSaslMinSSF
dsSaslMinSSF: 128
^D

ProcedureTo Disallow SASL Encryption

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. To disallow SASL encryption, set both the dsSaslMinSSF and dsSaslMaxSSF values to zero.


    $ ldapmodify -h host -p port -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: cn=SASL, cn=security, cn=config
changetype: modify
replace: dsSaslMinSSF
dsSaslMinSSF: 0

replace: dsSaslMaxSSF
dsSaslMaxSSF: 0
^D

SASL Authentication Through DIGEST-MD5

The DIGEST-MD5 mechanism authenticates clients by comparing a hashed value sent by the client with a hash of the user’s password. However, because the mechanism must read user passwords, all users that want to be authenticated through DIGEST-MD5 must have {CLEAR} passwords in the directory. When storing {CLEAR} passwords in the directory, you must ensure that access to password values is properly restricted through ACIs, as described in Chapter 6, Directory Server Access Control. In addition, you need to configure attribute encryption in the suffix, as described in Encrypting Attribute Values.

ProcedureTo Configure the DIGEST-MD5 Mechanism

The following procedure explains how to configure Directory Server to use DIGEST-MD5.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Use the ldapsearch command to verify that DIGEST-MD5 is a value of the supportedSASLMechanisms attribute on the root entry.

    For example, the following command shows which SASL mechanisms are enabled:


    $ ldapsearch -h host -p port -D cn=admin,cn=Administrators,cn=config -w - \
 -s base -b "" "(objectclass=*)" supportedSASLMechanisms
Enter bind password:
dn:
supportedSASLMechanisms: EXTERNAL
supportedSASLMechanisms: DIGEST-MD5
supportedSASLMechanisms: GSSAPI
^D

  2. If DIGEST-MD5 is not enabled, enable it.


    $ ldapmodify -h host -p port -D cn=admin,cn=Administrators,cn=config -w - 
Enter bind password:
dn: cn=SASL, cn=security, cn=config
changetype: modify
add: dsSaslPluginsEnable
dsSaslPluginsEnable: DIGEST-MD5
-
replace: dsSaslPluginsPath
dsSaslPluginsPath: SASL-library
^D

    where SASL-library is one of the following:

    JES installation

    /usr/lib/mps/sasl2

    Zip installation

    install-path/dsee6/private/lib

  3. Use the default identity mapping for DIGEST-MD5, or create new ones.

    For information, see DIGEST-MD5 Identity Mappings.

  4. Ensure that the password is stored in {CLEAR} for all users who will access the server through SSL using DIGEST-MD5.

    See Chapter 7, Directory Server Password Policy for password storage schemes.

  5. If you modified the SASL configuration entry or one of the DIGEST-MD5 identity mapping entries, restart Directory Server.

DIGEST-MD5 Identity Mappings

Identity mappings for SASL mechanisms try to match the credentials of the SASL identity with a user entry in the directory. Authentication fails if the mapping cannot find a DN that corresponds to the SASL identity. See Sun Java System Directory Server Enterprise Edition 6.2 Reference for a complete description of this mechanism.

The SASL identity is a string called the Principal that represents a user in a format specific to each mechanism. In DIGEST-MD5, clients should create a Principal that contains either a dn: prefix and an LDAP DN or a u: prefix followed by any text determined by the client. During the mapping, the Principal that is sent by the client is available in the ${Principal} placeholder.

The following entry in your server configuration is the default identity mapping for DIGEST-MD5:


dn: cn=default,cn=DIGEST-MD5,cn=identity mapping,cn=config
objectClass: top
objectClass: nsContainer
objectClass: dsIdentityMapping
objectClass: dsPatternMatching
cn: default
dsMatching-pattern: \${Principal}
dsMatching-regexp: dn:(.*)
dsMappedDN: \$1

This identity mapping assumes that the dn field of the Principal contains the exact DN of an existing user in the directory.

ProcedureTo Define Your Own Identity Mappings for DIGEST-MD5

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Edit the default mapping entry or create new mapping entries under cn=DIGEST-MD5,cn=identity mapping,cn=config.

    The following command shows how this mapping would be defined:


    $ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: cn=unqualified-username,cn=DIGEST-MD5,cn=identity mapping
cn=config
objectclass: dsIdentityMapping
objectclass: dsPatternMatching
objectclass: nsContainer
objectclass: top
cn: unqualified-username
dsMatching-pattern: \${Principal}
dsMatching-regexp: u:(.*)@(.*)\\.com
dsSearchBaseDN: dc=\$2
dsSearchFilter: (uid=\$1)

  2. Restart Directory Server for your new mappings to take effect.

SASL Authentication Through GSSAPI (Solaris OS Only)

The Generic Security Service API (GSSAPI) over SASL allows you to use a third-party security system such as Kerberos V5 to authenticate clients. The GSSAPI library is available only for the Solaris OS SPARC® platform. Sun recommends that you install the Kerberos V5 implementation on the Sun Enterprise Authentication MechanismTM 1.0.1 server.

The server uses the GSSAPI to validate the identity of the user. Then, the SASL mechanism applies the GSSAPI mapping rules to obtain a DN that is the bind DN for all operations during this connection.

ProcedureTo Configure the Kerberos System

Configure the Kerberos software according to the manufacturer’s instructions. If you are using the Sun Enterprise Authentication Mechanism 1.0.1 server, use this procedure.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Configure the files in /etc/krb5.

  2. Create the Kerberos database for storing users and services.

  3. In the database, create the Principal for the LDAP service.


    $ ldap/server-FQDN@realm

    where server-FQDN is the fully qualified domain name of your Directory Server.

  4. Start the Kerberos daemon processes.

    Note –

    The DNS must be configured on the host machine.

    Refer to your software documentation for detailed instructions for each of these steps. Also, see Example Configuration of Kerberos Authentication Using GSSAPI With SASL.

ProcedureTo Configure the GSSAPI Mechanism

The following procedure explains how to configure Directory Server to use GSSAPI on the Solaris OS:

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Create the default identity mapping for GSSAPI and any custom mappings as described in GSSAPI Identity Mappings.

  2. Create a keytab to store the service keys.

    Your LDAP service key is stored in the keytab.

    1. Ensure that the keytab is only readable by the Directory Server user.

    2. Change the file name to be different from the default /etc/krb5/krb5.keytab.

    3. Set the environment variable KRB5_KTNAME to ensure that the new keytab is used rather than the default keytab.

  3. If you modified the SASL configuration entry or one of the GSSAPI identity mapping entries, restart Directory Server.

    Note that the DNS must be configured on the host machine.

GSSAPI Identity Mappings

Identity mappings for SASL mechanisms try to match credentials of the SASL identity with a user entry in the directory. Authentication fails if the mapping cannot find a DN that corresponds to the SASL identity.

The SASL identity is a string called the Principal that represents a user in a format specific to each mechanism. In Kerberos using GSSAPI, the Principal is an identity with the format uid [/instance][@ realm]. The uid can contain an optional instance identifier followed by an optional realm that is often a domain name. For example, the following strings are all valid user Principals:


bjensen
bjensen/Sales
bjensen@EXAMPLE.COM
bjensen/Sales@EXAMPLE.COM

Initially, no GSSAPI mappings are defined in the directory. Define a default mapping and any custom mappings that you need according to how your clients define the Principal that your clients use.

ProcedureTo Define Identity Mappings for GSSAPI

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Create new mapping entries under cn=GSSAPI,cn=identity mapping, cn=config.

    See Sun Java System Directory Server Enterprise Edition 6.2 Reference for the definition of the attributes in an identity mapping entry. Examples of GSSAPI mappings are located in instance-path/ldif/identityMapping_Examples.ldif.

    The default GSSAPI mapping in this file assumes that the Principal contains only a user ID. This mapping determines a user in a fixed branch of the directory:


    dn: cn=default,cn=GSSAPI,cn=identity mapping,cn=config
objectclass: dsIdentityMapping
objectclass: nsContainer
objectclass: top
cn: default
dsMappedDN: uid=\${Principal},ou=people,dc=example,dc=com

    Another example in this file shows how to determine the user ID when the user ID is contained in a Principal that includes a known realm.


    dn: cn=same_realm,cn=GSSAPI,cn=identity mapping,cn=config
objectclass: dsIdentityMapping
objectclass: dsPatternMatching
objectclass: nsContainer
objectclass: top
cn: same_realm
dsMatching-pattern: \${Principal}
dsMatching-regexp: (.*)@EXAMPLE.COM
dsMappedDN: uid=\$1,ou=people,dc=EXAMPLE,dc=COM

  2. Restart Directory Server for your new mappings to take effect.

Configuring LDAP Clients to Use Security

The following sections explain how to configure and use SSL in LDAP clients that want to establish secure connections with Directory Server. In an SSL connection, the server sends its certificate to the client. The client must first authenticate the server by trusting its certificate. Then, the client can optionally initiate one of the client authentication mechanisms by sending its own certificate or information for one of the two SASL mechanism. The SASL mechanisms are DIGEST-MD5 and GSSAPI using Kerberos V5.

The following sections use the ldapsearch tool as an example of an SSL-enabled LDAP client.

To configure SSL connections on other LDAP clients, refer to the documentation provided with your application.

Note –

Some client applications implement SSL but do not verify that the server has a trusted certificate. These client applications use the SSL protocol to provide data encryption but cannot guarantee confidentiality nor protect against impersonation.

The following sections explain how to configure LDAP clients to use security:

Using SASL DIGEST-MD5 in Clients

When using the DIGEST-MD5 mechanism in clients, you do not need to install a user certificate. However, if you want to use encrypted SSL connections, you must still trust the server certificate as described in Managing Certificates.

Specifying a Realm

A realm defines the namespace from which the authentication identity is selected. In DIGEST-MD5 authentication, you must authenticate to a specific realm.

Directory Server uses the fully qualified host name of the machine as the default realm for DIGEST-MD5. The server uses the lowercase value of the host name that is found in the nsslapd-localhost configuration attribute.

If you do not specify a realm, the default realm offered by the server is used.

Specifying Environment Variables

In the UNIX environment, you must set the SASL-PATH environment variable so that the LDAP tools can find the DIGEST-MD5 libraries. The DIGEST-MD5 library is a shared library that is dynamically loaded by the SASL plug-in. Set the SASL_PATH environment variable as follows:


export SASL_PATH=SASL-library

This path assumes that Directory Server is installed on the same host where the LDAP tools are invoked.

Examples of the ldapsearch Command

You can perform DIGEST-MD5 client authentication without using SSL. The following example uses the default DIGEST-MD5 identity mapping to determine the bind DN:


$ ldapsearch -h host1 -p 1389 \
 -o mech=DIGEST-MD5 [ \
 -o realm="example.com"] \
 -o authid="dn:uid=bjensen,dc=example,dc=com" \
 -w - \
 -o authzid="dn:uid=bjensen,dc=example,dc=com" \
 -o secProp="minssf=56,maxssf=256,noplain" \
 -b "dc=example,dc=com" "(givenname=Richard)"

The preceding example shows the use of the -o (lowercase letter o) option to specify SASL options. The realm is optional, but if specified, it must be the fully qualified domain name of the server host machine. The authid and authzid must both be present and identical, although the authzid intended for proxy operations is not used. The -w password option applies to the authid.

The value of authid is the Principal used in identity mapping. The authid should contain either the dn: prefix followed by a valid user DN in the directory, or the u: prefix followed by any string determined by the client. This use of authid allows you to use the mappings that are shown in DIGEST-MD5 Identity Mappings.

The most common configuration is for an SSL connection to provide encryption over the LDAPS secure port and DIGEST-MD5 to provide the client authentication. The following example performs the same operation over SSL:


$ ldapsearch -h host1 -P 1636 \
 -Z -P .mozilla/bjensen/BJE6001.slt/cert8.db \
 -N "cert-example" -w - \
 -o mech=DIGEST-MD5 [-o realm="example.com"] \
 -o authid="dn:uid=bjensen,dc=example,dc=com" \
 -o authzid="dn:uid=bjensen,dc=example,dc=com" \
 -o secProp="minssf=0,maxssf=0,noplain" \
 -b "dc=example,dc=com" "(givenname=Richard)"

In this example, the -N and -w options are required by the ldapsearch command, as the operation is performed over SSL. However , these options are not used for client authentication. Instead, the server performs another DIGEST-MD5 identity mapping of the Principal in the authid value.

Using Kerberos SASL GSSAPI in Clients

When using the GSSAPI mechanism in clients, you do not need to install a user certificate, but you must configure the Kerberos V5 security system. Also, if you want to use encrypted SSL connections, you must trust the server certificate as described in Managing Certificates.

ProcedureTo Configure Kerberos V5 on a Host

You must configure Kerberos V5 on the host machine where your LDAP clients will run.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Install Kerberos V5 according to its installation instructions.

    Sun recommends installing the Sun Enterprise Authentication Mechanism 1.0.1 client software.

  2. Configure the Kerberos software.

    Using the Sun Enterprise Authentication Mechanism software, configure the files under /etc/krb5. This configuration sets up the kdc server, and defines the default realm and any other configuration required by your Kerberos system.

  3. If necessary, modify the file /etc/gss/mech so that the first value that is listed is kerberos_v5 .

ProcedureTo Specify SASL Options for Kerberos Authentication

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Before using a client application that is enabled with the GSSAPI mechanism, initialize the Kerberos security system with your user Principal.


    $ kinit user-principal

    where the user-principal is your SASL identity, for example, bjensen@example.com.

  2. Specify SASL options for using Kerberos.

    Note that in the UNIX environment, you must set the SASL_PATH environment variable to the correct path for the SASL libraries. For example in the Korn shell:


    $ export SASL_PATH=SASL-library

    This path assumes that Directory Server is installed on the same host where the LDAP tools are invoked.

    The following example of the ldapsearch tool shows the use of the -o (lowercase letter o) option to specify SASL options for using Kerberos:


    $ ldapsearch -h www.host1.com -p 1389 -o mech=GSSAPI -o authid="bjensen@EXAMPLE.COM" \
 -o authzid="bjensen@EXAMPLE.COM" -b "dc=example,dc=com" "(givenname=Richard)"

    The authid can be omitted because it is present in the Kerberos cache that was initialized by the kinit command. If authid is present, authid and authzid must be identical, although the authzid intended for proxy operations is not used. The value of authid is the Principal that is used in identity mapping. The Principal must be the full Principal, including the realm. See GSSAPI Identity Mappings.

Example Configuration of Kerberos Authentication Using GSSAPI With SASL

Configuring Kerberos for Directory Server can be complicated. Your first point of reference should be the Kerberos documentation.

For more help, use the following example procedure to get an idea of which steps to follow. Be aware, however, that this procedure is an example. You must modify the procedure to suit your own configuration and your own environment.

Additional information about configuring and using Kerberos in the Solaris OS can be found in System Administration Guide: Security Services. This guide is a part of the Solaris documentation set. You can also consult the man pages.

    Information about this example and the steps used are as follows:

  1. Assumptions for This Example

  2. All Machines: Edit the Kerberos Client Configuration File

  3. All Machines: Edit the Administration Server ACL Configuration File

  4. KDC Machine: Edit the KDC Server Configuration File

  5. KDC Machine: Create the KDC Database

  6. KDC Machine: Create an Administration Principal and Keytab

  7. KDC Machine: Start the Kerberos Daemons

  8. KDC Machine: Add Host Principals for the KDC and Directory Server Machines

  9. KDC Machine: Add an LDAP Principal for the Directory Server

  10. KDC Machine: Add a Test User to the KDC

  11. Directory Server Machine: Install the Directory Server

  12. Directory Server Machine: Configure the Directory Server to Enable GSSAPI

  13. Directory Server Machine: Create a Directory Server Keytab

  14. Directory Server Machine: Add a Test User to the Directory Server

  15. Directory Server Machine: Get a Kerberos Ticket as the Test User

  16. Client Machine: Authenticate to the Directory Server Through GSSAPI

Assumptions for This Example

This example procedure describes the process of configuring one machine to operate as a Key Distribution Center (KDC), and a second machine to run a Directory Server. The result of this procedure is that users can perform Kerberos authentication through GSSAPI.

It is possible to run both the KDC and the Directory Server on the same machine. If you choose to run both on the same machine, use the same procedure, but omit the steps for the Directory Server machine that have already been done for the KDC machine.

This procedure makes a number of assumptions about the environment that is used. When using the example procedure, modify the values accordingly to suit your environment. These assumptions are:

All Machines: Edit the Kerberos Client Configuration File

The /etc/krb5/krb5.conf configuration file provides information that Kerberos clients require in order to communicate with the KDC.

Edit the /etc/krb5/krb5.conf configuration file on the KDC machine, the Directory Server machine, and any client machines that will authenticate to the Directory Server using Kerberos.

The updated /etc/krb5/krb5.conf configuration file should look like the contents of the following example.

Example 5–1 Edited Kerberos Client Configuration File /etc/krb5/krb5.conf 


#pragma ident   "@(#)krb5.conf  1.2     99/07/20 SMI"
# Copyright (c) 1999, by Sun Microsystems, Inc.
# All rights reserved.
#
# krb5.conf template
# In order to complete this configuration file
# you will need to replace the __<name\>__ placeholders
# with appropriate values for your network.
#

[libdefaults]
        default_realm = EXAMPLE.COM
[realms]
        EXAMPLE.COM = {
                kdc = kdc.example.com
                admin_server = kdc.example.com
        }
[domain_realm]
        .example.com = EXAMPLE.COM
[logging]
        default = FILE:/var/krb5/kdc.log
        kdc = FILE:/var/krb5/kdc.log
        kdc_rotate = {

# How often to rotate kdc.log. Logs will get rotated no more
# often than the period, and less often if the KDC is not used
# frequently.
                period = 1d

# how many versions of kdc.log to keep around (kdc.log.0, kdc.log.1, ...)
                versions = 10
        }

[appdefaults]
        kinit = {
                renewable = true
                forwardable= true
        }
        gkadmin = {
                help_url =
 http://docs.sun.com:80/ab2/coll.384.1/SEAM/@AB2PageView/1195
        }

All Machines: Edit the Administration Server ACL Configuration File

Replace "___default_realm___" with "EXAMPLE.COM" in the /etc/krb5/kadm5.acl configuration file. The updated file should look like the following example.

Example 5–2 Edited Administration Server ACL Configuration File


#
# Copyright (c) 1998-2000 by Sun Microsystems, Inc.
# All rights reserved.
#
# pragma ident   "@(#)kadm5.acl  1.1     01/03/19 SMI"
*/admin@EXAMPLE.COM *

KDC Machine: Edit the KDC Server Configuration File

Edit the /etc/krb5/kdc.conf file to replace "___default_realm___" with "EXAMPLE.COM". The updated file should look like the following example.

Example 5–3 Edited KDC Server Configuration File /etc/krb5/kdc.conf 


# Copyright 1998-2002 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
#ident  "@(#)kdc.conf   1.2     02/02/14 SMI"

[kdcdefaults]
        kdc_ports = 88,750

[realms]
        EXAMPLE.COM = {
                profile = /etc/krb5/krb5.conf
                database_name = /var/krb5/principal
                admin_keytab = /etc/krb5/kadm5.keytab
                acl_file = /etc/krb5/kadm5.acl
                kadmind_port = 749
                max_life = 8h 0m 0s
                max_renewable_life = 7d 0h 0m 0s
                default_principal_flags = +preauth
        }

KDC Machine: Create the KDC Database


$ /usr/sbin/kdb5_util create -r EXAMPLE.COM -s
Initializing database ’/var/krb5/principal’ for realm ’EXAMPLE.COM’,
master key name ’K/M@EXAMPLE.COM’
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
Enter KDC database master key: password
Re-enter KDC database master key to verify: password
$

KDC Machine: Create an Administration Principal and Keytab

Use the following command to create an administration user with a Principal of kws/admin@EXAMPLE.COM and service keys that will be used by the administration daemon.


$ /usr/sbin/kadmin.local
kadmin.local:  add_principal kws/admin
Enter password for principal "kws/admin@EXAMPLE.COM": secret
Re-enter password for principal "kws/admin@EXAMPLE.COM": secret
Principal "kws/admin@EXAMPLE.COM" created.
kadmin.local:  ktadd -k /etc/krb5/kadm5.keytab kadmin/kdc.example.com
Entry for principal kadmin/kdc.example.com with kvno 3, encryption type
 DES-CBC-CRC added to keytab WRFILE:/etc/krb5/kadm5.keytab.
kadmin.local:  ktadd -k /etc/krb5/kadm5.keytab changepw/kdc.example.com

Entry for principal changepw/kdc.example.com with kvno 3, encryption type
 DES-CBC-CRC added to keytab WRFILE:/etc/krb5/kadm5.keytab.
kadmin.local:  ktadd -k /etc/krb5/kadm5.keytab kadmin/changepw
Entry for principal kadmin/changepw with kvno 3, encryption type
 DES-CBC-CRC added to keytab WRFILE:/etc/krb5/kadm5.keytab.
kadmin.local:  quit$

KDC Machine: Start the Kerberos Daemons

Run the following commands to start the KDC and administration daemons:


$ /etc/init.d/kdc start
$ /etc/init.d/kdc.master start
$

The KDC process will appear in the process list as /usr/lib/krb5/krb5kdc. The administration daemon will appear as /usr/lib/krb5/kadmind.

Note than in the Solaris 10 OS, the daemons are managed by the Service Management Facility (SMF) framework. Start the daemons on the Solaris 10 OS:


$ svcadm disable network/security/krb5kdc
$ svcadm enable network/security/krb5kdc
$ svcadm disable network/security/kadmin
$ svcadm enable network/security/kadmin
$

KDC Machine: Add Host Principals for the KDC and Directory Server Machines

Use the following sequence of commands to add host Principals to the Kerberos database for the KDC and Directory Server machines. The host Principal is used by certain Kerberos utilities such as klist.


$ /usr/sbin/kadmin -p kws/admin
Enter Password: secret
kadmin:  add_principal -randkey host/kdc.example.com
Principal "host/kdc.example.com@EXAMPLE.COM" created.
kadmin:  ktadd host/kdc.example.com
Entry for principal host/kdc.example.com with kvno 3, encryption type
 DES-CBC-CRC added to keytab WRFILE:/etc/krb5/krb5.keytab.
kadmin:  add_principal -randkey host/directory.example.com
Principal "host/directory.example.com@EXAMPLE.COM" created.
kadmin:  ktadd host/directory.example.com
Entry for principal host/directory.example.com with kvno 3, encryption type
 DES-CBC-CRC added to keytab WRFILE:/etc/krb5/krb5.keytab.
kadmin:  quit
$

KDC Machine: Add an LDAP Principal for the Directory Server

For the Directory Server to be able to validate the Kerberos tickets that are held by authenticating users, the Directory Server must have its own Principal. Currently, the Directory Server is hard coded to require a Principal of ldap/fqdn@realm where fqdn is the fully-qualified domain name of the Directory Server and realm is the Kerberos realm. The fqdn must match the fully qualified name provided when installing the Directory Server. In this case, the Principal for the Directory Server would be ldap/directory.example.com@EXAMPLE.COM.

Use the following sequence of commands to create an LDAP Principal for the Directory Server:


$ /usr/sbin/kadmin -p kws/admin 
Enter Password: secret 
kadmin: add_principal -randkey ldap/directory.example.com 
Principal "ldap/directory.example.com@EXAMPLE.COM" created. 
kadmin: quit 
$

KDC Machine: Add a Test User to the KDC

To perform Kerberos authentication, the user authenticating must exist in the Kerberos database. In this example, the user has the user name kerberos-test, which means that the Kerberos Principal is kerberos-test@EXAMPLE.COM.

Create the user by using the command sequence in this example:


$ /usr/sbin/kadmin -p kws/admin
Enter Password: secret
kadmin:  add_principal kerberos-test
Enter password for principal "kerberos-test@EXAMPLE.COM": secret

Re-enter password for principal "kerberos-test@EXAMPLE.COM": secret

Principal "kerberos-test@EXAMPLE.COM" created.
kadmin:  quit
$

Directory Server Machine: Install the Directory Server

Install Directory Server 6.0 and the latest patches. Following are example settings.

Variable Type 

Example Value 

Fully qualified computer name 

directory.example.com

Installation directory 

/opt/SUNWdsee

Instance path 

/local/ds

Server user 

unixuser

Server group 

unixgroup

Server port 

389

Suffix 

dc=example,dc=com

Directory Server Machine: Configure the Directory Server to Enable GSSAPI

First, create the file /data/ds/shared/bin/gssapi.ldif to define the mapping that should be used by the Directory Server, and to identify which Kerberos user is authenticating, based on the Principal. Create the file contents to be the same as what is shown in the following example.

Example 5–4 gssapi.ldif File Contents


dn: cn=GSSAPI,cn=identity mapping,cn=config
changetype: add
objectClass: top
objectClass: nsContainer
cn: GSSAPI
dn: cn=default,cn=GSSAPI,cn=identity mapping,cn=config
changetype: add
objectClass: top
objectClass: nsContainer
objectClass: dsIdentityMapping
objectClass: dsPatternMatching
cn: default
dsMatching-pattern: \${Principal}
dsMatching-regexp: (.*)@EXAMPLE.COM
dsMappedDN: uid=\$1,ou=People,dc=example,dc=com

dn: cn=SASL,cn=security,cn=config
changetype: modify
replace: dsSaslPluginsPath
dsSaslPluginsPath: /usr/lib/mps/sasl2/libsasl.so

Next, use the ldapmodify command to update the Directory Server to enable GSSAPI with the appropriate mappings, as shown in the following example:


$ ldapmodify -D cn=admin,cn=Administrators,cn=config -w - -a -f /data/ds/shared/bin/gssapi.ldif
adding new entry cn=GSSAPI,cn=identity mapping,cn=config
adding new entry cn=default,cn=GSSAPI,cn=identity mapping,cn=config
modifying entry cn=SASL,cn=security,cn=config
$

Directory Server Machine: Create a Directory Server Keytab

As mentioned previously, to authenticate Kerberos users through GSSAPI, the Directory Server must have its own Principal in the KDC. For authentication to work properly, the Principal information must reside in a Kerberos keytab on the Directory Server machine. This information must be in a file that is readable by the user account under which the Directory Server operates.

Create a keytab file with the correct properties by using the following command sequence:


$ /usr/sbin/kadmin -p kws/admin
Enter Password: secret
kadmin:  ktadd -k //local/ds/config/ldap.keytab ldap/directory.example.com
Entry for principal ldap/directory.example.com with kvno 3, encryption type
 DES-CBC-CRC added to keytab
 WRFILE:/local/ds/config/ldap.keytab.
kadmin:  quit
$

Change the permissions and ownership on this custom keytab. Make the keytab owned by the user account used to run Directory Server and readable only by that user:


$ chown unixuser:unixgroup /local/ds/config /ldap.keytab
$ chmod 600 /local/ds/config/ldap.keytab
$

By default, the Directory Server tries to use the standard Kerberos keytab in the file /etc/kerb5/krb5.keytab. However, making this file readable by the Directory Server user could constitute a security risk, which is why a custom keytab was created for the Directory Server.

Configure the Directory Server to use the new custom keytab. Do this by setting the KRB5_KTNAME environment variable.

Finally, restart the Directory Server to allow these changes to take effect:


$ KRB5_KTNAME=/etc/krb5/ldap.keytab dsadm restart /local/ds

Directory Server Machine: Add a Test User to the Directory Server

To authenticate a Kerberos user to the Directory Server, there must be a directory entry for the user that corresponds to the Kerberos Principal for that user.

In a previous step, a test user was added to the Kerberos database with a Principal of kerberos-test@EXAMPLE.COM. Because of the identity mapping configuration added to the directory, the corresponding directory entry for that user must have a DN of uid=kerberos-test,ou=People,dc=example,dc=com.

Before you can add the user to the directory, you must create the file testuser.ldif with the following contents.

Example 5–5 New testuser.ldif File


dn: uid=kerberos-test,ou=People,dc=example,dc=com
changetype: add
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
uid: kerberos-test
givenName: Kerberos
sn: Test
cn: Kerberos Test
description: An account for testing Kerberos authentication through GSSAPI

Next, use ldapmodify to add this entry to the server:


$ ldapmodify -D cn=admin,cn=Administrators,cn=config -w - -f testuser.ldif
adding new entry uid=kerberos-test,ou=People,dc=example,dc=com
$

Directory Server Machine: Get a Kerberos Ticket as the Test User

The test user exists in the Kerberos database and Directory Server and the KDC. Therefore, it is now possible to authenticate as the test user to the Directory Server over Kerberos through GSSAPI.

First, use the kinit command to get a Kerberos ticket for the user, as shown in the following example:


$ kinit kerberos-test
Password for kerberos-test@EXAMPLE.COM: secret
$

Then, use the klist command to view information about this ticket:


$ klist
Ticket cache: /tmp/krb5cc_0
Default principal: kerberos-test@EXAMPLE.COM

Valid starting            Expires                   Service principal
Sat Jul 24 00:24:15 2004  Sat Jul 24 08:24:15 2004  krbtgt/EXAMPLE.COM@EXAMPLE.COM
        renew until Sat Jul 31 00:24:15 2004
$

Client Machine: Authenticate to the Directory Server Through GSSAPI

The final step is to authenticate to the Directory Server by using GSSAPI. The ldapsearch utility provided with the Directory Server provides support for SASL authentication, including GSSAPI, DIGEST-MD5, and EXTERNAL mechanisms. However, to bind by using GSSAPI you must provide the client with the path to the SASL library. Provide the path by setting the SASL_PATH environment variable to the lib/sasl directory:


$ SASL_PATH=SASL-library
$ export SASL_PATH
$

To actually perform a Kerberos-based authentication to the Directory Server using ldapsearch, you must include the -o mech=GSSAPI and -o authzid=principal arguments.

You must also specify the fully qualified host name, shown here as -h directory.example.com, which must match the value of the nsslapd-localhost attribute on cn=config for the server. This use of the -h option is needed because the GSSAPI authentication process requires the host name provided by the client to match the host name provided by the server.

The following example retrieves the dc=example,dc=com entry while authenticated as the Kerberos test user account created previously:


$ ldapsearch -h directory.example.com -p 389 -o mech=GSSAPI \
 -o authzid="kerberos-test@EXAMPLE.COM" -b "dc=example,dc=com" -s base "(objectClass=*)"
version: 1
dn: dc=example,dc=com
dc: example
objectClass: top
objectClass: domain
$

Check the Directory Server access log to confirm that the authentication was processed as expected:


$ tail -12 /local/ds/logs/access

[24/Jul/2004:00:30:47 -0500] conn=0 op=-1 msgId=-1 - fd=23 slot=23 LDAP 
		connection from 1.1.1.8 to 1.1.1.8
[24/Jul/2004:00:30:47 -0500] conn=0 op=0 msgId=1 - BIND dn="" method=sasl 
     version=3 mech=GSSAPI
[24/Jul/2004:00:30:47 -0500] conn=0 op=0 msgId=1 - RESULT err=14 tag=97 
     nentries=0 etime=0, SASL bind in progress
[24/Jul/2004:00:30:47 -0500] conn=0 op=1 msgId=2 - BIND dn="" method=sasl 
     version=3 mech=GSSAPI
[24/Jul/2004:00:30:47 -0500] conn=0 op=1 msgId=2 - RESULT err=14 tag=97 
     nentries=0 etime=0, SASL bind in progress
[24/Jul/2004:00:30:47 -0500] conn=0 op=2 msgId=3 - BIND dn="" method=sasl 
     version=3 mech=GSSAPI
[24/Jul/2004:00:30:47 -0500] conn=0 op=2 msgId=3 - RESULT err=0 tag=97 
     nentries=0 etime=0 dn="uid=kerberos-test,ou=people,dc=example,dc=com"
[24/Jul/2004:00:30:47 -0500] conn=0 op=3 msgId=4 - SRCH base="dc=example,dc=com"
     scope=0 filter="(objectClass=*)" attrs=ALL
[24/Jul/2004:00:30:47 -0500] conn=0 op=3 msgId=4 - RESULT err=0 tag=101 nentries=1 
     etime=0
[24/Jul/2004:00:30:47 -0500] conn=0 op=4 msgId=5 - UNBIND
[24/Jul/2004:00:30:47 -0500] conn=0 op=4 msgId=-1 - closing - U1
[24/Jul/2004:00:30:48 -0500] conn=0 op=-1 msgId=-1 - closed.
$

This example shows that the bind is a three-step process. The first two steps return LDAP result 14 (SASL bind in progress), and the third step shows that the bind was successful. The method=sasl and mech=GSSAPI tags show that the bind used the GSSAPI SASL mechanism. The dn="uid=kerberos-test,ou=people,dc=example,dc=com" at the end of the successful bind response shows that the bind was performed as the appropriate user.

Pass-Through Authentication

Pass-through authentication (PTA) is a mechanism by which bind requests are filtered by bind DN. One Directory Server (the delegator) receives the bind request and, based on the filter, can consult another Directory Server (the delegate) to authenticate bind requests. As part of this functionality, the PTA plug-in enables the delegator Directory Server to accept simple password-based bind operations for entries that are not necessarily stored in its local database.

The PTA plug-in is also used by DSCC for private communication with the server. When a server instance is registered in DSCC, the PTA plug-in is enabled and the DSCC URL is added as an argument.


$ dsconf get-plugin-prop -h host -p port "Pass Through Authentication" enabled argument
argument  :  ldap://DSCC_URL:DSCC_PORT/cn=dscc
enabled   :  on
Note –

If possible, avoid modifying the PTA plug-in for your own use. Modifications to the PTA plug-in can cause access problems for DSCC.

If you cannot avoid modifying the PTA plug-in, you must do the following:

If the PTA plug-in is disabled or the DSCC URL is removed from the argument, the server instance will appear as inaccessible in DSCC. If this happens, DSCC will automatically give you the option of resetting the PTA plug-in.

Chapter 6 Directory Server Access Control

The control of access to your directory is an integral part of creating a secure directory. This chapter describes access control instructions (ACIs) that determine which permissions are granted to users who access the directory.

While you are in the planning phase of your directory deployment, define an access control strategy that serves your overall security policy. See the Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide for tips on planning an access control strategy.

For additional information about ACIs, including ACI syntax and bind rules, see Sun Java System Directory Server Enterprise Edition 6.2 Reference.

This chapter covers the following topics:

Creating, Viewing, and Modifying ACIs

You can create ACIs either by using Directory Service Control Center (DSCC) or by using the command line. Whichever method you choose, it is often easier to view and copy an existing ACI value, rather than to create a new ACI from scratch.

You can view and modify the aci attribute values in DSCC. For information about how to modify ACIs through DSCC, see the DSCC online help.

ProcedureTo Create, Modify, and Delete ACIs

To create ACIs by using the command line, you first create the ACIs in a file using LDIF statements. Then you add the ACIs to your directory tree by using the ldapmodify command.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Create the ACI in an LDIF file. 


    dn: dc=example,dc=com
changetype: modify
add: aci
aci: (target)(version 3.0; acl "name";permission bindrules;)

    This example shows how to add an ACI. To modify or delete the ACI, replace add with replace or delete.

    For more examples of ACIs that are commonly used, see Access Control Usage Examples.

  2. Make the change using the LDIF file. 


    $ ldapmodify -h host -p port -D cn=admin,cn=Administrators,cn=config -w - -f ldif-file

ProcedureTo View ACI Attribute Values

ACIs are stored as one or more values of the aci attribute of an entry. The aci attribute is a multi-valued operational attribute that can be read and modified by directory users. Therefore, the ACI attribute itself should be protected by ACIs. Administration users are usually given full access to the aci attribute.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. View the ACI attribute value of an entry by running the following ldapsearch command:


    $ ldapsearch -h host -p port -D cn=admin,cn=Administrators,cn=config -w - \
 -b entryDN -s base "(objectclass=*)" aci

    The result is LDIF text that you can copy to your new LDIF ACI definition for editing. Because the value of an ACI is a long string, the output from the ldapsearch operation is likely to be displayed over several lines. In addition, the first space is a continuation marker. If you want the LDIF output to not contain a continuation marker, use the -T option. Take the output format into account when copying and pasting the LDIF output.

    Note –

    To view the permissions that an aci value grants and denies, see Viewing Effective Rights.

ProcedureTo View ACIs at the Root Level

When you create a suffix, some default ACIs are created at the top or root level. These ACIs allow the default administration user cn=admin,cn=Administrators,cn=config to have the same access rights to directory data as the Directory Manager.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. View the default root level ACIs.


    $ ldapsearch -h host -p port -D cn=admin,cn=Administrators,cn=config -w - \
 -b "" -s base "(objectclass=*)" aci

Access Control Usage Examples

The examples in this section illustrate how an imaginary ISP company, Example.com, would implement its access control policy.

In addition, you can find ACI examples in the example LDIF file provided with your installation, install_path/ds6/ldif/Example.ldif.

All of the examples explain how to perform a given task by using an LDIF file. The following figure shows the example.com Directory Information Tree in graphical form.

Topography of an example directory tree. The top level entry and the entries directly below the top level entry are shown.

Example.com offers a web hosting service and internet access. Part of Example.com’s web-hosting service is to host the directories of client companies. Example.com actually hosts and partially manages the directories of two medium-sized companies, Company333 and Company999. Example.com also provides internet access to a number of individual subscribers.

Example.com wants to put the following access rules in place:

Granting Anonymous Access

Most directories are configured to enable you to anonymously access at least one suffix for read, search, or compare. You might want to set these permissions if you are running a corporate personnel directory, such as a phone book that you want employees to be able to search. This is the case at Example.com internally, as shown in ACI “Anonymous Example.com”.

As an ISP, Example.com also wants to advertise the contact information of all of its subscribers by creating a public phone book that is accessible to the world. This is depicted in ACI “Anonymous World”.

ACI “Anonymous Example.com”

In LDIF, to grant read, search, and compare permissions to the entire Example.com tree to Example.com employees, you would write the following statement:


aci: (targetattr !="userPassword")(version 3.0; acl "Anonymous
 example"; allow (read, search, compare)
 userdn= "ldap:///anyone") ;)

This example assumes that the aci is added to the dc=example,dc=com entry. Note that the userPassword attribute is excluded from the scope of the ACI.

Note –

Protect attributes that are confidential and attributes that should not be visible using the same syntax used in the example to protect the password attribute, (targetattr !="attribute-name").

ACI “Anonymous World”

In LDIF, to grant read and search access of the individual subscribers subtree to the world, while denying access to information on subscribers who want to be unlisted, you could write the following statement:


aci: (targetfilter= "(!(unlistedSubscriber=yes))")
 (targetattr="homePostalAddress || homePhone || mail")
 (version 3.0; acl "Anonymous World"; allow (read, search)
 userdn="ldap:///anyone";)

This example assumes that the ACI is added to the ou=subscribers,dc=example, dc=com entry. The example also assumes that every subscriber entry has an unlistedSubscriber attribute that is set to yes or no. The target definition filters out the unlisted subscribers based on the value of this attribute. For details on the filter definition, refer to Setting a Target Using Filtering.

Granting Write Access to Personal Entries

Many directory administrators want to allow internal users to change some but not all of the attributes in their own entry. The directory administrators at Example.com want to allow users to change their own password, home telephone number, and home address, but nothing else. This is depicted in ACI “Write Example.com”.

Example.com also has a policy to let their subscribers update their own personal information in the Example.com tree provided that the subscribers establish an SSL connection to the directory. This is depicted in ACI “Write Subscribers”.

ACI “Write Example.com”

Note –

By setting this permission, you are also granting users the right to delete attribute values.

In LDIF, to grant Example.com employees the right to update their home telephone number and home address, you would write the following statement:


aci: (targetattr="homePhone ||
 homePostalAddress")(version 3.0; acl "Write Example.com";
 allow (write) userdn="ldap:///self" ;)

This example assumes that the ACI is added to the ou=People,dc=example,dc=com entry.

ACI “Write Subscribers”

Note –

By setting this permission, you are also granting users the right to delete attribute values.

In LDIF, to grant Example.com subscribers the right to update their home telephone number, you would write the following statement:


aci: (targetattr="homePhone")
 (version 3.0; acl "Write Subscribers"; allow (write)
 userdn= "ldap://self" and authmethod="ssl";)

This example assumes that the aci is added to the ou=subscribers,dc=example, dc=com entry, and that users must bind using SSL.

Note that Example.com subscribers do not have write access to their home address because they might delete that attribute. The home address is business-critical information that Example.com needs billing purposes.

Granting Access to a Certain Level

You can set the scope of an ACI to affect different levels within your directory tree, to fine-tune the level of access you want to allow. The target ACI scope can be set to one of the following:

base

The entry itself

onelevel

The entry itself and all entries one level below

subtree

The entry itself and all entries beneath that entry, to an unlimited depth

ACI “Read Example.com only”

In LDIF, to grant Example.com subscribers the right to read the entry dc=example,dc=com for company contact information, but not allow access to any entries below it, you would write the following statement:


aci: (targetscope="base") (targetattr="*")(version 3.0;
 acl "Read Example.com only";  allow (read,search,compare)
 userdn="ldap:///cn=*,ou=subscribers,dc=example,dc=com";)

This example assumes that the ACI is added to the dc=example, dc=com entry.

Restricting Access to Key Roles

You can use role definitions in the directory to identify functions that are critical to your business, such as the administration of your network and directory.

For example, you might create a superAdmin role by identifying a subset of your system administrators who are available at a particular time of day and day of the week at corporate sites worldwide. Or you might want to create a First Aid role that includes all staff members who have first aid training at a particular site. For information about creating role definitions see Managing Roles.

When a role gives any sort of privileged user rights over critical corporate or business functions, consider restricting access to that role. For example, at Example.com, employees can add any role to their own entry, except the superAdmin role, as shown in the following example.

ACI “Roles”

In LDIF, to grant Example.com employees the right to add any role to their own entry, except the superAdmin role, you would write the following statement:


aci: (targetattr="*") (targattrfilters="add=nsRoleDN:
 (nsRoleDN !="cn=superAdmin, dc=example, dc=com")")
 (version 3.0; acl "Roles"; allow (write)
 userdn= "ldap:///self" ;)

This example assumes that the ACI is added to the ou=People,dc=example, dc=com entry.

Granting a Role Full Access to an Entire Suffix

Sometimes it is useful to grant certain users the same rights as the Directory Manager for a suffix. At Example.com, Kirsten Vaughan is an administrator for Directory Server. She has a role of superAdmin. This role has the following advantages:

Note –

Adding Kirsten Vaughan to the cn=Administrators,cn=config group would also grant her the same rights as Directory Manager.

To give a user the same rights as the Directory Manager for the whole server, follow the procedure in To Create an Administration User with Root Access.

ACI “Full Access”

In LDIF, to grant the administrator Kirsten Vaughan the same rights as a Directory Manager, use the following statement:


aci: (targetattr="*") (version 3.0; acl "Full Access";
 allow (all) groupdn= "ldap:///cn=SuperAdmin,dc=example,dc=com"
 and authmethod="ssl" ;)

This example assumes that the ACI is added to the root entry "" (no text).

Granting a Group Full Access to a Suffix

Most directories have groups that are used to identify certain corporate functions. A group can be given access to all or part of the directory. By applying access rights to a group, you can avoid setting access rights for each member individually. Instead, you grant users access rights by adding them to a group.

For example, when you create a Directory Server instance, an Administrators group cn=Administrators,cn=config with full access to the directory is created by default.

At Example.com, the Human Resources group is allowed full access to the ou=People branch of the directory so that they can update the employee directory, as shown in ACI “HR”.

ACI “HR”

In LDIF, to grant the HR group all rights to the employee branch of the directory, you would use the following statement:


aci: (targetattr="*") (version 3.0; acl "HR"; allow (all)
  groupdn= "ldap:///cn=HRgroup,ou=Groups,dc=example,dc=com";)

This example assumes that the ACI is added to the following entry:


ou=People,dc=example,dc=com

Granting Rights to Add and Delete Group Entries

Some organizations allow employees to create entries in the tree to increase employees' efficiency and to encourage employees to contribute to the corporate dynamics. At Example.com, for example, the social committee is organized into various clubs, such as tennis, swimming, skiing, and role-playing.

Any Example.com employee can create a group entry that represents a new club, as shown in ACI “Create Group”.

Any Example.com employee can become a member of one of these groups, as shown in Allowing Users to Add or Remove Themselves From a Group.

Only the group owner can modify or delete a group entry, as shown in ACI “Delete Group”.

ACI “Create Group”

In LDIF, to grant Example.com employees the right to create a group entry under the ou=Social Committee branch, you would write the following statement:


aci: (targetattr="*") (targattrfilters="add=objectClass: 
(|(objectClass=groupOfNames)(objectClass=top))") 
(version 3.0; acl "Create Group"; allow (read,search,add) 
userdn= "ldap:///uid=*,ou=People,dc=example,dc=com") 
and dns="*.Example.com";)

This example assumes that the ACI is added to the ou=Social Committee,dc=example,dc=com entry.

Note –

ACI “Delete Group”

In LDIF, to grant Example.com employees the right to modify or delete a group entry of the group to which they belong under the ou=Social Committee branch, you would write the following statement:


aci: (targetattr = "*") (targattrfilters="del=objectClass:
(objectClass=groupOfNames)")
 (version 3.0; acl "Delete Group"; allow (write,delete)
 userattr="owner#GROUPDN";)

This example assumes that the aci is added to the ou=Social Committee,dc=example,dc=com entry.

Note that to use DSCC to create this ACI is not very effective because you have to use manual editing mode to create the target filter and to check group ownership.

Allowing Users to Add or Remove Themselves From a Group

Many directories set ACIs that allow users to add or remove themselves from groups such as mailing lists.

At Example.com, employees can add themselves to any group entry under the ou=Social Committee subtree, as shown in ACI “Group Members”.

ACI “Group Members”

In LDIF, to grant Example.com employees the right to add themselves to a group, you would write the following statement:


aci: (targettattr="member")(version 3.0; acl "Group Members";
 allow (selfwrite)
 (userdn= "ldap:///uid=*,ou=People,dc=example,dc=com") ;)

This example assumes that the ACI is added to the ou=Social Committee, dc=example,dc=com entry.

Granting Conditional Access to a Group or Role

In many cases, when you grant a group or role privileged access to the directory, you must ensure that those privileges are protected from intruders trying to impersonate your privileged users. Therefore, in many cases, access control rules that grant critical access to a group or role are often associated with a number of conditions.

Example.com, for example, has created a Directory Administrator role for each of its hosted companies, Company333 and Company999. Example.com wants these companies to be able to manage their own data and implement their own access control rules while securing the data against intruders.

For this reason, Company333 and Company999 have full rights on their respective branches of the directory tree, provided that the following conditions are fulfilled:

These conditions are depicted in one ACI for each company, ACI “Company333” and ACI “Company999”. Because the content of both ACIs is the same, the following examples use the “Company333” ACI only.

ACI “Company333”

In LDIF, to grant Company333 full access to its own branch of the directory under the conditions stated previously, you would write the following statement:


aci: (targetattr = "*") (version 3.0; acl "Company333"; allow (all)
 (roledn="ldap:///cn=DirectoryAdmin,ou=Company333,
 ou=corporate clients,dc=example,dc=com") and (authmethod="ssl")
 and (dayofweek="Mon,Tues,Wed,Thu") and (timeofday >= "0800" and
 timeofday <= "1800") and (ip="255.255.123.234"); )

This example assumes that the ACI is added to the ou=Company333,ou=corporate clients,dc=example,dc=com entry.

Denying Access

If you have already allowed access to a large part of your suffix, you might want to deny access to a smaller part of the suffix beneath the existing ACI.

Note –

Denying access should be avoided where possible, because it can lead to surprising or complicated access control behavior. Restrict access by using a combination of scoping, attribute lists, target filters and so on.

Also, deleting a deny access ACI does not remove rights, but instead expands the rights set by other ACIs.

When the Directory Server evaluates access rights, it reads deny rights first, then allow rights.

In the examples that follow, Example.com wants all subscribers to be able to read billing information, such as connection time or account balance, under their own entries. Example.com also explicitly wants to deny write access to that information. The read access is depicted in ACI “Billing Info Read”. The deny access is depicted in ACI “Billing Info Deny”.

ACI “Billing Info Read”

In LDIF, to grant subscribers permission to read billing information in their own entry, you would write the following statement:


aci: (targetattr="connectionTime || accountBalance")
 (version 3.0; acl "Billing Info Read"; allow (search,read)
  userdn="ldap:///self";)

This example assumes that the relevant attributes have been created in the schema and that the ACI is added to the ou=subscribers,dc=example,dc=com entry.

ACI “Billing Info Deny”

In LDIF, to deny subscribers permission to modify billing information in their own entry, you would write the following statement:


aci: (targetattr="connectionTime || accountBalance")
 (version 3.0; acl "Billing Info Deny";
 deny (write) userdn="ldap:///self";)

This example assumes that the relevant attributes have been created in the schema and that the ACI is added to the ou=subscribers,dc=example,dc=com entry.

Proxy Authorization

The proxy authorization method is a special form of authentication. A user that binds to the directory by using his or her own identity is granted the rights of another user through proxy authorization.

To configure Directory Server to allow proxy requests you must do the following:

Note –

You can grant proxy rights to any users of the directory except the Directory Manager. In addition, you cannot use the Directory Manager’s DN as a proxy DN. You need to exercise great care when granting proxy rights because you grant the right to specify any DN (except the Directory Manager DN) as the proxy DN. If Directory Server receives more than one proxied authentication control in the same operation, an error is returned to the client application and the operation attempt is unsuccessful.

Example Proxy Authorization

Example.com wants the client application that binds as MoneyWizAcctSoftware to have the same access rights to the LDAP data as an Accounting Administrator.

The following parameters apply:

For the client application to gain access to the Accounting subtree, by using the same access permissions as the Accounting Administrator, the following must be true:

With this ACI in place, the MoneyWizAcctSoftware client application can bind to the directory and then send an LDAP command, such as ldapsearch or ldapmodify, that requires the access rights of the proxy DN.

In this example, if the client wanted to perform an ldapsearch command, the command would include the following controls:


$ ldapsearch -D "uid=MoneyWizAcctSoftware,ou=Applications,dc=example,dc=com" -w - \
 -y "uid=AcctAdministrator,ou=Administrators,dc=example,dc=com" ...

Note that the client binds as itself, but is granted the privileges of the proxy entry. The client does not need the password of the proxy entry.

Setting a Target Using Filtering

If you want to set access controls that allow access to a number of entries that are spread across the directory, you might want to use a filter to set the target.

In LDIF, to use a filter to allow all users in HR access to employee entries, you would write the following statement:


aci: (targetattr="*") (targetfilter=(objectClass=employee))
 (version 3.0; acl "HR access to employees";
 allow (all) groupdn= "ldap:///cn=HRgroup,ou=People,dc=example,dc=com";)

This example assumes that the ACI is added to the ou=People,dc=example,dc=com entry.

Note –

Because search filters do not directly name the object for which you are managing access, try not to allow or deny access to the wrong objects. Unintentionally allowing or denying access to the wrong objects becomes more of a risk as your directory becomes more complex. Additionally, filters can make it difficult for you to troubleshoot access control problems within your directory.

Defining Permissions for DNs That Contain a Comma

DNs that contain commas require special treatment within your LDIF ACI statements. In the target and bind rule portions of the ACI statement, commas must be escaped by a single backslash (\). The following example illustrates this syntax:


dn: o=Example.com Bolivia\, S.A. 
objectClass: top 
objectClass: organization 
aci: (target="ldap:///o=Example.com Bolivia\,S.A.") (targetattr="*") 
(version 3.0; acl "aci 2"; allow (all) groupdn = 
"ldap:///cn=Directory Administrators, o=Example.com Bolivia\, S.A.";)

Viewing Effective Rights

When maintaining the access policy on the entries of a directory, you need to know the effects on security of the ACIs that you define. Directory Server enables you to evaluate existing ACIs by viewing the effective rights that the ACIs grant for a given user on a given entry.

Directory Server responds to the “Get Effective Rights”, control which can be included in a search operation. The response to this control is to return the effective rights information about the entries and attributes in the search results. This extra information includes read and write permissions for each entry and for each attribute in each entry. The permissions can be requested for the bind DN that is used for the search or for an arbitrary DN. This choice allows administrators to test the permissions of directory users.

Effective rights functionality relies on an LDAP control. You must ensure that the proxy identity used to bind to the remote server is also allowed to access the effective rights attributes.

Restricting Access to the Get Effective Rights Control

The operation of viewing effective rights is a directory operation that needs to be protected and appropriately restricted.

To restrict access to effective rights information, modify the default ACI for getEffectiveRights attribute. Then create a new ACI for the getEffectiveRightsInfo attribute .

For example, the following ACI allows only members of the Directory Administrators Group to get effective rights:


aci: (targetattr != "aci")(version 3.0; acl
 "getEffectiveRights"; allow(all) groupdn =
 "ldap:///cn=Directory Administrators,ou=Groups,dc=example,dc=com";)

To obtain effective rights information, you need to have access control rights to use the Effective Rights control and read access to the aclRights attribute. This double layer of access control provides basic security that can be more finely tuned if necessary. By analogy with proxy, if you have read access to the aclRights attribute in an entry, you can request information about anyone’s rights to that entry and its attributes. This implies that the user who manages the resource can determine who has rights to that resource, even if that user does not actually manage those with the rights.

If a user requesting rights information does not have the rights to use the Effective Rights control, the operation fails and an error message is returned. However, if the user requesting rights information does have the rights to use the control but lacks the rights to read the aclRights attribute, the aclRights attribute will not appear in the returned entry. This behavior reflects Directory Server’s general search behavior.

Using the Get Effective Rights Control

Specify the “Get Effective Rights” control by using the ldapsearch command with the -J "1.3.6.1.4.1.42.2.27.9.5.2" option. By default, the control returns the effective rights of the bind DN entry on the entries and attributes in the search results.

Use the following options to change the default behavior:

Note –

The aclRights and aclRightsInfo attributes behave like virtual operational attributes. These attributes are not stored in the directory and are not returned unless explicitly requested. They are generated by Directory Server in response to the “Get Effective Rights” control.

Thus, these attributes cannot be used in filters or search operations of any kind.

The effective rights feature inherits other parameters that affect access control. These parameters include time of day, authentication method, machine address, and name.

The following example shows how the user Carla Fuente can view her rights in the directory. In the results, 1 means that permission is granted, and 0 means that permission is denied.


$ ldapsearch -J "1.3.6.1.4.1.42.2.27.9.5.2 -h host1.Example.com -p 389 \
 -D "uid=cfuente,ou=People,dc=example,dc=com" -w - -b "dc=example,dc=com" \
 "(objectclass=*)" aclRights
Enter bind password:
dn: dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0
dn: ou=Groups, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0
dn: ou=People, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0
dn: cn=Accounting Managers,ou=groups,dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0
dn: cn=HR Managers,ou=groups,dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0
dn: uid=bjensen,ou=People, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0
dn: uid=cfuente, ou=People, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:1,proxy:0

This result shows Carla Fuente the entries in the directory where she has at least read permission and shows that she can modify her own entry. The Effective Rights control does not bypass normal access permissions, so a user does not see the entries for which they do not have read permission. In the following example, the Directory Manager can see the entries to which Carla Fuente does not have read permission:


$ ldapsearch -h host1.Example.com -p 389 -D cn=admin,cn=Administrators,cn=config -w - \
 -c "dn: uid=cfuente,ou=People,dc=example,dc=com" -b "dc=example,dc=com" \
 "(objectclass=*)" aclRights
Enter bind password:
dn: dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0
dn: ou=Groups, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0
dn: cn=Directory Administrators, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:0,write:0,proxy:0
dn: ou=Special Users,dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:0,write:0,proxy:0
dn: ou=People, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0
dn: cn=Accounting Managers,ou=groups,dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0
dn: cn=HR Managers,ou=groups,dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0
dn: uid=bjensen,ou=People, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0
dn: uid=cfuente, ou=People, dc=example,dc=com
aclRights;entryLevel: add:0,delete:0,read:1,write:1,proxy:0

In the preceding output, the Directory Manager can see that Carla Fuente cannot even view the Special Users or the Directory Administrators branches of the directory tree. In the following example, the Directory Manager can see that Carla Fuente cannot modify the mail and manager attributes in her own entry:


$ ldapsearch -h host1.Example.com -p 389 -D cn=admin,cn=Administrators,cn=config -w - \
 -c "dn: uid=cfuente,ou=People,dc=example,dc=com" -b "dc=example,dc=com" \
 "(uid=cfuente)" aclRights "*"
Enter bind password:
version: 1
dn: uid=cfuente, ou=People, dc=example,dc=com
aclRights;attributeLevel;mail: search:1,read:1,compare:1,
 write:0,selfwrite_add:0,selfwrite_delete:0,proxy:0
mail: cfuente@Example.com
aclRights;attributeLevel;uid: search:1,read:1,compare:1,
 write:1,selfwrite_add:1,selfwrite_delete:1,proxy:0
uid: cfuente
aclRights;attributeLevel;givenName: search:1,read:1,compare:1,
 write:1,selfwrite_add:1,selfwrite_delete:1,proxy:0
givenName: Carla
aclRights;attributeLevel;sn: search:1,read:1,compare:1,
 write:1,selfwrite_add:1,selfwrite_delete:1,proxy:0
sn: Fuente
aclRights;attributeLevel;cn: search:1,read:1,compare:1,
 write:1,selfwrite_add:1,selfwrite_delete:1,proxy:0
cn: Carla Fuente
aclRights;attributeLevel;userPassword: search:0,read:0,
 compare:0,write:1,selfwrite_add:1,selfwrite_delete:1,proxy:0
userPassword: {SSHA}wnbWHIq2HPiY/5ECwe6MWBGx2KMiZ8JmjF80Ow==
aclRights;attributeLevel;manager: search:1,read:1,compare:1,
 write:0,selfwrite_add:0,selfwrite_delete:0,proxy:0
manager: uid=bjensen,ou=People,dc=example,dc=com
aclRights;attributeLevel;telephoneNumber: search:1,read:1,compare:1,
 write:1,selfwrite_add:1,selfwrite_delete:1,proxy:0
telephoneNumber: (234) 555-7898
aclRights;attributeLevel;objectClass: search:1,read:1,compare:1,
 write:1,selfwrite_add:1,selfwrite_delete:1,proxy:0
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetorgperson
aclRights;entryLevel: add:0,delete:0,read:1,write:0,proxy:0

Advanced Access Control: Using Macro ACIs

Organizations that use repeating directory tree structures can optimize the number of ACIs used in the directory by using macros. When you reduce the number of ACIs in your directory tree, it is easier to manage your access control policy. In addition, the efficiency of your ACI memory usage is improved.

Macros are placeholders that are used to represent a DN or a portion of a DN in an ACI. You can use a macro to represent a DN in the target portion of the ACI, in the bind rule portion, or in both. In practice, when Directory Server gets an incoming LDAP operation, the ACI macros are matched against the resource targeted by the LDAP operation. The matching occurs in order to determine a matching substring, if any matching substring exists. If a match exists, the bind rule-side macro is expanded using the matched substring, and access to the resource is determined by evaluating that expanded bind rule.

This section contains an example of a macro ACI and information about macro ACI syntax.

Macro ACI Example

The benefits of macro ACIs and how they work are best explained by using an example. Figure 6–1 shows a directory tree in which using macro ACIs is an effective way of reducing the overall number of ACIs.

In this illustration, note the repeating pattern of subdomains with the same tree structure (ou=groups,ou=people). This pattern is also repeated across the tree because the Example.com directory tree stores the two suffixes dc=hostedCompany2,dc=example,dc=com, and dc=hostedCompany3,dc=example,dc=com, which are not shown in the figure.

The ACIs in the directory tree also have a repeating pattern. For example, the following ACI is located on the dc=hostedCompany1,dc=example,dc=com node:


aci: (targetattr="*")
 (targetfilter=(objectClass=nsManagedDomain))(version 3.0;
 acl "Domain access"; allow (read,search) groupdn=
 "ldap:///cn=DomainAdmins,ou=Groups,dc=hostedCompany1,
 dc=example,dc=com";)

This ACI grants the domainAdmins group read and search rights to any entry in the dc=hostedCompany1,dc=example,dc=com tree.

Figure 6–1 Example Directory Tree for Macro ACIs

Topography of an example directory tree, showing dc=hostedcompany1,dc=example,dc=com, and various subdomains.

The following ACI is located on the dc=hostedCompany1,dc=example,dc=com node:


aci: (targetattr="*")
 (targetfilter=(objectClass=nsManagedDomain))
 (version 3.0; acl "Domain access"; allow (read,search)
 groupdn="ldap:///cn=DomainAdmins,ou=Groups,dc=hostedCompany1,dc=example,dc=com";)

The following ACI is located on the dc=subdomain1,dc=hostedCompany1, dc=example,dc=com node:


aci: (targetattr="*")
 (targetfilter=(objectClass=nsManagedDomain))
 (version 3.0; acl "Domain access"; allow (read,search)
 groupdn="ldap:///cn=DomainAdmins,ou=Groups,dc=subdomain1,dc=hostedCompany1,
  dc=example,dc=com";)

The following ACI is located on the dc=hostedCompany2,dc=example,dc=com node:


aci: (targetattr="*")
 (targetfilter=(objectClass=nsManagedDomain))
 (version 3.0; acl "Domain access"; allow (read,search)
 groupdn="ldap:///cn=DomainAdmins,ou=Groups,dc=hostedCompany2, dc=example,dc=com";)

The following ACI is located on the dc=subdomain1,dc=hostedCompany2, dc=example,dc=com node:


aci: (targetattr="*")
 (targetfilter=(objectClass=nsManagedDomain))
 (version 3.0; acl "Domain access"; allow (read,search)
 groupdn="ldap:///cn=DomainAdmins,ou=Groups,dc=subdomain1,dc=hostedCompany2,
 dc=example,dc=com";)

In the preceding four ACIs, the only difference is the DN that is specified in the groupdn keyword. By using a macro for the DN, it is possible to replace these ACIs with a single ACI at the root of the tree, on the dc=example,dc=com node. This macro ACI reads as follows:


aci: (target="ldap:///ou=Groups,($dn),dc=example,dc=com")
 (targetattr="*")(targetfilter=(objectClass=nsManagedDomain))
 (version 3.0; acl "Domain access"; allow (read,search) 
 groupdn="ldap:///cn=DomainAdmins,ou=Groups,[$dn],dc=example,dc=com";)

Note that the target keyword which was not previously used needs to be introduced.

In the preceding example, the number of ACIs is reduced from four to one. However, the real benefit is a factor of how many repeating patterns you have down and across your directory tree.

Macro ACI Syntax

To simplify the discussion in this section, the ACI keywords such as userdn, roledn, groupdn, and userattr that are used to provide bind credentials are collectively called the subject of the ACI. The subject determines to whom the ACI applies.

The following table shows which macros can be used to replace specific ACI keywords.

Table 6–1 Macro ACI Keywords

Macro 

Description 

ACI Keywords 

($dn)

For matching in the target, and direct substitution in the subject. 

target, targetfilter, userdn, roledn, groupdn, userattr

[$dn]

For substituting multiple RDNs that work in subtrees of the subject. 

targetfilter, userdn, roledn, groupdn, userattr

($attr.attrName)

For substituting the value of the attributeName attribute from the target entry into the subject.

userdn, roledn, groupdn, userattr

The following restrictions apply to macro ACI keywords:

Matching for ($dn) in the Target

The ($dn) macro in the target of an ACI determines the substitution value by comparing it to the entry targeted by the LDAP request. For example, you have an LDAP request targeted at this entry:


cn=all,ou=groups,dc=subdomain1, dc=hostedCompany1,dc=example,dc=com

In addition, you have an ACI that defines the target as follows:


(target="ldap:///ou=Groups,($dn),dc=example,dc=com")

The ($dn) macro matches with “dc=subdomain1, dc=hostedCompany1”. This substring is then used for substitutions in the subject of the ACI.

Substituting ($dn) in the Subject

In the subject of the ACI, the ($dn) macro is replaced by the entire substring that matches in the target. For example:


groupdn="ldap:///cn=DomainAdmins,ou=Groups,($dn),dc=example,dc=com"

The subject becomes this:


groupdn="ldap:///cn=DomainAdmins,ou=Groups,
 dc=subdomain1,dc=hostedCompany1,dc=example,dc=com"

After the macro has been expanded, Directory Server evaluates the ACI following the normal process to determine whether access is granted.

Note –

Unlike a standard ACI, an ACI that uses macro substitution does not necessarily grant access to the child of the targeted entry. This is because when the child DN is the target, the substitution might not create a valid DN in the subject string.

Substituting [$dn] in the Subject

The substitution mechanism for [$dn] is slightly different than for ($dn). The DN of the targeted resource is examined several times, each time dropping the left-most RDN component, until a match is found.

For example, suppose that you have an LDAP request targeted at the cn=all,ou=groups, dc=subdomain1,dc=hostedCompany1,dc=example,dc=com subtree, and the following ACI:


aci: (targetattr="*")
 (target="ldap:///ou=Groups,($dn),dc=example,dc=com")
 (version 3.0; acl "Domain access"; allow (read,search)
 groupdn="ldap:///cn=DomainAdmins,ou=Groups,[$dn],
 dc=example,dc=com";)

    The server proceeds as follows to expand this ACI:

  1. The server verifies that the ($dn) in target matches dc=subdomain1,dc=hostedCompany1.

  2. The server replaces [$dn] in the subject with dc=subdomain1,dc=hostedCompany1.

    The resulting subject is groupdn="ldap:///cn=DomainAdmins,ou=Groups, dc=subdomain1,dc=hostedCompany1,dc=example,dc=com". If access is granted because the bind DN is a member of that group, the macro expansion stops, and the ACI is evaluated. If the bind DN is not a member, the process continues.

  3. The server replaces [$dn] in the subject with dc=hostedCompany1.

    The resulting subject is groupdn="ldap:///cn=DomainAdmins,ou=Groups, dc=hostedCompany1,dc=example,dc=com". Again, the bind DN is tested as a member of this group and if it is, the ACI is evaluated fully. If the bind DN is not a member, macro expansion stops with the last RDN of the matched value, and ACI evaluation is finished for this ACI.

The advantage of the [$dn] macro is that it provides a flexible way to grant domain-level administrators access to all the subdomains in the directory tree. Therefore, the [$dn] macro is useful for expressing a hierarchical relationship between domains.

For example, consider the following ACI:


aci: (target="ldap:///ou=*,($dn),dc=example,dc=com") (targetattr="*")
(targetfilter=(objectClass=nsManagedDomain)) 
(version 3.0; acl "Domain access"; allow (read,search) groupdn= 
"ldap:///cn=DomainAdmins,ou=Groups,[$dn],dc=example,dc=com";)

The ACI grants access to the members of cn=DomainAdmins,ou=Groups, dc=hostedCompany1,dc=example,dc=com to all of the subdomains under dc=hostedCompany1. Thus, an administrator who belongs to that group could access, for example, the subtree ou=people,dc=subdomain1.1,dc=subdomain1.

However, at the same time, members of cn=DomainAdmins,ou=Groups, dc=subdomain1.1 would be denied access to the ou=people,dc=subdomain1, dc=hostedCompany1 and ou=people,dc=hostedCompany1 nodes.

Macro Matching for ($attr.attrName)

The ($attr.attrname) macro is always used in the subject part of a DN. For example, you could define the following roledn:


roledn = "ldap:///cn=DomainAdmins,($attr.ou),dc=HostedCompany1,dc=example,dc=com"

Now, assume that the server receives an LDAP operation that is targeted at the following entry:


dn: cn=Babs Jensen,ou=People,dc=HostedCompany1,dc=example,dc=com
cn: Babs Jensen
sn: Jensen
ou: Sales
...

To evaluate the roledn part of the ACI, the server reads the value of the ou attribute stored in the targeted entry. The server then substitutes this value in the subject to expand the macro. In the example, the roledn is expanded as follows:


roledn = "ldap:///cn=DomainAdmins,ou=Sales,dc=HostedCompany1,dc=example,dc=com"

Directory Server then evaluates the ACI according to the normal ACI evaluation algorithm.

When the attribute that is named in the macro is multivalued, each value is used in turn to expand the macro. The first value that provides a successful match is used.

Logging Access Control Information

To obtain information about access control in the error logs, you must set the appropriate log level.

ProcedureTo Set Logging for ACIs

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Set the log level to take into account ACI processing.


    $ dsconf set-log-prop -h host -p port error level:err-acl

Client-Host Access Control Through TCP Wrapping

You can control the host or IP address from which connections are accepted or rejected at the TCP level using TCP wrappers. You can limit client-host access through TCP wrapping. This enables you to have non host-based protection for initial TCP connections to a Directory Server.

Although you can set TCP wrapping for Directory Server, TCP wrapping can result in significant performance degradation, especially during a Denial of Service attack. The best performance is achieved by using a host-based firewall that is maintained outside Directory Server, or IP port filtering.

ProcedureTo Enable TCP Wrapping

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Create a hosts.allow file or a hosts.denyfile, somewhere within the instance path.

    For example, create the file in instance-path/config. Ensure that the formatting of the files that you create comply with hosts_access(4).

  2. Set the path to the access file. 


    $ dsconf set-server-prop -h host -p port host-access-dir-path:path-to-file

    For example:


    $ dsconf set-server-prop -h host -p port host-access-dir-path:/local/ds1/config
"host-access-dir-path" property has been set to "/local/ds1/config".
The "/local/ds1/config" directory on host1 must contain valid hosts.allow
and/or hosts.deny files.
Directory Server must be restarted for changes to take effect.

ProcedureTo Disable TCP Wrapping

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Set the host access path to "". 


    $ dsconf set-server-prop -h host -p port host-access-dir-path:""

Chapter 7 Directory Server Password Policy

When a user connects to Directory Server, the user is authenticated. The directory can grant access rights and resource limits to the user depending on the identity established during authentication. An account in this chapter refers loosely to a user entry. The account also reflects the permissions for the user to perform operations on the directory. In this discussion of password policy, every account is associated with a user entry, and a password.

This chapter also addresses account activation, an aspect of password policy. The Directory Administrator can directly lock and unlock accounts, independently of password policy.

This chapter does not cover authentication methods. Some authentication methods, such as SASL GSSAPI and client SSL certificate-based authentication, do not involve the use of passwords. The information about password policy in this chapter does not apply to such authentication methods. See Chapter 5, Directory Server Security for instructions on configuring authentication mechanisms.

This chapter also does not cover the compatibility of password policies between Directory Server 6.2 and previous Directory Server versions. When you create a Directory Server 6.2 instance, the password policy implementation defaults to a Directory Server 5 compatible mode to facilitate upgrading from earlier versions. To take full advantage of the password policy features described in this chapter, you will need to change the password policy compatibility mode. For more information about setting the password compatibility mode, see Password Policy Compatibility in Sun Java System Directory Server Enterprise Edition 6.2 Migration Guide.

This chapter covers the following topics:

Password Policies and Worksheet

This section explains password policy settings and provides a worksheet to help you define password policies that fit your requirements.

Note –

To use the default password policy, see Managing the Default Password Policy.

Password Policy Settings

When you specify a password policy in Directory Server, you either modify or create an entry that includes the object class pwdPolicy(5dsoc).

When defining a password policy for a particular type of user, you need to consider the following:

Subsequent sections in this chapter explain how you handle these areas of password policy. Use the Worksheet for Defining Password Policy to clarify each password policy that you plan to implement.

Policy for Account Lockout

This section explains the policy attributes that govern account lockout.

A Directory Server account refers loosely to a user's entry and to the permissions that user has to perform operations on the directory. Each account is associated with a bind DN and a user password. When an intruder appears to be trying to crack a password, you want Directory Server to lock the account. The lock prevents the intruder from using the account to bind. The lock also prevents the intruder from being able to continue the attack.

As administrator, you can also manually render inactive an account or the accounts of all users who share a role. See Manually Locking Accounts for instructions. Yet, a key part of your password policy is specifying under what circumstances Directory Server locks an account without your intervention.

First of all, you must specify that Directory Server can use pwdLockout(5dsat) to automatically lock accounts when too many failed binds occur. Directory Server keeps track of consecutive failed attempts to bind to an account. You use pwdMaxFailure(5dsat) to specify how many consecutive failures are allowed before Directory Server locks the account.

Directory Server locks accounts strictly according to password policy. The operation is purely mechanical. Accounts can lock not because an intruder is mounting an attack against the account, but because the user typed the password incorrectly. Thus, you can use pwdFailureCountInterval(5dsat) to specify how long Directory Server should wait between tries before cleaning out the records of failed attempts. You use pwdLockoutDuration(5dsat) to specify how long lockout should last before Directory Server automatically unlocks the account. The administrator does not have to intervene to unlock accounts of users who make legitimate mistakes with no malicious intent.

If your user data is replicated across a replication topology, lockout attributes are replicated along with other entry data. The pwdIsLockoutPrioritized(5dsat) attribute's default setting is TRUE, so updates for lockout attributes are replicated with a higher priority. A user is thus limited to making pwdMaxFailure consecutive failed attempts to bind to any single replica before being locked out, and probably fewer attempts at other replicas before being locked out. For details about how to make sure that a user gets exactly pwdMaxFailure attempts before being locked out across an entire replicated topology, see Preventing Authentication by Using Global Account Lockout in Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide.

Policy for Password Changes

This section explains the policy attributes that govern changes to passwords.

In many deployments, Directory Server is the repository for identity data. Users should be able to change their own passwords, as specified by pwdAllowUserChange(5dsat), so you do not have to change the passwords.

After you allow users to change their own passwords, you might also want to control the circumstances under which users can change their passwords. You can use pwdSafeModify(5dsat) to specify that users who change a password must provide the correct existing password before they are allowed to replace the password. See Modifying Passwords From the Command Line When pwdSafeModify Is TRUE for an example of how to modify the password. You can prevent users from reusing passwords by using pwdInHistory(5dsat) to specify how many passwords Directory Server remembers. You can also prevent users from changing their passwords too often by setting pwdMinAge(5dsat).

In many cases either you as administrator or some application that you manage creates user entries in the directory. You can assign a user password value to change when the user first binds to the new account. You might also have to reset a user password, after which the user should change the password when next using the account. Directory Server has a specific attribute, pwdMustChange(5dsat), that you can use to indicate whether a user must change passwords after the password value is reset by another user.

You can also specify that the Directory Administrator is not subject to policy when changing passwords by setting passwordRootdnMayBypassModsChecks(5dsat).

Policy for Password Content

This section explains the policy attributes that govern password content.

Although password values are not generally returned in directory searches, an attacker could potentially gain access to the directory database. Therefore, password values are generally stored in one of the supported hashed formats that you specify using passwordStorageScheme(5dsat).

You can also enforce a check that passwords meet your definition of minimum password quality, by setting pwdCheckQuality(5dsat). The server then checks that the password does not match any of the values of the cn, givenName, mail, ou, sn, or uid attributes. The comparison of the password with any of these attributes is case-insensitive.

Additional checks are available with pwdCheckQuality(5dsat) set. You can enforce that passwords have at least a specified number of characters by setting pwdMinLength(5dsat). Furthermore, when the Strong Password Check plug-in is enabled, Directory Server checks that the password does not contain strings from the dictionary file that the plug-in uses. The server also checks that the password contains an appropriate mix of different types of characters.

You can enable strong password checking with the dsconf set-server-prop command. Use the pwd-strong-check-enabled property to turn on the plug-in, and restart the server for the change to take effect. Use the pwd-strong-check-require-charset property to specify what character sets to require in passwords. The pwd-strong-check-require-charset property takes a mask of the following values:

lower

The new password must include a lower case character.

upper

The new password must include an upper case character.

digit

The new password must include a digit.

special

The new password must include a special character.

any-two

The new password must include at least one character from each of at least two of the above mentioned character sets.

any-three

The new password must include at least one character from each of at least three of the above mentioned character sets.

The default setting for the pwd-strong-check-require-charset property is lower && upper && digit && special.

Policy for Password Expiration

This section explains the policy attributes that govern password expiration.

To ensure that users change their passwords regularly, you can configure Directory Server to have passwords expire after the passwords reach a certain age, by setting pwdMaxAge(5dsat).

Users must be informed that their passwords are going to expire. You can configure Directory Server to return a warning that the password used to bind is going to expire. Use pwdExpireWarning(5dsat) to define how long before expiration that the warning should be returned when a client binds. Notice that the client application gets the warning. The user does not get the warning directly. Client applications must notify the end user when the applications receive the warning that the password is about to expire.

You can allow users one or more tries to bind with an expired password, by setting pwdGraceAuthNLimit(5dsat). Users who failed to change their passwords in time can thus still bind to change their passwords. Be aware that, when a user binds with a grace login, the user can perform any operation. A grace login works as if the password had not expired.

Directory Server updates the operational attribute pwdChangedTime(5dsat) every time that the password on the entry is modified. As a result, if you wait to enable password expiration, user passwords that have already aged expire immediately when you enable password expiration. Use warnings and grace logins if this behavior is not what you intend.

Policy for Tracking Last Authentication Time

This section covers the use of the password policy attribute pwdKeepLastAuthTime(5dsat).

When set, pwdKeepLastAuthTime causes Directory Server to track the time of the last successful bind every time that a user authenticates. The time is recorded on the pwdLastAuthTime(5dsat) operational attribute of the user's entry.

Because this behavior adds an update for each successful bind operation, the pwdKeepLastAuthTime feature is not activated by default. You must explicitly turn the feature on to use it in your deployment.

Worksheet for Defining Password Policy

This worksheet is designed to help you define a password policy to implement either through the command-line interface or using Directory Service Control Center (DSCC). Use one worksheet for each password policy.

After you record the DN of the password policy entry, record your decisions about settings for attributes in each policy area. Also record your rationale for those settings.

Password Policy Worksheet 

Password Policy Entry Distinguished Name 

dn: cn=

Policy Area 

Attribute 

Write Your Settings Here 

Write Your Rationale for Settings Here 

Account Lockout 

pwdFailureCountInterval(5dsat)

   

pwdIsLockoutPrioritized(5dsat)

           

           

pwdLockout(5dsat)

           

           

pwdLockoutDuration(5dsat)

           

           

pwdMaxFailure(5dsat)

           

           

Password Changes 

passwordRootdnMayBypassModsChecks(5dsat)

           

           

pwdAllowUserChange(5dsat)

           

           

pwdInHistory(5dsat)

           

           

pwdMinAge(5dsat)

           

           

pwdMustChange(5dsat)

           

           

pwdSafeModify(5dsat)

           

           

Password Content 

passwordStorageScheme(5dsat)

           

           

pwdCheckQuality(5dsat)

           

           

pwdMinLength(5dsat)

   

Password Expiration 

pwdExpireWarning(5dsat)

           

           

pwdGraceAuthNLimit(5dsat)

           

           

pwdMaxAge(5dsat)

           

           

Tracking Last Authentication Time 

pwdKeepLastAuthTime(5dsat)

           

           

Note –

When the pwdCheckQuality attribute is set to 2, the server can perform additional checks. When the Password Check plug-in is also enabled, settings for the plug-in affect what checks are performed the on values of new passwords.

Managing the Default Password Policy

The default password policy applies to all users in the directory instance who do not have a specialized policy defined. However, the default password policy does not apply to the Directory Manager. See Which Password Policy Applies for details on policy scope.

The default password policy is the one policy that you can configure using the dsconf command. You can also view default password policy by reading cn=Password Policy,cn=config.

This section shows the policy attributes for each policy area and the related dsconf server properties. It also explains how to view and change default password policy settings.

Correlation Between Password Policy Attributes and dsconf Server Properties

The following table shows the password policy attributes and related dsconf server properties for each password policy area.

Policy Area 

Policy Attribute 

dsconf Server Property

Account Lockout 

pwdFailureCountInterval

pwd-failure-count-interval

pwdLockout

pwd-lockout-enabled

pwdLockoutDuration

pwd-lockout-duration

pwdMaxFailure

pwd-max-failure-count

Password Changes 

passwordRootdnMayBypassModsChecks

pwd-root-dn-bypass-enabled

pwdAllowUserChange

pwd-user-change-enabled

pwdInHistory

pwd-max-history-count

pwdMinAge

pwd-min-age

pwdMustChange

pwd-must-change-enabled

pwdSafeModify

pwd-safe-modify-enabled

Password Content 

pwdCheckQuality

pwd-check-enabled, pwd-accept-hashed-password-enabled, pwd-strong-check-dictionary-path, pwd-strong-check-enabled, pwd-strong-check-require-charset

pwdMinLength

pwd-min-length

passwordStorageScheme

pwd-storage-scheme

Password Expiration 

pwdExpireWarning

pwd-expire-warning-delay

pwdGraceAuthNLimit

pwd-grace-login-limit

pwdMaxAge

pwd-max-age

Tracking Last Authentication Time 

pwdKeepLastAuthTime

pwd-keep-last-auth-time-enabled

Note –

The properties that correlate to pwdCheckQuality configure the Password Check plug-in. Therefore, the five properties apply to the entire server instance. The five properties thus also apply to other password policies where pwdCheckQuality: 2.

ProcedureTo View Default Password Policy Settings

You can view default password policy settings with the dsconf command.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Read the default password policy configuration.


    $ dsconf get-server-prop -h host -p port | grep ^pwd-
pwd-accept-hashed-pwd-enabled      :  N/A
pwd-check-enabled                  :  off
pwd-compat-mode                    :  DS5-compatible-mode
pwd-expire-no-warning-enabled      :  on
pwd-expire-warning-delay           :  1d
pwd-failure-count-interval         :  10m
pwd-grace-login-limit              :  disabled
pwd-keep-last-auth-time-enabled    :  off
pwd-lockout-duration               :  1h
pwd-lockout-enabled                :  off
pwd-lockout-repl-priority-enabled  :  on
pwd-max-age                        :  disabled
pwd-max-failure-count              :  3
pwd-max-history-count              :  disabled
pwd-min-age                        :  disabled
pwd-min-length                     :  6
pwd-mod-gen-length                 :  6
pwd-must-change-enabled            :  off
pwd-root-dn-bypass-enabled         :  off
pwd-safe-modify-enabled            :  off
pwd-storage-scheme                 :  SSHA
pwd-strong-check-dictionary-path   :  /local/ds6/plugins/words-english-big.txt
pwd-strong-check-enabled           :  off
pwd-strong-check-require-charset   :  lower
pwd-strong-check-require-charset   :  upper
pwd-strong-check-require-charset   :  digit
pwd-strong-check-require-charset   :  special
pwd-supported-storage-scheme       :  CRYPT
pwd-supported-storage-scheme       :  SHA
pwd-supported-storage-scheme       :  SSHA
pwd-supported-storage-scheme       :  NS-MTA-MD5
pwd-supported-storage-scheme       :  CLEAR
pwd-user-change-enabled            :  on

ProcedureTo Change Default Password Policy Settings

You can change the default password policy by setting server properties with the dsconf command.

Note –

Before completing this procedure, read and complete the Worksheet for Defining Password Policy.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Translate the settings from your worksheet into dsconf command property settings.

  2. Use the dsconf set-server-prop command to change default password policy properties appropriately.

    For example, the following command allows the Directory Manager to violate the default policy when modifying passwords:


    $ dsconf set-server-prop -h host -p port pwd-root-dn-bypass-enabled:on

Managing Specialized Password Policies

Specialized password policies are defined in a pwdPolicy(5dsoc) entry. A policy can be defined anywhere in the directory tree, typically in a subtree that is replicated with the accounts that the policy governs. The policy has a DN of the form cn=policy name,subtree.

After defining the password policy, you assign the password policy by setting the pwdPolicySubentry(5dsat) attribute in the desired user entry.

This section covers these topics:

Which Password Policy Applies

Directory Server allows you to configure multiple password policies. This section explains default password policies and specialized password policies. This section also explains which policy is enforced when multiple password policies could apply to a given account.

When you first create a Directory Server instance, that instance has a default password policy. That default password policy is expressed in the configuration entry cn=PasswordPolicy,cn=config. The default password policy applies to all accounts in the directory except for the Directory Manager.

As in all Directory Server password policies, cn=PasswordPolicy,cn=config has object class pwdPolicy(5dsoc) and object class sunPwdPolicy(5dsoc).

Note –

When you create a Directory Server instance, password policy attributes remain in Directory Server 5 compatible mode to facilitate upgrading from earlier versions. In Directory Server 5 compatible mode, Directory Server also handles password policy entries that have object class passwordPolicy(5dsoc).

After your upgrade is complete, you use the new password policy in fully featured mode, as described in Sun Java System Directory Server Enterprise Edition 6.2 Migration Guide. The administrative move is transparent to directory applications.

This chapter covers password policy configuration using the new password policy features.

You can change the default password policy to override the default settings. You can use the dsconf(1M) command to set the server properties for default password policy. Such server property names typically start with the pwd- prefix. When changing settings for such properties, you override the default password policy for the instance. Replication does not, however, copy the changes to replicas. The changes that you make to the default password policy are part of the configuration for the instance, not part of the directory data.

In addition to configuring the default password policy, you can also configure specialized password policies. A specialized password policy is defined by an entry in the directory tree. The specialized password policy entry has the same object class, pwdPolicy(5dsoc), as the default password policy, and therefore takes the same policy attributes. Because specialized password policies are regular directory entries, policy entries are replicated in the same manner as regular directory entries.

A user entry references a specialized password policy through the value of the operational attribute pwdPolicySubentry(5dsat). When referenced by a user entry, a specialized password policy overrides the default password policy for the instance. In many deployments, you assign users roles. You can configure roles to work with class of service (CoS) to determine the password policies that apply to user accounts, by setting the pwdPolicySubentry value. To override the password policy set by a role, change the pwdPolicySubentry value on that user's entry directly.

To summarize this section, initially the default password policy applies. You can change the default password policy to override the defaults. You can then create specialized password policy entries to override the default password policy. When you assign password policy with roles and CoS, you can override the CoS-assigned policy by specifying a password policy for an individual entry.

ProcedureTo Create a Password Policy

You create and modify specialized password policies in the same way that you create and modify any other directory entry. The following procedure demonstrates use of a text editor to write the password policy entry in LDIF. Then you use the ldapmodify command with the -a option to add the password policy entry to the directory.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Before You Begin

Example data as shown here is from Example.ldif unless stated otherwise.

  1. Complete a password policy worksheet for the policy you want to create.

    See Worksheet for Defining Password Policy for a sample.

  2. Write a password policy entry, in LDIF, that is based on the worksheet.

    For example, the following policy entry specifies a password policy for temporary employees at Example.com, whose subtree root is dc=example,dc=com:

    dn: cn=TempPolicy,dc=example,dc=com
objectClass: top
objectClass: pwdPolicy
objectClass: sunPwdPolicy
objectClass: LDAPsubentry
cn: TempPolicy
pwdAttribute: userPassword
pwdCheckQuality: 2
pwdLockout: TRUE
pwdLockoutDuration: 300
pwdMaxFailure: 3
pwdMustChange: TRUE

    In addition to the default password policy settings, the policy as shown here specifies additional behaviors. Password quality checks are enforced. Accounts are locked for five minutes, 300 seconds, after three consecutive bind failures. Passwords must be changed after the passwords are reset. After the policy is assigned to user accounts, the settings explicitly specified here override the default password policy.

  3. Add the password policy entry to the directory.

    For example, the following command adds the password policy for temporary employees at Example.com under dc=example,dc=com. The password policy has been saved in a file named pwp.ldif.


    $ ldapmodify -a -D uid=kvaughan,ou=people,dc=example,dc=com -w - -f pwp.ldif
Enter bind password: 
adding new entry cn=TempPolicy,dc=example,dc=com

$ ldapsearch -D uid=kvaughan,ou=people,dc=example,dc=com -w --b dc=example,dc=com \
"(&(objectclass=ldapsubentry)(cn=temppolicy))"
Enter bind password:
version: 1
dn: cn=TempPolicy,dc=example,dc=com
objectClass: top
objectClass: pwdPolicy
objectClass: LDAPsubentry
cn: TempPolicy
pwdCheckQuality: 2
pwdLockout: TRUE
pwdLockoutDuration: 300
pwdMaxFailure: 3
pwdMustChange: TRUE
$

    As shown in Example.ldif, kvaughan is an Human Resources manager who has access to modify dc=example,dc=com entries. Vaughan's bind password, as shown in Example.ldif, is bribery.

See Also

To define which user accounts are governed by the policies you define, see To Assign a Password Policy to an Individual Account or To Assign a Password Policy Using Roles and CoS.

ProcedureTo Assign a Password Policy to an Individual Account

This procedure assigns an existing password policy to a single user account.

Note –

To complete this procedure, you must have a specialized password policy to assign. See To Create a Password Policy.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Example data shown here is from Example.ldif unless stated otherwise.

  1. Add the password policy DN to the values of the pwdPolicySubentry attribute of the user entry.

    For example, the following commands assign the password policy that is defined in To Create a Password Policy to David Miller's entry, whose DN is uid=dmiller,ou=people,dc=example,dc=com:


    $ cat pwp.ldif 
dn: uid=dmiller,ou=people,dc=example,dc=com
changetype: modify
add: pwdPolicySubentry
pwdPolicySubentry: cn=TempPolicy,dc=example,dc=com

$ ldapmodify -D uid=kvaughan,ou=people,dc=example,dc=com -w - -f pwp.ldif 
Enter bind password: 
modifying entry uid=dmiller,ou=people,dc=example,dc=com

$ ldapsearch -D uid=kvaughan,ou=people,dc=example,dc=com -w - -b dc=example,dc=com \
"(uid=dmiller)" pwdPolicySubentry
Enter bind password:
version: 1
dn: uid=dmiller, ou=People, dc=example,dc=com
pwdPolicySubentry: cn=TempPolicy,dc=example,dc=com
$

    As shown in Example.ldif, kvaughan is a Human Resources manager who has access to modify dc=example,dc=com entries. Vaughan's bind password, as shown in Example.ldif, is bribery.

ProcedureTo Assign a Password Policy Using Roles and CoS

This procedure assigns an existing specialized password policy to a set of users by applying roles and class of service (CoS). See Chapter 9, Directory Server Groups, Roles, and CoS for more information about roles and CoS.

Note –

To complete this procedure, you must have a specialized password policy to assign. See To Create a Password Policy.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Example data shown here is from Example.ldif unless stated otherwise.

  1. Create a role for the entries to be governed by the password policy.

    For example, the following commands create a filtered role for temporary employees at Example.com:


    $ cat tmp.ldif
dn: cn=TempFilter,ou=people,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsComplexRoleDefinition
objectclass: nsFilteredRoleDefinition
cn: TempFilter
nsRoleFilter: (&(objectclass=person)(status=contractor))
description: filtered role for temporary employees

$ ldapmodify -a -D uid=kvaughan,ou=people,dc=example,dc=com -w - -f tmp.ldif
Enter bind password: 
modifying entry cn=TempFilter,ou=people,dc=example,dc=com

$

    As shown in Example.ldif, kvaughan is a Human Resources manager who has access to modify dc=example,dc=com entries. Vaughan's bind password, as shown in Example.ldif, is bribery.

  2. Create a class of service to generate the DN of the password policy entry.

    The DN is the value of the pwdPolicySubentry attribute of users who have the role that you created.

    For example, the following commands create a filtered role for temporary employees at Example.com. The commands assign cn=TempPolicy,dc=example,dc=com to users who have the role.


    $ cat cos.ldif
dn: cn=PolTempl,dc=example,dc=com
objectclass: top
objectclass: nsContainer

dn: cn="cn=TempFilter,ou=people,dc=example,dc=com",
 cn=PolTempl,dc=example,dc=com
objectclass: top
objectclass: extensibleObject
objectclass: LDAPsubentry
objectclass: costemplate
cosPriority: 1
pwdPolicySubentry: cn=TempPolicy,dc=example,dc=com

dn: cn=PolCoS,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosClassicDefinition
cosTemplateDN: cn=PolTempl,dc=example,dc=com
cosSpecifier: nsRole
cosAttribute: pwdPolicySubentry operational

$ ldapmodify -a -D uid=kvaughan,ou=people,dc=example,dc=com -w - -f cos.ldif
Enter bind password: 
modifying entry cn=TempFilter,ou=people,dc=example,dc=com

$

    Users whose status is contractor now become subject to the password policy cn=TempPolicy,dc=example,dc=com.

ProcedureTo Set Up a First Login Password Policy

In many deployments, the password policy to apply for new accounts differs from the password policy to apply for established accounts. This section demonstrates a first login password policy. The policy gives users three days to use a newly created account, and set their new passwords before that account is locked. The policy is designed to work in the same way for users whose passwords have been reset.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Create a specialized password policy for newly created accounts.

    For example, add a password policy entry that sets expiration time to three days, which is 259,200 seconds. This password policy also has pwdMustChange(5dsat) set to TRUE, meaning the users much change their passwords when they first bind.


    $ cat firstLogin.ldif
dn: cn=First Login,dc=example,dc=com
objectClass: top
objectClass: LDAPsubentry
objectClass: pwdPolicy
objectClass: sunPwdPolicy
cn: First Login
passwordStorageScheme: SSHA
pwdAttribute: userPassword
pwdInHistory: 0
pwdExpireWarning: 86400
pwdLockout: TRUE
pwdMinLength: 6
pwdMaxFailure: 3
pwdMaxAge: 259200
pwdFailureCountInterval: 600
pwdAllowUserChange: TRUE
pwdLockoutDuration: 3600
pwdMinAge: 0
pwdCheckQuality: 2
pwdMustChange: TRUE

$ ldapmodify -a -D cn=admin,cn=Administrators,cn=config -w - -f firstLogin.ldif
Enter bind password: 
adding new entry cn=First Login,dc=example,dc=com

$

  2. Create a role that includes all newly created accounts.

    In creating this role, set up some way to distinguish newly created accounts from established accounts.

    1. Define new accounts as accounts that have a pwdReset(5dsat) attribute set to TRUE.

      When a user's password is changed by another user, such as a password administrator, pwdReset is set to TRUE.

    2. Create the role that identifies new accounts.

      For example, the following commands create a role for accounts whose passwords have been reset.


      $ cat newRole.ldif 
dn: cn=First Login Role,ou=people,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsComplexRoleDefinition
objectclass: nsFilteredRoleDefinition
cn: First Login Role
nsRoleFilter: (pwdReset=TRUE)
description: Role to assign password policy for new and reset accounts

$ ldapmodify -a -D uid=kvaughan,ou=people,dc=example,dc=com -w - -f newRole.ldif
Enter bind password: 
adding new entry cn=First Login Role,ou=people,dc=example,dc=com

$

  3. Assign the password policy for newly created accounts with class of service.


    $ cat newCoS.ldif 
dn: cn=First Login Template,dc=example,dc=com
objectClass: top
objectClass: nsContainer

dn: cn="cn=First Login Role,ou=people,dc=example,dc=com",
 cn=First Login Template,dc=example,dc=com
objectClass: top
objectClass: extensibleObject
objectClass: LDAPSubEntry
objectClass: CoSTemplate
cosPriority: 1
pwdPolicySubentry: cn=First Login,dc=example,dc=com

dn: cn=First Login CoS,dc=example,dc=com
objectClass: top
objectClass: LDAPSubEntry
objectClass: CoSSuperDefinition
objectClass: CoSClassicDefinition
cosTemplateDN: cn=First Login Template,dc=example,dc=com
cosSpecifier: nsRole
cosAttribute: pwdPolicySubentry operational

$ ldapmodify -a -D uid=kvaughan,ou=people,dc=example,dc=com -f newCoS.ldif
Enter bind password: 
adding new entry cn=First Login Template,dc=example,dc=com

adding new entry cn="cn=First Login Role,ou=people,dc=example,dc=com",
 cn=First Login Template,dc=example,dc=com

adding new entry cn=First Login CoS,dc=example,dc=com

$
Example 7–1 Checking Password Policy Assignment

Add a new user that fits the role that you have added. You add the user to verify that new users are subject to the new password policy, but existing users are not.


$ cat quentin.ldif
dn: uid=qcubbins,ou=People,dc=example,dc=com
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
uid: qcubbins
givenName: Quentin
sn: Cubbins
cn: Quentin Cubbins
mail: quentin.cubbins@example.com
userPassword: ch4ngeM3!
description: New account

$ ldapmodify -a -D uid=kvaughan,ou=people,dc=example,dc=com -w - -f quentin.ldif
Enter bind password: 
adding new entry uid=qcubbins,ou=People,dc=example,dc=com

$ ldapsearch -D uid=kvaughan,ou=people,dc=example,dc=com -w - \
-b dc=example,dc=com uid=qcubbins nsrole pwdPolicySubentry
Enter bind password:
version: 1
dn: uid=qcubbins,ou=People,dc=example,dc=com
nsrole: cn=first login role,ou=people,dc=example,dc=com
pwdPolicySubentry: cn=First Login,dc=example,dc=com
$ ldapsearch -b dc=example,dc=com uid=bjensen nsrole pwdPolicySubentry
version: 1
dn: uid=bjensen, ou=People, dc=example,dc=com
$

Notice that Barbara Jensen's existing account is governed by the default password policy. Quentin Cubbins's new account is governed, however, by the password policy that you defined.

Modifying Passwords From the Command Line When pwdSafeModify Is TRUE

When the password policy for a user has pwdSafeModify set to TRUE, the old password must be provided with the new password to change the password. The command dsconf set-server-prop pwd-safe-modify-enabled:on has the same effect for the default password policy.

You can use the ldappasswd(1) command to change the password. This command provides support for safe password modification. This command implements RFC 3062, LDAP Password Modify Extended Operation

You can use the ldapmodify(1) command to change the password. The LDIF that you pass to the ldapmodify command in that case should be as follows:

dn: DN of user whose password you are changing
changetype: modify
delete: userPassword
userPassword: old password
-
add: userPassword
userPassword: new password

You can also use the LDAP password modify extended operation. Setting up support for the extended operation is explained in To Reset a Password With the Password Modify Extended Operation.

Resetting Expired Passwords

When password policy enforces password expiration, some users will not change their passwords in time. This section shows how you can change passwords that have expired.

Note –

Directory Server updates the operational attribute pwdChangedTime(5dsat) every time that the password on the entry is modified. As a result, if you wait to enable password expiration, user passwords that have already aged expire immediately when you enable password expiration. Use warnings and grace logins if this behavior is not what you intend.

This section includes procedures for resetting a password with the password modify extended operation and for allowing grace authentications when passwords expire.

The mechanisms described in this section are intended for use by administrators, or by applications that handle the actual user interaction with the directory. You typically rely on an application to ensure that the end user is in fact using the mechanisms in the way you intended.

ProcedureTo Reset a Password With the Password Modify Extended Operation

User accounts are locked when passwords expire. When you reset the password, you unlock the account. The password can be reset by another user such as an administrator. After password reset, Directory Server unlocks the user account. Directory Server provides support for RFC 3062, LDAP Password Modify Extended Operation. The extended operation enables you to allow a directory administrator or a directory application to unlock accounts through password reset.

Be cautious when allowing use of the password modify extended operation, as shown in this procedure. Limit access to administrators and applications that you trust. Do not allow passwords to travel over the network in clear text.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Give users access to a password administrator or to a password administration application.

  2. Allow the password administrator access to use the password modify extended operation.

    The following commands set an ACI to allow members of a Password Managers role to use the password modify extended operation when connected over SSL:


    $ cat exop.ldif
dn: oid=1.3.6.1.4.1.4203.1.11.1,cn=features,cn=config
objectClass: top
objectClass: directoryServerFeature
oid: 1.3.6.1.4.1.4203.1.11.1
cn: Password Modify Extended Operation
aci: (targetattr != "aci")(version 3.0;
 acl "Password Modify Extended Operation
 "; allow( read, search, compare, proxy ) (roledn = "
 ldap:///cn=Password Managers,dc=example,dc=com" and authmethod = "SSL");)

$ ldapmodify -a -D cn=admin,cn=Administrators,cn=config -w - -f exop.ldif
Enter bind password: 
adding new entry oid=1.3.6.1.4.1.4203.1.11.1,cn=features,cn=config

$

    The entry under cn=features,cn=config allows you to manage access to operations that use the password modify extended operation.

  3. Have the password administrator reset the user password.

    This step unlocks the user account, and can be completed with the ldappasswd(1) command.

  4. (Optional) If the user must change the password, have the password administrator notify the user.

    Users must change their passwords after reset if the password policy that governs their entries includes pwdMustChange: TRUE.

ProcedureTo Allow Grace Authentications When Passwords Expire

This procedure describes how to give users grace authentications, allowing users to change passwords that have expired.

The grace authentications are intended to be managed by an application that handles password policy request and response controls. The procedure shows a simple example of how to use the control in an application.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Make sure that users have access to an application that uses password policy request and response controls.

    The application should ensure that users handle grace authentications properly.

  2. Allow the application to use the password policy controls.

    The following commands set an ACI to allow members of a Password Managers role to use the password policy controls:


    $ cat ctrl.ldif
dn: oid=1.3.6.1.4.1.42.2.27.8.5.1,cn=features,cn=config
objectClass: top
objectClass: directoryServerFeature
oid: 1.3.6.1.4.1.42.2.27.8.5.1
cn: Password Policy Controls
aci: (targetattr != "aci")(version 3.0; acl "Password Policy Controls
 "; allow( read, search, compare, proxy ) roledn = "
 ldap:///cn=Password Managers,dc=example,dc=com";)

$ ldapmodify -a -D cn=admin,cn=Administrators,cn=config -w - -f ctrl.ldif
Enter bind password: 
adding new entry oid=1.3.6.1.4.1.42.2.27.8.5.1,cn=features,cn=config

$

    The entry under cn=features,cn=config has the sole purpose of allowing you to manage access to operations that use the password policy request and response controls.

  3. Set pwdGraceAuthNLimit in the password policy to the number of authentications to allow after the password has expired.

  4. Make sure that the application guides the end user to change the expired password promptly before grace authentications are exhausted.

Setting Account Properties

The following sections describe how to set the look-through limit, size limit, time limit and idle timeout of an account.

ProcedureTo Set the Look-Through Limit for an Account

  1. Use the ldapmodify command to set the value of nsLookThroughLimit.

    The following command removes the look-through limit for Barbara Jensen:


    $ ldapmodify -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password: 
dn: uid=bjensen,ou=people,dc=example,dc=com
changetype: modify
add: nsLookThroughLimit
nsLookThroughLimit: -1
^D
modifying entry uid=bjensen,ou=people,dc=example,dc=com

^D
$

ProcedureTo Set the Size Limit for an Account

  1. Use the ldapmodify command to set the value of nsSizeLimit.

    The following command removes the size limit for Barbara Jensen:


    $ ldapmodify -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password: 
dn: uid=bjensen,ou=people,dc=example,dc=com
changetype: modify
add: nsSizeLimit
nsSizeLimit: -1
^D
modifying entry uid=bjensen,ou=people,dc=example,dc=com

^D
$

ProcedureTo Set the Time Limit for an Account

  1. Use the ldapmodify command to set the value of nsTimeLimit.

    The following command removes the time limit for Barbara Jensen:


    $ ldapmodify -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password: 
dn: uid=bjensen,ou=people,dc=example,dc=com
changetype: modify
add: nsTimeLimit
nsTimeLimit: -1
^D
modifying entry uid=bjensen,ou=people,dc=example,dc=com

^D
$

ProcedureTo Set the Idle Timeout for an Account

  1. Use the ldapmodify command to set the value of nsIdleTimeout.

    The following command sets the idle timeout for Barbara Jensen to five minutes (300 seconds):


    $ ldapmodify -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password: 
dn: uid=bjensen,ou=people,dc=example,dc=com
changetype: modify
add: nsIdleTimeout
nsIdleTimeout: 300
^D
modifying entry uid=bjensen,ou=people,dc=example,dc=com

^D
$

Manually Locking Accounts

Directory Server allows you to configure password policy to force the lockout of accounts after a specified number of failed bind attempts. See Policy for Account Lockout for details. This section covers manual account locking and activation tools that the Directory Manager can use.

The Directory Manager can manage account lockout without using the lockout duration timer. The locked account remains locked until the password is manually reset. The Directory Manager can also render certain accounts inactive for an indefinite period of time.

This section shows how to check account status, render accounts inactive, and reactivate accounts.

ProcedureTo Check Account Status

Check account status as shown here.

Note –

You must bind as the Directory Manager.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Use the ns-accountstatus command to check the status the account or role.

    The following command checks Barbara Jensen's account status:


    $ ns-accountstatus -D "cn=Directory Manager" -j pwd.txt \
 -I uid=bjensen,ou=people,dc=example,dc=com
uid=bjensen,ou=people,dc=example,dc=com activated.
$

    See the ns-accountstatus(1M) man page for details.

ProcedureTo Render Accounts Inactive

Render an account or a role inactive as shown here.

Note –

You must bind as the Directory Manager.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Use the ns-inactivate command to render the account or role inactive.

    The following command renders Barbara Jensen's account inactive:


    $ ns-inactivate -D "cn=Directory Manager" -j pwd.txt \
-I uid=bjensen,ou=people,dc=example,dc=com
uid=bjensen,ou=people,dc=example,dc=com inactivated.
$

    See the ns-inactivate(1M) man page for details.

ProcedureTo Reactivate Accounts

Unlock an account or a role as shown here.

Note –

You must bind as the Directory Manager.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Use the ns-activate command to reactivate the account or role.

    The following command renders Barbara Jensen's account active again:


    $ ns-activate -D "cn=Directory Manager" -j pwd.txt \
-I uid=bjensen,ou=people,dc=example,dc=com
uid=bjensen,ou=people,dc=example,dc=com activated.
$

    ns-activate(1M) man page for details.

Chapter 8 Directory Server Backup and Restore

The data managed by your Directory Server is often imported in bulk. Directory Server Enterprise Edition provides tools for importing and exporting entire suffixes. It also provides tools for making backups of all suffixes at once and for restoring all data from a backup.

Before starting any backup or restore operation, ensure that you design a backup and restore strategy to suit your situation. For more information about the different backup options, considerations to take into account, and guidelines for planning a backup and restore strategy, see Designing Backup and Restore Policies in Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide.

This chapter covers the following topics:

Binary Backup

This section explains how to perform a binary backup of directory data. In addition to the binary backup procedures in this section, you can make a binary copy to use for initializing a suffix in a replication topology. See Initializing a Replicated Suffix by Using Binary Copy.

Backing Up Directory Data Only

A binary data backup saves a copy of your directory data that you can use if the database files later become corrupted or deleted. This operation does not back up configuration data. If you want to back up the whole Directory Server for disaster recovery, see Disaster Recovery.

Caution – Caution –

Never stop the server during a backup operation.

Your backup must be performed more frequently than the purge delay. The purge delay, specified by the nsDS5ReplicaPurgeDelay attribute, is the period of time, in seconds, after which internal purge operations are performed on the change log. The default purge delay is 604800 seconds (1 week). The change log maintains a record of updates, which might or might not have been replicated.

If your backup is performed less frequently than the purge delay, the change log might be cleared before it has been backed up. Changes will therefore be lost if you use the backup to restore data.

All backup procedures described in this section store a copy of the server files on the same host by default. You should then copy and store your backups on a different machine or file system for greater security.

ProcedureTo Back Up Your Directory Data

Your Directory Server must be stopped to run the dsadm backup command.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Back up your directory data.


    $ dsadm backup instance-path archive-dir

    For example:


    $ dsadm backup /local/ds /local/tmp/20051205
    Note –

    You can back up directory data while the server is running by using the command dsconf backup command. However, if changes are made to the directory data while the backup is running, proper recovery is more difficult. To avoid this problem when using dsconf backup, set replication referrals or make the server read-only.

    For more information about the dsadm and dsconf commands, see the dsadm(1M) and dsconf(1M) man pages.

ProcedureTo Back Up the dse.ldif File

When restoring a server, the dse.ldif configuration file must contain the same configuration information as when the server was backed up.

  1. Back up your dse.ldif configuration file. 


    $ cp instance-path/config/dse.ldif archive-dir

    When you perform the following actions, Directory Server automatically backs up the dse.ldif configuration file in the directory instance-path/config.

    • When you start Directory Server, a backup of the dse.ldif file is created in a file named dse.ldif.startOK.

    • When you make modifications to the cn=config branch, the file is first backed up to a file named dse.ldif.bak in the config directory before the server writes the modifications to the dse.ldif file.

Backing Up a File System

This procedure uses the frozen mode feature. Frozen mode enables you to stop database updates on disk so that a file system snapshot can be taken safely. You can use frozen mode as an additional measure for ensuring a robust backup.

Your server must not write user data on the disk while the file system backup is in progress. If you are sure that no updates will occur during a certain time frame, make your backup during this time. If you cannot guarantee that there will be no updates, put your server into frozen mode before making a backup.

A server in frozen mode continues to write to the access and errors logs. In a single-server topology, operations received when frozen mode is on result in an LDAP error being returned. The error message logged is the standard error for the database being offline. In a replicated topology, a referral is returned. For frozen mode to work correctly, no other tasks should be running on the databases.

Note that the databases of a server in frozen mode are more stable than those in read-only mode. Unlike frozen mode, read-only mode permits tasks to be created and configuration entries to be modified. When frozen mode is on, all configured databases are taken offline. Any internal operations in progress are notified of the database going offline. LDAP operations in progress are completed, and the database environment is flushed. Subsequent incoming operations, including searches to user data, are refused until frozen mode is set to off. You can, however, search configuration parameters while frozen mode is on.

ProcedureTo Back Up a File System

For parts of this procedure, you can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help. Other parts of the procedure can only be done using the command line.

  1. (Optional) Put your server into frozen mode. 


    $ dsconf set-server-prop -h host -p port read-write-mode:frozen

  2. Back up your file system, using a tool appropriate to your file system type.

  3. If your server is in frozen mode, make the server read-write again.


    $ dsconf set-server-prop -h host -p port read-write-mode:read-write

    If your server receives replication updates from another server, replication updates will start as soon as frozen mode is turned off.

Backing Up to LDIF

Backing up to LDIF allows you to back up directory data to a formatted LDIF file.

Exporting to LDIF

You can back up directory data by exporting the contents of a suffix using LDIF. Exporting data can be useful for doing the following:

The export operations do not export the configuration information ( cn=config).

Caution – Caution –

Do not stop the server while an export operation is in progress.

ProcedureTo Export a Suffix to LDIF

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Use one of the following commands to export a suffix to an LDIF file:

    • If your server is local and stopped, type:


      $ dsadm export instance-path suffix-DN LDIF-file

    • If your server is remote and running, type:


      $ dsconf export -h host -p port suffix-DN LDIF-file

    The following example uses dsconf export to export two suffixes to a single LDIF file:


    $ dsconf export -h host1 -p 1389 ou=people,dc=example,dc=com \
 ou=contractors,dc=example,dc=com /local/ds/ldif/export123.ldif

    The dsadm export and dsconf export commands can also be used with the --no-repl option to specify that no replication information is to be exported. The default is that the replicated suffix is exported to an LDIF file with replication information. The resulting LDIF file will contain attribute subtypes that are used by the replication mechanism. This LDIF file can then be imported on the consumer server to initialize the consumer replica, as described in Initializing Replicas

    For more information about these commands, see the dsadm(1M) and dsconf(1M) man pages.

Binary Restore

The following procedures describe how to restore suffixes in your directory. Your server must have been backed up using the procedures described in Backing Up Directory Data Only. Before restoring suffixes involved in replication agreements, read Restoring Replicated Suffixes.

Caution – Caution –

Do not stop the server during a restore operation. Because restoring your server overwrites any existing database files, any modifications that were made to the data since the backup are lost.

ProcedureTo Restore Your Server

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Use one of the following commands to restore your server:

    • If your server is local and stopped, type:


      $ dsadm restore instance-path archive-dir

      For example, to restore a backup from a backup directory, type:


      $ dsadm restore /local/ds/ local/ds/bak/2006_07_01_11_34_00

    • If your server is remote and running, type:


      $ dsconf restore -h host -p port archive-dir

      For example, to restore a backup from a backup directory:


      $ dsconf restore -h host1 -p 1389 /local/ds/bak/2006_07_01_11_34_00

    For more information about these commands, see the dsadm(1M) and dsconf(1M) man pages.

Restoring the dse.ldif Configuration File

Directory Server creates two backup copies of the dse.ldif file in the following directory:


instance-path/config

The dse.ldif.startOK file records a copy of the dse.ldif file at server start up. The dse.ldif.bak file contains a backup of the most recent changes to the dse.ldif file. Copy the file that contains the most recent changes to your directory.

ProcedureTo Restore the dse.ldif Configuration File

For parts of this procedure, you can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help. Other parts of the procedure can only be done using the command line.

  1. Stop the server.


    $ dsadm stop instance-path

  2. Change to the directory that contains the configuration files.


    $ cd instance-path/config

  3. Overwrite the dse.ldif file with a backup configuration file that is known to be valid, for example:


    $ cp dse.ldif.startOK dse.ldif

  4. Start the server with the following command:


    $ dsadm start instance-path

Importing Data From an LDIF File

You can import data to a Directory Server suffix in the following ways:

The following table shows the differences between initializing a suffix and adding, modifying, and deleting entries in bulk.

Table 8–1 Comparison of Initializing a Suffix and Importing Data in Bulk

Domain of Comparison 

Initializing Suffixes 

Adding, Modifying, and Deleting Entries in Bulk 

Overwrites content 

Overwrites 

content 

Does not overwrite content 

LDAP operations 

Add only 

Add, modify, delete 

Performance 

Fast 

Slower 

Response to server failure 

Atomic (all changes are lost after a failure) 

Best effort (all changes made up to the point of the failure remain) 

LDIF file location 

Local to client or local to server 

On client machine 

Imports configuration information (cn=config)

Imports configuration information 

Does not import configuration information 

Commands 

If server is local and stopped: 

dsadm import

If server is remote and running: 

dsconf import

ldapmodify -B

Initializing a Suffix

Initializing a suffix overwrites the existing data in a suffix with the contents of an LDIF file that contains only entries for addition.

You must be authenticated as the Directory Manager or an Administrator to initialize a suffix.

When the server is running, only the Directory Manager and Administrators can import an LDIF file that contains a root entry. For security reasons, only these users have access to the root entry of a suffix, for example, dc=example,dc=com..

Before restoring suffixes involved in replication agreements, read Restoring Replicated Suffixes.

ProcedureTo Initialize a Suffix

Note –

All LDIF files that you import must use UTF-8 character-set encoding.

When initializing a suffix, the LDIF file must contain the root entry and all directory tree nodes of the corresponding suffix.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Use one of the following commands to initialize the suffix from an LDIF file, that is, import the contents of a database to an LDIF file.

    Caution – Caution –

    These commands overwrite the data in your suffix.

    • If your server is local and stopped, type:


      $ dsadm import instance-path LDIF-file suffix-DN

      The following example uses the dsadm import command to import two LDIF files into a single suffix:


      $ dsadm import /local/ds /local/file/example/demo1.ldif \
 /local/file/example/demo2.ldif dc=example,dc=com

    • If your server is remote and running, type:


      $ dsconf import -h host -p port LDIF-file suffix-DN

      The following example imports an LDIF file using dsconf import. You do not need root privileges to run the command, but you must authenticate as a user with root permissions, such as the Directory Manager.


      $ dsconf import -h host1 -p 1389 /local/file/example/demo1.ldif \
 ou=People,dc=example,dc=com
    Note –

    If you run either dsconf import or dsconf reindex or both commands on multiple suffixes in parallel, transaction logs will grow and might negatively affect performance.

    For more information on these commands, see the dsadm(1M) and dsconf(1M)man pages.

Adding, Modifying, and Deleting Entries in Bulk

When you perform an ldapmodify operation, you are able to add, modify, or delete entries in bulk. Entries are specified in an LDIF file that contains update statements to modify or delete existing entries. This operation does not erase entries that already exist.

The changed entries may target any suffix that is managed by your Directory Server. As with any other operation that adds entries, the server will index all new entries as they are imported.

The ldapmodify command will import an LDIF file through LDAP and perform all operations that the file contains. Using this command you can modify data in all directory suffixes at the same time.

Before restoring suffixes involved in replication agreements, see Restoring Replicated Suffixes.

ProcedureTo Add, Modify and Delete Entries in Bulk

Note –

All LDIF files that you import must use UTF-8 character-set encoding.

When importing an LDIF file, parent entries must either exist in the directory or be added first from the file.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Add, modify, or delete from an LDIF file in bulk.


    $ ldapmodify -D cn=admin,cn=Administrators,cn=config -w - -B baseDN -f LDIF-file

    The following example performs an import using the ldapmodify command. You do not need root privileges to run this command, but you must authenticate as a user with root permissions, such as cn=Directory Manager or cn=admin,cn=Administrators,cn=config. The last parameter specifies the name of the LDIF file to import.


    $ ldapmodify -D cn=admin,cn=Administrators,cn=config -w - \
 -B dc=example,dc=com -f /local/ds/ldif/demo.ldif

Restoring Replicated Suffixes

Suffixes that are replicated between supplier servers and consumer servers require special consideration before being restored. If possible, update the suffix through the replication mechanism instead of restoring it from a backup.

When you restore a supplier or hub instance, the server configuration must be the same as it was when the backup was made. To ensure this, restore the dse.ldif file before restoring Directory Server data. See Restoring the dse.ldif Configuration File.

This section explains how and when to restore a replica, and how to ensure that it is synchronized with other replicas after the operation. To initialize a replica, see Initializing Replicas.

If you have a large replicated suffix and you want to add many entries and ensure that replication updates are added correctly, see Incrementally Adding Many Entries to Large Replicated Suffixes.

This section contains information about the following:

Restoring the Supplier in a Single-Master Scenario

A suffix that is a single-master supplier contains the authoritative data for the entire replication topology. Therefore, restoring this suffix is equivalent to reinitializing all data in the entire topology. You should restore a single master only if you want to reinitialize all data from the contents of the backup to be restored.

If the single-master data is not recoverable due to an error, consider using the data on one of the consumers because it might contain updates that are more recent than a backup. In this case, you need to export the data from the consumer replica to an LDIF file, and reinitialize the master from the LDIF file.

Whether you restore a backup or import an LDIF file on a master replica, you must then reinitialize all of the hubs and consumer replicas that receive updates from this replica. A message is logged to the supplier servers’ log files to remind you that reinitialization of the consumers is required.

Restoring a Supplier in a Multi-Master Scenario

In multi-master replication, the other masters each contain an authoritative copy of the replicated data. You cannot restore an old backup because it might be out of date with the current replica contents. If possible, allow the replication mechanism to bring the master up to date from the contents of the other masters.

If that is not possible, restore a multi-master replica in one of the following ways:

Regardless of how you restore or reinitialize, the master replica will remain in read-only mode after the initialization. This behavior allows the replica to synchronize with the other masters, after which time you may allow write operations, as described in Restoring a Master in a Multi-Master Scenario.

The advantage of allowing all replicas to converge before allowing write operations on the restored or reinitialized master is that none of the hub or consumer servers will require reinitialization.

Restoring a Hub

This section applies only in situations where the replication mechanism cannot automatically bring a hub replica up to date. Such situations include if the database files become corrupted or if replication has been interrupted for too long. In these cases, you need to restore or reinitialize the hub replica in one of the following ways:

Note –

Regardless of how you restore or reinitialize the hub replica, you must then reinitialize all consumers of this hub, including any other levels of hubs.

Restoring a Dedicated Consumer

This section applies only in situations where the replication mechanism cannot automatically bring a dedicated consumer replica up to date. Such situations include if the database files become corrupted or if replication has been interrupted for too long. In these cases, you need to restore or reinitialize the consumer in one of the following ways:

Restoring a Master in a Multi-Master Scenario

In the case of multi-master replication, other masters may process change operations while a given master is being restored. Therefore, when restoration is complete, the new master must also receive new updates that were not included in the restore data. Because restoring a master might take a significant amount of time, the number of pending updates might also be significant.

To allow convergence of these pending updates, newly restored masters are automatically set to read-only mode for client operations after restoration. This is true only when restoring a master by importing data from an LDIF file at the command line, or by using a backup to perform a binary copy.

Therefore, after restoration, a master in a multi-master configuration will process replication updates and allow read operations, but it will return referrals for all write operations from clients.

To verify that the new master is fully synchronized with the other masters before allowing updates, manually enable updates on an initialized master.

Note –

With master replicas sending referrals because of this new behavior, clients wanting to perform write operations might reach their configured hop limit. You might need to increase the hop limit configuration for clients so they can reach an available master. If all master replicas are initialized or reinitialized, all write operations will fail because no replica will be accepting client updates.

In any case, monitor initialized masters closely, and set the referral attributes appropriately to maximize server response.

ProcedureTo Begin Accepting Updates Through the Command Line

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

The following commands can be used in scripts that automate the process of initializing a multi-master replica.

  1. Use the insync tool to ensure that the replica has converged with all other masters.

    Replicas are in sync if the delay between modifications on all servers is zero or if the replica has never had any changes to replicate (delay of -1). For more information, see the insync(1) man page.

  2. Begin accepting updates. 


    $ dsconf set-suffix-prop -h host -p port suffix-DN repl-accept-client-update-enabled:on

    This command automatically sets the server to read-write mode.

Disaster Recovery

If you want to back up or restore your Directory Server for disaster recovery purposes, use the following procedures.

ProcedureTo Make a Backup for Disaster Recovery

For parts of this procedure, you can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help. Other parts of the procedure can only be done using the command line.

  1. Make a backup of your database files by using the command dsadn backup or dsconf backup.

    Use the procedure in Binary Backup, and store the backup files in a safe place.

  2. Copy the configuration directory instance-path/config to a safe place.

  3. Copy the schema directory instance-path/config/schema to a safe place.

  4. Copy the alias directory instance-path/alias to a safe place.

ProcedureTo Restore for Disaster Recovery

For parts of this procedure, you can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help. Other parts of the procedure can only be done using the command line.

  1. Install the same version of Directory Server that you had previously on the host.

  2. Create a server instance by using the dsadm create command.

    Use the same instance that was used at backup time. See Creating Suffixes.

  3. Restore the configuration directory instance-path /config.

  4. Restore the schema directory instance-path/config/schema .

  5. Restore the alias directory instance-path/alias .

  6. Ensure that the configuration for the restored server is correct.

    For example, the directory structure and plug-in configuration must be the same as on the backed up server.

  7. Restore your database files by using the command dsconf restore.

    Use the procedure in Binary Restore.

Chapter 9 Directory Server Groups, Roles, and CoS

Beyond the hierarchical structure of data in a directory, managing entries that represent users often requires creating groups that share common attribute values. Directory Server provides advanced entry management functionality through groups, roles, and class of service (CoS).

This chapter covers the following topics:

About Groups, Roles, and Class of Service

Groups, roles, and CoS are defined as follows:

Directory Server provides the ability to perform searches that are based on the values of the roles, and groups and the CoS computed attributes. Filter strings used in any operation can include the nsRole attribute or any attribute generated by a CoS definition. Filter strings can also be used to perform any of the comparison operations on the value of this attribute. However, computed CoS attributes cannot be indexed. Therefore, any search that involves a CoS-generated attribute might consume a large amount of resources in terms of time and memory.

To take full advantage of the features offered by roles, groups, and class of service, determine your grouping strategy in the planning phase of your directory deployment. Refer to Grouping Directory Data and Managing Attributes in Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide for a description of these features and how they can simplify your topology.

To gain a deeper understanding of how roles and groups work, see Chapter 8, Directory Server Groups and Roles, in Sun Java System Directory Server Enterprise Edition 6.2 Reference. For a detailed description of CoS, see Chapter 9, Directory Server Class of Service, in Sun Java System Directory Server Enterprise Edition 6.2 Reference.

Managing Groups

Groups enable you to associate entries for ease of administration. For example, using groups makes it easier to define access control instructions (ACIs). Group definitions are special entries that either name their members in a static list or provide a filter that defines a dynamic set of entries.

The scope of possible members of a group is the entire directory, regardless of where the group definition entries are located. To simplify administration, all group definition entries are usually stored in a single location, usually ou=Groups under the root suffix.

The two types of groups are static groups and dynamic groups.

ProcedureTo Create a New Static Group

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Create a new static group using the ldapmodify command.

    For example, to create a new static group called System Administrators and to add some members, you could use this command:


    $ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=System Administrators, ou=Groups, dc=example,dc=com
changetype: add
cn: System Administrators
objectclass: top
objectclass: groupOfNames
ou: Groups
member: uid=kvaughan, ou=People, dc=example,dc=com
member: uid=rdaugherty, ou=People, dc=example,dc=com
member: uid=hmiller, ou=People, dc=example,dc=com

  2. Check to see that the new group has been created and that the members have been added.

    For example, to check that Kirsten Vaughan is in the new System Administrators group, type:


    $ ldapsearch -b "dc=example,dc=com" uid=kvaughan isMemberOf
uid=kvaughan,ou=People,dc=example,dc=com
isMemberOf: cn=System Administrators, ou=Groups, dc=example,dc=com 
isMemberOf: cn=HR Managers,ou=groups,dc=example,dc=com

ProcedureTo Create a New Dynamic Group

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Create a new dynamic group by using the ldapmodify command.

    For example, to create a new dynamic group called “3rd Floor”, which includes all employees whose room numbers start with 3, you could use this command:


    $ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=3rd Floor, ou=Groups, dc=example,dc=com
changetype: add
cn: 3rd Floor
objectclass: top
objectclass: groupOfUrls
ou: Groups
memberURL: ldap:///dc=example,dc=com??sub?(roomnumber=3*)

Managing Roles

A role is an alternate grouping mechanism that is designed to be more efficient and easier for applications to use. While roles are defined and administered like groups, a generated role attribute in each member entry automatically indicates the roles of an entry. For example, an application can read the roles of an entry, rather than having to select a group and browse the members list.

By default, the scope of a role is limited to the subtree where the scope is defined. However, you can extend scoping of the nested role. You can allow the scope to nest roles located in other subtrees and to have members anywhere in the directory. For details see To Extend the Scope of a Role and Example of a Nested Role Definition.

This section explains how to use roles securely, and how to manage roles from the command line.

Using Roles Securely

To use roles securely, you must set access control instructions (ACIs) to protect appropriate attributes. For example, user A possesses the managed role, MR. Managed roles are equivalent to static groups, and explicitly assign a role to each member entry by adding the nsRoleDN attribute to the entry. The MR role has been locked using account inactivation through the command line. This means that user A cannot bind to the server because the nsAccountLock attribute is computed as “true” for that user. However, suppose the user was already bound and noticed that he is now locked through the MR role. If no ACI exists to prevent the user from having write access to the nsRoleDN attribute, the user can remove the nsRoleDN attribute from his own entry and unlock himself.

To prevent users from removing the nsRoleDN attribute, you must apply ACIs. With filtered roles, you must protect the part of the filter that would prevent the user from being able to relinquish the filtered role by modifying an attribute. Users should not be allowed to add, delete, or modify the attribute used by the filtered role. In the same way, if the value of the filter attribute is computed, all the attributes that can modify the value of the filter attribute need to be protected. As nested roles can contain filtered and managed roles, the preceding points should be considered for each of the roles that are contained in the nested role.

For detailed instructions on setting ACIs for security, see Chapter 6, Directory Server Access Control.

Managing Roles From the Command Line

Roles are defined in entries that the Directory Administrator can access through command-line utilities. After you create a role, you assign members to the role as follows:

All role definitions inherit from the LDAPsubentry and nsRoleDefinition object classes. The following example shows additional object classes and associated attributes specific to each type of role.

Example of a Managed Role Definition

To create a role for all marketing staff, use the following ldapmodify command:


$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=Marketing,ou=marketing,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsSimpleRoleDefinition
objectclass: nsManagedRoleDefinition
cn: Marketing
description: managed role for marketing staff

Notice that the nsManagedRoleDefinition object class inherits from the LDAPsubentry, nsRoleDefinition, and nsSimpleRoleDefinition object classes.

Assign the role to a marketing staff member who is named Bob by updating his entry as follows:


$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=Bob Arnold,ou=marketing,ou=People,dc=example,dc=com
changetype: modify
add: nsRoleDN
nsRoleDN: cn=Marketing,ou=marketing,ou=People,dc=example,dc=com

The nsRoleDN attribute indicates that the entry is a member of a managed role. The managed role is identified by the DN of its role definition. To allow users to modify their own nsRoleDN attribute, but to prevent users from adding or removing the nsManagedDisabledRole, add the following ACI:


aci: (targetattr="nsRoleDN")(targattrfilters="add=nsRoleDN: 
(!(nsRoleDN=cn=AdministratorRole,dc=example,dc=com)), 
del=nsRoleDN:(!(nsRoleDN=cn=nsManagedDisabledRole,dc=example, dc=com)") 
(version3.0;aci "allow mod of nsRoleDN by self except for critical values"; 
allow(write) userdn="ldap:///self";)

Example of a Filtered Role Definition

To set up a filtered role for sales managers, assuming that they all have the isManager attribute, use the following ldapmodify command:


$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=ManagerFilter,ou=sales,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsComplexRoleDefinition
objectclass: nsFilteredRoleDefinition
cn: ManagerFilter 
nsRoleFilter: (isManager=True)
Description: filtered role for sales managers

Notice that the nsFilteredRoleDefinition object class inherits from the LDAPsubentry, nsRoleDefinition, and nsComplexRoleDefinition object classes. The nsRoleFilter attribute specifies a filter that finds all employees in the ou=sales organization that have subordinates, for example:


$ ldapsearch -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - \
 -b "ou=People,dc=example,dc=com" -s sub "(cn=*Fuentes)"
dn: cn=Carla Fuentes,ou=sales,ou=People,dc=example,dc=comcn: Carla Fuentes 
isManager: TRUE...
nsRole: cn=ManagerFilter,ou=sales,ou=People,
dc=example,dc=com
Note –

The filter string of a filtered role can be based on any attribute, except computed attributes that are generated by the CoS mechanism.

When filtered role members are user entries, you can choose to restrict their ability to add or remove themselves from the role. Protect the filtered attributes with ACIs.

Example of a Nested Role Definition

The roles that are nested within the nested role are specified by using the nsRoleDN attribute. Use the following command to create a role that contains both the marketing staff and sales manager members of the roles created in the previous examples:


$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=MarketingSales,ou=marketing,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsComplexRoleDefinition
objectclass: nsNestedRoleDefinition
cn: MarketingSales
nsRoleDN: cn=ManagerFilter,ou=sales,ou=People,dc=example,dc=com
nsRoleDN: cn=Marketing,ou=marketing,ou=People,dc=example,dc=com
nsRoleScopeDN: ou=sales,ou=People,dc=example,dc=com

Notice that the nsNestedRoleDefinition object class inherits from the LDAPsubentry, nsRoleDefinition, and nsComplexRoleDefinition object classes. The nsRoleDN attributes contain the DN of the marketing managed role and the sales managers filtered role. Both of the users in the previous examples, Bob and Carla, would be members of this new nested role.

The scope of this filter includes the default scope, which is the subtree where the filter is located, and the subtree below any values of the nsRoleScopeDN attribute. In this case, the ManagerFilter is in the ou=sales,ou=People,dc=example,dc=com subtree. This subtree must be added to the scope.

Extending the Scope of a Role

Directory Server provides an attribute that allows the scope of a role to be extended beyond the subtree of the role definition entry. This single-valued attribute, nsRoleScopeDN, contains the DN of the scope to be added to an existing role. The nsRoleScopeDN attribute can only be added to a nested role. See Example of a Nested Role Definition.

ProcedureTo Extend the Scope of a Role

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

The nsRoleScopeDN attribute enables you to extend the scope of a role in one subtree to include an entry in another subtree. For example, imagine two main subtrees in the example.com directory tree: o=eng,dc=example,dc=com ( the engineering subtree) and o=sales,dc=example,dc=com (the sales subtree.) A user in the engineering subtree requires access to a sales application governed by a role in the sales subtree (SalesAppManagedRole). To extend the scope of the role, do the following:

  1. Create a role for the user in the engineering subtree.

    For example, create the role EngineerManagedRole. This example uses a managed role, but it could just as well have been a filtered or nested role.

  2. Create a nested role, for example, SalesAppPlusEngNestedRole , in the sales subtree to house the newly created EngineerManagedRole and the initial SalesAppManagedRole .

  3. Add the nsRoleScopeDN attribute to the SalesAppPlusEngNestedRole, with the DN of the engineering subtree scope that you want to add, in this case, o=eng,dc=example,dc=com.

    The necessary permissions must be granted to the engineering user so that he can access the SalesAppPlusEngNestedRole role and, in turn, the sales application. In addition, the entire scope of the role must be replicated.

    Note –

    The restriction of extended scope to nested roles means that an administrator who previously managed roles in one domain only has rights to use the roles that already exist in the other domain. The administrator is not able to create an arbitrary role in the other domain.

Class of Service

The class of service (CoS) mechanism generates computed attributes as an entry is retrieved for a client application, which simplifies entry management and reduces storage requirements. The CoS mechanism allows attributes to be shared between entries, and as with groups and roles, CoS relies on helper entries.

For an explanation of how you can use CoS in your deployment, see Managing Attributes With Class of Service in Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide.

For a description of how CoS is implemented in Directory Server, see Chapter 9, Directory Server Class of Service, in Sun Java System Directory Server Enterprise Edition 6.2 Reference.

Note –

Any search operation can test the existence of a CoS-generated attribute or compare the value of the attribute. The names of the computed attributes may be used in any filter string from a client search operation, except in an internal filter used in a filtered role.

Using CoS Securely

The following sections describe the general principles for read and write protection of data in each of the CoS entries. The detailed procedure for defining individual access control instructions (ACIs) is described in Chapter 6, Directory Server Access Control.

Protecting the CoS Definition Entry

Although the CoS definition entry does not contain the value of the generated attribute, it does provide the information to find that value. Reading the CoS definition entry reveals how to find the template entry that contains the value. Writing to this entry modifies how the computed attribute is generated.

You should therefore define both read and write ACIs for the CoS definition entries.

Protecting the CoS Template Entries

The CoS template entry contains the value of the generated CoS attribute. Therefore, at a minimum, the CoS attribute in the template must be protected by an ACI for both reading and updating.

Protecting the Target Entries of a CoS

All entries in the scope of a CoS definition, for which the computed CoS attribute is generated, also contribute to computing its value.

When the CoS attribute already exists in a target entry, by default, the CoS mechanism does not override this value. If you do not want this behavior, define your CoS to override the target entry, or protect the CoS attribute in all potential target entries.

Both indirect and classic CoS also rely on a specifier attribute in the target entry. This attribute specifies the DN or RDN of the template entry to use. You should use an ACI to protect this attribute either globally throughout the scope of the CoS or individually on each target entry where it is needed.

Protecting Other Dependencies

Computed CoS attributes can be defined in terms of other generated CoS attributes and roles. You must understand and protect these dependencies to ensure that your computed CoS attribute is protected.

For example, the CoS specifier attribute in a target entry could be nsRole. Therefore the role definition must also be protected by an ACI.

In general, any attribute or entry that is involved in the computation of the computed attribute value should have an ACI for both read and write access control. For this reason, complex dependencies should be well planned or simplified to reduce subsequent complexity of access control implementation. Keeping dependencies on other computed attributes to a minimum improves directory performance and reduces maintenance.

Managing CoS From the Command Line

Because all configuration information and template data are stored as entries in the directory, you can use the LDAP command-line tools to configure and manage CoS definitions. This section shows how to create CoS definition entries and CoS template entries from the command line.

Creating the CoS Definition Entry From the Command Line

All CoS definition entries have the LDAPsubentry object class and inherit from the cosSuperDefinition object class. In addition, each type of CoS inherits from specific object classes and contains the corresponding attributes. The following table lists the object classes and attributes that are associated with each type of CoS definition entry.

Table 9–1 Object Classes and Attributes in CoS Definition Entries

CoS Type 

CoS Definition Entry 

Pointer CoS 

objectclass: top

objectclass: LDAPsubentry

objectclass: cosSuperDefinition

objectclass: cosPointerDefinition

cosTemplateDN: DN

cosAttribute: attributeName override merge

Indirect CoS 

objectclass: top

objectclass: LDAPsubentry

objectclass: cosSuperDefinition

objectclass: cosIndirectDefinition

cosIndirectSpecifier: attributeName

cosAttribute: attributeName override merge

Classic CoS 

objectclass: top

objectclass: LDAPsubentry

objectclass: cosSuperDefinition

objectclass: cosClassicDefinition

cosTemplateDN: DN

cosSpecifier: attributeName

cosAttribute: attributeName override merge

In all cases, cosAttribute is multivalued. Each value defines an attribute that is generated by the CoS mechanism.

You can use the following attributes in CoS definition entries. For more information about each of these attributes, see the individual attributes in Sun Java System Directory Server Enterprise Edition 6.2 Man Page Reference.

Table 9–2 CoS Definition Entry Attributes

Attribute 

Purpose Within the CoS Definition Entry 

cosAttribute

attributeName override merge

Defines the name of the computed attribute for which you want to generate a value. This attribute is multivalued, and each value represents the name of an attribute whose value is generated from the template. The override and merge qualifiers specify how the CoS attribute value is computed in special cases described following this table.

The attributeName cannot contain any subtypes. Attribute names with subtypes are ignored, but other values of cosAttribute are processed.

cosIndirectSpecifier

attributeName

Defines the name of the attribute in target entries whose value is used by indirect CoS to identify the template entry. The named attribute is called the specifier and must contain a full DN string in each target entry. This attribute is single-valued, but the attributeName can be multivalued to designate multiple templates.

cosSpecifier

attributeName

Defines the name of the attribute in target entries whose value is used by classic CoS to identify the template entry. The named attribute is called the specifier and must contain a string that can be found in the RDN of template entries. This attribute is single-valued, but the attributeName can be multivalued to designate multiple templates.

cosTemplateDN

DN

Provides the full DN of the template entry for a pointer CoS definition or the base DN of the template entry for classic CoS. This attribute is single-valued.  

Note –

You cannot use the isMemberOf attribute as a CosSpecifier to make all the members of static groups automatically inherit from a common computed attribute value.

The cosAttribute attribute allows two qualifiers following the name of the CoS attribute, the override qualifier and the merge qualifier.

The override qualifier describes the behavior when an attribute that is dynamically generated by CoS already physically exists in the entry. The override qualifier can be one of the following:

The merge qualifier is either absent or merge-schemes. This qualifier allows the computed CoS attribute to be multivalued, either from multiple templates or multiple CoS definitions. For more information, see Multivalued CoS Attributes.

Overriding Real Attribute Values

You might create a pointer CoS definition entry that contains an override qualifier as follows:


dn: cn=pointerCoS,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosPointerDefinition
cosTemplateDn: cn=exampleUS,cn=data
cosAttribute: postalCode override

This pointer CoS definition entry indicates that the entry is associated with the template entry cn=exampleUS,cn=data that generates the value of the postalCode attribute. The override qualifier indicates that this value takes precedence over the value of the postalCode attribute if the attribute exists in a target entry.

Note –

If the CoS attribute is defined with the operational or override qualifiers, you cannot perform write operations on the “real” value of that attribute in any entry in the CoS scope.

Multivalued CoS Attributes

When you specify the merge-schemes qualifier, the generated CoS attribute can be multivalued in two ways:

The two situations can occur together and define even more values. However, in all cases, duplicate values will only be returned one time in a generated attribute.

In the absence of the merge-schemes qualifier, the cosPriority attribute of the template entry is used to determine a single value among all templates for the generated attribute. This scenario is described in the next section.

The merge-schemes qualifier never merges a “real” value that is defined in the target with generated values from the templates. The merge qualifier is independent of the override qualifier. All pairings are possible, and the behaviors implied by each are complimentary. Also, the qualifiers can be specified in any order after the attribute name.

Note –

When there are multiple CoS definitions for the same attribute, the definitions must all have the same override and merge qualifiers. When different pairs of qualifiers occur in CoS definitions, one of the combinations is selected arbitrarily among all definitions.

CoS Attribute Priority

If multiple CoS definitions or multivalued specifiers exist, but no merge-schemes qualifier, Directory Server uses a priority attribute to select a single template that defines the single value of the computed attribute.

The cosPriority attribute represents the global priority of a particular template among all those being considered. A priority of zero is the highest priority. Templates that contain no cosPriority attribute are considered the lowest priority. When two or more templates provide an attribute value but have the same or no priority, a value is chosen arbitrarily.

Template priorities are not taken into account when using the merge-schemes qualifier. When merging, all templates being considered define a value regardless of any priority that the templates define. The cosPriority attribute is defined on CoS template entries as described in the following section.

Note –

The cosPriority attribute must not have a negative value. Also, attributes generated by indirect CoS do not support priority. Do not use cosPriority in template entries of an indirect CoS definition.

Creating the CoS Template Entry From the Command Line

When using pointer CoS or classic CoS, the template entry contains the LDAPsubentry and cosTemplate object classes. This entry must be created specifically for the CoS definition. Making the CoS template entry an instance of the LDAPsubentry object class allows ordinary searches to be performed unhindered by the configuration entries.

The template of the indirect CoS mechanism is an arbitrary, existing entry in the directory. The target does not need to be identified ahead of time or given the LDAPsubentry object class, but the target must have the auxiliary cosTemplate object class. The indirect CoS template is accessed only when the CoS is evaluated to generate a computed attribute and its value.

In all cases, the CoS template entry must contain the attribute and the value that is generated by the CoS on the target entries. The attribute name is specified in the cosAttribute attribute of the CoS definition entry.

The following example shows a template entry of the highest priority for a pointer CoS that generates the postalCode attribute:


dn: cn=ZipTemplate,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
postalCode: 95054
cosPriority: 0

The following sections provide examples of template entries along with examples of each type of CoS definition entry.

Example of a Pointer CoS

The following command creates a pointer CoS definition entry that has the cosPointerDefinition object class. This definition entry uses the CoS template entry that is stated in the example in the previous section to share a common postal code among all entries in the ou=People,dc=example,dc=com tree.


$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=pointerCoS,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosPointerDefinition
cosTemplateDn: cn=ZipTemplate,ou=People,dc=example,dc=com
cosAttribute: postalCode

The CoS template entry (cn=ZipTemplate,ou=People,dc=example,dc=com ) supplies the value stored in its postalCode attribute to all entries located under the ou=People,dc=example,dc=com suffix. If you search for any entry that does not have a postal code in the same subtree, you will see the value of the generated attribute:


$ ldapsearch -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - \
 -b "ou=People,dc=example,dc=com" -s sub "(cn=*Jensen)"
dn: cn=Babs Jensen,ou=People,dc=example,dc=com
cn: Babs Jensen
...
postalCode: 95054

Example of an Indirect CoS

Indirect CoS names an attribute in the cosIndirectSpecifier attribute to locate the template specific to each target. The template entry for indirect CoS may be any entry in the directory, including other user entries. This example indirect CoS uses the manager attribute of the target entry to identify the CoS template entry. The template entry is the manager’s user entry. The manager’s user entry contains the value of the attribute to generate. The value is that of departmentNumber in this case.

The following command creates the indirect CoS definition entry, which contains the cosIndirectDefinition object class:


$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=generateDeptNum,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosIndirectDefinition
cosIndirectSpecifier: manager
cosAttribute: departmentNumber

Next, add the cosTemplate object class to the template entries, and make sure that they define the attribute to be generated. In this example, all manager entries are templates:


$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=Carla Fuentes,ou=People,dc=example,dc=com
changetype: modify
add: objectclass
objectclass: cosTemplate
-
add: departmentNumber
departmentNumber: 318842

With this CoS, target entries (the entries under ou=People,dc=example,dc=com) that contain the manager attribute automatically have the department number of their manager. The departmentNumber attribute is computed on the target entries because it does not exist in the server. However, the departmentNumber attribute is returned as part of the target entry. For example, if Babs Jensen’s manager is defined to be Carla Fuentes, her department number is the following:


$ ldapsearch -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - \
 -b "ou=People,dc=example,dc=com" -s sub "(cn=*Jensen)"
dn: cn=Babs Jensen,ou=People,dc=example,dc=com
cn: Babs Jensen
...
manager: cn=Carla Fuentes,ou=People,dc=example,dc=com
departmentNumber: 318842

Example of a Classic CoS

This example shows how to generate a postal address with a classic CoS. The generated value is specified in a template entry that is located by a combination of the cosTemplateDN in the CoS definition and the value of the cosSpecifier attribute in the target entry. The following command creates the definition entry by using the cosClassicDefinition object class:


$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=classicCoS,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosClassicDefinition
cosTemplateDn: ou=People,dc=example,dc=com
cosSpecifier: building
cosAttribute: postalAddress

Using the same command, create the template entries that give the postal address for each building:


dn: cn=B07,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
postalAddres: 7 Old Oak Street, Anytown, CA 95054

With this CoS, target entries (the entries under ou=People,dc=example,dc=com) that contain the building attribute will automatically have the corresponding postal address. The CoS mechanism searches for a template entry that has the specifier attribute value in its RDN. In this example, if Babs Jensen is assigned to building B07, her postal address is generated as follows:


$ ldapsearch -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - \
 -b "ou=People,dc=example,dc=com" -s sub "(cn=*Jensen)"
dn: cn=Babs Jensen,ou=People,dc=example,dc=com
cn: Babs Jensen
...
building: B07
postalAddress: 7 Old Oak Street, Anytown, CA 95054

Creating Role-Based Attributes

You can create classic CoS schemes that generate attribute values for an entry that is based on the role possessed by the entry. For example, you could use role-based attributes to set the server look-through limit on an entry-by-entry basis.

To create a role-based attribute, use the nsRole attribute as the cosSpecifier in the CoS definition entry of a classic CoS. Because the nsRole attribute can be multivalued, you can define CoS schemes that have more than one possible template entry. To resolve the ambiguity of which template entry to use, you can include the cosPriority attribute in your CoS template entry.

For example, you can create a CoS that allows members of the manager role to exceed the standard mailbox quota. The manager role is as follows:


dn: cn=ManagerRole,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsComplexRoleDefinition
objectclass: nsFilteredRoleDefinition
cn: ManagerRole
nsRoleFilter: (isManager=True)
Description: filtered role for managers

The classic CoS definition entry is created as follows:


dn: cn=generateManagerQuota,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosClassicDefinition
cosTemplateDn: cn=managerCOS,ou=People,dc=example,dc=com
cosSpecifier: nsRole
cosAttribute: mailboxquota override

The CoS template name must be a combination of the cosTemplateDn and the value of nsRole, which is the DN of the role. For example:


dn:cn="cn=ManagerRole,ou=People,dc=example,dc=com",\
 cn=managerCOS,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
mailboxquota: 1000000

The CoS template entry provides the value for the mailboxquota attribute. An additional qualifier of override tells the CoS to override any existing mailboxquota attributes values in the target entry. Target entries that are members of the role will have computed attributes generated by the role and by the CoS, for example:


$ ldapsearch -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -\
 -b "ou=People,dc=example,dc=com" -s sub "(cn=*Fuentes)"
dn: cn=Carla Fuentes,ou=People,dc=example,dc=comcn: Carla Fuentes
isManager: TRUE...nsRole: cn=ManagerRole,ou=People,dc=example,dc=com
mailboxquota: 1000000
Note –

The role entry and the CoS definition entry should be located in the same place in the directory tree so that they have the same target entries in their scope. The CoS target entry should also be located in the same place so that it is easy to find and maintain.

Monitoring the CoS Plug-In

Directory Server enables you to monitor certain aspects of the CoS plug-in. CoS monitoring attributes are stored in the cn=monitor,cn=Class of Service,cn=plugins,cn=config entry. For details of the each attribute under this entry and the information that they provide, see Sun Java System Directory Server Enterprise Edition 6.2 Man Page Reference.

Setting CoS Logging

Directory Server logs warning messages when it is forced to make an arbitrary distinction among multiple applicable definition entries. Such warning messages takes this form:


Definition /defDN1/ and definition /defDN2/ compete to provide attribute
 '/type/' at priority /level/

You can also configure Directory Server to log informational messages when the server is forced to make an arbitrary distinction among multiple, potentially applicable definition entries. To do so, set the error log to include messages from plug-ins.

Note –

Because setting additional log levels can result in a heavy logging load, you might not want to set logging on a production server.

The content of informational messages takes the following form:


Definition /defDN1/ and definition /defDN2/ potentially compete 
to provide attribute '/type/' at priority /level/

You can then choose whether to resolve such cases of CoS ambiguity by setting CoS priorities appropriately on the definition entries.

Maintaining Referential Integrity

Referential integrity is a plug-in mechanism that ensures that relationships between entries are maintained. Several types of attributes, such as those for group membership, contain the DN of another entry. Referential integrity can be used to ensure that when an entry is removed, all attributes that contain its DN are also removed.

For example, if a user’s entry is removed from the directory and referential integrity is enabled, the server also removes the user from any groups of which the user is a member. If referential integrity is not enabled, the user must be manually removed from the group by the administrator. This is an important feature if you are integratingDirectory Server with other Sun Java System products that rely on the directory for user and group management.

How Referential Integrity Works

When the referential integrity plug-in is enabled it performs integrity updates on specified attributes immediately after a delete, rename, or move operation. By default, the referential integrity plug-in is disabled.

Whenever you delete, rename, or move a user or group entry in the directory, the operation is logged to the referential integrity log file:

instance-path/logs/referint

After a specified time, known as the update interval, the server performs a search on all attributes for which referential integrity is enabled, and matches the entries resulting from that search with the DNs of deleted or modified entries present in the log file. If the log file shows that the entry was deleted, the corresponding attribute is deleted. If the log file shows that the entry was changed, the corresponding attribute value is modified accordingly.

When the default configuration of the referential integrity plug-in is enabled, it performs integrity updates on the member, uniquemember, owner, seeAlso, and nsroledn attributes immediately after a delete, rename, or move operation. You can, however, configure the behavior of the referential integrity plug-in to suit your own requirements. The following behavior can be configured:

ProcedureTo Configure the Referential Integrity Plug-In

Note –

All attributes in all databases that are used by the referential integrity plug-in must be indexed. The indexes need to be created in the configuration of all the databases. When the retro changelog is enabled, the cn=changelog suffix must be indexed. For information, see Chapter 12, Directory Server Indexing.

Certain limitations are associated with using the referential integrity plug-in in a replicated environment. For a list of these limitations, see Replication and Referential Integrity.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Make sure that all replicas are configured and that all replication agreements are defined.

  2. Determine the set of attributes for which you will maintain referential integrity and the update interval that you want to use on your master servers.

  3. Enable the referential integrity plug-in on all master servers using the same set of attributes and the same update interval.

    • To define the attributes for referential integrity, use this command:


      $ dsconf set-server-prop -h host -p port ref-integrity-attr:attribute-name \
 ref-integrity-attr:attribute-name

    • To add a referential integrity attribute to an existing list of attributes, use this command:


      $ dsconf set-server-prop -h host -p port ref-integrity-attr+:attribute-name

    • To define the referential integrity update interval, use this command:


      $ dsconf set-server-prop -h host -p port ref-integrity-check-delay:duration

    • To enable referential integrity, use this command:


      $ dsconf set-server-prop -h host -p port ref-integrity-enabled:on

  4. Ensure that the referential integrity plug-in is disabled on all consumer servers.

Chapter 10 Directory Server Replication

Replication is the mechanism by which directory contents are automatically copied from a Directory Server to one or more other Directory Servers. All write operations are automatically mirrored to other Directory Servers. For a complete description of replication concepts, replication scenarios, and how to plan for replication in your directory deployment, see the Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide.

In a replication topology, generally one suffix on a server is replicated to or from another suffix on a server. For this reason, the terms replica, replicated suffix and replicated server can be used interchangeably.

This chapter describes the tasks to be performed to set up the various replication scenarios by using the command line, and covers the following topics:

Planning Your Replication Deployment

You can configure a replication deployment with an unlimited number of masters. You are not required to include hubs or consumers in your deployment. Procedures for configuring replication for hubs and consumers are included in this chapter, but they are optional.

Before you begin configuring replication, you need to have a clear understanding of the way that replication will be deployed in your organization. You must understand the replication concepts described in Sun Java System Directory Server Enterprise Edition 6.2 Reference. You must also have carefully planned your future replication configuration using the design guidelines provided in the Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide.

Recommended Interface for Configuring and Managing Replication

The easiest way to configure and manage replication is by using Directory Service Control Center (DSCC). By using DSCC, you can configure replication automatically. You can choose the level of automation you require for setting up your replication topology, for example, whether you want to initialize the suffixes during replication configuration or not. DSCC also provides checks that can prevent errors. In addition, DSCC provides a graphical view of the replication topology.

The DSCC online help provides procedures for setting up replication by using DSCC.

Note –

Only use the command-line procedures provided in this chapter if you are unable to use DSCC for configuring replication.

Summary of Steps for Configuring Replication

Summary of Steps for Configuring Replication assumes that you are replicating a single suffix. If you are replicating more than one suffix, you can configure the suffixes in parallel on each server. In other words, you can repeat each step to configure replication on multiple suffixes.

The rest of this chapter contains detailed instructions on how to configure replication.

ProcedureSummary of Steps for Configuring Replication

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

To configure any replication topology, follow the general steps as outline in this procedure.

  1. Do the following on all servers that contain a dedicated consumer replica:

    1. Create an empty suffix for the consumer replicated suffix.

      See To Create a Suffix for a Consumer Replica.

    2. Enable the consumer replicated suffix.

      See To Enable a Consumer Replica.

    3. (Optional) Configure the advanced consumer settings.

      See To Perform Advanced Consumer Configuration.

  2. If applicable, do the following on all servers that contain a hub replicated suffix:

    1. Create an empty suffix for the hub replicated suffix.

      See To Create a Suffix for a Hub Replica.

    2. Enable the hub replicated suffix.

      See To Enable a Hub Replica.

    3. (Optional) Configure the advanced hub settings.

      See To Modify Change Log Settings on a Hub Replica.

  3. Do the following on all servers that contain a master replicated suffix:

    1. Create a suffix for the master replicated suffix.

      See To Create a Suffix for a Master Replica.

    2. Enable the master replicated suffix.

      See To Enable a Master Replica.

    3. (Optional) Configure the advanced master settings.

      See To Modify Change Log Settings on a Master Replica.

    Note –

    Make sure that you enable all replicas before you create a replication agreement so that you can initialize consumer replicas immediately after you create the replication agreement. Consumer initialization is always the last stage in setting up replication.

  4. Ensure your replication manager configuration is complete.

  5. Create replication agreements on all master replicas as follows:

    1. Between masters in a multimaster topology

    2. Between masters and their dedicated consumers

    3. Between masters and hub replicas

    See Creating and Changing Replication Agreements.

  6. (Optional) If you want to use fractional replication, configure it now.

    See Fractional Replication.

  7. (Optional) If you want to use replication priority, configure it now.

    See Replication Priority.

  8. Configure replication agreements between the hub replicas and their consumers.

    See Creating and Changing Replication Agreements.

  9. For multimaster replication, initialize all masters from the same master replica that contains the original copy of the data.

    See Initializing Replicas.

  10. Initialize the hub and consumer replicas.

    See Initializing Replicas.

Enabling Replication on a Dedicated Consumer

A dedicated consumer is a read-only copy of a replicated suffix. The dedicated consumer receives updates from servers that bind as the replication manager to make changes. Configuring the consumer server consists of preparing an empty suffix to hold the replicated suffix and enabling replication on that suffix. Optional advanced configuration can include setting referrals, changing the purge delay, and modifying properties.

The following sections explain how to configure one dedicated consumer replicated suffix on its server. Repeat all procedures on each server that will contain a dedicated consumer replicated suffix.

ProcedureTo Create a Suffix for a Consumer Replica

  1. If an empty suffix does not already exist, create it on the consumer with the same DN as the intended master replica.

    For instructions, see Creating Suffixes.

    Caution – Caution –

    If the suffix exists and is not empty, its contents will be lost when the replicated suffix is initialized from the master.

ProcedureTo Enable a Consumer Replica

After you have created an empty suffix, you need to enable the consumer replicated suffix.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Enable the consumer replicated suffix.


    $ dsconf enable-repl -h host -p port consumer suffix-DN

    For example:


    $ dsconf enable-repl -h host1 -p 1389 consumer dc=example,dc=com

ProcedureTo Perform Advanced Consumer Configuration

If you want to configure your consumer replicated suffix for advanced features, do so now.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. If you want to use SSL for referrals, set secure referrals.


    $ dsconf set-suffix-prop -h host -p port suffix-DN referral-url:ldaps://servername:port

    For example:


    $ dsconf set-suffix-prop -h host1 -p 1389 dc=example,dc=com \
 referral-url:ldaps://server2:2389

    The replication mechanism automatically configures consumers to return referrals for all known masters in the replication topology. These default referrals assume that clients will use simple authentication over a regular connection. If you want to give clients the option of binding to masters using SSL for a secure connection, add referrals of the form ldaps://servername :port that use a secure port number. Note that if the masters are configured for secure connections only, the URLs will point to the secure ports by default.

    If you have added one or more LDAP URLs as referrals, you can force the consumer to send referrals exclusively for these LDAP URLs and not for the master replicas. For example, suppose that you want clients to always be referred to the secure port on the master servers and not to the default port. Create a list of LDAP URLs for these secure ports, and set the property for using these referrals. You can also use an exclusive referral if you want to designate a specific master or a Directory Server proxy to handle all updates.

  2. If you want to change the replication purge delay for the consumer, use this command:


    $ dsconf set-suffix-prop -h host -p port suffix-DN repl-purge-delay:time

    For example, to set the purge delay to 2 days, type:


    $ dsconf set-suffix-prop -h host1 -p 1389 edc=example,dc=com repl-purge-delay:2d

    The consumer server stores internal information about updates to the replicated suffix contents, and the purge delay parameter specifies how long it must keep this information. The purge delay determines in part how long replication between the consumer and its master can be interrupted and still recover normally. It is related to the MaxAge parameter of the change log on its supplier server. The shorter of these two parameters determines the longest time that replication between the two servers can be disabled or down and still recover normally. The default value of 7 days is sufficient in most cases.

Enabling Replication on a Hub

Hub replicas act as both consumers and masters to further distribute replicated data to a larger number of consumers. Hub replicas receive replication updates from their suppliers and send replication updates to their consumers. They do not accept modifications, but instead return referrals to the masters.

Configuring a hub server consists of preparing an empty suffix to hold the replicated suffix and enabling replication on that suffix. Optional advanced configuration can include choosing a different replication manager, setting referrals, setting the purge delay, and modifying change log parameters.

The following sections explain how to configure one hub server. Repeat all procedures on each server that will contain a hub replicated suffix.

ProcedureTo Create a Suffix for a Hub Replica

  1. If an empty suffix does not already exist, create it on the hub server with the same DN as the intended master replica.

    For instructions, see Creating Suffixes.

    If the suffix exists and is not empty, its contents will be lost when the replicated suffix is initialized from the master.

ProcedureTo Enable a Hub Replica

If you have hub replicas, enable them now.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Enable the hub replicated suffix.


    $ dsconf enable-repl -h host -p port hub suffix-DN

    For example:


    $ dsconf enable-repl -h host1 -p 1389 hub dc=example,dc=com

ProcedureTo Modify Change Log Settings on a Hub Replica

For advanced hub configuration, the only parameters that you might want to modify are related to the change log. As a supplier, a hub server requires a change log.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. To modify a change log setting on a hub, use one of the following commands:


    $ dsconf set-server-prop -h host -p port suffix-DN repl-cl-max-age:value


    $ dsconf set-server-prop -h host -p port suffix-DN repl-cl-max-entry-count:value

Enabling Replication on a Master Replica

Master replicas contain the master copy of the data and centralize all modifications before propagating updates to all other replicas. A master records all changes, checks the status of its consumers, and sends updates to them when necessary. In multimaster replication, master replicas also receive updates from other masters.

Configuring a master server consists of defining the suffix that contains the master replica, enabling the master replica, and configuring it for advanced replication, if necessary.

The following sections explain how to configure one master server. Repeat all procedures on each server that will contain a master replicated suffix.

ProcedureTo Create a Suffix for a Master Replica

  1. Choose or create a suffix on the master server that will contain the entries that you want to replicate.

    For instructions, see to Creating Suffixes.

    To ensure correct multimaster configuration and initialization, only load one of the masters with the data. Any data on other replicated suffixes will be overwritten.

ProcedureTo Enable a Master Replica

When you enable replication on a master, you must assign a replication ID. The replication ID is used to distinguish the owner of update statements and to resolve conflicts that might occur with multimaster replication. Therefore, the replication ID must be unique for all master replicas of this suffix. Once set, the replication ID must not be changed.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Enable the master replicated suffix.


    $ dsconf enable-repl -h host -p port -d ReplicaID master suffix-DN

    where ReplicaID is an integer between 1 and 65534.

    For example, to create a master replicated suffix with replica ID 1, use this command:


    $ dsconf enable-repl -h host1 -p 1389 -d 1 master dc=example,dc=com

ProcedureTo Modify Change Log Settings on a Master Replica

For advanced master configuration, you might want to modify the change log settings.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. If you want to modify a change log setting on a master, use one of the following commands:


    $ dsconf set-server-prop -h host -p port suffix-DN repl-cl-max-age:value


    $ dsconf set-server-prop -h host -p port suffix-DN repl-cl-max-entry-count:value

Configuring the Replication Manager

This section describes how to configure a non-default replication manager and how to set the default replication manager password.

Using a Non-Default Replication Manager

The replication manager is the user that suppliers will use to bind to a consumer server when sending replication updates. All servers that contain suffixes receiving updates must have at least one replication manager entry.

Directory Server has a default replication manager entry that you can use on every server, especially for simple replication scenarios: cn=replication manager,cn=replication,cn=config. The replication mechanism automatically configures consumer replicas with this user, simplifying the deployment of replicas.

If you have a more complex replication scenario, you might want several replication managers with a different password for each replicated suffix. You can replace the existing default replication manager with one or more new replication managers.

Caution – Caution –

Never bind or perform operations on the server using the DN and password of the replication manager. The replication manager is for use only by the replication mechanism. Any other use might require reinitializing the replicas.

Never use the Directory Manager as the replication manager. Because the cn=admin,cn=Administrators,cn=config entry is used for other administrative tasks, you must also not use this user or any other user in the administrator group as the replication manager.

After you have chosen the replication manager for each consumer, ensure that you remember the replication manager DN that you chose or created. You will need this DN and its password later when creating the replication agreement with this consumer on its supplier.

ProcedureTo Set A Non-Default Replication Manager

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. On all consumer (destination) replicated suffixes, create a new replication manager and password. 


    $ ldapmodify -a -h host -p port -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn:"cn=new-replication-manager,cn=replication,cn=config"
objectclass: top
objectclass: person
userpassword:password
sn:new-replication-manager

    For example:


    $ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn:"cn=ReplicationManager3,cn=replication,cn=config"
objectclass: top
objectclass: person
userpassword:secret
sn:ReplicationManager3

  2. On all consumer (destination) replicated suffixes, set the replication manager bind DN.


    $ dsconf set-suffix-prop -h host -p port suffix-DN \
 repl-manager-bind-dn:"cn=new-replication-manager,cn=replication,cn=config"

    For example: 


    $ dsconf set-suffix-prop -h host1 -p 1389 dc=example,dc=com \
 repl-manager-bind-dn:"cn=ReplicationManager3,cn=replication,cn=config"

  3. For all replication agreements that you have created on all supplier (source) replicated suffixes, set the replication manager bind DN.

    1. Create a temporary file for setting the new replication manager password.

      This file is read once, and the password is stored for future use.


      $ echo password > password-file

    2. Set the replication manager bind DN and password to be used by the replication mechanism when performing updates.


      $ dsconf set-repl-agmt-prop -h host -p port suffix-DN host:port \
 auth-bind-dn:"cn=new-replication-manager,cn=replication,cn=config" \
 auth-pwd-file:password-file

      For example:


      $ dsconf set-repl-agmt-prop -h host2 -p 1389 dc=example,dc=com host1:1389 \
 auth-bind-dn:"cn=ReplicationManager3,cn=replication,cn=config" \
 auth-pwd-file:pwd.txt

    3. Remove the temporary password file.


      $ rm password-file

ProcedureTo Change the Default Replication Manager Password

  1. Create a temporary file for setting the replication manager password.

    This file is read once, and the password is stored for future use.


    $ echo password > password-file

  2. On all consumer (destination) servers in the replication topology, set the replication manager bind password.


    $ dsconf set-server-prop -h host -p port def-repl-manager-pwd-file:password-file

    For example:


    $ dsconf set-server-prop -h host1 -p 1389 def-repl-manager-pwd-file:pwd.txt

  3. Remove the temporary password file.


    $ rm password-file

Creating and Changing Replication Agreements

A replication agreement is a set of parameters on a supplier that configures and controls how updates are sent to a given consumer. The replication agreement must be created on the supplier replicated suffix that is sending updates to its consumer. You must create a replication agreement on the supplier for every consumer that you want updated.

ProcedureTo Create a Replication Agreement

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

If you use DSCC to create a new replication agreement, you can choose to copy some or all replication agreement configuration settings from an existing replication agreement.

  1. From your master server, create a replication agreement for each consumer that you want to replicate to.


    $ dsconf create-repl-agmt -h host -p port suffix-DN consumer-host:consumer-port [consumer-host:consumer-port]

    For example:


    $ dsconf create-repl-agmt -h host1 -p 1389 dc=example,dc=com host2:1389

    To list existing replication agreements by using the command line, use the dsconf list-repl-agmts command.

    Note –

    If you change the port number on a master when replication is running, you do not need to reinitialize the servers. However, the old replication agreement that pointed to the old address (host:old-port) is no longer useful. If you want replication to continue as it did before the port number was changed, you must create a new agreement with the new address (host:new-port).

  2. Check that the replication agreement has been created correctly.


    $ dsconf show-repl-agmt-status -h host -p port suffix-DN consumer-host:consumer-port

  3. If the authentication status is not OK, run the dsconf accord-repl-agmt command.

    Note –

    Only use the command dsconf accord-repl-agmt if you are using the default replication manager. If you have created a new replication manager, do not use this command because it overwrites some required settings.

    The dsconf accord-repl-agmt command ensures that both the supplier and destination servers share the same replication authentication settings. 


    $ dsconf accord-repl-agmt -h host -p port suffix-DN consumer-host:consumer-port

    For example:


    $ dsconf accord-repl-agmt -h host2 -p 1389 dc=example,dc=com host1:1389

ProcedureTo Change the Destination of a Replication Agreement

This procedure changes the remote replica pointed to by an existing replication agreement. The suffix DN and configuration of the existing agreement remain the same.

  1. Change the host name and port number of the remote replica in the replication agreement.


    $ dsconf change-repl-dest -h host -p port suffix-DN host:port new-host:new-port

    If this command is run with the -A protocol option, you can change the authentication protocol that is used by replication.

Fractional Replication

By default, the replication operation copies entire entries in the replicated suffix to consumer replicas. With the fractional replication feature, you can select the suffix that you want to use, and which attributes you want to include or exclude. Fractional replication is configured in the replication agreement, allowing you to define the attribute set for each consumer replicated suffix of a master. You can control which data is distributed and use replication bandwidth and consumer resources more efficiently.

For example, if you want to reduce replication bandwidth, you can choose not to replicate attributes with typically large values such as photo, jpegPhoto, and audio. As a result, these attributes will not be available on consumers. As another example, you can choose to replicate only the uid and userpassword attributes to a consumer server that is dedicated to performing authentication.

Considerations for Fractional Replication

Note –

Fractional replication cannot be used in versions of the product prior to Directory Server 5.2. When configuring a fractional replication agreement, both the master and consumer replicas must use at least Directory Server 5.2.

Enabling or modifying a fractional set of attributes requires you to reinitialize the consumer replica. Therefore, you need to determine your fractional replication needs before deployment and define your attribute set before you initialize your replicated suffixes for the first time.

You need to proceed with caution when replicating a small set of attributes, given the dependency of complex features such as ACIs, roles, and CoS on certain attributes. In addition, not replicating other attributes that are mentioned in specifiers or filters of the ACI, roles, or CoS mechanisms might compromise the security of the data. Not replicating might also result in different sets of attributes being returned in searches. Managing a list of attributes to exclude is safer, and less prone to human error, than managing a list of attributes to include.

You need to turn off schema checking in the consumer server if the attribute set that you replicate does not allow all replicated entries to follow the schema. Replication of non-conforming entries does not cause errors because the replication mechanism bypasses schema checking on the consumer. However, the consumer will contain non-conforming entries and should have schema checking turned off to expose a coherent state to its clients.

Fractional replication is configured in the replication agreement of master replicas with hubs and dedicated consumers. Configuration of fractional replication between two master replicas in a multimaster replication environment is not supported. Also, if several masters have replication agreements with the same replica, all these agreements must replicate the same set of attributes.

ProcedureTo Configure Fractional Replication

To configure fractional replication, you must specify the suffix, determine whether to include or exclude attributes on that suffix, then choose which attributes to include or exclude. If you choose to exclude attributes on a suffix, all other attributes are automatically included. Likewise, if you choose to include certain attributes on a suffix, all other attributes are automatically excluded.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Configure fractional replication on a replication agreement located on the source server. 


    $ dsconf set-repl-agmt-prop -h host -p port suffix-DN consumer-host:consumer-port property:value

    where property is either repl-fractional-exclude-attr or repl-fractional-include-attr.

    For example, if you want to configure a fractional agreement to exclude JPEG and TIFF photos from being replicated on the suffix dc=example,dc=com, use this command:


    $ dsconf set-repl-agmt-prop -h host2 -p 1389 dc=example,dc=com host1:1389 
 repl-fractional-exclude-attr:jpegPhoto repl-fractional-exclude-attr:tiffPhoto

    To add an attribute to an existing list of attributes that should be excluded, use this command:


    $ dsconf set-repl-agmt-prop -h host -p port suffix-DN consumer-host:consumer-port repl-fractional-exclude-attr+:attribute

Replication Priority

Specifying replication priority is optional. You can create replication rules to specify that certain changes, such as updating the user password, are replicated with high priority. Any changes specified in replication rules are replicated as high priority, and all other changes are replicated with normal priority.

Note –

Replication priority rules only need to be created on the master server. No configuration is required for hubs and consumers.

ProcedureTo Configure Replication Priority

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. To create a new replication priority rule on a master, use this command:


    $ dsconf create-repl-priority -h host -p port suffix-DN priority-name property:value

    You can set replication priority with one or more of the following properties:

    • Operation type , op-type

    • Bind DN, bind-dn

    • Base DN, base-dn

    • Attribute type, attr

    The priority-name is user defined.

    For example, to create a replication rule specifying that user password changes are replicated with high priority, use this command:


    $ dsconf create-repl-priority -h host2 -p 1389 dc=example,dc=com pw-rule \
 attr:userPassword

    To display current replication rules, use the dsconf list-repl-priorities -v command. When used with the -v option, this command displays additional information related to prioritized replication rules.


    $ dsconf list-repl-priorities -h host2 -p 1389 -v

    For more information, see the dsconf(1M) man page.

Initializing Replicas

After you have created a replication agreement and after both replicas have been configured, you must initialize the consumer replicated suffix before replication can begin. During initialization, you physically copy data from the supplier replicated suffix to the consumer replicated suffix.

In addition, certain error conditions or configuration changes require you to reinitialize replicas. For example, if the data in a single master replicated suffix is restored from a backup for any reason, you need to reinitialize all of the replicas that it updates.

When reinitializing, the contents of the replicated suffix are deleted on the consumer and replaced with the contents of the suffix on the master. This ensures that the replicas are synchronized and that replication updates can resume. All of the initialization methods described in this section automatically rebuild the indexes of the consumer replica so that the consumer is ready to respond optimally to client read requests.

With multimaster replication, consumers might not need to be reinitialized if they have been updated by the other masters in the topology.

ProcedureTo Initialize a Replicated Suffix from a Remote (Supplier) Server

You can initialize a suffix from a remote server by using an existing replication agreement. Use this method of initializing if possible, because it is less complicated than the other methods. Use the other methods only for large quantities of data that make the import too time consuming.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Online initialization of a replicated suffix by using DSCC is an easy way to initialize or reinitialize a consumer. However, if you are initializing a large number of entries, this process can be time consuming. In this case, you might find offline consumer initialization with the command line more efficient.

  1. Initialize your replica.


    $ dsconf init-repl-dest -h host -p port suffix-DN destination-host:destination-port [destination-host:destination-port]

    where destination-host:destination-port is the host and port of the destination server that you are initializing from the remote server.

  2. (Optional) For each agreement, check that the suffix appears as initialized.


    $ dsconf show-repl-agmt-status -h host -p port suffix-DN destination-host:destination-port

Replica Initialization From LDIF

ProcedureTo Initialize a Replicated Suffix From LDIF

This procedure outlines the general steps to use to initialize a replicated suffix from an LDIF file.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Online initialization of a replicated suffix by using DSCC is an easy way to initialize or reinitialize a consumer. However, if you are initializing a large number of entries, this process can be time consuming. In this case, you might find offline consumer initialization with the command line more efficient.

  1. Ensure that you have set up replication agreements.

    You must do this before you initialize replicas.

  2. Export the original copy of the suffix data from a master replicated suffix to an LDIF file.

    See To Export a Replicated Suffix to LDIF.

    In a multimaster replication environment, you can use the LDIF file exported from the original master to initialize both the other masters and any consumers. In a cascading replication environment, you can use the same file to initialize both the hub replicas and their consumers.

    In all cases, you must start with an LDIF file that has been exported from a configured master replica. You cannot use an arbitrary LDIF file to initialize all replicas because it does not contain replication meta-data.

  3. If you are initializing a fractional replica, filter the file to keep only the replicated attributes, then transfer that file to all of the consumer servers.

    See Filtering an LDIF File for Fractional Replication.

  4. Initialize your replica.

    Do one of the following:

    • For fast initialization on a server that is offline (stopped), use the dsadm import command.


      $ dsadm import instance-path LDIF_file suffix-DN

    • To initialize a replica online from an LDIF file, use the dsconf import command. 


      $ dsconf import -h host -p port LDIF_file suffix-DN

      Using dsconf import is slower than using dsadm import, but you do not need to stop your server while performing the import operation.

    For more detailed information about initializing suffixes, and for examples, see Initializing a Suffix. For detailed command usage, see dsadm(1M) and dsconf(1M).

  5. (Optional) For each agreement, check that the suffix appears as initialized.


    $ dsconf show-repl-agmt-status -h host -p port suffix-DN destination-host:destination-port

ProcedureTo Export a Replicated Suffix to LDIF

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Export the replicated suffix contents in an LDIF file by using one of the following commands:

    • For an offline export, type:


      $ dsadm export instance-path suffix-DN LDIF_file

    • For an online export, type:


      $ dsconf export -h host -p port suffix-DN LDIF_file

    The following example will export the entire dc=example,dc=com replicated suffix and replication information to the file example_replica_export.ldif:


    $ dsconf export -h host2 -p 1389 dc=example,dc=com  \
 /local/ds/ldif/example_export_replica.ldif

    For more information, see Backing Up to LDIF and the dsadm(1M) and dsconf(1M) man pages.

Filtering an LDIF File for Fractional Replication

Initializing a replica with fractional replication configured is transparent when using DSCC. Only the selected attributes will be sent to the consumer during the initialization.

If you have configured fractional replication, you should filter out any unused attributes before copying the exported LDIF file to the consumer servers. Directory Server provides the fildif tool for this purpose. This tool filters the given LDIF file to keep only the attributes that are allowed by the attribute set defined in your replication agreement.

This tool reads the server’s configuration to determine the attribute set definition. To read the configuration file, the fildif tool must be run as root or as the user who owns the process and the files (specified by the nsslapd-localuser attribute). For example, the following command filters the file exported from the dc=example,dc=com suffix in the previous example:


$ fildif -i /local/ds1/ldif/example_master.ldif \
 -o /local/ds1/ldif/filtered.ldif -b "cn=host2.example.com:1389, \
 cn=replica,cn=\\"dc=example,dc=com\\",cn=mapping tree,cn=config" -p /local/ds1

For the location of the fildif command, see Command Locations.

The -i and -o options are the input and output files, respectively. The -b option is the DN of the replication agreement where fractional replication is defined. You can find this DN by using this command:


$ ldapsearch -h host -p port -D cn=admin,cn=Administrators,cn=config -w - \
 -b "cn=config" "(&(objectclass=nsds5replicationagreement) (nsDS5ReplicaPort=replica-port) \
 (nsDS5ReplicaHost=replica-host))" dn

For example:


$ ldapsearch -h host2 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - \
 -b "cn=config" "(&(objectclass=nsds5replicationagreement) \
 (nsDS5ReplicaPort=2090)(nsDS5ReplicaHost=host2))" dn
Enter bind password:
version: 1
dn: cn=host2:1389,cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config

For the full command-line syntax for the fildif tool, see the fildif(1) man page.

You can then use the filtered.ldif file produced by fildif to initialize the consumer in this replication agreement. Transfer the file to the consumer server and import it as described in Importing Data From an LDIF File.

Initializing a Replicated Suffix by Using Binary Copy

A binary copy enables you to clone an entire server by using the binary backup files from one server to restore the identical directory contents onto another server. You can use a binary copy to initialize or reinitialize any server from the binary copy of a master or hub server, or a consumer from the binary copy of another consumer server.

Note –

This advanced procedure interacts with the database files of Directory Server and should only be used by experienced administrators.

Certain restrictions on this feature make it practical and time efficient only for replicas with very large database files, for example, replicas containing millions of entries.

Restrictions for Using Binary Copy With Replication

Because a binary copy moves database files from one machine to another, the mechanism is subject to the following strict limitations:

Making a Binary Copy for Initializing a Server

This section describes how to make a binary copy for initializing a server, and how to make a binary copy that uses minimum disk space.

ProcedureTo Make a Binary Copy For Initializing a Server

Use this procedure to perform a binary copy for initializing a replicated server because it uses the normal backup functionality to create a copy of the server’s database files. Performing a normal backup ensures that all database files are in a coherent state without requiring you to stop the server.

This procedure has certain limitations. The backup and restore operations create copies of the database files on the same machine, thereby doubling the amount of disk space required by those files on each machine. Additionally, the actual copy operation on these files might take a significant amount time if your directory contains gigabytes of data.

For parts of this procedure, you can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help. Other parts of the procedure can only be done using the command line.

  1. Install Directory Server on the target machine for the new replicated suffix, create a new instance of the server if necessary, and configure the server according to Restrictions for Using Binary Copy With Replication.

  2. Create all replication agreements in your replication topology that involve this replicated suffix.

    Include agreements from suppliers to this replica. If this replica is not a dedicated consumer, include agreements from this replica to its consumers. See Creating and Changing Replication Agreements.

  3. Select a fully configured and initialized replica of the same type as you want to initialize, either master, hub, or consumer, and perform a normal backup on it according to Binary Backup.

  4. Copy or transfer the files from the backup directory to a directory on the target machine by using the ftp command, for example.

  5. If you have initialized a new master in a multimaster replication scenario, follow the procedures in Restoring a Master in a Multi-Master Scenario.

ProcedureTo Use Binary Copy for Initializing a Server Using Minimum Disk Space

This procedure uses less disk space and takes less time because it does not make backup copies of the database files. However, it requires you to stop the server that is being cloned to order to ensure that the database files are in a coherent state.

Caution – Caution –

This procedure must not be used to reinitialize a master that has already participated in a multimaster replication scenario. It can only be used to reinitialize a consumer server or to initialize a new master server. To reinitialize an existing master replica, use online initialization, import an LDIF file, or follow the procedure in Making a Binary Copy for Initializing a Server.

For parts of this procedure, you can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help. Other parts of the procedure can only be done using the command line.

  1. Install Directory Server on the target machine for the new replicated suffix, create a new instance of the server if necessary, and configure the server according to Restrictions for Using Binary Copy With Replication.

  2. Create all replication agreements in your replication topology that involve this replica.

    Include agreements from suppliers to this replica. If this replica is not a dedicated consumer, include agreements from this replica to its consumers. See Creating and Changing Replication Agreements.

  3. Stop the target server that will be initialized or reinitialized, as described in Starting, Stopping, and Restarting a Directory Server Instance .

  4. Select a fully configured and initialized replica of the same type that you want to initialize, either master, hub, or consumer, and stop this server as well.

    If you are cloning a master replica in a multimaster configuration, ensure that it is fully up-to-date with all of the latest changes from the other masters before stopping it.

  5. Remove all database files from the target server, including transaction logs, change logs, and region files (__db.xxx files).

    Unless the files have been relocated, database files and transaction logs are located in the instance-path/db directory.

  6. Copy or transfer all database files, including transaction logs and change logs, from the source replica machine to the target machine, by using the ftp command, for example.

    Unless the files have been relocated, database files and transaction logs are located in the instance-path/db directory.

    If you are initializing a master or hub replica, you must also copy all files in the change log, which is located in instance-path/changelog by default.

  7. Restart both the source and the target servers.

Initializing Replicas in Cascading Replication

In the case of cascading replication, always initialize replicas in the order shown in the following procedure.

ProcedureTo Initialize Replicas in Cascading Replication

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. If you also have multimaster replication, ensure that one master has the complete set of data to replicate, then use this master to initialize the replica on each of the other masters.

  2. Initialize the replicas on the first-level hub replicas from their master replicas.

  3. If you have several levels of hubs, initialize each level from the previously initialized level of hubs.

  4. From the last level of hub replicas, initialize the replicas on the dedicated consumers.

Indexing Replicated Suffixes

Indexes are not replicated automatically from one server instance to another. To index an attribute for all server instances holding a replicated suffix, perform one of the following actions.

Incrementally Adding Many Entries to Large Replicated Suffixes

If you have a directory with a very large number of entries and you want to add a large quantity of entries, do not use ldapmodify -a because it is too time consuming. Instead, add the new entries incrementally by using the dsconf import command with an option for adding entries in a replicated topology. When you import the entries, an LDIF file is generated that contains the additions as well as replication meta-data. You then import this generated LDIF file to the other replicas. The generated LDIF file ensures that replication synchronization is constant across the replicas to which you add data.

ProcedureTo Add Many Entries to Large Replicated Suffixes

Before You Begin

This procedure generates a large LDIF file. Before running the first dsconf import command, ensure that you have enough disk space available for the generated LDIF file.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

Caution – Caution –

This procedure can be used to initialize a server with a large number of entries in several passes. However, if one of the imports fails, the whole database can be lost. Be sure to backup data prior to each import.

  1. On any master replica, import the entries.


    $ dsconf import -h host -p port -K generated-LDIF-file suffix-DN

    The -K option ensures that existing data is not removed. It also generates a file generated-LDIF-file, that contains the new entries and information required by the replication process.

  2. On all other replicas, import the file generated in the previous step.


    $ dsconf import -h host -p port \
-K -f incremental-output=no generated-LDIF-file suffix-DN

    The option -f incremental-output=no specifies that an additional LDIF file will not be generated. Only one generated LDIF file is needed for this procedure.

Replication and Referential Integrity

If you are using the referential integrity plug-in with replication, you must enable it on all master servers. You do not need to enable it on hub or consumer servers.

The following limitations are associated with the use of the referential integrity plug-in in a replication environment:

For information about configuring the referential integrity plug-in, see To Configure the Referential Integrity Plug-In.

Replication Over SSL

You can configure Directory Servers involved in replication so that all replication operations occur over an SSL connection.

ProcedureTo Configure Replication Operations for SSL

This procedure shows example commands for setting up replication on a replication topology with two masters.

Note –

This example shows a simple replication configuration, using a self-signed certificate. When setting up replication over SSL in a production environment, you will have better security if you use Certificate Authority trusted certificates instead.

Replication over SSL will fail if the supplier server certificate is an SSL server-only certificate that cannot act as a client during an SSL handshake.

While replication is secure by SSL, authentication of the replication manager is still done using a simple bind and password. You can use client-based authentication to fully secure replication, but this requires more complex settings.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Create new servers and start them.


    $ dsadm create -p 1389 -P 1636 /local/ds1
$ dsadm create -p 2389 -P 2636 /local/ds2

$ dsadm start /local/ds1
$ dsadm start /local/ds2

  2. On all servers, create empty suffixes.


    $ dsconf create-suffix -e -i -p 1389 dc=example,dc=com
$ dsconf create-suffix -e -i -p 2389 dc=example,dc=com

  3. On all servers, set the multimaster password file.


    $ dsconf set-server-prop -e -i -h example1.server -p 1389 \
 def-repl-manager-pwd-file:/local/ds1/replmanrpwd1.txt
$ dsconf set-server-prop -e -i -h example2.server -p 2389 \
 def-repl-manager-pwd-file:/local/ds1/replmanrpwd2.txt

  4. On all servers, enable replication.


    $ dsconf enable-repl -h example1.server -p 1389 -e -i -d 1 master dc=example,dc=com
$ dsconf enable-repl -h example2.server -p 2389 -e -i -d 2 master dc=example,dc=com

  5. On all servers, view the existing default certificate.


    $ dsadm show-cert -F der -o certfile1 /local/ds1 defaultCert
$ dsadm show-cert -F der -o certfile2 /local/ds2 defaultCert

  6. On all servers, add the CA trusted certificate from all other servers.


    $ dsadm add-cert --ca /local/ds1 "ds2 Repl Manager Cert" certfile2
$ dsadm add-cert --ca /local/ds2 "ds1 Repl Manager Cert" certfile1

  7. On all master and hub (source) servers, create replication agreements with all consumer (destination) servers.

    Note that secure LDAP ports are used for the replication agreements. 


    $ dsconf create-repl-agmt -h example1.server -p 1389 -e -i \
 --auth-protocol "ssl-simple" dc=example,dc=com example2.server:2636
$ dsconf create-repl-agmt -h example2.server -p 2389 -e -i \
 --auth-protocol "ssl-simple" dc=example,dc=com example1.server:1636

  8. For all replication agreements, configure the authentication password file to be the replication manager password file of the consumer (destination) server in the replication agreement.


    $ dsconf set-repl-agmt-prop -h example1.server -p 1389 -e -i \
 dc=example,dc=com example2.server:2636 auth-pwd-file:/local/ds1/replmanrpwd2.txt
$ dsconf set-repl-agmt-prop -h example2.server -p 2389 -e -i \
 dc=example,dc=com example1.server:1636 auth-pwd-file:/local/ds1/replmanrpwd1.txt

    After you have initialized the suffixes, the supplier will send all replication update messages to the consumer over SSL and will use certificates if you chose that option. Customer initialization will also use a secure connection if performed through DSCC using an agreement configure for SSL.

  9. On all servers, restart the server in order to take configuration changes into account.


    $ dsadm restart /local/ds1
$ dsadm restart /local/ds2

  10. On one of the master servers, initialize the suffix.


    $ dsconf import -h example1.server -p 1389 -e -i /tmp/Example.ldif dc=example,dc=com

  11. On all servers not yet initialized, initialize the servers by using a replication agreement.


    $ dsconf init-repl-dest -e -i -h example1.server -p 1389 \
 dc=example,dc=com example1.server:2636

Replication Over a WAN

Directory Server enables you to perform all forms of replication including multimaster replication between machines connected through a wide area network (WAN). This replication allows supplier servers to initialize and update consumers by making optimal use of the bandwidth over networks with higher latency and lower bandwidth.

Note –

When deploying or troubleshooting a replication topology that replicates over a WAN, you must check network speed, latency, and packet loss. Network problems in any of these areas might cause replication delay.

In addition, replication data transfer rates will always be less than what the available physical medium allows in terms of bandwidth. If the update volume between replicas cannot physically be made to fit into the available bandwidth, tuning will not prevent your replicas from diverging under heavy update load. Replication delay and update performance are dependent on many factors, including but not limited to: modification rate, entry size, server hardware, error rates, average latency, and average bandwidth.

If you have questions about replication in your environment, contact your Sun Service Provider.

Internal parameters of the replication mechanism are optimized by default for WANs. However, if you experience slow replication due to the factors mentioned previously, you might want to empirically adjust the window size and group size parameters. You might also be able to schedule your replication to avoid peak network times, thus improving your overall network usage. Finally, Directory Server supports the compression of replication data to optimize bandwidth usage.

Configuring Network Parameters

The window and group network parameters determine how the replication mechanism groups entries to send them more efficiently over the network. These parameters affect how suppliers and consumers exchange replication update messages and acknowledgments. The parameters are configurable in every replication agreement, which allows you to tailor the replication performance according to the specific network conditions of each consumer.

Monitor the effects of any modifications that you make and adjust the parameters accordingly. Refer to Getting Replication Status for instructions. You do not need to interrupt replication to modify the window size and group size parameters.

Configuring Window Size

The window size (default value 10) represents the maximum number of update messages that can be sent without immediate acknowledgment from the consumer.

It is more efficient to send many messages in quick succession instead of waiting for an acknowledgment after each message. Using the appropriate window size, you can eliminate the time replicas spend waiting for replication updates or acknowledgments to arrive.

If your consumer replica is lagging behind the supplier, increase the window size to a higher value than the default, such as 100, and check replication performance again before making further adjustments. When the replication update rate is high and the time between updates is therefore small, even replicas connected by a local area network (LAN) can benefit from a higher window size.

ProcedureTo Configure Window Size

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Modify the window size.


    $ dsconf set-repl-agmt-prop -h host -p port suffix-DN consumer-host:consumer-port transport-window-size:value

    For example: 


    $ dsconf set-repl-agmt-prop -h host2 -p 1389 dc=example,dc=com host1:1389 \
 transport-window-size:20

Configuring Group Size

The group size (default value 1) represents the maximum number of data modifications that can be bundled into a single update message. If the network connection appears to be impeding replication, increase the group size to a higher value than the default, such as 10, and recheck replication performance.

When increasing the group size, make sure that the following are true:

ProcedureTo Configure Group Size

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Modify the group size.


    $ dsconf set-repl-agmt-prop -h host -p port suffix-DN \
 consumer-host:consumer-port transport-group-size:value

    For example: 


    $ dsconf set-repl-agmt-prop -h host2 -p 1389 dc=example,dc=com host1:1389 \
 transport-group-size:10

Scheduling Replication Activity

If immediate synchronization between your replicas is not critical, you can schedule replication during periods of low network usage. Replication of data should complete significantly faster when the network is more available.

You can schedule replication to start and end at a certain time of day, on a daily or weekly basis. You can do this independently for every consumer through its replication agreement. The new schedule will take effect immediately, causing the next replication of data for the corresponding consumer to be delayed until first allowed by the schedule.

ProcedureTo Schedule Replication Activity

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Modify the replication schedule.


    $ dsconf set-repl-agmt-prop -h host -p port suffix-DN \
 host:port repl-schedule:value

    For example, if you want to set replication to occur between 2:00 and 4:00 every night, type:


    $ dsconf set-repl-agmt-prop -h host2 -p 1389 dc=example,dc=com host1:1389 \
 repl-schedule:"0200-0400 0123456"

    where 0123456 indicate the days of the week, with 0 representing Sunday, 1 representing Monday, and so on.

Configuring Replication Compression

To reduce the bandwidth used by replication, you may configure replication to compress the data that is sent when updating consumers. The replication mechanism uses the Zlib compression library. Both supplier and consumer must be running on a Solaris or Linux platform to enable compression.

You should empirically test and select the compression level that gives you best results for your expected replication usage in your WAN environment. Do not set this parameter in a LAN where there is wide network bandwidth because the compression and decompression computations will slow down replication.

ProcedureTo Configure Replication Compression

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Configure replication compression on the replication agreement entry in the master server.


    $ dsconf set-repl-agmt-prop -h host -p port suffix-DN \
 consumer-host:consumer-port transport-compression:level

    where level can be high, medium, low, or none.

    For example, to use the fastest compression when sending replication updates to the consumer on host1:1389, type:


    $ dsconf set-repl-agmt-prop -h host2 -p 1389 dc=example,dc=com host1:1389 \
 transport-compression:high

    For more information about setting the compression level, see Sun Java System Directory Server Enterprise Edition 6.2 Reference.

Modifying the Replication Topology

This section explains these aspects of managing an existing replication topology:

Changing the Replication Manager

You can edit a replication agreement to change the replication manager identity that is used to bind to the consumer server. To avoid any interruption of the replication, you should define the new replication manager entry or certificate entry on the consumer before modifying the replication agreement. However, if replication is interrupted due to a bind failure, the replication mechanism will automatically send all the necessary updates when you correct the error, within the limits of the replication recovery settings. For the procedure, see Using a Non-Default Replication Manager.

Managing Replication Agreements

You can disable, enable, or delete a replication agreement.

Disabling a Replication Agreement

When a replication agreement is disabled, the master stops sending updates to the designated consumer. Replication to that server is stopped, but all settings in the agreement are preserved. You may resume replication by re-enabling the agreement at a later time. See Enabling a Replication Agreement for information about resuming the replication mechanism after an interruption.

ProcedureTo Disable a Replication Agreement

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Disable a replication agreement.


    $ dsconf disable-repl-agmt -h host -p port suffix-DN consumer-host:consumer-port

    For example: 


    $ dsconf disable-repl-agmt -h host2 -p 1389 dc=example,dc=com host1:1389

Enabling a Replication Agreement

Enabling a replication agreement resumes replication with the designated consumer. However, if replication has been interrupted longer than the replication recovery settings allow and the consumer was not updated by another supplier, you must reinitialize the consumer. The replication recovery settings are the maximum size and age of this supplier’s change log and the purge delay of the consumer (see To Perform Advanced Consumer Configuration).

When the interruption is short and replication can recover, the master will update the consumer automatically when the agreement is re-enabled.

ProcedureTo Enable a Replication Agreement

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Enable a replication agreement.


    $ dsconf -h host -p port enable-repl-agmt suffix-DN consumer-host:consumer-port

    For example: 


    $ dsconf -h host2 -p 1389 enable-repl-agmt dc=example,dc=com host1:1389

Deleting a Replication Agreement

Deleting a replication agreement stops the replication to the corresponding consumer and removes all configuration information about the agreement. If you want to resume replication at a later date, disable the agreement instead, as described in Disabling a Replication Agreement.

ProcedureTo Delete a Replication Agreement

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Delete a replication agreement.


    $ dsconf delete-repl-agmt -h host -p port suffix-DN consumer-host:consumer-port

    For example: 


    $ dsconf delete-repl-agmt -h host2 -p 1389 dc=example,dc=com host1:1389

Promoting or Demoting Replicas

Promoting or demoting a replica changes its role in the replication topology. Dedicated consumers can be promoted to hubs, and hubs can be promoted to masters. Masters can be demoted to hubs, and hubs can also be demoted to dedicated consumers. However, masters cannot be demoted directly to consumers, just as consumers cannot be promoted directly to masters.

The allowed promotions and demotions within the multimaster replication mechanism make the topology very flexible. A site that was formerly served by a consumer replica might grow and require a hub with several replicas to handle the load. If the load includes many modifications to the replica contents, the hub can become a master to allow faster local changes that can then be replicated to other masters at other sites.

When promoting or demoting replicas, be aware of the following:

ProcedureTo Promote or Demote a Replica

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Promote or demote a replica by using one of the commands:


    $ dsconf promote-repl -h host -p port role suffix-DN


    $ dsconf demote-repl -h host -p port role suffix-DN

    where role is master, hub or consumer.

Disabling a Replicated Suffix

Disabling a replicated suffix removes it from the replication topology. It will no longer be updated or send updates, depending on its role as a master, hub, or consumer. Disabling a suffix on a supplier server deletes all replication agreements, and they will have to be re-created if the replica is enabled again.

ProcedureTo Disable a Replicated Suffix

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Disable a replicated suffix.


    $ dsconf disable-repl -h host -p port suffix-DN

    For example: 


    $ dsconf disable-repl -h host2 -p 1389 dc=example,dc=com

Keeping Replicated Suffixes Synchronized

After you stop a Directory Server involved in replication for regular maintenance, when it comes back online, you need to ensure that it gets updated through replication immediately. In the case of a master in a multimaster environment, the directory information needs to be updated by another master in the multimaster set. In other cases, after a hub server or a dedicated consumer server is taken offline for maintenance, when they come back online, they need to be updated by the master server.

This section describes the replication retry algorithm and explains how to force replication updates to occur without waiting for the next retry.

Note –

The procedures described in this section can be used only when replication is already set up and consumers have been initialized.

Replication Retry Algorithm

When a source replica is unsuccessful in replicating to a destination, it retries periodically in incremental time intervals. The retry intervals depend on the error type.

Note that even if you have configured replication agreements to always keep the source replica and the destination replica synchronized, this is not sufficient to immediately update a replica that has been offline for over five minutes.

ProcedureTo Force Replication Updates

If replication has stopped, you can force replication updates to the destination suffixes.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. On the source server, restart replication updates to the destination server.


    $ dsconf update-repl-dest-now -h host -p port suffix-DN destination-host:destination-port

    For example:


    $ dsconf update-repl-dest-now -h host2 -p 1389 dc=example,dc=com host1:1389

Moving a Master Replica to a New Machine

In some situations, it might be necessary to move a master replica to a different machine. If you do not need to use the same host name and port number, use dsconf change-repl-dest to change the host name and port number of the remote replica. For more information, see To Change the Destination of a Replication Agreement.

If you need to retain the same host name and port number, you must remove the master from the existing topology, and then re-add the master to the topology.

It is much easier to use DSCC to perform these tasks, because DSCC takes care of any impacted replication agreements. If you use DSCC, however, you cannot specify the same replica ID that the master originally had in the topology. To use the same replica ID, you must use the command line to perform these tasks, as follows.

ProcedureTo Remove a Master From an Existing Replication Topology

Before You Begin

Make sure that all changes from the master have already been replicated.

  1. If you can, back up the master using binary copy so that you do not lose any changes.

  2. Demote the master replica to a hub replica.

    See Promoting or Demoting Replicas.

  3. Wait for the hub to start replicating to other servers.

    When the hub opens a replication session to the other servers in the topology, it remains in the RUV but is no longer used in referrals.

  4. Stop the hub.

    See Starting, Stopping, and Restarting a Directory Server Instance.

  5. Remove the hub from the topology.

    See Disabling a Replicated Suffix.

ProcedureTo Add a Master to an Existing Replication Topology

  1. Add the master replica, using the same replica ID.

    See Enabling Replication on a Master Replica.

  2. Recreate the replication agreements from that master to the other replicas in the topology.

  3. Initialize the new master.

    1. If you were able to back up the master, initialize the master from this backup.

    2. If you were not able to back up the master (in the event of a machine crash), initialize the master from another master in the topology.

Replication With Releases Prior to Directory Server 6.2

This section provides information about how to configure replication with releases of Directory Server prior to 6.2.

Replicating Between Directory Server 6.2 and Directory Server 5.1 or 5.2

Directory Server 5.1, 5.2 and 6.2 are compatible with regard to replication configuration, with the following exceptions:

Using the Retro Change Log

The retro change log is used by LDAP clients to ascertain the history of changes made to the Directory Server data. The retro change log is stored in a separate database to the Directory Server change log, under the suffix cn=changelog.

A retro change log can be enabled on a standalone server or on each server in a replication topology. When the retro change log is enabled on a server, by default updates to all suffixes on that server are logged. The retro change log can be configured to log updates to specified suffixes only.

For information about using the retro change log in a replicated topology and about restrictions on using the retro change log, see Replication and the Retro Change Log Plug-In in Sun Java System Directory Server Enterprise Edition 6.2 Reference.

For information about the attributes of an entry in the retro change log, see the changeLogEntry(5dsoc) man page.

For more information about modifying the retro change log, see the dsconf(1M) man page.

This section explains various ways that you can use the retro change log.

ProcedureTo Enable the Retro Change Log

To use the retro change log, you must enable it.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Modify the retro change log configuration entry:


    $ dsconf set-server-prop -h host -p port retro-cl-enabled:on

  2. Restart the server.

    For information, see Starting, Stopping, and Restarting a Directory Server Instance.

ProcedureTo Configure the Retro Change Log to Record Updates for Specified Suffixes

When the retro change log is enabled on a server, by default it records updates to all suffixes on the server. This procedure describes how to configure the retro change log to record updates to specified suffixes only.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Modify the retro change log configuration entry:


    $ dsconf set-server-prop -h host -p port retro-cl-suffix-dn:suffix-DN

    For example, to log changes only on the cn=Contractors,dc=example,dc=com suffix and the ou=People,dc=example,dc=com suffix, use this command:


    $ dsconf set-server-prop -h host2 -p 1389 \
 retro-cl-suffix-dn:"cn=Contractors,dc=example,dc=com" \
 retro-cl-suffix-dn:"ou=People,dc=example,dc=com"

    To add a suffix to an existing list of specified suffixes, use this command:


    $ dsconf set-server-prop -h host -p port retro-cl-suffix-dn+:suffix-DN

  2. Restart the server.

    For information, see Starting, Stopping, and Restarting a Directory Server Instance.

ProcedureTo Configure the Retro Change Log to Record Attributes of a Deleted Entry

This procedure describes how to configure the retro change log to record specified attributes of an entry when that entry is deleted.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Specify the attributes that must be recorded:


    $ dsconf set-server-prop -h host -p port retro-cl-deleted-entry-attr: \
 attribute1 attribute2

    For example, to set the retro change log to record the UID attributes of deleted entries, use this command:


    $ dsconf set-server-prop -h host -p port retro-cl-deleted-entry-attr:uid

    To add an attribute to an existing list of specified attributes, use this command:


    $ dsconf set-server-prop -h host -p port retro-cl-deleted-entry-attr+:attribute

  2. Restart the server.

    For information, see Starting, Stopping, and Restarting a Directory Server Instance.

ProcedureTo Trim the Retro Change Log

The entries in the retro change log can be removed automatically after a specified period of time. To configure the period of time after which entries are deleted automatically, make sure that the retro change log is enabled, then set the nsslapd-changelogmaxage configuration attribute in the cn=Retro Changelog Plugin, cn=plugins, cn=config entry.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Check that the retro change log is enabled.


    $ dsconf get-server-prop -h host -p port retro-cl-enabled

  2. If the retro change log is not enabled, enable it.


    $ dsconf set-server-prop -h host -p port retro-cl-enabled:on

  3. Set the maximum age for changes logged.


    $ dsconf set-server-prop -h host -p port retro-cl-max-age:duration

    where duration can be either undefined (no age limit) or one of the following:

    • s for seconds

    • m for minutes

    • h for hours

    • d for days

    • w for weeks

    For example, to set the retro change log maximum age to two days, type:


    $ dsconf set-server-prop -h host 2 -p 1389 retro-cl-max-age:2d

    The retro change log will be trimmed at the next operation on the change log.

Accessing Control and the Retro Change Log

The retro change log supports search operations. It is optimized for searches that include filters of this form:


(&(changeNumber>=X)(changeNumber<=Y))

As a general rule, do not perform add or modify operations on the retro change log entries. You can delete entries to trim the size of the log. The only time that you need to perform a modify operation on the retro change log is to modify the default access control policy.

When the retro change log is created, by default, the following access control rules apply:

To modify the default access control policy that applies to the retro change log, modify the aci attribute of the cn=changelog entry. Refer to Chapter 6, Directory Server Access Control.

Getting Replication Status

You can get replication status by using DSCC or by using command-line tools.

Getting Replication Status in DSCC

You can graphically view replication, including replication agreements and replication delay, by using the Suffix tab. For more information, see the DSCC online help.

In addition, you can use DSCC to view your replication topology, as shown in following figure.

Figure 10–1 Sample Replication Topology

Sample replication topology in DSCC.

Getting Replication Status by Using the Command Line

If you are unable to use DSCC, use command-line tools to obtain information about your replication deployment.

The man pages provide full command-line syntax and usage examples for these tools.

To find the directories where these commands are located, see Command Locations.

Solving Common Replication Conflicts

Multimaster replication uses a loose consistency replication model. This means that the same entries may be modified simultaneously on different servers. When updates are sent between the two servers, any conflicting changes must be resolved. Most resolution occurs automatically. For example, the timestamp associated with the change on each server is resolved by the most recent change taking precedence. However, some change conflicts require manual intervention to reach a resolution.

This section covers the following topics:

Solving Replication Conflicts by Using DSCC

The easiest way to resolve a replication conflict is by using DSCC. See the DSCC online help for information.

Solving Replication Conflicts by Using the Command Line

You can solve replication conflicts by using the command line. Entries that have a change conflict that cannot be resolved automatically by the replication process contain the operational attribute nsds5ReplConflict as a conflict marker.

To find entries with conflicts, periodically search for entries that contain this attribute. For example, you could use the following ldapsearch command to find entries with conflicts:


$ ldapsearch -h host2 -p 1389 -D cn=admin,cn=Administrators,cn=config \
 -w - -b "dc=example,dc=com" "(nsds5ReplConflict=*)"

Note that the nsds5ReplConflict attribute is indexed by default.

Solving Naming Conflicts

Entries with identical DNs may be created on separate masters if they are created before the servers replicate the changes to each other. Upon replication, the conflict resolution mechanism will automatically rename the second entry created.

An entry with a DN naming conflict is renamed by including its unique identifier, provided by the operational attribute nsuniqueid, in its DN.

For example, if the entry uid=bjensen,ou=People,dc=example,dc=com is created simultaneously on two masters, both will have the following two entries after replication:

The second entry must be given a useful DN. You can delete the conflicting entry and add it again with a non-conflicting name. However, renaming the entry ensures that its contents have not changed. The renaming procedure depends on whether the naming attribute is single-valued or multivalued. See the following procedures.

ProcedureTo Rename a Conflicting Entry That has a Multivalued Naming Attribute

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Rename the entry while keeping the old RDN value, for example:


    $ ldapmodify -h host2 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: nsuniqueid=66446001-1dd211b2-66225011-2ee211db+uid=bjensen,dc=example,dc=com
changetype: modrdn
newrdn: uid=bj66446001
deleteoldrdn: 0
^D

    You cannot delete the old RDN value in this step because it also contains the nsuniqueid operational attribute, which cannot be deleted.

  2. Remove the old RDN value of the naming attribute and the conflict marker attribute, for example:


    $ ldapmodify -h host2 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: uid=bj66446001,dc=example,dc=com
changetype: modify
delete: uid
uid: bjensen
-
delete: nsds5ReplConflict
^D

ProcedureTo Rename a Conflicting Entry With a Single-Valued Naming Attribute

When the naming attribute in a duplicate entry is single-valued, for example dc (domain component), you cannot simply rename the entry to another value of the same attribute. Instead, you must give the entry a temporary name.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Rename the entry by using a different naming attribute, and keep the old RDN, for example:


    $ ldapmodify -h host2 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: nsuniqueid=66446001-1dd211b2-66225011-2ee211db+dc=HR,dc=example,dc=com
changetype: modrdn
newrdn: o=TempHREntry
deleteoldrdn: 0
^D

    You cannot delete the old RDN value in this step because it also contains the nsuniqueid operational attribute, which cannot be deleted.

  2. Change the desired naming attribute to a unique value and remove the conflict marker attribute, for example:


    $ ldapmodify -h host2 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: o=TempHREntry,dc=example,dc=com
changetype: modify
replace: dc
dc: NewHR
delete: nsds5ReplConflict
^D

  3. Rename the entry back to the intended naming attribute, for example:


    $ ldapmodify -h host2 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: dc=NewHR,dc=example,dc=com
changetype: modrdn
newrdn: dc=HR
deleteoldrdn: 1
^D

    By setting the value of the deleteoldrdn attribute to 1, you delete the temporary attribute-value pair o=TempHREntry. If you want to keep this attribute, set the value of the deleteoldrdn attribute to 0.

Solving Orphan Entry Conflicts

When a delete operation is replicated, and the consumer server finds that the entry to be deleted has child entries, the conflict resolution procedure creates a glue entry to avoid having orphaned entries in the directory.

In the same way, when an add operation is replicated, and the consumer server cannot find the parent entry, the conflict resolution procedure creates a glue entry representing the parent so that the new entry is not an orphan entry.

Glue entries are temporary entries that include the object classes glue and extensibleObject. Glue entries can be created in various ways:

Solving Potential Interoperability Problems

For interoperability with applications that rely on attribute uniqueness, such as a mail server, you might need to restrict access to the entries that contain the nsds5ReplConflict attribute. If you do not restrict access to these entries, the applications that require only one attribute will pick up both the original entry and the conflict resolution entry that contains the nsds5ReplConflict and operations will fail.

To restrict access, you need to modify the default ACI that grants anonymous read access using the following command:


$ ldapmodify -h host2 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: dc=example,dc=com
changetype: modify
delete: aci
aci: (target ="ldap:///dc=example,dc=com")
 (targetattr !="userPassword"
 (version 3.0;acl "Anonymous read-search  access";
 allow (read, search, compare)(userdn = "ldap:///anyone");)
-
add: aci
aci: (target="ldap:///dc=example,dc=com")
 (targetattr!="userPassword")
 (targetfilter="(!(nsds5ReplConflict=*))")(version 3.0;acl
 "Anonymous read-search access";allow (read, search, compare)
 (userdn="ldap:///anyone");)
^D

The new ACI will keep entries that contain the nsds5ReplConflict attribute from being returned in search results.

Chapter 11 Directory Server Schema

Directory Server comes with a standard schema that includes hundreds of object classes and attributes. While the standard object classes and attributes should meet most of your requirements, you might need to extend the schema by creating new object classes and attributes. For an overview of the standard schema and for instructions on designing schema to suit your deployment, see the Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide.

This chapter describes how to manage your schema and covers the following topics:

Managing Schema Checking

When schema checking is on, Directory Server ensures that all import, add, and modify operations conform to the currently defined directory schema.

Note –

When modifying an entry, Directory Server performs schema checking on the entire entry, not just on the attributes that are being modified. Therefore, the operation might fail if any object class or attribute in the entry does not conform to the schema.

However, schema checking does not verify the validity of attribute values with regard to their syntax.

Schema checking is turned on by default. In general, run Directory Server with schema checking turned on. Many client applications assume that having schema checking turned on is an indication that all entries conform to the schema. However, turning on schema checking does not cause Directory Server to verify the existing contents in the directory. The only way to guarantee that all directory contents conform to the schema is to turn on schema checking before adding any entries or reinitializing all entries.

One case where you might want to turn schema checking off is to accelerate import operations of LDIF files known to conform to the schema. However, there is a risk of importing entries that do not conform to the schema. If schema checking is off, imported entries that do not confirm to the schema are not detected.

See Replicating Directory Schema for details on using schema checking in replicated environments.

ProcedureTo Fix Schema Compliance Problems

When an entry does not conform to the schema, it might not be possible to search for this entry, and modification operations on the entry might fail. Follow the steps in this procedure to correct the problem.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Before You Begin

To avoid having to fix schema compliance issues, plan your schema ahead of your deployment to minimize schema changes. For more information, see the Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide.

  1. To determine why the entry does not comply, retrieve the entry and manually compare it with the currently defined schema.

    See To View Attribute Types and To View an Object Class for details.

  2. Modify the entry so that it complies with the schema, or modify the schema so that it complies with the entry.

About Custom Schema

You can extend the standard schema if it is too limited for your directory needs. Follow these guidelines when customizing schema:

When customizing the schema, do not modify, delete, or replace any existing definitions of attributes or object classes in the standard schema. Doing so can lead to compatibility problems with other directories and with LDAP client applications.

Do not modify any Directory Server internal operational attributes. You can, however, create your own operational variables for external applications.

Always define object classes instead of using objectClass: extensibleObject. Directory Server does not perform schema checking for entries that have the object class extensibleObject, so it does not constrain or check what attributes are present on the entry. Typos in applications, for example, giveName for the givenName attribute type, go unnoticed by Directory Server. Also, Directory Server must assume that all otherwise undefined attributes of extensibleObject entries are multivalued and have case-insensitive string syntax. Furthermore, some applications rely on entries having a particular object class. In general, if you have an application that requires an extension to an object class, do not relinquish schema management. Instead, create an auxiliary object class that contains the attributes that are required for the application.

This section contains information about the default directory schema, and about creating customized attributes and object classes.

Default Directory Server Schema

The schema provided with Directory Server is described in a set of files that are stored in the instance-path/config/schema/directory.

This directory contains all of the common schema for Directory Server and related products. The LDAP v3 standard user and organization schema is located in the 00core.ldif file. The configuration schema used by earlier versions of the directory is located in the 50ns-directory.ldif file.

Note –

Do not modify files in this directory while the server is running.

Object Identifiers

Each LDAP object class or attribute must be assigned a unique name and object identifier (OID). When you define a schema, you need an OID that is unique to your organization. One OID is enough to meet all of your schema needs. You then add new branches on that OID for your attributes and object classes.

Obtaining and assigning OIDs in your schema involves doing the following:

Naming Attributes and Object Classes

When creating names for new attributes and object classes, make the name meaningful so your schema is easier to use.

Avoid naming collisions between custom schema elements and existing schema elements by including a unique prefix on custom elements. For example, Example.com Corporation might add the prefix Example before each of its custom schema elements. It might also add a special object class called ExamplePerson to identify Example.com employees in its directory.

Note that in LDAP, attribute type names and object class names are case insensitive. Applications should treat them as case insensitive strings.

When Defining New Object Classes

Add new object classes when the existing object classes do not support all of the information you need to store in a directory entry.

There are two approaches to creating new object classes:

Consider the following when deciding how to implement new object classes.

When Defining New Attributes

Add new attributes when the existing attributes do not support all of the information you need to store in a directory entry. Try to use standard attributes whenever possible. Search the attributes that already exist in the default directory schema and use those attributes in association with a new object class.

For example, you might find that you want to store more information on a person entry than the person, organizationalPerson, or inetOrgPerson object classes support. If you want to store birth dates in your directory, no attribute exists within the standard Directory Server schema. You can create a new attribute called dateOfBirth. Allow this attribute to be used on entries that represent people by defining a new auxiliary class that allows this attribute.

When Creating Custom Schema Files

Keep the following in mind when creating custom schema files, especially when you are using replication:

Managing Attribute Types Over LDAP

This section explains how to create, view, and delete attribute types over LDAP.

Creating Attribute Types

The cn=schema entry has a multivalued attribute, attributeTypes, that contains definitions of each attribute type in the directory schema. You can add to those definitions by using the ldapmodify(1) command.

New attribute type definitions, and changes that you make to user-defined attribute types, are saved in the file 99user.ldif.

For each attribute type definition, you must provide at least an OID to define your new attribute type. Consider using at least the following elements for new attribute types:

ProcedureTo Create an Attribute Type

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Prepare your attribute type definition according to the syntax specified in RFC 4517.

  2. Use the ldapmodify(1) command to add your attribute type definition.

    Notice that Directory Server adds X-ORIGIN 'user defined' to the definition that you provide.

Example 11–1 Creating an Attribute Type

The following example adds a new attribute type with Directory String syntax using the ldapmodify command:


$ cat blogURL.ldif 
dn: cn=schema
changetype: modify
add: attributeTypes
attributeTypes: ( 1.2.3.4.5.6.7 
 NAME ( 'blog' 'blogURL' ) 
 DESC 'URL to a personal weblog' 
 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 
 SINGLE-VALUE )

$ ldapmodify -D cn=admin,cn=Administrators,cn=config -w - -f blogURL.ldif
Enter bind password: 
modifying entry cn=schema

$

In a production environment, you would provide a valid, unique OID, not 1.2.3.4.5.6.7.

Viewing Attribute Types

The cn=schema entry has a multivalued attribute, attributeTypes, that contains definitions of each attribute type in the directory schema. You can read those definitions by using the ldapsearch(1) command.

ProcedureTo View Attribute Types

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Use the ldapsearch command to view all the attribute type definitions that currently exist in your directory schema.

Example 11–2 Viewing Attribute Types

The following command displays definitions for all attribute types:


$ ldapsearch -T -b cn=schema "(objectclass=*)" attributeTypes

The -T option prevents the ldapsearch command from folding LDIF lines, so you can more easily work with the output using commands such as grep or sed. If you then pipe the output of this command through the grep command, you can view only the user-defined extensions to directory schema. For example:


$ ldapsearch -T -b cn=schema "(objectclass=*)" attributeTypes | grep "user defined"
 attributeTypes: ( 1.2.3.4.5.6.7 NAME ( 'blog' 'blogURL' ) 
 DESC 'URL to a personal weblog' 
 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE 
 X-ORIGIN 'user defined' )

Deleting Attribute Types

The cn=schema entry has a multivalued attribute, attributeTypes, that contains definitions of each attribute type in the directory schema. You can delete definitions with X-ORIGIN 'user defined' by using the ldapmodify(1) command.

Because the schema is defined by the LDAP view in cn=schema, you can view and modify the schema online using the ldapsearch and ldapmodify utilities. However, you can delete only schema elements that have the value ’user defined’ for the X-ORIGIN field. The server will not delete other definitions.

Changes that you make to user-defined attributes are saved in the file 99user.ldif.

ProcedureTo Delete Attribute Types

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. View the definition of the attribute type to delete.

    See To View Attribute Types for details.

  2. Use the ldapmodify(1) command to delete the attribute type definition as it appears in the schema.

Example 11–3 Deleting an Attribute Type

The following command deletes the attribute type that is created in Example 11–1:


$ ldapmodify -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password: 
dn: cn=schema
changetype: delete
delete: attributeTypes
attributeTypes: ( 1.2.3.4.5.6.7 NAME ( 'blog' 'blogURL' ) 
 DESC 'URL to a personal weblog' 
 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 SINGLE-VALUE 
 X-ORIGIN 'user defined' )
^D

Notice that you must include the X-ORIGIN 'user defined', which was added by Directory Server to classify this schema definition as an extension.

Managing Object Classes Over LDAP

This section explains how to create, view, and delete object classes over LDAP.

Creating Object Classes

The cn=schema entry has a multivalued attribute, objectClasses, that contains definitions of each object class in the directory schema. You can add to those definitions by using the ldapmodify(1) command.

New object class definitions, and changes that you make to user-defined object classes, are saved in the file 99user.ldif.

If you are creating several object classes that inherit from other object classes, you must create the parent object classes first. If your new object class uses custom attributes, you must also define those first.

For each object class definition, you must provide at least an OID. Consider using at least the following elements for new object classes:

ProcedureTo Create an Object Class

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Prepare your object class definition according to the syntax specified in RFC 4517.

  2. Use the ldapmodify(1) command to add your object class definition.

    Notice that Directory Server adds X-ORIGIN 'user defined' to the definition that you provide.

Example 11–4 Creating an Object Class

The following example adds a new object class using the ldapmodify command:


$ cat blogger.ldif 
dn: cn=schema
changetype: modify
add: objectClasses
objectClasses: ( 1.2.3.4.5.6.8 
 NAME 'blogger' 
 DESC 'Someone who has a blog' 
 SUP inetOrgPerson 
 STRUCTURAL 
 MAY blog )

$ ldapmodify -D cn=admin,cn=Administrators,cn=config -w - -f blogger.ldif
Enter bind password: 
modifying entry cn=schema

$

In a production environment, you would provide a valid, unique OID, not 1.2.3.4.5.6.8.

Viewing Object Classes

The cn=schema entry has a multivalued attribute, objectClasses, that contains definitions of each object class in the directory schema. You can read those definitions by using the ldapsearch(1) command.

ProcedureTo View an Object Class

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Use the ldapsearch command to view all the object class definitions that currently exist in your directory schema.

Example 11–5 Viewing Object Classes

The following command displays definitions for all object classes:


$ ldapsearch -T -b cn=schema "(objectclass=*)" objectClasses

The -T option prevents the ldapsearch command from folding LDIF lines, so you can more easily work with the output using commands such as grep or sed. If you then pipe the output of this command through the grep command, you can view only the user-defined extensions to directory schema. For example:


$ ldapsearch -T -b cn=schema "(objectclass=*)" objectClasses | grep "user defined"
objectClasses: ( 1.2.3.4.5.6.8 NAME 'blogger'
 DESC 'Someone who has a blog' STRUCTURAL MAY blog
 X-ORIGIN 'user defined' )
$

Deleting Object Classes

The cn=schema entry has a multivalued attribute, objectClasses, that contains definitions of each object class in the directory schema. You can delete definitions with X-ORIGIN 'user defined' by using the ldapmodify(1) command.

Because the schema is defined by the LDAP view in cn=schema, you can view and modify the schema online using the ldapsearch and ldapmodify utilities. However, you can delete only schema elements that have the value ’user defined’ for the X-ORIGIN field. The server will not delete other definitions.

Changes that you make to user-defined elements are saved in the file 99user.ldif .

ProcedureTo Delete an Object Class

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. View the definition of the object class to delete.

    See To View an Object Class for details.

  2. Use the ldapmodify(1) command to delete the object class definition as it appears in the schema.

Example 11–6 Deleting an Object Class

The following command deletes the object class that was created in Example 11–4:


$ ldapmodify -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password: 
dn: cn=schema
changetype: delete
delete: objectClasses
objectClasses: ( 1.2.3.4.5.6.8 NAME 'blogger' DESC 'Someone who has a blog' 
 STRUCTURAL MAY blog X-ORIGIN 'user defined' )
^D

Notice that you must include X-ORIGIN 'user defined', which was added by Directory Server to classify this schema definition as an extension.

Extending Directory Server Schema

When you add new attributes to your schema, you must create a new object class to contain the new attributes. Although it might seem convenient to just add the attributes to an existing object class that already contains most of the attributes you require, doing so compromises interoperability with LDAP clients.

Interoperability of Directory Server with existing LDAP clients relies on the standard LDAP schema. If you change the standard schema, you will also have difficulties when upgrading your server. For the same reasons, you cannot delete standard schema elements.

Directory Server schema are stored in attributes of the cn=schema entry. Like the configuration entry, this is an LDAP view of the schema that is read from files during server startup.

The method that you use to extend Directory Server schema depends on whether you want control over the file name where schema extensions are stored. It also depends whether you want to push changes to consumers through replication. See the following table to determine which procedure to follow in your specific case.

Table 11–1 Ways to Extend Schema

Task 

Instructions 

You do not use replication. You intend to extend the schema by adding a custom schema file. 

To Extend Schema With a Custom Schema File

You intend to extend the schema through LDAP. 

To Extend Schema Through LDAP

You use replication. You intend to preserve the file name of your custom schema file on all servers. 

To Extend Schema With a Custom Schema File

You use replication. You intend to extend the schema by adding a custom schema file on a master replica. You then let the replication mechanism copy the schema extensions to consumer servers. 

To Extend Schema Using a Schema File and Replication

For more information about object classes, attributes, and the directory schema as well as guidelines for extending your schema, see Designing a Directory Schema in Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide. For information about standard attributes and object classes, see Sun Java System Directory Server Enterprise Edition 6.2 Man Page Reference.

This section provides information about the various methods to extend the directory schema.

Extending Schema With a Custom Schema File

Schema files are LDIF files that are located in instance-path/config/schema/. The instance-path corresponds to the file system directory where the Directory Server instance resides. For example, the instance might be located in /local/ds/. The files define standard schema that are used by Directory Server and all servers that rely on Directory Server. The files and the standard schema are described in Sun Java System Directory Server Enterprise Edition 6.2 Reference and Sun Java System Directory Server Enterprise Edition 6.2 Man Page Reference.

Schema files are read once only at startup by the server. The LDIF contents of the files are added to the in-memory LDAP view of the schema in cn=schema . Because the order of schema definitions is important, schema file names are prepended with a number and loaded in alphanumerical order. Schema files in this directory are writable only by the system user who is defined during installation.

When defining the schema directly in an LDIF file, do not use the value ’user defined’ for the X-ORIGIN field. This value is reserved for schema elements that are defined through the LDAP view of cn=schema and that appear in the file 99user.ldif.

The 99user.ldif file contains additional ACIs for the cn=schema entry and all schema definitions that have been added from the command-line or using DSCC. The 99user.ldif file is overwritten when new schema definitions are added. If you want to modify this file, you must restart the server immediately to ensure that your changes are current.

Do not modify the standard schema that is defined in the other schema files. You can, however, add new files to define new attributes and object classes. For example, to define new schema elements in many servers, you could define the elements in a file named 98mySchema.ldif and copy this file to the schema directory on all servers. You would then restart all servers to load your new schema file.

ProcedureTo Extend Schema With a Custom Schema File

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Create your own schema definition file, such as 98mySchema.ldif.

    The syntax of definitions in the schema files is described in RFC 4517.

  2. (Optional) If this server is a master replica that sends updates to other servers, copy your schema definition file to each server instance in the replication topology.

    The replication mechanism cannot detect any changes that you make directly to the LDIF files that contain the schema. Therefore, your changes are not replicated to consumers even after restarting the master.

  3. Restart each Directory Server instance to which you copied your schema definition file.

    Your changes take effect when the servers restart and thus reload schema definitions.

Extending Schema Through LDAP

Because the schema is defined by the LDAP view in cn=schema, you can view and modify the schema online using the ldapsearch and ldapmodify utilities. However, you can modify only schema elements that have the value ’user defined’ for the X-ORIGIN field. The server refuses any modification to the other definitions.

New element definitions, and changes that you make to user-defined elements, are saved in the file 99user.ldif.

ProcedureTo Extend Schema Through LDAP

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

Before You Begin

Modifying schema definitions from the command line is prone to error because of the long values that you must type exactly. However, you can use this functionality in scripts that need to update your directory schema.

  1. Use the ldapmodify(1) command to add or delete individual attributeTypes attribute values.

    See To Create an Attribute Type or To Delete Attribute Types for details.

  2. Use the ldapmodify(1) command to add or delete individual objectClasses attribute values.

    See To Create an Object Class or To Delete an Object Class for details.

See Also

To modify one of the values, you must delete the specific value and then add the value as a new value. This process is required because the attributes are multivalued. For details, see Modifying One Value of a Multi Valued Attribute.

Extending Schema Using a Schema File and Replication

For information about custom schema files, see Extending Schema With a Custom Schema File. The following procedure explains how to use the replication mechanism to propagate schema extensions to all the servers in a topology.

ProcedureTo Extend Schema Using a Schema File and Replication

For parts of this procedure, you can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help. Other parts of the procedure can only be done using the command line.

  1. Prepare your schema extensions in one of the following ways:

    • Create your own schema definition file, such as 98mySchema.ldif .

    • Add your schema extensions to 99user.ldif.

    The syntax of definitions in the schema files is described in RFC 4517.

  2. Run the schema_push command on the master server where you put the schema definition file.

    This script does not actually push the schema to replicas. Instead the script writes a special attribute into the schema files so that the schema files are replicated as soon as they are loaded. For more information, see the schema_push(1M) man page.

  3. Restart the master server where you put the schema definition file.

    The replication mechanism cannot detect any changes that you make directly to the LDIF files that contain the schema. When you restart the server after running schema_push, however, the server loads all schema files and then the replication mechanism replicates the new schema to consumers.

Replicating Directory Schema

Whenever you configure the replication of one or more suffixes between two servers, schema definitions are automatically replicated as well. The automatic replication of schema definitions ensures that all replicas have a complete, identical schema that defines all object classes and attributes that can be replicated to the consumers. Master servers therefore also contain the master schema.

However, schema replication is not instantaneous, even when you modify schema over LDAP. Schema replication is triggered either by updates to directory data or at the start of the first replication session after the schema is modified.

To enforce the schema on all replicas, you must at least enable schema checking on all masters. As the schema is checked on the master where the LDAP operation is performed, the schema does not need to be checked when updating the consumer. To improve performance, the replication mechanism bypasses schema checking on consumer replicas.

Note –

Do not turn off schema checking on hubs and dedicated consumers. Schema checking has no performance impact on a consumer. Keep schema checking on to indicate that the replica contents conform to its schema.

Master servers replicate the schema automatically to their consumers during consumer initialization. Master servers also replicate the schema automatically any time the schema is modified through DSCC or through the command-line tools. By default, the entire schema is replicated. Any additional schema elements that do not yet exist on the consumer are created on the consumer and stored in the 99user.ldif file.

For example, assume that a master server contains schema definitions in the 98mySchema.ldif file when the server is started. Also assume that you then define replication agreements to other servers, either masters, hubs, or dedicated consumers. When you subsequently initialize the replicas from this master, the replicated schema contains the definitions from 98mySchema.ldif, but the definitions are stored in 99user.ldif on the replica servers.

After the schema has been replicated during consumer initialization, modifying the schema in cn=schema on the master also replicates the entire schema to the consumer. Therefore, any modifications to the master schema through the command-line utilities or through DSCC are replicated to the consumers. These modifications are stored in 99user.ldif on the master, and by the same mechanism as described previously, the modifications are also stored in 99user.ldif on the consumers.

Consider the following guidelines for maintaining consistent schema in a replicated environment:

When configuring fractional replication, also consider the following guidelines:

Limiting Schema Replication

By default, whenever the replication mechanism replicates the schema, it sends the entire schema to its consumers. There are two situations where it is not desirable to send the entire schema to consumers:

Note –

Directory Server uses the 11rfc2307.ldif schema file. The schema file conforms to RFC 2307.

Versions of Directory Server prior to Directory Server 5.2 use the 10rfc2307.ldif schema file.

ProcedureTo Limit Schema Replication

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Limit schema replication so that only the user-defined schema is replicated.


    $ dsconf set-server-prop -h host -p port repl-user-schema-enabled:on

    The default value, off, causes the entire schema to be replicated when necessary.

Chapter 12 Directory Server Indexing

Like a book index, Directory Server indexes speed up searches by associating search strings with references to the directory contents.

For information about the types of indexes and index tuning, see Chapter 6, Directory Server Indexing, in Sun Java System Directory Server Enterprise Edition 6.2 Reference.

This chapter covers the following topics:

Managing Indexes

This section describes how to manage indexes for specific attributes. The section includes information about creating, modifying, and deleting indexes. See Managing Browsing Indexes for procedures specific to virtual list view (VLV) operations.

ProcedureTo List Indexes

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. To list your existing indexes and their properties, use this command:


    $ dsconf list-indexes -h host -p port -v suffix-DN

ProcedureTo Create Indexes

Note –

You cannot create a new system index. Only the existing system indexes defined internally by Directory Server are maintained.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Create the new index configuration.

    Use the dsconf create-index command-line utility to configure the new index information by specifying the attribute that you want to index.

    For example, to create an index entry for the preferredLanguage attribute, use this command:


    $ dsconf create-index -h host -p port dc=example,dc=com preferredLanguage
    Note –

    The command dsconf create-index sets the index configuration, but does not actually create the index files necessary for searches. Generating the index files can affect performance. To give you more control over the indexing procedure, generating the index files is done manually after the new index configuration has been created.

    Always use the attribute’s primary name when creating indexes. Do not use the attribute’s alias. The primary name of the attribute is the first name listed for the attribute in the schema, for example, uid for the userid attribute.

  2. (Optional) Set the index properties by using the dsconf set-index-prop command.

    The dsconf create-index command creates an index with default properties. If you want to modify these properties, use the dsconf set-index-prop command . For more information about modifying index properties, see To Modify Indexes.

  3. Generate the index files.

    See To Generate Indexes.

  4. Repeat the previous steps for all servers that you want to be indexed.

ProcedureTo Modify Indexes

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Modify the index properties.


    $ dsconf set-index-prop -h host -p port suffix-DN attr-name property:value

    For example, to enable the approximate index approx-enabled for the preferredLanguage index , use the command:


    $ dsconf set-index-prop -h host -p port dc=example,dc=com preferredLanguage approx-enabled:on

    You can modify the following properties for each index:

    • eq-enabled equality

    • pres-enabled presence

    • sub-enabled substring

    One of the properties that you might want to modify is the optional nsMatchingRule attribute. This attribute contains the OID for any matching rule known by the server. It enables the OID of a language collation order for internationalized indexes, and other matching rules such as CaseExactMatch. For a list of supported locales and the OID of their associated collation order, see Sun Java System Directory Server Enterprise Edition 6.2 Reference.

    For more information about index configuration attributes, see Sun Java System Directory Server Enterprise Edition 6.2 Reference.

  2. Regenerate your new indexes.

    See To Generate Indexes.

  3. Repeat the previous steps for all servers that include the modified attribute index.

ProcedureTo Generate Indexes

This procedure generates index files so that new or modified indexes can be searchable.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Generate your index files in one of the following ways:

    • Generate your new index files online.


      $ dsconf reindex -h host -p port [-t attr] suffix-DN

      where -t specifies that only the specified attribute or attributes are to be reindexed, not all attributes.

      For example, to regenerate the preferredLanguage index, type:


      $ dsconf reindex -h host -p port -t preferredLanguage dc=example,dc=com

      While the dsconf reindex command is running, the contents of the suffix remain available through the server. However, searches are not indexed until the command has completed. Reindexing is a resource-intensive task that can impact the performance of other operations on the server.

    • Generate your new index files offline. 


      $ dsadm reindex -t attr instance-path suffix-DN

      For example, to regenerate the preferredLanguage index, type:


      $ dsadm reindex -t preferredLanguage /local/ds dc=example,dc=com

    • Regenerate all of your indexes quickly offline by reinitializing your suffix.

      When you reinitialize a suffix, all index files are automatically regenerated. Depending on the size of the directory, reinitializing the suffix is usually faster than reindexing two or more attributes. However, the suffix is unavailable during the initialization. For more information, see Reindexing a Suffix by Reinitialization.

    Note –

    If you run either dsconf import or dsconf reindex or both commands on multiple suffixes in parallel, transaction logs will grow and might negatively affect performance.

ProcedureTo Delete Indexes

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Remove all indexes that are configured for an attribute.


    $ dsconf delete-index -h host -p port suffix-DN attr-name

    For example, the following command deletes all indexes for the preferredLanguage attribute:


    $ dsconf delete-index -h host -p port dc=example,dc=com preferredLanguage

    Take great care when deleting default indexes because it can affect Directory Server functioning.

Changing the Index List Threshold

Slow searches might be a result of your system index list size exceeding the index list threshold. The index list threshold is the maximum number of values for each index key. To determine whether the index list threshold size has been exceeded, examine the access log. The notes=U flag at the end of an access log RESULT message indicates that an unindexed search was performed. A previous SRCH message for the same connection and operation specifies the search filter that was used. The following two-line example traces an unindexed search for cn=Smith that returns 10,000 entries. Timestamps have been removed from the messages.


conn=2 op=1 SRCH base="o=example.com" scope=0 filter="(cn=Smith)"
conn=2 op=1 RESULT err=0 tag=101 nentries=10000 notes=U

If your system often exceeds the index list threshold, consider increasing the threshold to improve performance. The following procedure uses the dsconf set-server-prop command to modify the all-ids-threshold property. For more information about tuning indexes and the all-ids-threshold property, see Tuning Indexes for Performance in Sun Java System Directory Server Enterprise Edition 6.2 Reference.

ProcedureTo Change the Index List Threshold

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Adjust the index list threshold.

    You can adjust your index list threshold at any of the following levels:

    • At the instance level:


      dsconf set-server-prop -h host -p port all-ids-threshold:value

    • At the suffix level:


      dsconf set-suffix-prop -h host -p port suffix-DN all-ids-threshold:value

    • At the entry level:


      dsconf set-index-prop -h host -p port suffix-DN all-ids-threshold:value

    • At the index level, by search type:


      dsconf set-index-prop -h host -p port suffix-DN all-ids-threshold search-type:value

      where search-type is one of the following:

      • eq-enabled equality

      • pres-enabled presence

      • sub-enabled substring

      The all-ids-threshold property cannot be configured for the approximate index.

    You can use DSCC to set the threshold at the index level, by search type. For more information, see the Directory Server online help.

  2. Regenerate the suffix indexes.

    See To Generate Indexes.

  3. If the database cache size was tuned for the old all IDs threshold value and the server has adequate physical memory, consider increasing the database cache size.

    Increase the database cache size by 25 percent of the magnitude of the increase to the all IDs threshold.

    In other words, if you increase the all IDs threshold from 4000 to 6000, you can increase the database cache size by about 12 ½ percent to account for the increase in index list size.

    Database cache size is set using the attribute dbcachesize. Find the optimum size empirically before applying changes to production servers.

Reindexing a Suffix

If your index files become corrupt, you must reindex the suffix to recreate the index files in the corresponding database directory. You can reindex a suffix either by reindexing the suffix while the directory server is running or by reinitializing the suffix.

Reindexing a Suffix While the Directory Server Is Running

When you reindex a suffix, the server examines all of the entries the suffix contains and rebuilds the index files. During reindexing, the contents of the suffix are read-only. Because the server must scan the entire suffix for every attribute that is reindexed, this process might take up to several hours for suffixes with millions of entries. The length of time also depends on the indexes you configure. In addition, while the suffix is being reindexed, indexes are not available and server performance is impacted.

ProcedureTo Reindex All Indexes on A Suffix

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Reindex all indexes on a suffix.


    $ dsconf reindex -h host -p port suffix-DN

    For example, to initialize all indexes on the dc=example,dc=com suffix, use this command:


    $ dsconf reindex -h host -p port dc=example,dc=com

Reindexing a Suffix by Reinitialization

When you reinitialize a suffix, the new contents are imported, which means that the suffix contents are replaced and new index files are created. Reinitializing a suffix can be faster than reindexing more than one attribute because all attributes are indexed in parallel as the entries are loaded. However, be aware that the suffix is unavailable while it is being reinitialized.

ProcedureTo Reindex a Suffix Through Reinitialization

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Set the suffix to read-only, as described in Setting Referrals and Making a Suffix Read-Only.

  2. Export the entire suffix to an LDIF file, as described in Backing Up to LDIF.

  3. Import the same LDIF file to reinitialize the suffix, as described in Importing Data From an LDIF File.

    During the initialization, the suffix is unavailable. When the initialization is complete, all configured indexes are ready to be used.

  4. Make the suffix writable again, as described in Setting Referrals and Making a Suffix Read-Only.

Managing Browsing Indexes

Browsing indexes are special indexes used only for search operations that request server-side sorting of results. Sun Java System Directory Server Enterprise Edition 6.2 Reference explains how browsing indexes work in Directory Server.

Browsing Indexes for Client Searches

Customized browsing indexes for sorting client search results must be defined manually. To create a browsing index, or virtual list view (VLV) index, use the following procedure. This section also includes procedures for adding or modifying browsing index entries and for regenerating browsing indexes.

ProcedureTo Create a Browsing Index

For parts of this procedure, you can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help. Other parts of the procedure can only be done using the command line.

  1. Add new browsing index entries or edit existing browsing index entries by using the ldapmodify command.

    For instructions, see To Add or Modify Browsing Index Entries.

  2. Run the dsconf reindex command to generate the new set of browsing indexes to be maintained by the server.

    For instructions, see To Regenerate Browsing Indexes.

ProcedureTo Add or Modify Browsing Index Entries

A browsing index is specific to a given search on a given base entry and its subtree. The browsing index configuration is defined in the database configuration of the suffix that contains the entry.

  1. Configure the vlvBase, vlvScope, and vlvFilter attributes for each browsing index on a directory server.

    These attributes configure the base of the search, the scope of the search, and a filter for the search. These attributes use the vlvSearch object class.

  2. Configure the vlvSort attribute for each browsing index.

    This attribute specifies the name of the attribute or attributes that sort the index. This entry is a child of the first entry and uses the vlvIndex object class to specify which attributes to sort and in what order.

    The following example uses the ldapmodify command to create the browsing index configuration entries:


    $ ldapmodify -a -h host -p port -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: cn=people_browsing_index, cn=database-name,
cn=ldbm database,cn=plugins,cn=config
objectClass: top
objectClass: vlvSearch
cn: Browsing ou=People
vlvBase: ou=People,dc=example,dc=com
vlvScope: 1
vlvFilter: (objectclass=inetOrgPerson)

dn: cn=Sort rev employeenumber, cn=people_browsing_index,
 cn=database-name,cn=ldbm database,cn=plugins,cn=config
objectClass: top
objectClass: vlvIndex
cn: Sort rev employeenumber
vlvSort: -employeenumber
^D

    The vlvScope is one of the following:

    • 0 for the base entry alone

    • 1 for the immediate children of the base

    • 2 for the entire subtree rooted at the base

    The vlvFilter is the same LDAP filter that is used in the client search operations. Because all browsing index entries are located in the same place, you should use descriptive cn values to name your browsing indexes.

    Each vlvSearch entry must have at least one vlvIndex entry. The vlvSort attribute is a list of attribute names that defines the attribute to sort on and the sorting order. The dash ( -) in front of an attribute name indicates reverse ordering. You can define more than one index for a search by defining several vlvIndex entries. With the previous example, you could add the following entry:


    $ ldapmodify -a -h host -p port
 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=Sort sn givenname uid, cn=people_browsing_index,
 cn=database-name,cn=ldbm database,cn=plugins,cn=config
objectClass: top
objectClass: vlvIndex
cn: Sort sn givenname uid
vlvSort: sn givenname uid
^D

  3. To modify a browsing index configuration, edit the corresponding vlvSearch entry or the corresponding vlvIndex entry.

  4. To remove a browsing index so that the browsing index is no longer maintained by the server, remove the individual vlvIndex entries.

    Alternatively, if only one vlvIndex entry exists, remove both the vlvSearch entry and the vlvIndex entry.

ProcedureTo Regenerate Browsing Indexes

  1. After you have created the browsing index entries, generate the new browsing indexes for the attributes specified.


    $ dsadm reindex -l -t attr-index instance-path suffix-DN

    The command scans the directory contents and creates a database file for the browsing index.

    The following example generates the browsing index that you defined in the previous section:


    $ dsadm reindex -l -b database-name -t Browsing /local/ds \
 ou=People,dc=example,dc=com

    For more information about the dsadm reindex command, see the dsadm(1M) man page.

Chapter 13 Directory Server Attribute Value Uniqueness

The UID uniqueness plug-in ensures that the value of a given attribute is unique among all entries of the directory or of a subtree. The plug-in stops any operation that tries to add an entry that contains an existing value for the given attribute. The plug-in also stops any operation that adds or modifies the attribute to a value that already exists in the directory.

The UID uniqueness plug-in is disabled by default. When the plug-in is enabled, it ensures the uniqueness of the uid attribute by default. You can create new instances of the plug-in to enforce unique values on other attributes. The UID uniqueness plug-in ensures attribute value uniqueness on a single server.

This chapter covers the following topics:

Overview of Attribute Value Uniqueness

The UID uniqueness plug-in is a pre-operation plug-in. It checks LDAP add, modify, and modify DN operations before the server performs an update of the directory. The plug-in determines whether the operation will cause two entries to have the same attribute value. If so, the server terminates the operation and returns error 19 LDAP_CONSTRAINT_VIOLATION to the client.

You can configure the plug-in to enforce uniqueness in one or more subtrees in the directory or among entries of a specific object class. This configuration determines the set of entries for which unique attribute values is enforced.

You can define several instances of the UID uniqueness plug-in if you want to enforce the uniqueness of other attributes. Define one plug-in instance for each attribute whose value must be unique. You can also have several plug-in instances for the same attribute to enforce “separate” uniqueness in several sets of entries. A given attribute value is allowed only once in each set of subtrees.

When you enable attribute uniqueness on an existing directory, the server does not check for uniqueness among existing entries. Uniqueness is only enforced when an entry is added or when the attribute is added or modified.

By default, the UID uniqueness plug-in is disabled because the plug-in affects multimaster replication. You can enable the UID uniqueness plug-in when using replication, but you should be aware of the behavior described in Using the Uniqueness Plug-In With Replication.

Enforcing Uniqueness of the uid and Other Attributes

This section explains how to enable and configure the default uniqueness plug-in for the uid attribute and how to enforce uniqueness of any other attribute.

ProcedureTo Enforce Uniqueness of the uid Attribute

This procedure describes how to enable and configure the UID uniqueness plug-in by using the dsconf command. The DN of the plug-in configuration entry is cn=uid uniqueness,cn=plugins,cn=config.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

When using DSCC, you must not modify the default UID uniqueness plug-in to enforce uniqueness of another attribute. If you do not want to have a UID uniqueness plug-in, leave the plug-in disabled and create a new plug-in instance for another attribute, as described in To Enforce Uniqueness of Another Attribute.

  1. Enable the plug-in.


    $ dsconf enable-plugin -h host -p port "uid uniqueness"

  2. Modify the plug-in arguments according to how you want to specify the subtrees where uniqueness is enforced.

    • To specify the base DN of a single subtree, type:


      $ dsconf set-plugin-prop -h host -p port "uid uniqueness" argument:uid argument:subtreeBaseDN

      For example:


      $ dsconf set-plugin-prop -h host1 -p 1389 "uid uniqueness" argument:uid \
 argument:dc=People,dc=example,dc=com

    • To specify more than one subtree, add more arguments with the full base DN of a subtree as the value of each argument.


      $ dsconf set-plugin-prop -h host -p port "uid uniqueness" argument:uid \
 argument:subtreeBaseDN argument:subtreeBaseDN

    • To specify subtrees according to the object class of their base entries, set the arguments to the following values. Uniqueness of the uid attribute is enforced in the subtree below every entry with the baseObjectClass. Optionally, you can specify the entryObjectClass in the third argument so that the plug-in only enforces uniqueness in operations that target entries with this object class.


      $ dsconf set-plugin-prop -h host -p port "uid uniqueness" argument:attribute=uid \
 argument:markerObjectClass=baseObjectClass argument:entryObjectClass=baseObjectClass

    • To add an argument to an existing list of arguments, use the following command:


      $ dsconf set-plugin-prop -h host -p port "uid uniqueness" argument+:argument-value

  3. Restart the server for your changes to take effect.

ProcedureTo Enforce Uniqueness of Another Attribute

The UID uniqueness plug-in can be used to enforce the uniqueness of any attribute. You must create a new instance of the plug-in by creating a new entry under cn=plugins,cn=config in the directory.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Create a new plug-in.


    $ dsconf create-plugin -h host -p port -H lib-path -F init-func \
 -Y type plugin-name

    plugin-name should be a short and descriptive name that includes the name of the attribute. For example, to create a plug-in for the uniqueness of the mail ID attribute, use this command:


    $ dsconf create-plugin -h host1 -p 1389 -H /opt/SUNWdsee/ds6/lib/uid-plugin.so \
 -F NSUniqueAttr_Init -Y preoperation "mail uniqueness"

  2. Set the plug-in properties.


    $ dsconf set-plugin-prop -h host -p port plugin-name property:value

    For example, to set the properties for the mail uniqueness plug-in, :


    $ dsconf set-plugin-prop -h host1 -p 1389 "mail uniqueness" \
 desc:"Enforce unique attribute values..." version:6.0 \
 vendor:"Sun Microsystems, Inc." depends-on-type:database

  3. Enable the plug-in.


    $ dsconf enable-plugin -h host -p port plugin-name

  4. Specify the plug-in arguments.

    These arguments depend on how you want to determine the subtrees where uniqueness is enforced.

    • To define one or more subtrees according to their base DN, the first argument must be the name of the attribute that should have unique values. Subsequent arguments are the full DNs of the base entries of the subtrees.


      $ dsconf set-plugin-prop -h host -p port plugin-name argument:attribute-name \
 argument:subtreeBaseDN argument:subtreeBaseDN...

    • To add an argument to an existing list of arguments, use the following command:


      $ dsconf set-plugin-prop -h host -p port plugin-name argument+:argument-value

    • To define subtrees according to the object class of their base entries, the first argument must contain attribute=attribute-name which specifies the name of the attribute that should have unique values. The second argument must be the baseObjectClass that determines the base entry of subtrees where uniqueness is enforced. Optionally, you can specify an entryObjectClass in the third argument so that the plug-in enforces uniqueness only in operations that target entries with this object class.


      $ dsconf set-plugin-prop -h host -p port plugin-name argument:attribute=attribute-name \
 argument:markerObjectClass=baseObjectClass argument:requiredObjectClass=entryObjectClass

    In all plug-in arguments, no space can appear before or after the = sign.

  5. Restart the server for your changes to take effect.

Using the Uniqueness Plug-In With Replication

The UID uniqueness plug-in does not perform any checking on attribute values when an update is performed as part of a replication operation. This does not affect single-master replication, but the plug-in cannot automatically enforce attribute uniqueness for multimaster replication.

Single-Master Replication Scenario

Because all modifications by client applications are performed on the master replica, the UID uniqueness plug-in should be enabled on the master server. The plug-in should be configured to enforce uniqueness in the replicated suffix. Because the master ensures that the values of the desired attribute are unique, you do not need to enable the plug-in on the consumer server.

Enabling the UID uniqueness plug-in on the consumer of a single master does not interfere with replication or normal server operations. However, it might cause slight performance degradation.

Multimaster Replication Scenario

The UID uniqueness plug-in was not designed for use in a multimaster replication scenario. Because multimaster replication uses a loosely consistent replication model, simultaneously adding the same attribute value on both servers will not be detected, even if the plug-in is enabled on both servers.

However, you can use the UID uniqueness plug-in if the attribute on which you are performing the uniqueness check is a naming attribute, and the uniqueness plug-in is enabled for the same attribute in the same subtrees on all masters.

When these conditions are met, uniqueness conflicts are reported as naming conflicts at replication time. Naming conflicts must be resolved manually. For more information, refer to Solving Common Replication Conflicts.

Chapter 14 Directory Server Logging

This chapter describes how to manage Directory Server logs.

If you want information to assist you in defining a logging strategy, use the logging policy information in Designing a Logging Strategy in Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide.

For a description of the log files and their contents, see Chapter 7, Directory Server Logging, in Sun Java System Directory Server Enterprise Edition 6.2 Reference.

This chapter covers the following topics:

Log Analysis Tool

The Directory Server Resource Kit provides a log analysis tool, logconv, that enables you to analyze Directory Server access logs. The log analysis tool extracts usage statistics. It also counts the occurrences of significant events. For more information about this tool, see the logconv(1) man page.

Viewing Directory Server Logs

You can view the logs directly on the server in the default instance-path/logs file. If you have modified the default path, you can find the log file location using the dsconf command as follows:


$ dsconf get-log-prop -h host -p port log-type path

Alternatively, you can view the log files through Directory Service Control Center (DSCC). DSCC enables you to view and sort the log entries.

The following figure shows a sample of a Directory Server access log in DSCC.

Figure 14–1 DSCC Access Log

Access log viewed through DSCC. The access log entries are listed in a table.

ProcedureTo Tail Directory Server Logs

You can use the dsadm command to display a specified number of lines of the Directory Server logs, or to display log entries younger than a specified age. This example tails the error log. To tail the access log, use show-access-log instead of show-error-log.

  1. Display error log entries younger than a certain age.


    $ dsadm show-error-log -A duration instance-path

    You must specify a unit for the duration. For example, to display error log entries younger than 24 hours, type:


    $ dsadm show-error-log -A 24h /local/ds

  2. Display a specified number of lines from the error log (starting from the end).


    $ dsadm show-error-log -L last-lines instance-path

    The number of lines is expressed as an integer. For example, to display the last 100 lines, type:


    $ dsadm show-error-log -L 100 /local/ds

    If you do not specify a value, the default number of lines displayed is 20.

Configuring Logs for Directory Server

Many aspects of the log files can be modified. Some examples include the following:

The following procedures describe how to modify log configuration and how to enable the audit log.

ProcedureTo Modify Log Configuration

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. View the settings for the log that you want to modify.


    $ dsconf get-log-prop -h host -p port log-type

    For example, to list the existing error log settings, type:


    $ dsconf get-log-prop -h host1 -p 1389 error
Enter "cn=Directory Manager" password:
buffering-enabled         :  off
enabled                   :  on
level                     :  default
max-age                   :  1M
max-disk-space-size       :  100M
max-file-count            :  2
max-size                  :  100M
min-free-disk-space-size  :  5M
path                      :  /tmp/ds1/logs/errors
perm                      :  600
rotation-interval         :  1w
rotation-min-file-size    :  unlimited
rotation-time             :  undefined
verbose-enabled           :  off

  2. Set the new value.

    Set the value that you want for the property. 


    $ dsconf set-log-prop -h host -p port log-type property:value

    For example, to set the rotation interval for the error log to two days, use this command:


    $ dsconf set-log-prop -h host1 -p 1389 error rotation-interval:2d

ProcedureTo Enable the Audit Log

Unlike the access log and errors log, the audit log is not enabled by default. Before viewing the audit log, you must enable it.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Enable the audit log.


    $ dsconf set-log-prop -h host -p port audit enabled:on

Rotating Directory Server Logs Manually

If you have a log that is getting very large, you can manually rotate the log at any time. Rotation backs up the existing log file and creates a fresh log file.

ProcedureTo Rotate Log Files Manually

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Rotate the log file.


    $ dsconf rotate-log-now -h host -p port log-type

    For example, to rotate the access log:


    $ dsconf rotate-log-now -h host1 -p 1389 access

Chapter 15 Directory Server Monitoring

Directory Server can be monitored using a variety of methods. These methods are described in Chapter 3, Directory Server Monitoring, in Sun Java System Directory Server Enterprise Edition 6.2 Reference.

This chapter describes how to set up and administer monitoring in Directory Server.

This chapter covers the following topics:

Setting Up SNMP for Directory Server

This section describes how to set up your server to be monitored through SNMP.

For a description of SNMP implementation in Directory Server, see Directory Server and SNMP in Sun Java System Directory Server Enterprise Edition 6.2 Reference.

ProcedureTo Set Up SNMP

For parts of this procedure, you can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help. Other parts of the procedure can only be done using the command line.

  1. Enable the Java ES Management Framework plug-in.

    Use the procedure Enabling Java ES MF Monitoring. This procedure also enables the Common Agent Container, which is part of the Java ES MF.

  2. Access the SNMP-managed objects defined by the MIB and exposed through the agents.

    The tasks required for this step are entirely dependent on your SNMP management system. See your SNMP management system documentation for instructions.

    When exposing the MIB, you might want to use the RFC text files for this MIB. These files are available at http://www.ietf.org/rfc/rfc2605.txtand http://www.ietf.org/rfc/rfc2788.txt.

Enabling Java ES MF Monitoring

If you want to use the Sun Java ES Management Framework (Java ES MF) for monitoring, you must enable the Java ES MF plug-in.

For more information about administering the Java ES MF, see the Sun Java Enterprise System 5 Monitoring Guide.

ProcedureTo Enable Java ES MF Monitoring

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Initialize and register the Java ES Monitoring Framework.


    $ dsccsetup mfwk-reg

    For the location of this command, see Command Locations.

  2. Enable the Java ES Management Framework plug-in.


    $ dsconf enable-plugin -h host -p port "Monitoring Plugin"
Enter "cn=Directory Manager" password:
Directory Server must be restarted for changes to take effect.

  3. Restart the Directory Server instance.


    $ dsadm restart instance-path

  4. Verify that the Java ES Management Framework plug-in is enabled.


    $ dsconf get-plugin-prop -h host -p port -v "Monitoring Plugin"
Enter "cn=Directory Manager" password:
Reading property values of the plugin "Monitoring Plugin"...
argument          :
depends-on-named  :
depends-on-type   :  database
desc              :  Monitoring plugin
enabled           :  on
feature           :  Monitoring
init-func         :  mf_init
lib-path          :  /opt/SUNWdsee/ds6/lib/mf-plugin.so
type              :  object
vendor            :  Sun Microsystems, Inc.
version           :  6.0

Troubleshooting Java ES MF Monitoring

If Java ES MF monitoring does not work, ensure that you have correctly installed the Common Agent Container, as described in Chapter 2, Installing Directory Server Enterprise Edition 6.2, in Sun Java System Directory Server Enterprise Edition 6.2 Installation Guide.

If you are still experiencing problems, see the Sun Java Enterprise System 5 Monitoring Guide.

Monitoring a Server Using cn=monitor

Server status, replication status, resource usage, and other monitoring information is available through DSCC.

Alternatively, you can monitor the Directory Server’s current activities from any LDAP client by performing a search operation on the following entries: