Sun Java System Directory Server Enterprise Edition 6.2 Installation Guide

Part I Installing Directory Service Control Center, Directory Proxy Server, Directory Server, and Directory Server Resource Kit

This part includes the following chapters.

For help with installation of Identity Synchronization for Windows software, see Part II, Installing Identity Synchronization for Windows.

This guide does not cover installation with other Java Enterprise System (Java ES) products. If you plan to install Directory Server and Directory Service Control Center software with other Java ES software, read the installation instructions for Java ES software at http://docs.sun.com/coll/1286.3.

This guide does not cover the installation of Directory Editor software. If you plan to install Directory Editor software, first read the Known Problems and Limitations in Directory Editor in Sun Java System Directory Server Enterprise Edition 6.2 Release Notes then read the installation instructions in the Sun Java System Directory Editor 1 2005Q1 Installation and Configuration Guide.

Make sure you read Chapter 6, Directory Editor Bugs Fixed and Known Problems.

Chapter 1 Before You Install

Before installing Directory Server Enterprise Edition software in a production environment, obtain the plans for deployment that were created with the help of Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide. With the plans in hand, read this section to gauge how to approach installation for your deployment.

This chapter includes the following sections.

The Administration Framework and Installation

This section highlights key aspects of the administration framework you must understand before installing server software in a production environment. This section does not address the developer and performance tuning tools provided with Directory Server Resource Kit. You can install such tools independently of the administration framework.

Before you read this section, read Directory Server Enterprise Edition Administration Model in Sun Java System Directory Server Enterprise Edition 6.2 Deployment Planning Guide. Consider the following figure which shows how the network traffic flows. The figure shows network traffic flows between the configuration management tools, DSCC, dsconf(1M), and dpconf(1M), the local administration agents, and servers. The figure also shows communication between the local agents, the local command line tools, dsadm(1M) and dpadm(1M), and the servers that you manage.

Administration framework and installation model

Notice the command line management and monitoring tools, dsconf(1M) and dpconf(1M), require only LDAP access to the servers that you manage. LDAP traffic typically flows through the default ports, 389 for LDAP and 636 for secure LDAP using SSL. When you create servers as a non-root user, the default ports are 1389 for LDAP, and 1636 for secure LDAP using SSL.

By convention, only root can install software using reserved port numbers less than 1024. Solaris systems allow the administrator to permit non-root users to use privileged ports, using role-based access control (RBAC).

DSCC is a web application that runs in the following modes:

You typically install DSCC on only one system in your deployment. You then manage all your servers from that installation of DSCC. You access DSCC through a browser using the URL, https://hostname:6789, http://hostname:8080, or https://hostname:8181 based on the software distribution you use to install Directory Server Enterprise Edition and the configuration of the application server in case of installation using the zip distribution.

DSCC requires LDAP access to the servers for online management operations. DSCC also requires Java Management Extension (JMX) access to agents installed alongside the servers. The agents perform server process management operations on behalf of DSCC, that cannot be performed through LDAP on a running server. You can use DSCC to create and to start new servers.

As part of the normal installation process, you install the local DSCC agents alongside server software. DSCC contacts the agents over the network using a specific port number. You must therefore either accept the default port number, 11162, or specify a different port number.

The agents run inside a common agent container on the server system. This common agent container provides its agents with a single external port for management applications. The common agent container also consolidates resources to save resources on systems where multiple local agents share the container. The common agent container is the agent that listens for DSCC on the default port number, 11162, routing management traffic to other agents. DSCC communicates with local agents through the common agent container. For troubleshooting purposes, a common agent container can be managed independently using the cacaoadm command.

Figure 1–1 Ports and Protocols After Installation of Native Packages Distribution

This figure shows the ports used by the components of
the administration framework, and the management protocol traffic going through
those ports.

Each time you install Directory Server Enterprise Edition software from the zip distribution, you also install an instance of the common agent container. Therefore, when you install multiple versions in parallel on the same host system, only one version can use the default port. You cannot install from the zip distribution where a common agent container instance already uses the default port. You must then specify a different port number for the additional common agent container instance.

    Server software installation is a three stage process.

  1. Install configuration management software.

    The configuration management tools are installed and DSCC is initialized.

    As DSCC stores its configuration data in its own, private Directory Server instance, Directory Server is also installed from native packages during the DSCC installation.

  2. Install server software on the systems where you plan to run server instances.

    The server software, required libraries, local administration tools, and local agents are installed. All the software is installed to enable you to set up directory services but no servers are running at this point.

  3. Create and configure server instances on the systems.

    The Directory Server and Directory Proxy Server instances are created. Instances are created either using DSCC, or with the local administration tools that are installed alongside the server software. Server instances are then configured either through DSCC or through the configuration management command line tools.

The first two stages are combined when you install everything on a single host system. DSCC uses the local agents to perform certain operations on the servers. Thus, the local agents must be installed in a local common agent container.

In the zip distribution, the Web Archive (WAR) file that is used to configure DSCC is copied to your system during the second stage. No installation or initialization of the WAR file is done during the first stage. The WAR file is further deployed with the supported application server to configure DSCC.

Comparison of Single System And Distributed Installation

This section compares and contrasts single host system installations with installations that involve multiple systems.

    Following are the ways in which you can do the installation:

  1. To install DSCC and configuration management tools on the same host as the servers that you manage. Alternatively, you can install the tools on a different host from the servers that you manage remotely.

  2. To create multiple server instances on the same host, or create each server instance on a different host.

Where You Install Directory Service Control Center

Installing DSCC on the same host as the servers that you manage provides a quick and simple solution for evaluation and development. This solution is not recommended for production installations where you rely on redundant systems and on server replica to provide high availability.

When you install DSCC, you also install Directory Server software. DSCC uses its own private instance of Directory Server to store configuration information. If you also install the local agent for Directory Server alongside DSCC, you can create Directory Server instances on the system using DSCC. You can do so without having to know additional host names and port numbers.

You can install DSCC on a different host from the servers you manage remotely. This solution is recommended for production installations where you rely on redundant systems and on server replica to provide high availability.

Figure 1–2 Administration Host and Server Host on Different Systems After Installation of Native Packages Distribution

This figure shows DSCC installed on an administration
host, accessing the server instance on a server host.

When you install DSCC on the administration host, you must be root. However, you can use DSCC installed on the administration host to manage server hosts installed as non-root.


Note –

The DSCC configured using the WAR file deployed with the supported application server installs DSCC outside of Sun Java Web Console and any non-Root user can perform this action.


For example, you install DSCC on a server or even a suitable workstation outside the data center. You also install server software from the zip distribution on server hosts inside the data center, performing such installations as non-root. Over secure LDAP and JMX, you can then create, configure, and manage all your servers through DSCC on the administration host.

Where You Create Server Instances

For production installations, you rely on redundant systems, load balancing, failover capabilities, and server replica to provide high availability. You therefore typically create servers on multiple host systems. Yet, more powerful host systems might each house multiple server instances.

When you create multiple server instances on a single host system, only one server instance can listen on the default ports. As long as you install Directory Server Enterprise Edition software only once, multiple server instances can share the same common agent container.

When you install multiple Directory Server Enterprise Edition versions on a system, each version comes with its own common agent container. Only one of those common agent containers can listen on the default port for JMX management traffic.

Directory Server Enterprise Edition Software Distributions

This section compares the different Directory Server Enterprise Edition software distributions available.

Figure 1–3 The Two Software Distributions

To install all software, get both distributions.

Java Enterprise System Distribution

This section introduces the Java Enterprise System distribution, which comes with the Java ES installer.

The Java ES installer offers a graphical wizard, a command-line interactive wizard, and also silent installation capabilities to add natively packaged software to your system. As this distribution is based on native packages, you must be root to perform the installation with the Java ES installer.

The Java ES installer provides a fresh installation of Directory Server Enterprise Edition 6.2 on Solaris and Linux. To install Directory Server Enterprise Edition 6.2 on Windows, see Installation Procedure Quick Reference. Directory Server Enterprise Edition 6.2 is not delivered on HP-UX.

All Java ES software can work together, relying on a common framework of basic components and of libraries. You can therefore install all the software products together on a single system.

The Java ES installation software also facilitates installation of shared components. The software integrates with the system, so you can configure directory services to restart automatically when the operating system reboots. With a native package based installation, you benefit from the package versioning and patching tools that are part of the operating system.

This guide does not describe all installation alternatives available using the Java ES installer. However, this guide addresses the key Java ES installer wizard screens related to Directory Server Enterprise Edition 6.2 software installation. For detailed instructions on using all features of the Java ES installer, see the Java Enterprise System documentation at http://docs.sun.com/coll/1286.3.

Native Patches

This section introduces the native patches that enable you to upgrade Directory Server Enterprise Edition 6.0 and 6.1 installations.

You must be root to do the installation using native patches. These patches are applied on the top of the existing Directory Server Enterprise Edition 6.0 or 6.1 installation. Native patches contain all the components of Directory Server Enterprise Edition as in Java Enterprise System distribution but upgrade the only components that are already installed as a part of Directory Server Enterprise Edition 6.0 or 6.1 installation. You cannot do fresh installation of any of the components in Directory Server Enterprise Edition using native patches.

