Chapter 6 Directory Proxy Server

This chapter describes how to upgrade Directory Proxy Server to Java ES 5 (Release 5): Sun Java System Directory Proxy 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 Proxy Server Upgrades

Upgrading Directory Proxy Server from Java ES Release 4

Upgrading Directory Proxy Server from Java ES Release 3

Upgrading Directory Proxy Server from Java ES Release 2



Note	File locations in this chapter are specified with respect to directory paths referred to as serverRoot (Directory Proxy Server 5.x) and DirServer-base (Directory Proxy Server 6.0). At least part of these paths might have been specified as installation directories when Directory Proxy Server was installed. If not, the Java ES installer assigned a default value. The default values of these directory paths are shown in the following table.

Table 6-1 Directory Proxy Server Directory Paths
Path Name Variable	Solaris OS	Linux OS
serverRoot (Directory Proxy Server 5.x)	/var/opt/mps/serverroot	/var/opt/sun/directory-server
DirServer-base (Directory Proxy Server 6.0)	/opt/SUNWdsee	/opt/sun

Overview of Directory Proxy Server Upgrades

This section describes the following general aspects of Directory Proxy Server that impact upgrading to Java ES 5 (Release 5):

About Java ES Release 5

Java ES Release 5 Upgrade Roadmap

Directory Proxy Server Data

Directory Proxy Server Upgrade Strategy

About Java ES Release 5

Java ES Release 5 Directory Proxy Server represents a major release, being a new product with respect to Release 4 Directory Proxy Server and all previous releases.

Release 5 Directory Proxy Server is still an LDAP proxy, but with new, extensible routing capabilities. Release 5 also enables the Virtual Directory feature, the ability to aggregate multiple data views in a single view. These data views can represent LDAP or SQL accessible data stores.

For more information, see the Directory Server Enterprise Edition 6 Release Notes.

Java ES Release 5 Upgrade Roadmap

Table 6-2 shows the supported Directory Proxy Server upgrade paths to Java ES Release 5. The table applies to both Solaris and Linux operating systems.

Table 6-2 Upgrade Paths to Java ES 5 (Release 5): Directory Proxy Server 6.0
Java ES Release	Directory Proxy Server Version	General Approach	Reconfiguration Required
Release 4	Sun Java System Directory Proxy Server 5.2 2005Q4	Direct upgrade: Replace Release 4 with a fresh install and configuration of Release 5.	If backward compatibility desired, manually map previous configuration to new configuration properties.
Release 3	Sun Java System Directory Proxy Server 5.2 2005Q1	Direct upgrade: Replace Release 3 with a fresh install and configuration of Release 5.	If backward compatibility desired, manually map previous configuration to new configuration properties.
Release 2	Sun Java System Directory Proxy Server 5.2 2004Q2	Direct upgrade: Replace Release 2 with a fresh install and configuration of Release 5.	If backward compatibility desired, manually map previous configuration to new configuration properties.
Release 1	Sun ONE Directory Proxy Server 5.2	Direct upgrade not certified: But you can use the same approach as upgrading from Release 2.	If backward compatibility desired, manually map previous configuration to new configuration properties.
Pre-dates Java ES releases	Sun ONE Directory Proxy Server 5.2	Direct upgrade not certified: But you can use the same approach as upgrading from Release 2.	If backward compatibility desired, manually map previous configuration to new configuration properties.
Pre-dates Java ES releases	Sun ONE Directory Access Router 5.0 or 5.0 SP1	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 Proxy Server Data

Directory Proxy Server no longer makes use of Directory Server for storing configuration data. Configuration is performed using the new Directory Service Control Center or Directory Server EE command-line utilities.

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

Table 6-3 Directory Proxy Server Data Usage
Type of Data	Location	Usage
Directory Proxy Server configuration data	Directory Proxy Server 5.2: configuration directory Directory Proxy Server 6.0: accessed through Directory Service Control Center and Directory Server EE command-line utilities.	Configuration of Directory Proxy Server
Security data	Directory Proxy Server 5.2: SSL configured through Directory Proxy Server Console. Directory Proxy Server 6.0: SSL configured through Directory Service Control Center and Directory Server EE command-line utilities.	Server certificates

Directory Proxy Server Upgrade Strategy

Your strategy for upgrading Directory Proxy 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 Proxy Server by presenting issues that might influence your Directory Proxy Server upgrade plan.

Compatibility Issues

Release 5 Directory Proxy Server introduces interface changes that make it incompatible with earlier Directory Proxy Server releases. Release 5 Directory Proxy Server is based on a completely new Java-based implementation and its configuration differs fundamentally from Release 4 Directory Proxy Server, as well as earlier releases.

