Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide

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.