You can install Directory Server Enterprise Edition 6.2 on Windows by installing native patches on the top of Directory Server Enterprise Edition 6.0 installation. The Java Enterprise System distribution does not provide fresh installation for Directory Server Enterprise Edition 6.2 on Windows.

Zip Distribution

This section introduces the zip distribution, which provides the dsee_deploy(1M) command-line installer.

This distribution offers self-contained software that you can install anywhere on local disk where you have write permission. You can both install and administer zip distribution software as a non-root user.

As zip distribution software is self-contained, each software installation performed from the zip distribution is independent. You can therefore install software from multiple zip distribution versions on the same system. Your system administrator must manually configure the software that you install to restart when the operating system reboots.

Furthermore, with the zip distribution, you must keep careful track of what you have installed, and the patches you have applied.

Comparison of Java Enterprise System Distribution and Zip Distribution

This section identifies the software supported in each distribution.

Both the Java ES and zip distributions allow you to create and configure Directory Server and Directory Proxy Server instances as non-root.

Directory Server Enterprise Edition Software Component 

Java Enterprise System Distribution 

Zip Distribution 

Directory Service Control Center 

Provided 

Provided, configurable by deploying WAR file with application server 

Directory Server 

Provided 

Provided, installable with dsee_deploy

Directory Proxy Server 

Provided 

Provided, installable with dsee_deploy

Directory Editor 

Not provided in this distribution 

Provided, but not installed with dsee_deploy

Identity Synchronization for Windows 

Not provided in this distribution 

Provided, but not installed with dsee_deploy

Directory Server Resource Kit 

Not provided in this distribution 

Provided, installed with dsee_deploy


Note –

A server instance can only be managed by one DSCC.


Identity Synchronization for Windows and Directory Editor software are bundled with the zip distribution, but are not installed using the dsee_deploy command. This guide covers Identity Synchronization for Windows installation. See Part II, Installing Identity Synchronization for Windows.

This guide does not cover installation of Directory Editor software. If you plan to install Directory Editor software, read the installation instructions in the Sun Java System Directory Editor 1 2005Q1 Installation and Configuration Guide.

Installation in Solaris Zones

This section addresses the key points to consider when installing Directory Server Enterprise Edition in a Solaris zone.

Global and full local Solaris zones present Directory Server Enterprise Edition software with complete systems. Directory Server Enterprise Edition software treats both the zones as an independent physical system. The Directory Server Enterprise Edition installation is like installing on an independent system. The software does not share services or file locations with other zones.

In sparse zones, you can install some services to be used in system-wide fashion. Single instances of Java Enterprise System common component services can therefore be used by multiple Java ES server instances. For example, Directory Server Enterprise Edition software in sparse zones can use the same Common Agent Container and Java ES Monitoring Framework installed in the global zone. You must, however, install the system-wide services before you can complete installation of sparse zone software that depends on the system-wide services.

Directory Server Enterprise Edition does not require you to use system-wide services when you install in a sparse zone. When you install self-contained software from the zip distribution, you also install the common component services in the sparse zone. Therefore, zip distribution installations in sparse zones resemble installations on independent systems.

The following table outlines constraints for Directory Server Enterprise Edition installations, which pertain essentially to installations in sparse zones.

Directory Server Enterprise Edition Software Component 

Software Distribution 

Constraints Installing in Global or Full Local Zone 

Constraints For Sparse Zone Installations 

Directory Service Control Center 

Java Enterprise System distribution 

No constraints 

First install Java Enterprise System shared components in the global zone, then install Directory Service Control Center in the sparse zone. 

Zip distribution 

No constraints 

No constraints 

Directory Server 

Java Enterprise System distribution 

No constraints 

First install Java Enterprise System shared components in the global zone, then install Directory Server in the sparse zone. 

Zip distribution 

No constraints 

No constraints 

Directory Proxy Server 

Java Enterprise System distribution 

No constraints 

First install Java Enterprise System shared components in the global zone, then install Directory Proxy Server in the sparse zone. 

Zip distribution 

No constraints 

No constraints 

Directory Editor 

Zip distribution 

No constraints 

The web application container must allow installation in the sparse zone. 

Identity Synchronization for Windows 

Zip distribution 

No constraints 

Not supported 

Directory Server Resource Kit 

Zip distribution 

No constraints 

No constraints 

For details about installation from the Java Enterprise System distribution in sparse zones, see the Java Enterprise System documentation, http://docs.sun.com/coll/1286.3.

Installation Procedure Quick Reference

This section provides you with the complete information on what you require to install or upgrade to Directory Server Enterprise Edition 6.2.

From the following table, based on your current installation and the type of distribution you are using for installation, you can directly access the related information to install or upgrade to Directory Server Enterprise Edition 6.2.

Previous Directory Server Enterprise Edition Version 

Software Distribution 

Related Information 

None or 5.x 

Native (Solaris and Linux) 

See Software Installation to install Directory Server Enterprise Edition 6.2.

In case of 5.x, you need to migrate Directory Server instances to 6.2. See Sun Java System Directory Server Enterprise Edition 6.2 Migration Guide.

None or 5.x 

Native (Windows) 

Look for the information in the following sequence: 

  1. See Sun Java System Directory Server Enterprise Edition 6.0 Installation Guide to install Directory Server Enterprise Edition 6.0.

  2. See To Upgrade Directory Server Enterprise Edition Using Native Packages to upgrade to version 6.2.

In case of 5.x, you need to migrate Directory Server instances to 6.2. See Sun Java System Directory Server Enterprise Edition 6.2 Migration Guide.

None or 5.x 

Zip 

See To Install Directory Server Enterprise Edition From Zip Distribution to install Directory Server Enterprise Edition 6.2.

Also see, Installing Directory Service Control Center From Zip Distribution

In case of 5.x, you need to migrate Directory Server instances to 6.2. See Sun Java System Directory Server Enterprise Edition 6.2 Migration Guide.

6.0 

Native 

See To Upgrade Directory Server Enterprise Edition Using Native Packages to upgrade to version 6.2.

6.0 

Zip 

See To Install Directory Server Enterprise Edition From Zip Distribution to install Directory Server Enterprise Edition 6.2.

Also see, Installing Directory Service Control Center From Zip Distribution

6.1 

Native 

See To Upgrade Directory Server Enterprise Edition Using Native Packages to upgrade to version 6.2.

6.1 

Zip 

See To Install Directory Server Enterprise Edition From Zip Distribution to install Directory Server Enterprise Edition 6.2.

Also see, Installing Directory Service Control Center From Zip Distribution

Chapter 2 Installing Directory Server Enterprise Edition 6.2

This chapter guides you in installing Directory Server Enterprise Edition 6.2 software.

This chapter contains the following sections:

At the end of this chapter, you will have verified that the software that you installed works as expected. You can then continue to configure the software as described in the Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide.

Software Installation

This section covers basic installation. After you install server software, see Server Instance Creation for instructions on creating server instances.

Directory Server Enterprise Edition is also installed in French, German, Spanish, Japanese, Korean, Simplified Chinese, and Traditional Chinese languages. Instructions to install the multilingual packages are provided in the following sections, wherever required.

ProcedureTo Install Directory Service Control Center From Native Packages

This procedure covers installation of Directory Service Control Center, also known as DSCC, and remote administration command-line tools.

You must be root to perform this procedure.

You can also install Directory Service Control Center with the Zip distribution by deploying the WAR file provided with the software packages. For more information, see Installing Directory Service Control Center From Zip Distribution.

When you install DSCC, you automatically install Directory Server from native packages. DSCC uses its own local instance of Directory Server to store information about your directory service configuration. The instance is referred to as the DSCC Registry.

You can use the Directory Server software that is installed alongside DSCC to create your own additional Directory Server instances on the system.

Before You Begin

Obtain the Java Enterprise System distribution for this installation, as shown in the following figure:

The Java Enterprise System distribution installs natively packaged
software.

Complete the following worksheet for your installation.

Requisite Information 

Hints 

Your Answers 

Hostname of the system where you install DSCC 

  

 

root password for the system

  

 

Java Web Console URL 

Default: https://localhost:6789

 

