Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java Enterprise System 2005Q4 Upgrade Guide 

Chapter 4
Directory Server and
Administration Server

This chapter describes how to upgrade Directory Server and Administration Server components to Java ES 2005Q4 (Release 4): Sun Java System Directory Server 5.2 2005Q4 and Sun Java System Administration Server 5.2 2005Q4.

These upgrades are documented together because they work closely together.

The chapter provides a general overview of upgrade issues and procedures for the different upgrade paths supported by Java ES Release 4. The chapter covers upgrades on both the Solaris and Linux operating systems:

Overview of Directory Server and Administration Server Upgrades

This section describes the following general aspects of Directory Server and Administration Server components that impact upgrading to Java ES 2005Q4 (Release 4):

About Java ES Release 4

Java ES Release 4 versions of Directory Server and Administration Server represent only minor bug fixes and improvements. There are no new functional capabilities.

Java ES Release 4 Upgrade Roadmap

Table 4-1 shows the supported Directory Server and Administration Server upgrade paths to Java ES Release 4. The table applies to both Solaris and Linux operating systems.

Table 4-1  Upgrade Paths to Java ES Release 4: Sun Java System Directory Server 5.2 2005Q4
and Sun Java System Administration Server 5.2 2005Q4 

Java ES Release

Directory Server, Administration Server, and Directory Proxy Server Version

General Approach

Re-configuration Required

Release 3

Sun Java System Directory Server 5 2005Q1

Sun Java System Administration Server 5 2005Q1

Direct upgrade:
Apply patches and re-configure configuration directory.

Automatic re-configuration of data in configuration directory

Release 2

Sun Java System Directory Server 5.2 2004Q2

Sun Java System Administration Server 5.2 2004Q2

Direct upgrade:
Apply patches and re-configure configuration directory.

Automatic re-configuration of data in configuration directory

Release 1

Sun One Directory Server 5.2

Sun One Administration Server 5.2

Direct upgrade not certified:
But you can use the same approach as upgrading from Release 2.

Automatic re-configuration of data in configuration directory

Pre-dates Java ES releases

Sun One Directory Server 5.2

Sun One Administration Server 5.2

Direct upgrade not certified:
But you can use the same approach as upgrading from Release 2.

Automatic re-configuration of data in configuration directory

Sun One Directory Server 5.1, 5.0, or 4.x

Sun One Administration Server 5.1, 5.0, or 4.x