It is possible, however, to configure Release 5 Directory Proxy Server to be backwardly compatible, that is, to behave like Release 4 Directory Proxy Server and earlier releases. This configuration requires you to manually map previous configuration attributes to Release 5 configuration properties. Details are in the Directory Server Enterprise Edition 6 Migration Guide, http://docs.sun.com/doc/819-0994.

However, Release 5 Directory Proxy Server has different default behaviors compared to previous versions: it does not allow LDAP controls to pass through the proxy. To reproduce the behavior of previous versions, you can unblock these controls as described in Post-Upgrade Tasks.

Dependencies

Dependencies on other Java ES components can impact the procedure for upgrading and re-configuring Directory Proxy Server software.

Shared components. Directory Proxy Server has dependencies on specific Java ES shared components (see Table 1-9). Directory Proxy Server upgrades might depend upon upgraded versions of these shared components.

Directory Server. Directory Proxy Server has a co-dependency on Directory Server for providing improved security and performance for LDAP requests. Directory Proxy Server provides front-end access to Directory Server but has no dependency on Directory Server beyond this functional relationship.

Dual Upgrade

Fresh operating system installation

In-place operating system upgrade

Fresh Operating System Installation

Back up existing Directory Proxy Server data.

See Directory Proxy Server Data for the location of essential data.

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.

Install Release 5 Directory Proxy Server.

Create a Release 5 Directory Proxy Server instance and map configuration attributes to the Release 5 Directory Proxy Server properties.

See the relevant steps in the procedure for Upgrading Release 4 Directory Proxy Server.

In-place Operating System Upgrade

Back up existing Directory Proxy Server data.

See Directory Proxy Server Data for the location of essential data.

Upgrade the operating system.

The upgrade leaves the existing file system in place.

Upgrade to Release 5 Directory Proxy Server.

See the relevant section of this chapter, depending on upgrade path.

Upgrading Directory Proxy Server from Java ES Release 4

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

Introduction

Release 4 Directory Proxy Server Upgrade

Multiple Instance Upgrades

Introduction

When upgrading Java ES Release 4 Directory Proxy 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 Proxy Server and then configuring new Directory Proxy Server instances using the Directory Service Control Center or Directory Server EE command-line utilities.

Upgrade Dependencies. Directory Proxy 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 Proxy Server.

Backward Compatibility. Release 5 Directory Proxy Server can be configured to be backwardly compatible with its Release 4 version, as explained in Compatibility Issues.

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 Proxy Server is the same on both Solaris and Linux operating systems.

Release 4 Directory Proxy Server Upgrade

This section describes how to perform an upgrade of Directory Proxy 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

Upgrading Release 4 Directory Proxy Server

Verifying the Upgrade

Post-Upgrade Tasks

Rolling Back the Upgrade

Pre-Upgrade Tasks

Before you upgrade Directory Proxy Server software you should perform the following tasks:

Verify Current Version Information

Upgrade Directory Proxy Server Dependencies

Obtain Required Configuration Information and Passwords

Verify Current Version Information

You can verify the current version of Directory Proxy Server using the following commands:

Table 6-4 Directory Proxy Server Version Verification Outputs
Java ES Release	Directory Proxy Server Version Number
Release 2	Sun ONE Directory Proxy Server Version 5.2_Patch_2
Release 3	Sun ONE Directory Proxy Server Version 5.2_Patch_3
Release 4	Sun ONE Directory Proxy Server Version 5.2_Patch_4
Release 51	Sun ONE Directory Proxy Server Version 6.0

1The ldapfwd command cannot be used to return a version number for Release 5. See Verifying the Upgrade.

Upgrade Directory Proxy 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. Directory Proxy Server has hard upgrade dependencies on only a few shared components.

When upgrading Directory Proxy Server dependencies, you should do so in the order below (skipping any that might already have been upgraded), before you upgrade Directory Proxy Server. Upgrade of shared components is normally achieved automatically by the Java ES installer.

Shared Components. Instructions for synchronizing Java ES shared components to Release 5 are provided in Upgrading Java ES Shared Components. However, all shared components required by Directory Proxy Server are upgraded automatically by the Java ES installer when you perform an upgrade of Directory Proxy Server to Release 5.

Directory Server (soft upgrade dependency) Instructions for upgrading Directory Server to Release 5 are provided in Chapter 5, "Directory Server". However, Release 5 Directory Proxy Server is supported by Release 4 Directory Server.

Obtain Required Configuration Information and Passwords

Configuration information is preserved through the upgrade process and can be used to map Release 4 configuration attributes to Release 5 configuration properties. See Compatibility Issues.

Upgrading Release 4 Directory Proxy Server

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