Directory Service Manager password 

  

 

  1. Install prerequisite patches or service packs for your platform.

    See Operating System Requirements in Sun Java System Directory Server Enterprise Edition 6.2 Release Notes.

  2. With the Java Enterprise System distribution, run the Java ES installer as root.


    # ./installer
    
  3. Select the Directory Service Control Center component for installation.

    The Directory Service Control Center component is selected.

    If you do not want to install the multilingual packages, deselect the Install multilingual package(s) for all selected components check box.

  4. Choose to configure the software later, as you will register the software and create server instances after installation.

    Configure Later is selected.
  5. Complete installation with the Java ES installer.

    After you complete installation, the native packages are installed on the system.

  6. Initialize DSCC with the dsccsetup initialize command.

    For example, on a Solaris system the following command performs initialization.


    root# /opt/SUNWdsee/dscc6/bin/dsccsetup initialize
    ***
    Registering DSCC Application in Sun Java(TM) Web Console
    This operation is going to stop Sun Java(TM) Web Console.
    Do you want to continue ? [y,n] y
    Stopping Sun Java(TM) Web Console...
    Registration is on-going. Please wait...
    DSCC is registered in Sun Java(TM) Web Console
    Restarting Sun Java(TM) Web Console
    Please wait : this may take several seconds...
    Sun Java(TM) Web Console restarted successfully
    ***
    Registering DSCC Agent in Cacao...
    Checking Cacao status...
    Starting Cacao...
    DSCC agent has been successfully registered in Cacao.
    ***
    Choose password for Directory Service Manager:
    Confirm password for Directory Service Manager:
    Creating DSCC registry...
    DSCC Registry has been created successfully
    ***

    The dsccsetup command is located in install-path/dscc6/bin/dsccsetup. See Default Paths to determine the default install-path for your system.

  7. Access DSCC through Java Web Console in your browser.

    To access Console in a different locale, set the preferred language for your browser. For information on setting the preferred language for your browser, see the respective browser documentation.

    1. Login to Java Web Console using your operating system login information or server's root login information.

      If you do not login to Java Web Console using server's root login information, the system might require you to have the root privileges while performing certain tasks such as starting the server instances.

      By default, the URL to access Java Web Console is https://hostname:6789

      Java Web Console login page
    2. Click the Directory Service Control Center link.

      Page showing applications to manage through Java Web
Console
    3. Login to DSCC as Directory Service Manager.

      Directory Service Manager's entry is stored in the DSCC registry. Directory Service Manager has administrator access to DSCC. Directory Service Manager also has administrator access to the server instances registered with DSCC.

      Directory Service Manager login page
    4. Begin managing your servers through Directory Service Control Center.

      Common tasks page for Directory Service Control Center
  8. After Directory Service Control Center is running, enable Java Web Console to restart when the system reboots.

    On a Solaris system, the following command enables restart upon reboot.


    root# /usr/sbin/smcwebserver enable

    For the exact location of this command on your system, see Command Locations.

  9. (Optional) Enable the Common Agent Container, cacao, to restart when the operating system reboots.


    root# cacaoadm enable

    If you decide not to enable the common agent container, the operating system would not be able to use DSCC to communicate with the servers handled by that instance of cacao after rebooting the operating system.

Next Steps

After installing the software, see Environment Variables.

ProcedureTo Troubleshoot Directory Service Control Center Access

Use this procedure on the host where you installed Directory Service Control Center.

You must be root to perform this procedure.

  1. Verify that Directory Service Control Center has been initialized properly.


    root# /opt/SUNWdsee/dscc6/bin/dsccsetup status
    ***
    DSCC Application is registered in Sun Java (TM) Web Console
    ***
    DSCC Agent is registered in Cacao
    ***
    DSCC Registry has been created
    Path of DSCC registry is /var/opt/SUNWdsee/dscc6/dcc/ads
    Port of DSCC registry is 3998
    ***

    The default installation path for native packages on Solaris operating systems is /opt/SUNWdsee. For the default installation path on your operating system, see Default Paths.

    If you find any initialization problems with DSCC, fix them using the dsccsetup(1M) command.

  2. Check the status of Java Web Console and start using the smcwebserver command if not already running.


    root# /usr/sbin/smcwebserver status
    Sun Java(TM) Web Console is stopped
    root# /usr/sbin/smcwebserver start
    Starting Sun Java(TM) Web Console Version 3.0.2 ...
    The console is running.
  3. If you see errors that pertain to the DSCC agent, check the Common Agent Container.

    The cacaoadm(1M) man page describes the error codes that the command returns. For the exact location of this command on your system, see Command Locations.

    If you installed Directory Server from the zip distribution, you must run the cacaoadm command as the user who performed the installation. Otherwise, run the command as root.

    After installing Directory Server, the Common Agent Container is started automatically. However, when you reboot, you might have to start the Common Agent Container manually.


    root# /usr/sbin/cacaoadm status
    default instance is DISABLED at system startup.
    Smf monitoring process:
    26129
    Uptime: 0 day(s), 3:16

    For more information about the Common Agent Container, see Sun Java Enterprise System 5 Monitoring Guide.

ProcedureTo Install Only Directory Server From Native Packages

This procedure covers installation of Directory Server from native packages. You must be root to perform this procedure.


Note –

If you installed Directory Service Control Center, you automatically installed Directory Server from native packages. You can use the Directory Server software that is installed alongside DSCC to create your own additional Directory Server instances on the system.


Before You Begin

Obtain the Java Enterprise System distribution for this installation, as shown in the following figure:

The Java Enterprise System distribution installs natively packaged
software.

Complete the following worksheet for your installation.

Requisite Information 

Hints 

Your Answers 

Fully qualified hostname of the system where you install Directory Server 

Example: ds.example.com

 

(Optional) Cacao common agent container port number to access from Directory Service Control Center 

Default: 11162

 

File system paths where you create Directory Server instances 

Example: /local/ds/

Create instances only on local file systems, never on network–mounted file systems such as NFS. 

Each path is henceforth referred to as an instance-path.

 

LDAP port number 

Default: 389 - root installation; 1389 - non-root installation

 

LDAP/SSL port number 

Default: 636 - root installation; 1636 - non-root installation

 

Directory Manager DN 

Default: cn=Directory Manager

 

Directory Manager password 

Must be at least 8 characters long 

 

Base suffix DN 

Example: dc=example,dc=com

 

(UNIX systems) Server user (uid)

Example: noaccess

 

(UNIX systems) Server group (gid)

Example: noaccess

 

  1. Install prerequisite patches or service packs for your platform.

    See Operating System Requirements in Sun Java System Directory Server Enterprise Edition 6.2 Release Notes.

  2. Using the Java Enterprise System distribution, run the Java ES installer as root.


    root# ./installer
    
  3. Select the Directory Server component for installation.

    The Directory Server component is selected.

    If you do not want to install the multilingual packages, deselect the Install multilingual package(s) for all selected components check box.

  4. Choose to configure the software later, as you will register the software and create server instances after installation.

    Configure Later is selected.
  5. Complete installation with the Java ES installer.

    You can now create server instances on the system. See Server Instance Creation for details.

  6. (Optional) Enable the Common Agent Container, cacao, to restart when the operating system reboots.


    root# cacaoadm enable

    If you decide not to enable the common agent container, the operating system would not be able to use DSCC to communicate with the servers handled by that instance of cacao after rebooting the operating system.

Next Steps

After installing the software, see Environment Variables.

ProcedureTo Install Only Directory Proxy Server From Native Packages

This procedure covers installation of Directory Proxy Server from native packages. You must be root to perform this procedure.

Before You Begin

Obtain the Java Enterprise System distribution for this installation, as shown in the following figure:

The Java Enterprise System distribution installs natively packaged
software.

Complete the following worksheet for your installation.

Requisite Information 

Hints 

Your Answers 

Fully qualified hostname of the system where you install Directory Proxy Server 

Example: dps.example.com

 

(Optional) Cacao common agent container port number to access from Directory Service Control Center 

Default: 11162

 

File system paths where you create Directory Proxy Server instances 

Example: /local/dps/

Create instances only on local file systems, never on network–mounted file systems such as NFS. 

Each path is henceforth referred to as an instance-path.

 

LDAP port number 

Default: 389 - root installation; 1389 - non-root installation

 

LDAP/SSL port number 

Default: 636 - root installation; 1636 - root installation

 

Directory Proxy Manager DN 

Default: cn=Proxy Manager

 

Directory Proxy Manager password 

Must be at least 8 characters long 

 

(UNIX platforms) Server user (uid)

Example: noaccess

 

(UNIX platforms) Server group (gid)

Example: noaccess

 

(Optional) Connection information for each server to access through the proxy 

Example: ds1.example.com:1389, ds2.example.com:1636

 

  1. Install prerequisite patches or service packs for your platform.

    See Operating System Requirements in Sun Java System Directory Server Enterprise Edition 6.2 Release Notes.

  2. Using the Java Enterprise System distribution, run the Java ES installer as root.


    root# ./installer
    
  3. Select the Directory Proxy Server component for installation.

    The Directory Proxy Server component is selected.

    If you do not want to install the multilingual packages, deselect the Install multilingual package(s) for all selected components check box.

  4. Choose to configure the software later, as you will register the software and create server instances after installation.

    Configure Later is selected.
  5. Complete installation with the Java ES installer.

    You can now create server instances on the system. See Server Instance Creation for details.

  6. (Optional) Enable the Common Agent Container, cacao, to restart when the operating system reboots.


    root# cacaoadm enable

    If you decide not to enable the common agent container, the operating system would not be able to use DSCC to communicate with the servers handled by that instance of cacao after rebooting the operating system.

Next Steps

After installing the software, see Environment Variables.

ProcedureTo Install Directory Server Enterprise Edition From Zip Distribution

Before You Begin