No direct upgrade:
Upgrade first to Release 3. Refer to the Java Enterprise System 2005Q1 Upgrade and Migration Guide
(http://docs.sun.com/doc/819-0062).

Then upgrade from Release 3 to Release 4.

Refer to theJava Enterprise System 2005Q1 Upgrade and Migration Guide
(http://docs.sun.com/doc/819-0062).

Directory Server and Administration Server Data

Directory Server and Administration Server make use of Directory Server itself for storing configuration data. The data is stored in a specific tree structure within the directory. The Directory Server instance hosting the configuration is referred to as the configuration directory.

The configuration directory can be a dedicated Directory Server instance, which is a recommended security practice, or it can also host user identity data or service configuration data. The configuration directory can reside on the same computer as other Directory Server instances or the Administration Server; however in most deployment architectures, the configuration directory is remote from the other components that use it to store configuration information.

The following table shows the type of data that could be impacted by an upgrade of Directory Server and Administration Server software.

Table 4-2  Directory Server, Administration Server, and Directory Proxy Server Data Usage

Type of Data

Location

Usage

Directory Server configuration data

Configuration directory

Configuration of Directory Server

Administration Server configuration data

Configuration directory

Configuration of Administration Server

Compatibility Issues

Java ES Release 4 Directory Server and Administration Server do not introduce any interface changes. These components are, as a group, backwardly compatible with earlier versions. However, both of these components are not backwardly compatible with earlier versions of the others; both need to be upgraded as a unit.

Dependencies

Dependencies on other Java ES components can impact the procedure for upgrading and re-configuring Directory Server and Administration Server software. Each of these components has dependencies on Java ES components as follows:

Upgrading Directory Server and Administration Server from Java ES Release 3

This section includes information about upgrading Directory Server and Administration Server from Java ES 2005 Q1 (Release 3) to Java ES 2005Q4 (Release 4). The section covers the following topics:

Introduction

When upgrading Java ES Release 3 Directory Server and Administration Server to Release 4, consider the following aspects of the upgrade process:

Release 3 Directory Server and Administration Server Upgrade

This section describes how to perform an upgrade of Directory Server and Administration Server from Java ES Release 3 to Java ES Release 4 on both the Solaris and Linux platform. Where a topic depends on platform-specific procedures, the topic will indicate the operating system to which it applies. The section covers the following topics:

Pre-Upgrade Tasks

Before you upgrade Directory Server and Administration Server, you should perform the tasks described below.

Verify Current Version Information

You can verify the current version of Directory Server and Administration Server by restarting the Directory Server daemon using the -v option:

and then checking the startup messages in the Directory Server error log:

Note: If the ns-slapd command fails on the Solaris 10 platform, set the library path to null when running the command:

Upgrade Directory Server and Administration Server Dependencies

It is generally recommended that all Java ES components on a computer system (and in a computing environment) be upgraded to Java ES Release 4. However, because Directory Server and Administration Server do not require upgrading Release 3 shared components, this task is optional.

Back Up Directory Server Data

The Directory Server and Administration Server upgrade process modifies configuration directory data. Therefore, before you upgrade, it is recommended that you back up your configuration directory data using the Directory Server Console or a command-line utility such as db2bak.

For more information about backing up Directory Server, see the Sun Java System Directory Server Administration Guide (http://docs.sun.com/doc/817-7613).

Obtain Required Configuration Information and Passwords

You should know the Directory Server administrator user ID and password for your currently installed version.

In addition, Directory Server and Administration Server must run as the same user and group. That is, they must run with the same UID and GID.

Upgrading Release 3 Directory Server and Administration Server (Solaris)

This section discusses considerations that impact the upgrade procedure for Directory Server and Administration Server, followed by a description of the procedure itself.

Upgrade Considerations (Solaris)

The upgrade of Directory Server and Administration Server software to Java ES Release 4 takes into account the following considerations:

Upgrade Procedure (Solaris)

The procedure documented below applies to Directory Server and Administration Server instances residing locally on the computer where the upgrade is taking place.

The steps below make use of two commands: directoryserver(1m) and mpsadmserver(1m). For more information about these commands, see the Directory Server Man Page Reference and the Administration Server Man Page Reference.

  1. Obtain the required patches, based on Table 4-4.

    2. Patches can be downloaded to /tmp from: http://sunsolve.sun.com/pub-cgi/show.pl?target=patches/patch-access

  2. Log in as root or become superuser.

    3. su -

  3. Stop the Administration Console if it is running locally.
  4. Shut down all Java ES components dependent on the Directory Server instances that are to be upgraded. This step might depend on how these components are replicated within your deployment architecture.

    5. Components should be shut down in the following order:

    1. Directory Server clients: Access Manager, Communications Express, Messaging Server, Portal Server, and others
    2. Directory Proxy Server, if being used to access Directory Server
    3. Administration Server, if running locally
    4. Directory Server
    5. Configuration directory, if running locally as a separate Directory Server instance.

      6. For information about how to shut down a Java ES component, see its respective administration guide.

  5. Make sure you have upgraded any Java ES components upon which Directory Server and Administration Server have hard upgrade dependencies (see Upgrade Directory Server and Administration Server Dependencies).
  6. Upgrade Administration Server.

    7. You need to perform this step even if Directory Server had originally been installed in standalone mode on the computer where the upgrade is taking place (some Administration Server code is installed even in standalone mode).

    1. Restart the Administration Server to be upgraded.
    2. Apply the Administration Server patches in Table 4-4.

      3. Be sure to apply the Administration Server localization patch (117047) before applying the Administration Server base patch.

      patchadd patch_ID

    3. Confirm that the patch upgrade was successful:

      4. showrev -p | grep patch_ID

      The output should return the versions of patch IDs applied in Step b.

    4. Ensure that the configuration directory is running.

      5. If it is local you might have to start it up. If it is remote, check to make sure it is running.

    5. Synchronize the upgraded settings with the configuration directory.

      6. /usr/sbin/mpsadmserver sync-cds

      You will be prompted for the admin username and password.

  7. Upgrade Directory Server.
    1. If you are running Directory Server in standalone mode, without Administration Server, perform the following procedure, otherwise proceed directly to Step 7b.
      1. Ensure that you have upgraded Administration Server, Step 6.
      2. Change directory to the serverroot directory.

        3. cd /var/opt/mps/serverroot

      3. Create a configuration directory:

        4. mkdir -p admin-serv/config

      4. Create an adm.config file:

        5. vi admin-serv/config/adm.conf

      5. Add the following text

        6. isie: cn=Administration Server, cn=Server Group, cn=hostname, ou=administration_domain, o=NetscapeRoot

        All on one line where hostname is the fully qualified Directory Server host name and administration_domain is typically the host’s domain name.

    2. Ensure that the Directory Server instance being upgraded is shut down.
    3. Apply the Directory Server patches in Table 4-5.

      4. Be sure to apply the Directory Server localization patch (117015) before applying the Directory Server base patch.

      patchadd patch_ID

    4. Confirm that the patch upgrade was successful:

      5. showrev -p | grep patch_ID

      The output should return the versions of patch IDs applied in Step c.

    5. Reset the default Directory Server version number:

      6. /usr/sbin/directoryserver -d 5.2

    6. Ensure that the configuration directory is running.

      7. If it is local you might have to start it up. If it is remote, check to make sure it is running.

    7. Synchronize the upgraded settings with the configuration directory.

      8. /usr/sbin/directoryserver -u 5.2 sync-cds

      You will be prompted for the admin username and password.

  8. Restart all Java ES components in the reverse order they were shut down in Step 4.
    1. Configuration directory, if local and running as a separate Directory Server instance
    2. Directory Server
    3. Administration Server, if running locally
    4. Directory Proxy Server, if being used to access Directory Server
    5. Directory Server clients: Access Manager, Communications Express, Messaging Server, Portal Server, and others

Upgrading Release 3 Directory Server and Administration Server (Linux)

This section discusses considerations that impact the upgrade procedure for Directory Server and Administration Server, followed by a description of the procedure itself.

Upgrade Considerations (Linux)

The upgrade of Directory Server and its associated components to Java ES Release 4 on the Linux platform takes into account the same considerations as on the Solaris platform (see Upgrade Considerations (Solaris)), except that the Linux Release 4 upgrade patches differ from the Solaris patches.

The Release 4 Directory Server and Administration Server upgrade patches for Linux OS are shown in the following table:

Table 4-5  Patches1 to Upgrade Directory Server and Administration Server on Linux 

Description

Patch ID and RPM names

Directory Server

118080-11:

sun-directory-server-5.2-25.i386.rpm
sun-directory-server-man-5.2-9.i386.rpm

Directory Server localization

118290-12:

sun-directory-server-Locale-5.2-17.i386.rpm

Administration Server

118079-10:

sun-admin-server-5.2-18.i386.rpm
sun-server-console-5.2-18.i386.rpm
sun-admin-server-man-5.2-8.i386.rpm

Administration Server localization

118289-13:

sun-admin-server-Locale-5.2-19.i386.rpm
sun-server-console-Locale-5.2-19.i386.rpm

1Patch revision numbers are the minimum required for upgrade to Java ES Release 4. If newer revisions become available, use the newer ones instead of those shown in the table.

Upgrade Procedure (Linux)

The procedure documented below applies Directory Server and Administration Server instances residing locally on the computer where the upgrade is taking place.

Caution

An upgrade from Java ES Release 3 to Java ES Release 4 on Linux cannot be rolled back.

The steps below make use of two commands: directoryserver(1m) and mpsadmserver(1m). For more information about these commands, see the Directory Server Man Page Reference and the Administration Server Man Page Reference.

  1. Obtain the required patches using the patch numbers and RPM names from Table 4-5. Use this information to obtain the version numbers for the RPM.

    2. Patches can be downloaded to /tmp from: http://sunsolve.sun.com/pub-cgi/show.pl?target=patches/patch-access

    In the following procedure oldVersion signifies the RPM for the Release 3 version of Directory Server and Administration Server.

  2. Log in as root or become superuser.

    3. su -

  3. Stop the Administration Console if it is running locally.
  4. Shut down all Java ES components dependent on the Directory Server instances that are to be upgraded. This step might depend on how these components are replicated within your deployment architecture.

    5. Components should be shut down in the following order:

    1. Directory Server clients: Access Manager, Communications Express, Messaging Server, Portal Server, and others
    2. Directory Proxy Server, if being used to access Directory Server
    3. Administration Server, if running locally
    4. Directory Server
    5. Configuration directory, if running locally as a separate Directory Server instance.

      6. For information about how to shut down a Java ES component, see its respective administration guide.

  5. Make sure you have upgraded any Java ES components upon which Directory Server and Administration Server have hard upgrade dependencies (see Upgrade Directory Server and Administration Server Dependencies).
  6. Apply each of the RPMs for Administration Server.
    1. Apply the RPM for Administration Server: Product.

      2. You need to perform this step even if Directory Server had originally been installed in standalone mode on the computer where the upgrade is taking place.

      1. Apply the RPM as follows:

        2. Be sure to apply the Administration Server localization RPMs (118289) before applying the Administration Server base RPMs.

        rpm -Fvh sun-admin-server-Locale-5.2-19.i386.rpm
        rpm -Fvh sun-server-console-Locale-5.2-19.i386.rpm
        rpm -Fvh sun-admin-server-5.2-18.i386.rpm
        ...

        If your Administration Server was configured previously, the following error will be returned:

        error: execution of %preun scriptlet from sun-admin-server-5.2-oldVersion failed, exit status 1

        If this is the case, remove the old version of the RPM using the --noscripts option, as follows:

        rpm -e --noscripts sun-admin-server-5.2-oldVersion

      2. If your Administration Server was configured previously, ensure that the configuration directory is running.

        3. If it is local you might have to start it up. If it is remote, check to make sure it is running.

      3. Synchronize the upgraded settings with the configuration directory.

        4. /opt/sun/sbin/mpsadmserver sync-cds

        You will be prompted for the admin username and password.

      4. Confirm that the upgrade was successful:

        5. rpm -q sun-admin-server

        The new version number of the RPM should be returned.

    2. Apply the RPM for the Administration Server: Console.

      3. rpm -Fvh sun-server-console-5.2-18.i386.rpm

    3. Apply the RPM for the Administration Server: man pages.

      4. rpm -Uvh sun-admin-server-man-5.2-8.i386.rpm

  7. Apply each of the RPMs for Directory Server.
    1. If you are running Directory Server in standalone mode, without Administration Server, apply the Administration Server RPM.

      2. rpm -Fvh sun-admin-server-5.2-18.i386.rpm

      Otherwise proceed directly to Step 7b.

    2. Apply the RPM for the Directory Server: Product.
      1. Ensure that the Directory Server instance being upgraded is shut down.
      2. Apply the RPM as follows:

        3. Be sure to apply the Directory Server localization RPMs (118290) before applying the Directory Server RPMs.

        rpm -Fvh sun-directory-server-Locale-5.2-17.i386.rpm
        rpm -Fvh sun-directory-server-5.2-25.i386.rpm
        ...

        If your Directory Server was configured previously, the following error will be returned:

        error: execution of %preun scriptlet from sun-directory-server-5.2-oldVersion failed, exit status 1

        If this is the case, remove the old version of the RPM using the --noscripts option, as follows:

        rpm -e --noscripts sun-directory-server-5.2-oldVersion

      3. If your Directory Server was configured previously, ensure that the configuration directory is running

        4. If it is local you might have to start it up. If it is remote, check to make sure it is running.

      4. Synchronize the upgraded settings with the configuration directory.

        5. /opt/sun/sbin/directoryserver sync-cds

        You will be prompted for the admin username and password.

      5. Confirm that the upgrade was successful:

        6. rpm -q sun-directory-server

        The new version number of the RPM should be returned.

    3. Apply the RPM for the Directory Server: man pages.

      4. rpm -Uvh sun-directory-server-man-5.2-9.i386.rpm

  8. Restart all Java ES components in the reverse order they were shut down in Step 4.
    1. Configuration directory, if local and running as a separate Directory Server instance
    2. Directory Server
    3. Administration Server, if running locally
    4. Directory Proxy Server, if being used to access Directory Server
    5. Directory Server clients: Access Manager, Communications Express, Messaging Server, Portal Server, and others

Verifying the Upgrade

You can verify successful upgrade of Directory Server and Administration Server by restarting the Directory Server daemon using the -v option:

and then checking the startup messages in the Directory Server error log:

See Table 4-3 for output values.

Post-Upgrade Tasks

There are no post-upgrade tasks beyond the steps described in Upgrade Procedure (Solaris) and Upgrade Procedure (Linux).

Rolling Back the Upgrade (Solaris)

This section describes considerations that impact the upgrade rollback procedure for Directory Server and Administration Server, followed by the procedure itself.

Rollback Considerations (Solaris)

The procedure for rolling back the upgrade to Release 4 of Directory Server and Administration Server is pretty much the reverse of the procedure for upgrading to Release 4. The patches are removed and the configuration directory is re-synchronized.

One special consideration is that when you apply patches, you upgrade the SSL certificate database to a cert8 format. The patch backs up the cert7 data, and then converts it to cert8 format. If you subsequently decide to roll back the upgrade and have added new certificates to the certificate database, you should manually extract these certificates, back out the patches, and then add the certificates back to the previous cert7 format certificate database.

When you roll back an upgrade after having changed the SSL certificate database, you cannot start in SSL mode. To work around this problem, turn off SSL mode, restart Directory Server and Administration Server, reinstall the certificate, and then enable SSL mode.

Rollback Procedure (Solaris)
  1. Stop the Administration Console if it is running locally.
  2. Shut down all Java ES components dependent on the Directory Server instances that are to be rolled back. This step depends on how these components are replicated within your deployment architecture.

    3. Components should be shut down in the following order:

    1. Directory Server clients: Access Manager, Communications Express, Messaging Server, Portal Server, and others
    2. Directory Proxy Server, if being used to access Directory Server
    3. Administration Server, if running locally
    4. Directory Server
    5. Configuration directory, if running locally as a separate Directory Server instance.

      6. For information about how to shut down a Java ES component, see its respective administration guide.

  3. Roll back the Directory Server upgrade.
    1. Ensure that the Directory Server instance being rolled back is shut down.
    2. Remove the Directory Server patches in Table 4-5.

      3. patchrm patch_ID

    3. Ensure that the configuration directory is running.

      4. If it is local you might have to start it up. If it is remote, check to make sure it is running.

    4. Synchronize the rolled back settings with the configuration directory.

      5. /usr/sbin/directoryserver -u 5.2 sync-cds

      You will be prompted for the admin username and password.

    5. If you are running Directory Server standalone, without Administration Server, you must roll back the partial Administration Server upgrade, follow the instructions in Step 4.
  4. Roll back the Administration Server upgrade.
    1. Remove the Administration Server patches in Table 4-5.

      2. patchrm patch_ID

    2. Ensure that the configuration directory is running.

      3. If it is local you might have to start it up. If it is remote, check to make sure it is running.

    3. Synchronize the upgraded settings with the configuration directory.

      4. /usr/sbin/mpsadmserver sync-cds

      You will be prompted for the admin username and password.

  5. Roll back upgrades to any Java ES components upon which Directory Server and Administration Server have hard upgrade dependencies.
  6. Restart all Java ES components in the reverse order they were shut down in Step 2.
    1. Configuration directory, if local and running as a separate Directory Server instance
    2. Directory Server
    3. Administration Server, if running locally
    4. Directory Proxy Server, if being used to access Directory Server
    5. Directory Server clients: Access Manager, Communications Express, Messaging Server, Portal Server, and others

Multiple Instance Upgrades

The procedures in Release 3 Directory Server and Administration Server Upgrade do not explicitly deal with deployment architectures in which Directory Server is replicated for availability or scalability. These architectures might include Directory Server multi-master replication or the deployment of Directory Server as a data service in a Sun Cluster environment.

This section discusses Directory Server upgrades in these situation.

Rolling Upgrades of Multimaster Replicates

Multiple instances of Directory Server on different computer systems, as used in multimaster replication deployment architectures, can be sequentially upgraded one instance at a time. The upgrade of each instance on its respective host computer is performed while the other instances are left running. This rolling upgrade allows the directory service to remain online while the individual Directory Server instances that provide the service are being upgraded.

Upgrading Directory Server as a Data Service

This section describes how to upgrade and roll back Directory Server as a data service in a Sun Cluster environment. Consider the following points before you upgrade or back out Directory Server as a Sun Cluster data service:

Upgrading Directory Server as a Sun Cluster Data Service
  1. Stop each Directory Server instance and its associated Administration Server.

    2. serverroot/stop-admin
    serverroot/slapd-    instanceName/stop-slapd

  2. Make the current cluster node the active node:

    3. scswitch -z -g ldap-group -h this-node-name

  3. Upgrade Directory Server on the current node as described in Release 3 Directory Server and Administration Server Upgrade.
  4. Make another cluster node the active node:

    5. scswitch -z -g ldap-group -h another-node-name

  5. Repeat Step 3 and Step 4 until all nodes in the cluster are upgraded.
Rolling Back Directory Server as a Sun Cluster Data Service
  1. Stop each Directory Server instance and its associated Administration Server.

    2. serverroot/stop-admin
    serverroot/slapd-    instanceName/stop-slapd

  2. Make the current cluster node the active node:

    3. scswitch -z -g ldap-group -h this-node-name

  3. Roll back Directory Server on the current node as described in Rolling Back the Upgrade (Solaris).
  4. Make another cluster node the active node:

    5. scswitch -z -g ldap-group -h another-node-name

  5. Repeat Step 3 and Step 4 until Directory Server is rolled back on all nodes in the cluster.

Upgrading Directory Server and Administration Server from Java ES Release 2

The procedure for upgrading Java ES 2004Q2 (Release 2) Directory Server and Administration Server to Release 4 is the same as that for upgrading Release 3 Directory Server and Administration Server to Release 4, with the exception that the pre-upgrade tasks should include the upgrading to Release 4 of all shared components (see Table 1-6) and all locally-resident product components upon which Directory Server and Administration Server depend:

Instructions for upgrading Java ES shared components to Release 4 are provided in Chapter 2, "Upgrading Java ES Shared Components".

To upgrade Release 2 Directory Server and Administration Server to Release 4, use the instructions in Upgrading Directory Server and Administration Server from Java ES Release 3, except substitute Release 2 wherever Release 3 is referenced.



Previous      Contents      Index      Next     

Part No: 819-2331-13.   Copyright 2006 Sun Microsystems, Inc. All rights reserved.