test

Oracle Fusion Middleware Administration Guide for Oracle Directory Server Enterprise Edition

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 Checking Your Directory Server Enterprise Edition Installation in Oracle Fusion Middleware Installation Guide for Oracle Directory Server Enterprise Edition.

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.

The dsadm command enables you to manage a Directory Server instance and the files belonging to that instance on the local host. The command does not let you administer servers over the network, but only directly on the local host. The dsadm command has subcommands for each key management task. For a complete description, see dsadm(1M).

The dsconf command is an LDAP client. The command enables you to configure nearly all server settings on a running Directory Server instance from the command line. You can configure settings whether the server is on the local host or another host that is accessible across the network. The dsconf command has subcommands for each key configuration task. For a complete description, see dsconf(1M).

  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/dsInst, use this command:


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

    The instance is created in a directory on the local file system and not a network file system.

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


    $ dsadm info instance-path

    For example: 


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

  3. (Optional) If you installed Directory Server using the native packages and your operating system 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 

    dsadm enable-service --type SMF instance-path

    Solaris 9 

    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 with Directory Service Control Center by using either of the following methods.

    • Login to DSCC, and then use the Register Existing Server action on the Servers tab of the Directory Servers tab.

      Access DSCC using http://hostname:8080/dscc7 or https://hostname:8181/dscc7 as per your application server configuration.

    • Use the command dsccreg add-server.


      $ dsccreg add-server -h hostname --description "My DS" /local/dsInst
Enter DSCC administrator's password:
/local/dsInst is an instance of DS
Enter password of "cn=Directory Manager" for /local/dsInst:
This operation will restart /local/dsInst.
Do you want to continue ? (y/n) y
Connecting to /local/dsInst
Enabling DSCC access to /local/dsInst
Restarting /local/dsInst
Registering /local/dsInst in DSCC on hostname.

      See dsccreg(1M) for more information about the command.

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

    The above action should be performed in the specified sequence.

    For more information about password policies compatibilities, see Password Policy in Oracle Fusion Middleware Upgrade and Migration Guide for Oracle Directory Server Enterprise Edition.

ProcedureTo Delete a Directory Server Instance

Before you delete the server instance, you must prepare the instance for deletion. Refer to the following procedure to delete a server instance successfully:

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 [--force] instance-path

  2. If the server was previously registered with DSCC, unregister the server using the following command:


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

    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 

    dsadm disable-service --type SMF instance-path

    Solaris 9 

    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, under the instance-path directory.

    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.

For more information about dsadm subcommands and options used below, see dsadm(1M).

  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/dsInst, use this command:


      $ dsadm start /local/dsInst

      If the start operation fails after a configuration change, use the --safe option as shown in the following command:


      $ dsadm start --safe /local/dsInst

    • To stop the server, type:


      $ dsadm stop [--force] instance-path

      For example:


      $ dsadm stop --force /local/dsInst

    • To restart the server, type:


      $ dsadm restart instance-path

      For example:


      $ dsadm restart /local/dsInst

ProcedureTo List All the Running Instances

  1. List the running instances on a host using the following command:


    dsadm list-running-instances [--all]

    The –all option lists the running instances from any installation path.

ProcedureTo Stop the Running Instances

  1. Stop the running instances on a host using the following command:


    dsadm stop-running-instances [-i] [--force]

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 Oracle Fusion Middleware Deployment Planning Guide for Oracle Directory Server Enterprise Edition.

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

    Note –

    Database names can contain only ASCII (7-bit) alphanumeric characters, hyphens (-), and underscores (_). Directory Server does not accept multibyte characters (such as in Chinese or Japanese character sets) in strings for database names, file names, and path names.

    To work around this issue, when creating a Directory Server suffix having multibyte characters, specify a database name that has no multibyte characters. When creating a suffix on the command line, for example, explicitly set the --db-name option of the dsconf create-suffix command.


    $ dsconf create-suffix --db-name asciiDBName UTF-8SuffixDN

    Do not use default as database name for the suffix. Do not use multibyte characters for the database name.

  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

  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.