During the installation process, if dsee_deploy finds an existing instance of Directory Server Enterprise Edition, it upgrades the instance automatically. Backup the Directory Server Enterprise Edition installation directory, if any, before upgrading to Directory Server Enterprise Edition 6.2, as later you will not be able to restore any previous Directory Server Enterprise Edition installation.

This version removes any previous partial installation of Directory Server Enterprise Edition.

You can install the zip distribution as non-root user.

Refer to the following table for information about the appropriate zip patch for your system. If newer patch revisions become available, use the newer ones instead of those shown in the table.

Operating System 

Patch number 

Solaris SPARC 

126748-02

Solaris 9 x86 

126749-02

Solaris 10 x86 and AMD x64 

126750-02

Linux 

126751-02

Windows 

126753-02

All the multilingual files are included in the above mentioned patches.

Complete the worksheet given below before you start your installation.

Requisite Information 

Hints 

Your Answers 

Fully qualified hostname of the system where you install  

Example:  

 
  • Directory Server

  • Directory Proxy Server

  • ds.example.com

  • dps.example.com

 

(Optional) Common agent container port number to access from Directory Service Control Center 

Default: 11162

 

File system paths where you create instances for: 

Example:  

 
  • Directory Server

  • Directory Proxy Server

  • /local/ds/

  • /local/dps/

Create instances only on local file systems, never on network–mounted file systems such as NFS. 

Each path is henceforth referred to as an instance-path.

 

LDAP port number 

Default: 389 when installing as root; 1389 for non-root

 

LDAP or SSL port number 

Default: 636 when installing as root; 1636 for non-root

 

Directory Manager DN 

Default: cn=Directory Manager

 

Directory Proxy Manager DN 

Default: cn=Proxy Manager

 

Directory Manager password 

Must be at least eight characters long 

 

Directory Proxy Manager password 

Must be at least eight characters long 

 

Base suffix DN 

Example: dc=example,dc=com

 

(UNIX systems) Server user (uid)

Example: noaccess

 

(UNIX systems) Server group (gid)

Example: noaccess

 

(Optional) Connection information for each server to access through the proxy 

Example: ds1.example.com:1389, ds2.example.com:1636

 

By default, the user and group IDs for zip installations are those of the user performing the installation.

  1. Obtain the zip distribution for this installation.

  2. Perform any of the following based on your requirements.

  3. Change to the zip distribution directory that contains the dsee_deploy command.

  4. Install the software with the dsee_deploy(1M) command.


    $ ./dsee_deploy install -i install-path options
    

    For example, the following command installs the component in the /local directory, assuming that you have write access to the directory.


    $ ./dsee_deploy install -i /local
    

    You can also use the --no-inter option to install in non-interactive mode, accepting the license without confirmation. Non-interactive mode is particularly useful for silent installation.

    This step installs a Common Agent Container, cacao, with the local Directory Service Control Center agent as well, allowing you to use DSCC to create server instances. The previous command works properly only if you have not yet installed a Common Agent Container using the default port, 11162.

    If you installed DSCC previously on the same system, a Common Agent Container using the default port is already installed. Specify a different port using the -p option.


    $ ./dsee_deploy install -i /local -p 11169
    

    During the installation process, a WAR file is saved on your system. For more information about WAR file, see Installing Directory Service Control Center From Zip Distribution.

    During the installation process, the multilingual packages are also installed.

  5. Restart Directory Server and Directory Proxy Server instances, if any.

  6. (Optional) Load sample data in your directory.

    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 ldif/Example.ldif file.

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

    2. After you load the Example.ldif content into the directory, generate test data for examples by using the makeldif(1) command 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}.
    3. Copy the template content to template.ldif and use commands such as the following to generate the data in test.ldif and to load the content into the directory.


      $ cd install-path/dsrk6/bin/example_files/
      $ makeldif -t test.template -o test.ldif
      Processing complete.
      101 total entries written.
      $ ldapmodify -a -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.

Next Steps

After installing the software, see Environment Variables.

Installing Directory Service Control Center From Zip Distribution

The Directory Server Enterprise Edition zip distribution includes a WAR file (dscc.war) that contains the Directory Service Control Center (DSCC) web application. The WAR file is deployed with the application server to enable you to do the following tasks:

The WAR file supports the following application servers:

The following two procedures contain information about deploying the WAR file with Sun Java System Application Server and Tomcat respectively.

ProcedureTo Deploy the WAR File with Sun Java System Application Server

After you install Directory Server Enterprise Edition, the WAR file, dscc.war, is at install path/var/dscc6/.

The steps might differ depending on the application server that you use to deploy the WAR file. For information about deploying the WAR file using other application servers, see the respective server documentation.

  1. Initialize the DSCC registry.


    $ install path/dscc6/bin/dsccsetup ads-create
    Choose password for Directory Service Manager:
    Confirm password for Directory Service Manager:
    Creating DSCC registry...
    DSCC Registry has been created successfully
  2. Create an application server instance.


    $ mkdir /local/domainroot
    $ setenv AS_DOMAINS_ROOT /local/domainroot
    $ cd app-server-install-path/apserver/bin
    $ asadmin create-domain --domaindir ${AS_DOMAINS_ROOT} --adminport 3737 \
    --adminuser boss dscc
  3. Edit the server.policy file.

    1. Open the server.policy file.


      $ vi ${AS_DOMAINS_ROOT}/dscc/config/server.policy
    2. Add the following statements to the end of the file:


      // Permissions for Directory Service Control Center
      grant codeBase "file:${com.sun.aas.instanceRoot}/applications/j2ee-modules/dscc/-" 
      {
      	permission java.security.AllPermission;
      };

    This configures the application server to grant all of the Java permissions to the DSCC application.

  4. Deploy the WAR file in your application server instance.


    $ asadmin start-domain --domaindir ${AS_DOMAINS_ROOT} dscc 
    $ cp install path/var/dscc6/dscc.war ${AS_DOMAINS_ROOT}/dscc/autodeploy

    For more information about creating and configuring application server instances and deploying the WAR file, refer to the Sun Java System Application Server Online Help.

  5. Open DSCC.

    Use http://localhost:8080 or https://localhost:8181 based on the configuration of your application server.

    The Directory Service Manager Login page displays.

ProcedureTo Deploy WAR File with Tomcat

After you install Directory Server Enterprise Edition, the WAR file, dscc.war, is at install path/var/dscc6/.

The dscc.war is installed in the same way as any other web application, except the following settings:

The following example shows how to install DSCC in Tomcat on a Solaris 10 system.

The steps might differ depending on the application server that you use to deploy the WAR file. For information about deploying the WAR file using other application servers, see the respective server documentation.

  1. Initialize the DSCC registry.


    $ install path/dscc6/bin/dsccsetup ads-create
    Choose password for Directory Service Manager:
    Confirm password for Directory Service Manager:
    Creating DSCC registry...
    DSCC Registry has been created successfully
  2. Identify your Tomcat installation and instance.


    $ setenv CATALINA_HOME tomcat-install-path
    $ setenv CATALINA_BASE tomcat-instance-path
    $ setenv JAVA_HOME jdk-home-dir
    

    For installing Tomcat and creating instances, refer to the Tomcat documentation.

  3. Deploy the WAR file.


    $ mkdir ${CATALINA_BASE}/webapps/dscc
    $ unzip -d ${CATALINA_BASE}/webapps/dscc install path/var/dscc6/dscc.war
    $ vi ${CATALINA_BASE}/conf/web.xml 

    Add the emphasized text in the file as shown below:


     ...
        <servlet>
            <servlet-name>jsp</servlet-name>
            <servlet-class>org.apache.jasper.servlet.JspServlet</servlet-class>
            <init-param>
                <param-name>fork</param-name>
                <param-value>false</param-value>
            </init-param>
            <init-param>
                <param-name>xpoweredBy</param-name>
                <param-value>false</param-value>
            </init-param>
    	...
            <init-param>
                <param-name>enablePooling</param-name>
                <param-value>false</param-value>
            </init-param>
            <load-on-startup>3</load-on-startup>
        </servlet>
        ....

    $ ${CATALINA_HOME}/bin/startup.sh

    Verify the permissions of startup.sh.

  4. Use http://localhost:8080/dscc to connect to DSCC.

    The Directory Service Manager Login page displays.

ProcedureTo Troubleshoot Problems Accessing Directory Service Control Center

Use this procedure on the host where you installed DSCC.

  1. Verify that DSCC has been initialized properly.


    $ install-path/dscc6/bin/dsccsetup status
    ***
    Sun Java (TM) Web Console is not installed
    ***
    DSCC Agent is registered in Cacao
    Cacao uses a custom port number (11168)
    ***
    DSCC Registry has been created
    Path of DSCC registry is /var/opt/SUNWdsee/dscc6/dcc/ads
    Port of DSCC registry is 3998
    ***
  2. If you see errors that pertain to the DSCC agent, check the status of Common Agent Container.

    The cacaoadm(1M) man page describes the error codes that the command returns. For the exact location of this command on your system, see Command Locations.

    You must run the cacaoadm command as the user who performed the installation. Otherwise, run the command as root.


    # cacaoadm status
    default instance is DISABLED at system startup.
    Smf monitoring process:
    13400
    Uptime: 0 day(s), 0:16

    After installing Directory Server, the Common Agent Container starts automatically. However, when you reboot, you might have to start the Common Agent Container manually as follows:


    # cacaoadm start

    For more information about the Common Agent Container, see Sun Java Enterprise System 5 Monitoring Guide.

