Sun Java Enterprise System 2005Q4 Upgrade Guide |
Chapter 4
Directory Server and
Administration ServerThis 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 UpgradesThis 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 2005Q4Java 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.
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:
- Directory Server. Directory Server has dependencies on specific Java ES shared components (see Table 1-6). Directory Server has a dependency on Administration Server, which is used to configure Directory Server replication and other aspects of Directory Server functions.
- Administration Server. Administration Server (and the Administration Console user interface) has dependencies on specific Java ES shared components (see Table 1-6). Administration Server has a dependency on Directory Server (specifically a configuration directory) where it stores configuration data.
Upgrading Directory Server and Administration Server from Java ES Release 3This 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:
- General Upgrade Approach. The upgrade is performed by applying patches to the Java ES Release 3 version. Re-configuration of Directory Server and Administration Server are achieved by synchronizing the configuration directory with the upgraded software.
- Upgrade Dependencies. While Directory Server and Administration Server have dependencies on a number of Java ES shared components (see Table 1-6), Java ES Release 4 Directory Server and Administration Server are compatible with the Release 3 versions of these shared components. Upgrade of these shared components is therefore optional with respect to upgrade of Directory Server and Administration Server to Release 4.
- Backward Compatibility. Release 4 Directory Server and Administration Server are backwardly compatible with their Release 3 versions.
- Upgrade Rollback. A rollback of the Release 4 upgrade is achieved on Solaris by removing the Release 4 upgrade patches and re-synchronizing the configuration directory with the previous software state. On Linux, however, there is no procedure for rolling back the Release 4 upgrade.
- Platform Issues. The general approach for upgrading Directory Server and Administration Server is the same on both Solaris and Linux operating systems, however the patching technologies are different. The upgrade process therefore includes platform-specific procedures.
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:
- Any Java ES components using a Directory Server instance (such as Access Manager, Communications Express, Messaging Server, Portal Server, and so forth) should be shut down before you upgrade that instance. However, most deployment architectures use multiple instances of Directory Server to provide high availability or scalability. In such cases, you can perform a rolling upgrade of Directory Server and the Directory Server clients need not be shut down.
- Administration Server must be upgraded before Directory Server because the re-configuration of data must take place in a particular order.
- The component being upgraded must be shut down when patches are being applied, however the associated configuration directory must subsequently be running to re-configure the component being upgraded.
- In a deployment architecture in which there are multiple instances of Directory Server running on a single computer (all corresponding to the same installed Directory Server image), upgrading the Directory Server image will upgrade all the instances. In such architectures, there is only one Administration Server instance per installed Directory Server image.
- In many deployment architectures the configuration directory is a separate Directory Server instance. It might be local or on a different computer system from where the upgrade is being performed. Similarly, the Administration Server might be local or on a different computer system from where the upgrade of Directory Server is being performed.
- In some deployment architectures Directory Server has been installed standalone by deselecting Administration Server at installation time. In that case, however, the Administration Server upgrade procedure must still be performed (some Administration Server code is installed even in standalone mode), in addition to the Directory Server upgrade procedure, as described in the instructions that follow.
- The Release 4 Directory Server and Administration Server upgrade patches for Solaris OS are shown in the following table:
Table 4-4 Patches1 to Upgrade Directory Server and Administration Server on Solaris
Description
SPARC
Solaris 8, 9, & 10
X86
Solaris 9 & 10
Directory Server
115614-26
115615-26
Directory Server localization
117015-21
117015-21
Administration Server
115610-23
115611-23
Administration Server localization
117047-24
117047-24
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 (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.
- Obtain the required patches, based on Table 4-4.
Patches can be downloaded to /tmp from: http://sunsolve.sun.com/pub-cgi/show.pl?target=patches/patch-access
- Log in as root or become superuser.
su -
- Stop the Administration Console if it is running locally.
- 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.
Components should be shut down in the following order:
- Directory Server clients: Access Manager, Communications Express, Messaging Server, Portal Server, and others
- Directory Proxy Server, if being used to access Directory Server
- Administration Server, if running locally
- Directory Server
- Configuration directory, if running locally as a separate Directory Server instance.
For information about how to shut down a Java ES component, see its respective administration guide.
- 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).
- Upgrade Administration Server.
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).
- Restart the Administration Server to be upgraded.
- Apply the Administration Server patches in Table 4-4.
Be sure to apply the Administration Server localization patch (117047) before applying the Administration Server base patch.
patchadd patch_ID
- Confirm that the patch upgrade was successful:
showrev -p | grep patch_ID
The output should return the versions of patch IDs applied in Step b.
- Ensure that the configuration directory is running.
If it is local you might have to start it up. If it is remote, check to make sure it is running.
- Synchronize the upgraded settings with the configuration directory.
/usr/sbin/mpsadmserver sync-cds
You will be prompted for the admin username and password.
- Upgrade Directory Server.
- If you are running Directory Server in standalone mode, without Administration Server, perform the following procedure, otherwise proceed directly to Step 7b.
- Ensure that you have upgraded Administration Server, Step 6.
- Change directory to the serverroot directory.
cd /var/opt/mps/serverroot
- Create a configuration directory:
mkdir -p admin-serv/config
- Create an adm.config file:
vi admin-serv/config/adm.conf
- Add the following text
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.
- Ensure that the Directory Server instance being upgraded is shut down.
- Apply the Directory Server patches in Table 4-5.
Be sure to apply the Directory Server localization patch (117015) before applying the Directory Server base patch.
patchadd patch_ID
- Confirm that the patch upgrade was successful:
showrev -p | grep patch_ID
The output should return the versions of patch IDs applied in Step c.
- Reset the default Directory Server version number:
/usr/sbin/directoryserver -d 5.2
- Ensure that the configuration directory is running.
If it is local you might have to start it up. If it is remote, check to make sure it is running.
- Synchronize the upgraded settings with the configuration directory.
/usr/sbin/directoryserver -u 5.2 sync-cds
You will be prompted for the admin username and password.
- Restart all Java ES components in the reverse order they were shut down in Step 4.
- Configuration directory, if local and running as a separate Directory Server instance
- Directory Server
- Administration Server, if running locally
- Directory Proxy Server, if being used to access Directory Server
- 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.rpmDirectory 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.rpmAdministration 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.
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.
- 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.
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.
- Log in as root or become superuser.
su -
- Stop the Administration Console if it is running locally.
- 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.
Components should be shut down in the following order:
- Directory Server clients: Access Manager, Communications Express, Messaging Server, Portal Server, and others
- Directory Proxy Server, if being used to access Directory Server
- Administration Server, if running locally
- Directory Server
- Configuration directory, if running locally as a separate Directory Server instance.
For information about how to shut down a Java ES component, see its respective administration guide.
- 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).
- Apply each of the RPMs for Administration Server.
- Apply the RPM for Administration Server: Product.
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.
- Apply the RPM as follows:
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
- If your Administration Server was configured previously, ensure that the configuration directory is running.
If it is local you might have to start it up. If it is remote, check to make sure it is running.
- Synchronize the upgraded settings with the configuration directory.
/opt/sun/sbin/mpsadmserver sync-cds
You will be prompted for the admin username and password.
- Confirm that the upgrade was successful:
rpm -q sun-admin-server
The new version number of the RPM should be returned.
- Apply the RPM for the Administration Server: Console.
rpm -Fvh sun-server-console-5.2-18.i386.rpm
- Apply the RPM for the Administration Server: man pages.
rpm -Uvh sun-admin-server-man-5.2-8.i386.rpm
- Apply each of the RPMs for Directory Server.
- If you are running Directory Server in standalone mode, without Administration Server, apply the Administration Server RPM.
rpm -Fvh sun-admin-server-5.2-18.i386.rpm
Otherwise proceed directly to Step 7b.
- Apply the RPM for the Directory Server: Product.
- Ensure that the Directory Server instance being upgraded is shut down.
- Apply the RPM as follows:
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
- If your Directory Server was configured previously, ensure that the configuration directory is running
If it is local you might have to start it up. If it is remote, check to make sure it is running.
- Synchronize the upgraded settings with the configuration directory.
/opt/sun/sbin/directoryserver sync-cds
You will be prompted for the admin username and password.
- Confirm that the upgrade was successful:
rpm -q sun-directory-server
The new version number of the RPM should be returned.
- Apply the RPM for the Directory Server: man pages.
rpm -Uvh sun-directory-server-man-5.2-9.i386.rpm
- Restart all Java ES components in the reverse order they were shut down in Step 4.
- Configuration directory, if local and running as a separate Directory Server instance
- Directory Server
- Administration Server, if running locally
- Directory Proxy Server, if being used to access Directory Server
- 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)
- Stop the Administration Console if it is running locally.
- 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.
Components should be shut down in the following order:
- Directory Server clients: Access Manager, Communications Express, Messaging Server, Portal Server, and others
- Directory Proxy Server, if being used to access Directory Server
- Administration Server, if running locally
- Directory Server
- Configuration directory, if running locally as a separate Directory Server instance.
For information about how to shut down a Java ES component, see its respective administration guide.
- Roll back the Directory Server upgrade.
- Ensure that the Directory Server instance being rolled back is shut down.
- Remove the Directory Server patches in Table 4-5.
patchrm patch_ID
- Ensure that the configuration directory is running.
If it is local you might have to start it up. If it is remote, check to make sure it is running.
- Synchronize the rolled back settings with the configuration directory.
/usr/sbin/directoryserver -u 5.2 sync-cds
You will be prompted for the admin username and password.
- 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.
- Roll back the Administration Server upgrade.
- Remove the Administration Server patches in Table 4-5.
patchrm patch_ID
- Ensure that the configuration directory is running.
If it is local you might have to start it up. If it is remote, check to make sure it is running.
- Synchronize the upgraded settings with the configuration directory.
/usr/sbin/mpsadmserver sync-cds
You will be prompted for the admin username and password.
- Roll back upgrades to any Java ES components upon which Directory Server and Administration Server have hard upgrade dependencies.
- Restart all Java ES components in the reverse order they were shut down in Step 2.
- Configuration directory, if local and running as a separate Directory Server instance
- Directory Server
- Administration Server, if running locally
- Directory Proxy Server, if being used to access Directory Server
- 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:
- Back up data before performing an upgrade or rollback operation.
- Patch Directory Server and its associated Administration Server on all cluster nodes sequentially rather than in parallel.
- All cluster nodes should run the same version and release of Directory Server and its associated Administration Server.
- If you are running the cluster in failover mode, consider upgrading from HAStorage to HAStoragePlus.
Upgrading Directory Server as a Sun Cluster Data Service
- Stop each Directory Server instance and its associated Administration Server.
serverroot/stop-admin
serverroot/slapd-instanceName/stop-slapd- Make the current cluster node the active node:
scswitch -z -g ldap-group -h this-node-name
- Upgrade Directory Server on the current node as described in Release 3 Directory Server and Administration Server Upgrade.
- Make another cluster node the active node:
scswitch -z -g ldap-group -h another-node-name
Rolling Back Directory Server as a Sun Cluster Data Service
- Stop each Directory Server instance and its associated Administration Server.
serverroot/stop-admin
serverroot/slapd-instanceName/stop-slapd- Make the current cluster node the active node:
scswitch -z -g ldap-group -h this-node-name
- Roll back Directory Server on the current node as described in Rolling Back the Upgrade (Solaris).
- Make another cluster node the active node:
scswitch -z -g ldap-group -h another-node-name
Upgrading Directory Server and Administration Server from Java ES Release 2The 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.