|
| |
| Sun Java Enterprise System 5 Upgrade Guide for UNIX | |
Chapter 5
Directory ServerThis chapter describes how to upgrade Directory Server to Java ES 5 (Release 5): Sun Java System Directory Server 6.0.
The chapter provides an overview of upgrade considerations for the different upgrade paths supported by Release 5. The chapter covers upgrades on both the Solaris and Linux operating systems:
Overview of Directory Server UpgradesThis section describes the following general aspects of Directory Server that impacts upgrading to Java ES 5 (Release 5):
About Java ES Release 5
Java ES Release 5 Directory Server represents a major release, with a variety of new features and improvements. See the Directory Server Enterprise Edition 6 Release Notes, http://docs.sun.com/doc/819-0991 for details.
Java ES Release 5 Upgrade Roadmap
Table 5-2 shows the supported Directory Server upgrade paths to Java ES Release 5. The table applies to both Solaris and Linux operating systems.
Table 5-2 Upgrade Paths to Java ES 5 (Release 5): Directory Server 6.0
Java ES Release
Directory Server Version
General Approach
Reconfiguration Required
Release 4
Sun Java System Directory Server 5.2 2005Q4
Sun Java System Administration Server 5.2 2005Q4
Direct upgrade:
Fresh install and migration of all data.Administration Server functionality replaced by Directory Service Control Center and Directory Server EE command-line utilities.
Configuration data migrated from previous version to newly installed Directory Server
Release 3
Sun Java System Directory Server 5 2005Q1
Sun Java System Administration Server 5 2005Q1
Direct upgrade:
Fresh install and migration of all data.Administration Server functionality replaced by Directory Service Control Center and Directory Server EE command-line utilities.
Configuration data migrated from previous version to newly installed Directory Server
Release 2
Sun Java System Directory Server 5.2 2004Q2
Sun Java System Administration Server 5.2 2004Q2
Direct upgrade:
Fresh install and migration of all data.Administration Server functionality replaced by Directory Service Control Center and Directory Server EE command-line utilities.
Configuration data migrated from previous version to newly installed Directory Server
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.Configuration data migrated from previous version to newly installed Directory Server
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.Configuration data migrated from previous version to newly installed Directory Server
Sun ONE Directory Server 5.1
Sun ONE Administration Server 5.1
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 5.
Refer to the Java Enterprise System 2005Q1 Upgrade and Migration Guide, http://docs.sun.com/doc/819-0062.
Directory Server Data
Directory Server 5.x versions made use of Directory Server itself for storing configuration data. The data was stored in a specific tree structure within the directory. The Directory Server instance hosting the configuration was referred to as the configuration directory. The configuration directory could reside on the same computer as other Directory Server instances; however in most deployment architectures, the configuration directory was remote from the other components that use it to store configuration information.
Directory Server 6.0 no longer stores configuration data in a configuration directory. Configuration is performed using the Directory Service Control Center (or the Directory Server EE command-line utilities), and should be accessed through this interface. Directory Service Control Center stores configuration data in its own local Directory Server instance.
The following table shows the type of data that is impacted by an upgrade of Directory Server software to Release 5.
Directory Server Upgrade Strategy
Your strategy for upgrading Directory Server generally depends on the many considerations discussed in Chapter 1, "Planning for Upgrades": upgrade path, dependencies between Java ES components, selective upgrade versus upgrade all, multi-instance deployments, and so forth.
This section is to particularize that general discussion to Directory Server by presenting issues that might influence your Directory Server upgrade plan.
Compatibility Issues
Java ES Release 5 Directory Server does not introduce new public interfaces and is therefore backwardly compatible with earlier versions; it supports all components supported by Release 4 Directory Server and earlier versions.
However, Release 5 introduces changes to private administrative interfaces. The Release 5 interfaces are incompatible with earlier releases of Directory Server. In particular, the Administration Server, used to configure earlier Directory Server instances, has been replaced by the Directory Service Control Center and Directory Server EE command-line utilities, and the o=NetscapeRoot directory suffix for storing Directory Server configuration information has been eliminated. Details can be found in the Directory Server Enterprise Edition 6 Migration Guide, http://docs.sun.com/doc/819-0994.
Dependencies
Dependencies on other Java ES components can, in general, impact the procedure for upgrading Directory Server software.
Directory Server has dependencies on the following Java ES components:
- Shared components. Directory Server has dependencies on specific Java ES shared components (see Table 1-9). Directory Server upgrades might depend upon upgraded versions of these shared components.
- Directory Proxy Server. Directory Server has a co-dependency on Directory Proxy Server for providing improved security and performance for LDAP requests.
Dual Upgrade
Dual upgrades, in which both Directory Server and operating system are upgraded (as described in Dual Upgrades: Java ES and Operating System Softwared) can be performed in either of two ways:
Fresh Operating System Installation
- Back up the existing Directory Server data.
See Create Directory Server Image (Optional) regarding Directory Server 5.x information.
- Install the new operating system.
The operating system installation can be on a new system (or a Solaris 10 zone) or it can wipe out the existing file system.
- Restore the Directory Server data that was backed up in Step 1.
- Install Release 5 Directory Server.
- Create a Release 5 Directory Server instance and migrate directory data to the new instance.
See the relevant steps in the procedure for Upgrading Release 4 Directory Server.
In-place Operating System Upgrade
- Back up the existing Directory Server data.
See Create Directory Server Image (Optional) regarding Directory Server 5.x information.
- Upgrade the operating system.
The upgrade leaves the existing file system in place.
- Upgrade to Release 5 Directory Server.
See the relevant section of this chapter, depending on upgrade path.
Upgrading Directory Server from Java ES Release 4This section includes information about upgrading Directory Server from Java ES 2005 Q4 (Release 4) to Java ES 5 (Release 5). The section covers the following topics:
Introduction
When upgrading Java ES Release 4 Directory Server to Release 5, consider the following aspects of the upgrade process:
- General Upgrade Approach. The upgrade is achieved by performing a fresh install of Release 5 Directory Server and then using migration tools to re-create the previous Directory Server instances in new, distinct Release 5 Directory Server instances.
- Upgrade Dependencies. Directory Server has dependencies on a number of Java ES shared components (see Table 1-9), all of which are automatically upgraded to Release 5 by the Java ES installer when you perform an upgrade of Directory Server.
- Backward Compatibility. Release 5 Directory Server is not backwardly compatible with the Release 4 version, as described in Compatibility Issues. However, the migration tools make it possible to migrate the o=NescapeRoot suffix if you continue to maintain a set of Directory Server instances relying on the Directory Server 5.x administration framework.
- Upgrade Rollback. A rollback of the Release 5 upgrade is achieved by reverting to the previous version, which is left intact by the upgrade to Release 5.
- Platform Issues. The general approach for upgrading Directory Server is the same on both Solaris and Linux operating systems.
Release 4 Directory Server Upgrade
This section describes how to perform an upgrade of Directory Server from Java ES Release 4 to Java ES Release 5 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 software you should perform the following tasks:
Verify Current Version Information
You can verify the current version of Directory Server by restarting the Directory Server daemon using the -v option:
cd serverRoot/bin/slapd/server
./ns-slapd -v
If the ns-slapd command fails on the Solaris 10 platform, set the library path to null when running the command:
LD_LIBRARY_PATH= ./ns-slapd -v
Upgrade Directory 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 5. However, all shared components required by Directory Server are upgraded automatically when you perform an upgrade of Directory Server to Release 5.
Obtain Required Configuration Information and Passwords
You should know the Directory Server administrator user ID and password for your currently installed version. Other configuration information is preserved through the upgrade process.
Create Directory Server Image (Optional)
In cases where Release 5 Directory Server is being installed on a computer different from where the Release 4 version resides, an image of the Release 4 version should be created on the computer where Release 5 Directory Server is being installed. The image is needed to automate data migration (using the dsmig command) to the new Release 5 Directory Server instances.
The Release 4 image includes all schema files, configuration files, security files, and database files, in an identical layout to the original Directory Server 5.x serverRoot file structure. The image is needed to perform data migration to the new Release 5 Directory Server instances.
Upgrading Release 4 Directory Server
This section discusses considerations that impact the upgrade procedure for Directory Server, followed by a description of the procedure itself.
Upgrade Considerations
The upgrade of Directory Server software to Java ES Release 5 takes into account the following considerations:
- Any Java ES components using a Directory Server instance (such as Access Manager or Portal Server, or Sun Java Communications Suite components) should be shut down and re-configured, if needed, to access the corresponding new Release 5 instance.
- 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), you only have to upgrade the Directory Server image once; however, you have to separately migrate the data for each of the instances.
- In many Release 4 Directory Server deployment architectures the configuration directory is a separate Directory Server instance. These instances do not need to be upgraded because the configuration directory has been deprecated in Release 5. On the other hand, the upgrade might entail the deployment of the Release 5 Directory Server administrative console (the Directory Service Control Center) to a separate computer from which you remotely manage Directory Server instances.
- A command line tool is provided with Directory Server, which helps automate the migration of schema, configuration, security and user data. The migration tool allows a step by step migration of these different data. Most upgrade scenarios benefit from automated migration of at least some of the data.
Upgrade Procedure
The procedure documented below applies to Directory Server instances residing locally on the computer where the upgrade is taking place, or in the case where instances are moving to another computer, all instances that will run on the target computer.
- Log in as root or become superuser.
su -
- Shut down the Release 4 Directory Server (5.2) instances.
serverRoot/slapd-instanceName/stop-slapd
Check that the error log (serverRoot/slapd-hostName/logs/errors) reports a clean shutdown:
[23/Jan/2006:15:56:47 +0100] - All database threads now stopped
[23/Jan/2006:15:56:50 +0100] - slapd stopped.
- Ensure that the host computer for Release 5 Directory Server has sufficient disk space.
The basic calculation is as follows:
2 * (space for existing server) + (space for LDIF files)There is unfortunately no tool allowing to anticipate the size of an LDIF file created from an exported database. The size will depend upon the number of data entries, their internal representation, the number of indexes, and so forth.
- For remote install of Release 5, create a Release 4 image and transfer it to the remote computer.
See Create Directory Server Image (Optional).
- Make sure you have upgraded any Java ES components upon which Directory Server has hard upgrade dependencies (see Upgrade Directory Server Dependencies).
- Perform a fresh install of Release 5 Directory Server.
Perform the following steps:
- Launch the Java ES installer.
where os_arch matches your platform, such as Solaris_sparc. (Use the installer -nodisplay option for the command line interface.)
After the Welcome and License Agreement pages are displayed, you will be presented with a component selection page. (When installed components are detected that can be directly upgraded by the Java ES installer, they are shown with a status of “upgradable.”)
- Select the Directory Server subcomponent of Directory Server Enterprise Edition.
You will also need to install the administrative subcomponents (Directory Service Control Panel or command line utilities) you wish to use.
- Specify an installation path different from that of any existing Release 4 Directory Server.
- Choose to Configure Now or Configure Later.
It does not matter whether you choose to Configure Now or to Configure Later because there is really no configuration required for Directory Server. However, if you choose to Configure Now, do not opt to create a new instance.
- Confirm your installation choices.
Directory Server packages will be upgraded and an upgrade summary displayed.
- Exit the Java ES installer.
- Create a Directory Server instance.
DirServer-base/ds6/bin/dsadm create instancePath
where instancePath is the full path to the Directory Server instance.
For information on creating a Directory Server instance, see the Directory Server Enterprise Edition 6 Administration Guide, http://docs.sun.com/doc/819-0995.
If you fail to create a new instance, a new instance will automatically be created for you when you migrate data with the dsmig command (Step 8).
If the dsadm command fails on the Solaris 10 platform, set the library path to null when running the command:
LD_LIBRARY_PATH= ./dsadm create instancePath
- Migrate Release 4 data to the Release 5 Directory Server instance.
Use the DirServer-base/ds6/bin/dsmig commands.
The dsmig commands adapt the Release 4 data to the Release 5 format and write it to the appropriate locations. For example, a typical migration on a single computer with one Directory Server instance might look like this:
Notes
- If the Directory Server instance you're migrating is storing configuration data for other Java ES components, for example for the Sun Java Communications Suite Messaging Server component, it might be required that you migrate a specific part of the directory information tree named o=netscaperoot. This root suffix is not migrated by default. To migrate o=netscaperoot, use the -N option of the dsmig migrate-config and dsmig migrate-data commands. For example:
- If you are migrating from an instance on a 32-bit architecture to one on a 64-bit architecture, you cannot use the dsmig migrate-data command (automatic migration tool). You have to migrate the data manually, as documented in the Migration Guide referenced below. However you can still perform automatic migration of schema, configuration, and security data.
- In some cases, when starting Directory Server after migrating directory data, new Release 5 error checking detects circular definitions in Directory Server group entries. These circular definitions are functionally benign, but can result in a large number of errors being logged into the error file.
For details of the migration process, the dsmig commands, and manual migration, see the Directory Server Enterprise Edition 6 Migration Guide, http://docs.sun.com/doc/819-0994.
Verifying the Upgrade
You can verify successful upgrade of Directory Server as follows.
- Start the new Directory Server instance:
DirServer-base/ds6/bin/dsadm -V
See Table 5-4 for output values.
- Check the startup messages in the Directory Server error log:
instancePath/logs/errors
Post-Upgrade Tasks
There are no post-upgrade tasks beyond the steps described in Upgrade Procedure, except that all Java ES components dependent on Directory Server need to be re-configured to point to the new Directory Server instances.
Rolling Back the Upgrade
A rollback of the Release 5 upgrade is achieved by reverting to the previous version, which is left intact by the upgrade to Release 5.
Multiple Instance Upgrades
The procedures in Release 4 Directory 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 replication or the deployment of Directory Server as a data service in a Sun Cluster environment.
Rolling Upgrades of Directory Server Replicates
Multiple instances of Directory Server on different computer systems, such as used in multi-master replication deployment architectures, can be sequentially upgraded one instance at a time. After first synchronizing all Directory Server masters, you upgrade each instance on its respective host computer 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
Information regarding upgrade and roll back of Directory Server as a data service in a Sun Cluster environment is currently under development.
Upgrading Directory Server from Java ES Release 3The procedure for upgrading Java ES 2003Q1 (Release 3) Directory Server to Release 5 is the same as that for upgrading Release 4 Directory Server to Release 5.
To upgrade Release 3 Directory Server to Release 5, use the instructions in Upgrading Directory Server from Java ES Release 4, except substitute Release 3 wherever Release 4 is referenced.
Upgrading Directory Server from Java ES Release 2The procedure for upgrading Java ES 2004Q2 (Release 2) Directory Server to Release 5 is the same as that for upgrading Release 4 Directory Server to Release 5, with the exception that the pre-upgrade tasks should include the upgrading to Release 5 of all shared components (see Table 1-9).
Instructions for upgrading Java ES shared components to Release 5 are provided in Chapter 2, "Upgrading Java ES Shared Components".
To upgrade Release 2 Directory Server to Release 5, use the instructions in Upgrading Directory Server from Java ES Release 4, except substitute Release 2 wherever Release 4 is referenced.
Note
If you are upgrading from Release 2 Directory Server on the Linux platform, then you will have to perform a dual upgrade, in which both Directory Server and the operating system are upgraded (Release 5 Directory Server is not supported on RHEL 2.1). See Dual Upgrade for more information.