Upgrading Shared Components

For Directory Server Enterprise Edition to work properly you must upgrade the shared components.

You can upgrade the shared components using any of the following procedures:

ProcedureUpgrading Shared Components Using Java ES Installer

Before You Begin

You must be root to perform this procedure.

You can use the Java ES installer to upgrade the shared components only on Solaris and Linux .

  1. Start the Java ES installer.


    # ./installer

    After the Welcome and License Agreement pages are displayed, the component selection page displays. (When installed components are detected that can be directly upgraded by the Java ES installer, they are shown with a status of “upgradable.”)

  2. Select the All Shared Components check box in the component selection page.

  3. Confirm your choice.

    All shared components will be upgraded.

  4. Finish installing the shared components using the Java ES installer.

ProcedureUpgrading Shared Components Using Patches

Before You Begin

You must be root to perform this procedure.

Using patches, you can upgrade shared components on Solaris, Linux, and Windows.

On Linux, to install patches you must use installpatch, when available.

Select the platform as per your requirements and install all the patches specified for that platform. If newer patch revisions become available, use the newer ones instead of those shown in the table.

Description 

Solaris 10 SPARC and Solaris 9 SPARC 

Solaris 10 x86, AMD x64 and Solaris 9 x86 

Linux 

International Components for Unicode (ICU) 

119810-04 (Solaris 10)

114677-14 (Solaris 9)

119811-04 (Solaris 10)

114678-14 (Solaris 9)

126368-03

Sun Java Web Console (SJWC) 

125952-05 (Solaris 10)

125950-05 (Solaris 9)

125953-05 (Solaris 10)

125951-05 (Solaris 9)

125954-05

Network Security Services/Netscape Portable Runtime/Java Security Services (NSS/NSPR/JSS) 

125358-03

125359-03

121656-14

Java Dynamic ManagementTM Kit Runtime

119044-03

119044-03

119046-03

Common Agent Container Runtime 

123893-03

123896-03

123899-03

Sun Java Monitoring Framework (MFWK) 

125444-09

125446-09 (Solaris 10 64–bit)

125445-09 (Solaris 10 32–bit and Solaris 9 32-bit)

125447-09

On Windows, before you upgrade Common Agent Container Runtime shared component, you must run the following command:


cacaoadm.exe prepare-uninstall

Description 

Windows 

Windows Installer Patch 

126910-02

Sun Java Web Console (SJWC) 

125955-05

Network Security Services/Netscape Portable Runtime/Java Security Services (NSS/NSPR/JSS) 

125923-03

Common Agent Container Runtime 

126183-04

Sun Java Monitoring Framework (MFWK) 

125449-09

  1. Shut down any processes using the shared components.

  2. If applicable, shut down the shared components.

  3. Obtain the latest upgrade patches as shown in the table above.

    For more information on how to obtain the patches, see Getting the Software in Sun Java System Directory Server Enterprise Edition 6.2 Release Notes.

  4. Apply the appropriate patches for the shared components.

    Read the README.patchID file for detailed patch installation procedures.

  5. Verify that the patch upgrades were successful.

    Read the README.patchID file for verification procedure.

  6. If applicable, restart the shared components.

ProcedureTo Upgrade Directory Server Enterprise Edition Using Native Packages

Before You Begin

If you already have Directory Server Enterprise Edition 6.0 or 6.1 installed, upgrade to version 6.2 using the following procedure.

You must be root to perform these steps.

All the Directory Server instances, Directory Proxy Server instances, and configuration information remain unaffected after you complete the Directory Server Enterprise Edition upgrade.

The following table displays the patch numbers that are required to upgrade Directory Server Enterprise Edition on different platforms. If newer patch revisions become available, use the newer ones instead of those shown in the table.

Description 

Patch ID: Solaris SPARC 

Patch ID: Solaris x86 

Patch ID: Solaris AMD x64 

Patch ID: Linux 

Patch ID: Windows 

Directory Server Enterprise Edition core 

125276-05

125277-05

125278-05

125309-05

125311-05

Directory Server Enterprise Edition localization 

125937-05

125938-05

125938-05

125939-06

125311-05


Note –

To make the localized Directory Server Enterprise Edition work successfully, install the localized patches before installing the core patches.

Each localization patch contains all the supported languages for the selected platform.


  1. Stop the DSCC registry.

    • On Solaris


      # dsadm stop /var/opt/SUNWdsee/dscc6/dcc/ads
    • On Linux


      # dsadm stop /var/opt/sun/dscc6/dcc/ads
    • On Windows


      dsadm.exe stop C:\Program Files\Sun\JavaES5\DSEE\var\dscc6\dcc\ads
  2. Stop any running instances of Directory Server and Directory Proxy Server.

  3. Upgrade the shared components. See Upgrading Shared Components.

  4. Download the Directory Server Enterprise Edition 6.2 patch.

    See Getting the Software in Sun Java System Directory Server Enterprise Edition 6.2 Release Notes for more details.

  5. Change to the directory where you have saved the patch.

  6. Run the following command to install the patch.

    • Solaris OS

      Before upgrading Directory Server Enterprise Edition, you must install 19254-38 on Solaris 10 SPARC and 119255-38 on Solaris 10 x86. See Getting the Software in Sun Java System Directory Server Enterprise Edition 6.2 Release Notes for information on downloading patches.

      Alternatively, use -G with the patchadd command on Solaris 10 SPARC and Solaris 10 x86 while applying the Directory Server Enterprise Edition upgrade patch.

      For example, # patchadd -G patch-id

      For rest of the Solaris OS, use the following command:

      # patchadd patch-id

    • Linux

      1. Open the directory where the installpatch file is located.

      2. Run installpatch.


        # ./installpatch

      During installation, if installpatch reports an error, you must resolve the error and install the patch again.

    • Windows

      1. Open the folder where the patch-id.exe executable file is located.

      2. Double click patch-id.exe.

      The localized patches are delivered within the base patch.

      After the successful installation of the patch, run the following commands:


      dsccsetup console-unreg
      dsccsetup console-reg
  7. Start the Directory Server instances and Directory Proxy Server instances, if any.

  8. Restart the DSCC registry.


    $ dsadm start install-path/var/dscc6/dcc/ads

Environment Variables

This section lists environment variables that you can set to facilitate creating server instances and using Directory Server Resource Kit and software development kits.

Environment Variable 

Set to include… 

Applies to… 

DIR_PROXY_HOST

Hostname of Directory Proxy Server for administration tools 

dpconf(1M) command

DIR_PROXY_PORT

Port number of Directory Proxy Server for administration tools 

dpconf(1M) command

DIRSERV_HOST

Hostname of Directory Server for administration tools 

dsconf(1M) command

DIRSERV_PORT

Port number of Directory Server or for administration tools 

dsconf(1M) command

LDAP_ADMIN_PWF

Path to the file that contains the directory administrator password 

To administer all servers registered with Directory Service Control Center, set this environment variable to a file containing Directory Service Manager password. 

dpconf(1M), dsconf(1M) commands

LDAP_ADMIN_USER

Directory administrator DN 

To administer all servers registered with Directory Service Control Center, set this environment variable to cn=admin,cn=Administrators,cn=dscc.

If you have not installed DSCC, use cn=admin,cn=Administrators,cn=config for Directory Server, cn=Proxy Manager for Directory Proxy Server.

dpconf(1M), dsconf(1M) commands

MANPATH

install-path/dsee6/man

Online manual pages to browse with the man command

MANSECT

Add any of the following sections not in your MANSECT environment variable.

1:1m:4:5dsconf:5dpconf:5dssd:5dsat:5dsoc

Alternatively, specify the sections to search explicitly when using the man command.

The man command can use the MANSECT environment variable to identify the sections to search by default.

PATH

install-path/dps6/bin

Directory Proxy Server commands 

install-path/ds6/bin

Directory Server commands 

install-path/dscc6/bin

Directory Service Control Center commands 

install-path/dsrk6/bin

Directory Server Resource Kit and LDAP client commands 

Server Instance Creation

After installing server software as described in Software Installation, create server instances. This section contains the following sub sections.

ProcedureTo Create a Directory Server Instance With DSCC

Before You Begin

Install the component software as described in Software Installation.

Non-root users can create server instances.

  1. Access Directory Service Control Center through Java Web Console.

    The default URL for Java Web Console on the local system is https://localhost:6789.

    If you have installed Directory Server Enterprise Edition from the zip distribution, use http://localhost:8080 or https://localhost:8181 to access DSCC based on the application server configuration.

  2. Follow the instructions in the Directory Service Control Center New Server wizard to create the server instance.

    Web-based wizard for creating a Directory Server instance
    Note –

    The instance path does not support non-ASCII characters.