Importing Data From an LDIF File

You can import data to a Directory Server suffix in the following ways:

Note –

The offline import (dsadm import) does not remove the changelog as the changelog data may still be in the suffix. At server start, replication decides if the changelog needs to be kept or not. Online import (dsconf import) decides straight away if changelog needs to be recreated or not.

The following table shows the differences between initializing a suffix and adding, modifying, and deleting entries in bulk.

Table 2–1 Comparison of Initializing a Suffix and Importing Data in Bulk

Domain of Comparison 

Initializing Suffixes 

Adding, Modifying, and Deleting Entries in Bulk 

Content 

Overwrites content 

Does not overwrite content 

LDAP operations 

N/A 

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 

Accessible from server 

On client machine 

Commands 

If server is local and stopped: 

dsadm import

If server is remote and running: 

dsconf import

ldapmodify -B

Note –

Bulk import using the ldapmodify -B command erases the existing entries under the target suffix.

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/dsInst /local/file/example/demo1.ldif \
 /local/file/example/demo2.ldif dc=example,dc=com

    • If your server is running (local or remote), 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 –

      When using the dsconf command, the dse.ldif file must be available to the host running the server.

    For more information, see the dsadm(1M) and dsconf(1M)man pages.

Procedure To Load Sample Data in Directory Server Instance

Examples that use command-line tools depend on sample data residing under the dc=example,dc=com suffix of your directory.

You can set up part of the data that is required by creating a dc=example,dc=com suffix. You can then populate the suffix with entries from the install-path/dsee7/resources/ldif/Example.ldif file.

  1. Create a new Directory Server instance and start the instance.


    $ dsadm create -p port -P SSL-port instance-path
$ dsadm start instance-path

  2. Read the Example.ldif file to find bind passwords needed in the examples.

  3. Create suffix and load the Example.ldif content into the directory by using the following commands:


    $ dsconf create-suffix -h localhost -p 1389 dc=example,dc=com
$ dsconf import -h localhost -p 1389 \
install-path/dsee7/resources/ldif/Example.ldif dc=example,dc=com

    For more information, see To Create a Directory Server Instance.

  4. Generate test data for examples by using the makeldif(1) command, as shown in the next step, and the following template:

    define suffix=dc=example,dc=com
define maildomain=example.com

branch: ou=test,[suffix]
subordinateTemplate: person:100

template: person
rdnAttr: uid
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
givenName: <first>
sn: <last>
cn: {givenName} {sn}
initials: {givenName:1}{sn:1}
employeeNumber: <sequential>
uid: test{employeeNumber}
mail: {uid}@[maildomain]
userPassword: auth{employeeNumber}{employeeNumber}
telephoneNumber: <random>
description: This is the description for {cn}.

  5. Create a test.template file and copy the template content, as shown above, into it. Use commands such as the following to generate the data in test.ldif and to load the content into the directory.

    Note –

    The test.template file must be created in the install-path/dsee7/dsrk/bin/example_files directory.


    $ cd install-path/dsee7/dsrk/bin/example_files
$ ../makeldif -t test.template -o test.ldif
Processing complete.
101 total entries written.
$ ../ldapmodify -a -c -D uid=hmiller,dc=example,dc=com -w - -f test.ldif
Enter bind password:
…

    If you read Example.ldif, you see that the password for hmiller is hillock.

    Note –

    This step is specific to the zip installation because the makeldif command is available only in the zip distribution.

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.

  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/dsInst/ldif/demo.ldif

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 11g Release 1 (11.1.1) 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, and returns the storage space to the filesystem, if possible. Since application data is not processed and based on the way the database keys are managed, it is not guaranteed that the storage space can be reclaimed. Nevertheless database size will not grow.

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.