Upgrade Considerations

The upgrade of Directory Proxy Server software to Java ES Release 5 takes into account the following considerations:

Any Java ES components using a Directory Proxy Server instance (such as Access Manager, Communications Express, Messaging Server, Portal Server, and so forth) should be shut down and re-configured to access the corresponding new Release 5 instance.

In a deployment architecture in which there are multiple instances of Directory Proxy Server running on a single computer (all corresponding to the same installed Directory Proxy Server image), upgrading the Directory Proxy Server image will require you to create new Directory Proxy Server instances.

In Release 4 deployment architectures involving Directory Proxy Server, an Administration Server was used to configure and manage Directory Proxy Server instances. In Release 5 the upgrade of Directory Proxy Server might entail deployment of the Directory Service Control Center, used to configure and manage Directory Proxy Server instances.

Upgrade Procedure

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

su -

Shut down all Java ES components dependent on the Directory Proxy Server instances that are to be upgraded. This step might depend on how Directory Proxy Server is replicated within your deployment architecture.

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

Perform a fresh install of Release 5 Directory Proxy Server.

Perform the following steps:

Launch the Java ES installer.

cd Java ES Release 5 distribution/os_arch
./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 Proxy 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 Proxy 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 Proxy Server. However, if you choose to configure now, you are asked if you want to create a new instance. (Once the component is installed, you can create as many Directory Proxy Server instances as you wish.)

If needed, select the option to install localized packages.

Confirm your installation choices.

Directory Proxy Server packages will be installed and an installation summary displayed.

Exit the Java ES installer.

If you have not created a new instance, continue to Step 4, otherwise continue with Step 5.

Create a Directory Proxy Server instance.

DirServer-base/dps6/bin/dpadm create instancePath

where instancePath is the full path to the Directory Proxy Server instance.

For information on creating a Directory Proxy Server instance, see the Directory Server Enterprise Edition 6 Administration Guide, http://docs.sun.com/doc/819-0995.

If desired, map Release 4 configuration attributes to the Release 5 Directory Proxy Server properties.

For details of the mapping procedure, see the Directory Server Enterprise Edition 6 Migration Guide, http://docs.sun.com/doc/819-0994.

Verifying the Upgrade

Start the new Directory Proxy Server instance.

DirServer-base/dps6/bin/dpadm start instancePath

Check for the Directory Proxy Server version.

DirServer-base/dps6/bin/dpadm --version

Output values are shown in Table 6-4.

Post-Upgrade Tasks

All Java ES components dependent on Directory Proxy Server need to be re-configured to point to the new Directory Proxy Server instances.

In addition, to reproduce the default behavior of previous versions, LDAP controls must be explicitly allowed to pass through the proxy. You can enabled these controls by setting the allowed-ldap-controls property as follows:

./dpconf set-server-prop
allowed-ldap-controls:auth-request
allowed-ldap-controls:chaining-loop-detection
allowed-ldap-controls:manage-dsa
allowed-ldap-controls:persistent-search
allowed-ldap-controls:proxy-auth-v1
allowed-ldap-controls:proxy-auth-v2
allowed-ldap-controls:real-attributes-only
allowed-ldap-controls:server-side-sorting

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

In some deployment architectures Directory Proxy Server is deployed on multiple computer systems to provide for scalability and to improve availability. For example, you might have Directory Proxy Server components running on multiple computers with a load balancer to distribute the load.

In the case of load-balanced instances of Directory Proxy Server, you cannot perform a rolling upgrade; the load balancer needs to be shut down and re-configured to access the Release 5 instances. You perform the upgrade of each instance as described in Release 4 Directory Proxy Server Upgrade.

Upgrading Directory Proxy Server from Java ES Release 3

The procedure for upgrading Java ES 2005Q1 (Release 3) Directory Proxy Server to Release 5 is the same as that for upgrading Release 4 Directory Proxy Server to Release 5.

Upgrading Directory Proxy Server from Java ES Release 2

The procedure for upgrading Java ES 2004Q2 (Release 2) Directory Proxy Server to Release 5 is the same as that for upgrading Release 4 Directory Proxy Server to Release 5, with the exception that the pre-upgrade tasks should include the synchronizing to Release 5 of all shared components (see Table 1-9) and all locally-resident product components upon which Directory Proxy Server depends.

Previous Contents Index Next
Sun Java Enterprise System 5 Upgrade Guide for UNIX


Note	If you are upgrading from Release 2 Directory Proxy Server on the Linux platform, then you will have to perform a dual upgrade, in which both Directory Proxy Server and the operating system are upgraded (Release 5 Directory Proxy Server is not supported on RHEL 2.1). See Dual Upgrade for more information.