ProcedureTo Create a Directory Server Instance From the Command Line

In this procedure, you create a server instance on the local host using the dsadm command. You then create a suffix that you populate with data using the dsconf command.

Non-root users can create server instances.

A Directory Server instance contains the configuration and data necessary to respond to directory client applications. When you start or stop an instance, you start or stop the server process. The server process is what serves directory client requests corresponding to the data managed by that instance.

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

Before You Begin

Install the component software, then set your PATH as described in Software Installation.

  1. Create a new Directory Server instance.


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

    For example, the following command creates the ds instance under the existing directory, /local/. The new instance has default ports 389 for LDAP, 636 for LDAPS for root users, and 1389 for LDAP, 1636 for LDAPS for non-root users.


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

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

  2. Start the instance.


    $ dsadm start instance-path
    

    For example, the following command starts the instance located under /local/ds/.


    $ dsadm start /local/ds
    Server started: pid=2845
  3. Verify that you can read the root DSA Specific Entry (DSE) of the new instance.


    $ ldapsearch -h localhost -p 1389 -b "" -s base "(objectclass=*)"
    version: 1
    dn:
    objectClass: top
    …
    supportedLDAPVersion: 2
    supportedLDAPVersion: 3
    vendorName: Sun Microsystems, Inc.
    vendorVersion: Sun-Java(tm)-System-Directory/6.2
    …

    Note –

    At this point, you have a working server instance. However, you must further configure the server instance. The instance is not yet registered with Directory Service Control Center.


  4. (Optional) Use the new password policy mode, unless the instance belongs to a replication topology with the Directory Server Enterprise Edition 5 instances.

    Your server instance might be standalone. Alternatively, your instance might belong to a replication topology that has already been migrated to the new password policy mode. In either case, perform this step.


    $ dsconf pwd-compat -h localhost -p 1389 to-DS6-migration-mode
    Certificate "CN=hostname, CN=1636, CN=Directory Server, O=Sun Microsystems"
     presented by the server is not trusted.
    Type "Y" to accept, "y" to accept just once, "n" to refuse, "d" for more details: Y
    Enter "cn=Directory Manager" password:
    ## Beginning password policy compatibility changes.
    ## Password policy compatibility changes finished.
    
    Task completed (slapd exit code: 0).
    $ dsconf pwd-compat -p 1389 to-DS6-mode
    Enter "cn=Directory Manager" password:
    ## Beginning password policy compatibility changes.
    ## Password policy compatibility changes finished.
    
    Task completed (slapd exit code: 0).
  5. (Optional) Prepare an example suffix.

    1. Create an empty suffix.

      For example, the following command creates a suffix with root dc=example,dc=com.


      $ dsconf create-suffix -h localhost -p 1389 dc=example,dc=com
      Enter "cn=Directory Manager" password:
      $ 
    2. Populate the suffix with LDIF data.

      If you plan to populate the suffix with data that is replicated from another Directory Server instance, skip this step.

      For example, the following command fills the suffix that you created with sample data from Example.ldif.


      $ dsconf import -h localhost -p 1389 install-path/ds6/ldif/Example.ldif \
      dc=example,dc=com
      Enter "cn=Directory Manager" password:
      New data will override existing data of the suffix "dc=example,dc=com".
      Initialization will have to be performed on replicated suffixes.
      Do you want to continue [y/n] ?  y
      ## Index buffering enabled with bucket size 40
      ## Beginning import job...
      ## Processing file "install-path/ds6/ldif/Example.ldif"
      ## Finished scanning file "install-path/ds6/ldif/Example.ldif" (160 entries)
      ## Workers finished; cleaning up...
      ## Workers cleaned up.
      ## Cleaning up producer thread...
      ## Indexing complete.
      ## Starting numsubordinates attribute generation.
       This may take a while, please wait for further activity reports.
      ## Numsubordinates attribute generation complete. Flushing caches...
      ## Closing files...
      ## Import complete.  Processed 160 entries in 4 seconds. (40.00 entries/sec)
      
      Task completed (slapd exit code: 0).
    3. Search for the data in the new instance.


      $ ldapsearch -h localhost -p 1389 -b dc=example,dc=com "(uid=bjensen)"
      version: 1
      dn: uid=bjensen, ou=People, dc=example,dc=com
      cn: Barbara Jensen
      cn: Babs Jensen
      sn: Jensen
      givenName: Barbara
      objectClass: top
      objectClass: person
      objectClass: organizationalPerson
      objectClass: inetOrgPerson
      ou: Product Development
      ou: People
      l: Cupertino
      uid: bjensen
      mail: bjensen@example.com
      telephoneNumber: +1 408 555 1862
      facsimileTelephoneNumber: +1 408 555 1992
      roomNumber: 0209
  6. (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 through the URL https://localhost:6789, http://localhost:8080, or https://localhost:8181 as per the type of distribution you have installed and the way your application server is configured.

    • Use the command dsccreg add-server.


      $ dsccreg add-server -h dscchost --description "My DS" /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
      Connecting to /local/ds
      Enabling DSCC access to /local/ds
      Restarting /local/ds
      Registering /local/ds in DSCC on dscchost.

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

  7. (Optional) If you installed from native packages with the Java Enterprise System distribution, enable the server to restart when the operating system reboots.

    On Solaris 10 and Windows systems, use the dsadm enable-service command.


    root# dsadm enable-service /local/ds

    On Solaris 9 and Red Hat systems, use the dsadm autostart command.


    root# dsadm autostart /local/ds

    If you installed with the zip distribution, this step must be done manually, with a script run at system startup time, for example.

Next Steps

You can add more suffixes, configure replication with other server instances, tune the instance, and generally proceed with other configuration operations.

See the online help for Directory Service Control Center for hints on configuring Directory Server through the graphical user interface.

See Part I, Directory Server Administration, in Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide for instructions on configuring Directory Server with command-line administration tools.

ProcedureTo Create a Directory Proxy Server Instance With DSCC

Non-root users can create server instances.

Before You Begin

Install the component software as described in Software Installation.

  1. Access Directory Service Control Center through Java Web Console.

    The default URL for Java Web Console on the local system is https://localhost:6789.

    If you have installed Directory Server Enterprise Edition from the zip distribution, use http://localhost:8080 or https://localhost:8181 to access DSCC based on your application server configuration.

  2. Follow the instructions in the Directory Service Control Center New Server wizard to create the server instance.

    Web-based wizard for creating a Directory Proxy Server instance

ProcedureTo Create a Directory Proxy Server Instance From the Command Line

In this procedure, you create a server instance on the local host using the dpadm command. You then configure the instance using the dpconf command.

Non-root users can create server instances.

A Directory Proxy Server instance must be configured to proxy directory client application requests to data sources through data views. When you start or stop an instance, you start or stop the server process that proxies directory client application requests.

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

The dpconf command is an LDAP client. The command enables you to configure nearly all server settings on a running Directory Proxy 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 dpconf command has subcommands for each key configuration task. For a complete description, see dpconf(1M).

Before You Begin

Install the component software, then set your PATH as described in Software Installation.

  1. Create a new Directory Proxy Server instance.


    $ dpadm create -p port -P SSL-port instance-path
    

    For example, the following command creates an instance, dps, under the existing directory, /local/. The default ports are 389 for LDAP, 636 for LDAPS for root users, and 1389 for LDAP, 1636 for LDAPS for non-root users.


    $ dpadm create -p 1390 -P 1637 /local/dps
    Choose the Proxy Manager password:
    Confirm the Proxy Manager password:
    Use 'dpadm start /local/dps' to start the instance

    Notice that the instance must be created in a directory on the local file system, not a network file system.

  2. Start the instance.


    $ dpadm start instance-path
    

    For example, the following command starts the instance located under /local/dps/.


    $ dpadm start /local/dps
    …
    Directory Proxy Server instance '/local/dps' started: pid=28732
  3. Verify that you can read the root DSE of the new instance.


    $ ldapsearch -h localhost -p 1390 -b "" -s base "(objectclass=*)"
    version: 1
    dn:
    objectClass: top
    objectClass: extensibleObject
    supportedLDAPVersion: 2
    supportedLDAPVersion: 3
    …
    vendorName: Sun Microsystems, Inc
    vendorVersion: Directory Proxy Server 6.2
    …

    Note –

    At this point, you have a working server instance. However, you must further configure the server instance. The instance is not yet registered with Directory Service Control Center.


  4. (Optional) Enable the Directory Proxy Server instance to function as an LDAP proxy.

    1. Create an LDAP data source.

      For example, the following command creates a data source, My DS, pointing to the directory instance created on the local host in To Create a Directory Server Instance From the Command Line.


      $ dpconf create-ldap-data-source -h localhost -p 1390 "My DS" localhost:1389
      Certificate "CN=hostname:1390" presented by the server is not trusted.
      Type "Y" to accept, "y" to accept just once, "n" to refuse, "d" for more details: Y
      Enter "cn=Proxy Manager" password:
    2. Create an LDAP data source pool.


      $ dpconf create-ldap-data-source-pool -h localhost -p 1390 "My Pool"
      Enter "cn=Proxy Manager" password:
    3. Attach the LDAP data source to the LDAP data source pool.


      $ dpconf attach-ldap-data-source -h localhost -p 1390 "My Pool" "My DS"
      Enter "cn=Proxy Manager" password:
    4. Create an LDAP data view using the LDAP data source pool.

      For example, the following command creates a data view, My View, which allows client applications to view the suffix dc=example,dc=com:


      $ dpconf create-ldap-data-view -h localhost -p 1390 "My View" \
       "My Pool" dc=example,dc=com
      Enter "cn=Proxy Manager" password:
    5. Enable the LDAP data source.


      $ dpconf set-ldap-data-source-prop -h localhost -p 1390 "My DS" is-enabled:true
      Enter "cn=Proxy Manager" password:
    6. Restart the server for the change to take effect.


      $ dpadm restart /local/dps
      Directory Proxy Server instance '/local/dps' stopped
      [31/Aug/2006:11:32:26 +0200] - STARTUP    - INFO  -
       Sun Java(TM) System Directory Proxy Server/6.0 (Build 0824060144) starting up
      Directory Proxy Server instance '/local/dps' started: pid=28901
    7. Enable searches on the LDAP data source.


      $ dpconf set-attached-ldap-data-source-prop -h localhost -p 1390 \
       "My Pool" "My DS" search-weight:100
      Enter "cn=Proxy Manager" password:
    8. Verify that you can read directory data through the new instance.


      $ ldapsearch -h localhost -p 1390 -b dc=example,dc=com "(uid=bjensen)"
      version: 1
      dn: uid=bjensen, ou=People, dc=example,dc=com
      cn: Barbara Jensen
      cn: Babs Jensen
      sn: Jensen
      givenName: Barbara
      objectClass: top
      objectClass: person
      objectClass: organizationalPerson
      objectClass: inetOrgPerson
      ou: Product Development
      ou: People
      l: Cupertino
      uid: bjensen
      mail: bjensen@example.com
      telephoneNumber: +1 408 555 1862
      facsimileTelephoneNumber: +1 408 555 1992
      roomNumber: 0209

      Note –

      Notice that LDAP search operations work for the suffix handled by your data view, but do not work for other suffixes. If you search a suffix for which no data view is configured, the server returns an error.


      $ ldapsearch -h localhost -p 1390 -b o=example.com "(uid=bjensen)"
      ldap_search: Operations error
      ldap_search: additional info: Unable to retrieve a backend SEARCH
       connection to process the search request

      For detailed instructions on configuring Directory Proxy Server, see Part II, Directory Proxy Server Administration, in Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide.


  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 Proxy Servers tab.

      Access DSCC through the URL https://localhost:6789, http://localhost:8080, or https://localhost:8181 as per the type of distribution you have installed and the way you have configured application server.

    • Use the command dsccreg add-server.


      $ dsccreg add-server -h dscchost --description "My Proxy" /local/dps
      Enter DSCC administrator's password:
      /local/dps is an instance of DPS
      Enter password of "cn=Proxy Manager" for /local/dps:
      Connecting to /local/dps
      Enabling DSCC access to /local/dps
      Registering /local/dps in DSCC on dscchost.

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

  6. (Optional) If you installed from native packages with the Java Enterprise System distribution, enable the server to restart when the operating system reboots.

    On Solaris 10 and Windows systems, use the dpadm enable-service command.


    root# dpadm enable-service /local/dps

    On Solaris 9 and Red Hat systems, use the dpadm autostart command.


    root# dpadm autostart /local/dps

    If you installed with the zip distribution, this step must be done manually, with a script run at system startup time.

Next Steps

You can continue to configure further data sources and data views. You can also configure load balancing, data distribution, and other server capabilities.

See the online help for Directory Service Control Center for hints on configuring Directory Proxy Server through the graphical user interface.

See Part II, Directory Proxy Server Administration, in Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide for instructions on configuring Directory Proxy Server with command-line administration tools.

Working With Sun Cryptographic Framework on Solaris 10 Systems

This section explains briefly how to use Sun Crypto Accelerator cards through the Sun cryptographic framework on Solaris 10 systems with Directory Server, and Directory Proxy Server. See Chapter 12, Solaris Cryptographic Framework (Overview), in System Administration Guide: Security Services for more information about the framework.

ProcedureTo Use Directory Server With Cryptographic Hardware on a Solaris 10 System

Before You Begin

This procedure is designed for use with Sun Crypto Accelerator hardware. Perform the following procedure as the same user who runs the Directory Server instance.

  1. Set the PIN used to access the cryptographic framework with the pktool setpin command.

  2. Export the current Directory Server certificate to a PKCS#12 file.

    The following command shows how to perform this step if the Directory Server instance is located under /local/ds/.


    $ dsadm export-cert -o cert-file /local/ds defaultCert
  3. Configure Directory Server to use the appropriate token when accessing the key material.

    Typically, the token is Sun Metaslot.


    $ dsconf set-server-prop 'ssl-rsa-security-device:Sun Metaslot'
  4. Stop Directory Server.


    $ dsadm stop /local/ds
  5. (Optional) If you have no other certificates in the existing certificate database for the Directory Server instance, remove the certificate database.


    $ rm -f /local/ds/alias/*.db

    This optional step ensures that no certificates are stored in the software database.

  6. Create a new certificate database backed by the Solaris cryptographic framework.

    If you did not remove the certificate database, you do not need to run the modutil -create line in this example.


    $ /usr/sfw/bin/64/modutil -create -dbdir /local/ds/alias -dbprefix slapd-
    $ /usr/sfw/bin/64/modutil -add "Solaris Kernel Crypto Driver" -libfile \
     /usr/lib/64/libpkcs11.so -dbdir /local/ds/alias -dbprefix slapd-
    $ /usr/sfw/bin/64/modutil -enable "Solaris Kernel Crypto Driver" \
     -dbdir /local/ds/alias -dbprefix slapd-
  7. Import the PKCS#12 certificate that you exported.


    $ /usr/sfw/bin/64/pk12util -i cert-file \
     -d /local/ds/alias -P slapd- -h "Sun Metaslot"
    $ /usr/sfw/bin/64/certutil -M -n "Sun Metaslot:defaultCert" -t CTu \
     -d /local/ds/alias -P slapd-

    If your accelerator board has a FIPS 140-2 keystore, make sure the private key is generated on the device. Sun Crypto Accelerator 4000 and 6000 boards have FIPS 140-2 keystores, for example. The exact process depends on the board.

  8. Create a password file that contains the PIN needed to access the cryptographic framework.


    $ echo "Sun Metaslot:password" > /local/ds/alias/slapd-pin.txt
  9. Start Directory Server.


    $ dsadm start /local/ds

ProcedureTo Use Directory Proxy Server With Cryptographic Hardware on a Solaris 10 System

Before You Begin

This procedure is designed for use with Sun Crypto Accelerator hardware. Perform the following procedure as the same user who runs the Directory Proxy Server instance.

  1. Stop Directory Proxy Server.


    $ dpadm stop /local/dps
  2. Turn off certificate database password storage.


    $ dpadm set-flags /local/dps cert-pwd-prompt=on
    Choose the certificate database password:
    Confirm the certificate database password:
  3. Set the PIN used to access the cryptographic framework with the pktool setpin command.

    Use the same password that you entered when turning off certificate database password storage.

  4. Generate a key pair, using the cryptographic framework as the key store.


    $ keytool -genkeypair -alias defaultDPScert
     -dname "ou=dps server,dc=example,dc=com" -keyalg RSA -sigalg MD5withRSA
     -validity 3652 -storetype PKCS11 -keystore NONE -storepass pin-password
    

    Here, pin-password is the password you set as the PIN with the pktool setpin command.

  5. Edit the Directory Proxy Server configuration file, adding the following attributes to the base entry, cn=config.

    serverCertificateNickName: defaultDPScert
    certificateKeyStore: NONE
    certificateKeyStoreType: PKCS11
  6. Start Directory Proxy Server.


    $ dpadm start /local/dps

Chapter 3 Uninstalling Directory Server Enterprise Edition 6.2

This chapter guides you in removing Directory Server Enterprise Edition software.

This chapter contains the following sections:

Server Instance Removal

Before removing Directory Server Enterprise Edition software used by server instances on the system, you must remove all the server instances.

ProcedureTo Delete a Directory Proxy Server Instance With DSCC

  1. Access Directory Service Control Center through Java Web Console.

    The default URL for Java Web Console on the local system is https://localhost:6789.

    If you have installed Directory Server Enterprise Edition from the zip distribution, use http://localhost:8080 or https://localhost:8181 to access DSCC based on your application server configuration.

  2. Delete the server instance with the Delete command in the action drop-down list.

ProcedureTo Delete a Directory Proxy Server Instance From the Command Line

  1. (Optional) If you have used DSCC to manage the server instance, remove registration for the server.


    $ dsccreg remove-server -h dscchost /local/dps
    Enter DSCC administrator's password:
    /local/dps is an instance of DPS
    Enter password of "cn=Proxy Manager" for /local/dps:
    Unregistering /local/dps from DSCC on dscchost.
    Connecting to /local/dps
    Disabling DSCC access to /local/dps

    For details, see dsccreg(1M)

  2. Delete the server instance.


    $ dpadm delete /local/dps
    Directory Proxy Server instance '/local/dps' stopped
    Directory Proxy Server instance '/local/dps' removed.
See Also

After you have removed all server instances on the system, you can proceed to Software Removal.

ProcedureTo Delete a Directory Server Instance With DSCC

Deleting a Directory Server instance completely removes all instance files, including all directory databases managed by the instance. Before you delete an instance, back up your data as described in Chapter 8, Directory Server Backup and Restore, in Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide.

  1. Access Directory Service Control Center through Java Web Console.

    The default URL for Java Web Console on the local system is https://localhost:6789.

    If you have installed Directory Server Enterprise Edition from the zip distribution, depending on the way you have configured application server, use http://localhost:8080 or https://localhost:8181 to access Directory Service Control Center.

  2. Delete the server instance with the Delete command in the action drop-down list.

ProcedureTo Delete a Directory Server Instance From the Command Line

Deleting a Directory Server instance completely removes all instance files, including all directory databases managed by the instance. Before you delete an instance, back up your data as described in Chapter 8, Directory Server Backup and Restore, in Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide.

  1. (Optional) If you have used DSCC to manage the server instance, remove registration for the server.


    $ dsccreg remove-server -h dscchost /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 dscchost.
    Connecting to /local/ds
    Disabling DSCC access to /local/ds
    Restarting /local/ds

    For details, see dsccreg(1M)

  2. Delete the server instance.


    $ dsadm delete /local/ds
    Server stopped
    /local/ds deleted
See Also

After you have removed all server instances on the system, you can proceed to Software Removal.

Software Removal

After you have removed all server instances that depend on the installed product components, you can remove the component software.

ProcedureTo Remove Directory Service Control Center Software

By removing all of DSCC, you also remove Directory Server packages from the system.

  1. Dismantle DSCC with the dsccsetup dismantle command.

    For example, on a Solaris system the following command dismantles DSCC.


    root# /opt/SUNWdsee/dscc6/bin/dsccsetup dismantle
    ***
    Unregistering DSCC Application from Sun Java(TM) Web Console...
    This operation is going to stop Sun Java(TM) Web Console.
    Do you want to continue ? [y,n] y
    Stopping Sun Java(TM) Web Console...
    Unregistration is on-going. Please wait...
    /var/opt/SUNWdsee/dscc6/dcc has not been removed
    DSCC Application has been unregistered from Sun Java(TM) Web Console
    Restarting Sun Java(TM) Web Console
    Please wait : this may take several seconds...
    Sun Java(TM) Web Console restarted successfully
    ***

    The dsccsetup command is located in install-path/dscc6/bin/dsccsetup. See Default Paths to determine the default install-path for your system.

  2. Remove Directory Service Control Center with the Java ES installer.

    For instructions, see the Java Enterprise System documentation at http://docs.sun.com/coll/1286.3.

    Directory Service Control Center installed from the zip delivery is not uninstalled using the above procedure. If you need to uninstall DSCC, manually remove the WAR file from the application server instance.

ProcedureTo Remove Directory Server, or Directory Proxy Server Installed From Native Packages

  1. Remove the software with the Java ES installer.

    For instructions, see the Java Enterprise System documentation at http://docs.sun.com/coll/1286.3.

ProcedureTo Remove Software Installed From the Zip Distribution

  1. Remove the software with the dsee_deploy(1M) command.

    If zip distribution software was installed by a non-root user, that user can also remove the software.

    For example, to remove all Directory Server Enterprise Edition software installed under /local, issue the following command.


    $ /local/dsee6/bin/dsee_deploy uninstall -i /local
    
See Also

For a full list of supported components, see dsee_deploy(1M).

ProcedureTo Force Removal of Software Installed From the Zip Distribution

Before You Begin

You can force removal by deleting installed files, if you have installed the software from the zip distribution.

If zip distribution software was installed by a non-root user, that user can also remove the software.

Do not directly delete files that are installed from native packages.

  1. Remove components with a system command.


    $ rm -rf install-path
    

Directory Server Enterprise Edition 6.2 Downgrade Instructions

After you upgrade to Directory Server Enterprise Edition 6.2 you might want to restore your previous Directory Server Enterprise Edition installation. This section provides complete information about how to downgrade the Directory Server Enterprise Edition installation.

Downgrading Directory Server Enterprise Edition Using Native Packages

Downgrading Directory Server Enterprise Edition restores the previous working copy of your Directory Server Enterprise Edition instance and retains all your configuration information that you had before upgrading to Directory Server Enterprise Edition 6.2.

To downgrade Directory Server Enterprise Edition, do the following steps:

  1. Stop all running server instances.

  2. Run the following command to remove the patch.

    Remove the localization patch before you remove the base patch to clean up the system.

    • Solaris OS

      # patchrm patch-id

    • Linux. Go to the directory where the Directory Server Enterprise Edition 6.1 or 6.0 .rpm files are stored and run the following command repetitively for all the rpm files as specified in the table below. The set of rpm files that you choose depends on the previous installation of Directory Server Enterprise Edition you had.


      # rpm -U --oldpackage rpm-file-name
      

      For example, if you choose to downgrade to Directory Server Enterprise Edition 6.1 base installation, run the above command repetitively with all the rpm files mentioned in the corresponding cell in the table below. Do not alter the order while executing the commands.

      Localized 6.1 rpm files


      sun-ldap-console-gui-l10n-6.1-3.i386.rpm
      sun-ldap-console-gui-help-l10n-6.1-3.i386.rpm 
      sun-ldap-proxy-client-l10n-6.1-3.i386.rpm
      sun-ldap-proxy-l10n-6.1-3.i386.rpm
      sun-ldap-directory-client-l10n-6.1-3.i386.rpm
      sun-ldap-directory-l10n-6.1-3.i386.rpm
      sun-ldap-shared-l10n-6.1-3.i386.rpm

      Base 6.1 rpm files


      sun-ldap-console-gui-6.0-32.i386.rpm
      sun-ldap-console-gui-help-6.0-32.i386.rpm
      sun-ldap-console-agent-6.0-32.i386.rpm
      sun-ldap-console-cli-6.0-32.i386.rpm
      sun-ldap-proxy-man-6.0-4.i386.rpm
      sun-ldap-proxy-client-6.0-24.i386.rpm
      sun-ldap-proxy-config-6.0-24.i386.rpm
      sun-ldap-proxy-6.0-24.i386.rpm
      sun-ldap-directory-man-6.0-4.i386.rpm
      sun-ldap-directory-client-6.0-32.i386.rpm
      sun-ldap-directory-config-6.0-32.i386.rpm
      sun-ldap-directory-6.0-32.i386.rpm
      sun-ldap-shared-6.0-32.i386.rpm

      Localized 6.0 rpm files


      sun-ldap-console-gui-l10n-6.0-10.i386.rpm
      sun-ldap-console-gui-help-l10n-6.0-10.i386.rpm 
      sun-ldap-proxy-client-l10n-6.0-8.i386.rpm
      sun-ldap-proxy-l10n-6.0-8.i386.rpm
      sun-ldap-directory-client-l10n-6.0-10.i386.rpm
      sun-ldap-directory-l10n-6.0-10.i386.rpm
      sun-ldap-shared-l10n-6.0-10.i386.rpm

      Base 6.0 rpm files


      sun-ldap-console-gui-6.1-2.i386.rpm
      sun-ldap-console-gui-help-6.1-2.i386.rpm
      sun-ldap-console-agent-6.1-2.i386.rpm
      sun-ldap-console-cli-6.1-2.i386.rpm
      sun-ldap-proxy-man-6.1-2.i386.rpm
      sun-ldap-proxy-client-6.1-2.i386.rpm
      sun-ldap-proxy-config-6.1-2.i386.rpm
      sun-ldap-proxy-6.1-2.i386.rpm
      sun-ldap-directory-man-6.1-2.i386.rpm
      sun-ldap-directory-client-6.1-2.i386.rpm
      sun-ldap-directory-config-6.1-2.i386.rpm
      sun-ldap-directory-6.1-2.i386.rpm 
      sun-ldap-shared-6.1-2.i386.rpm

    • Windows. Double-click the Uninstall_patch-id.bat file to remove the patch. The Uninstall_patch-id.bat file is stored in the folder where the patch is saved.

Downgrading Directory Server Enterprise Edition Using Zip Distribution

Directory Server Enterprise Edition 6.2 instance does not downgrade to the previous version. If you need to revert to the previous Directory Server Enterprise Edition version, restore the backup copy that you saved before upgrading to Directory Server Enterprise Edition 6.2.

To remove Directory Server Enterprise Edition completely, see To Remove Software Installed From the Zip Distribution.