Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java Enterprise System 2005Q4 Upgrade Guide 

Chapter 11
Access Manager

This chapter describes how to upgrade Access Manager software from previous Java ES versions to Java ES 2005Q4 (Release 4): Sun Java System Access Manager 7 2005Q4.

The chapter provides a general overview of Access Manager 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 Access Manager Upgrades

This section describes the following general aspects of Access Manager that impact upgrading to Java ES 2005Q4 (Release 4):

About Java ES Release 4 Access Manager

Java ES Release 4 Access Manager has been enhanced in major ways. On the back end, the product has been re-architected to support multiple identity repositories, or user data stores. Thus Release 4 Access Manager supports not only an LDAP directory such as Directory Server, but other data storage protocols and formats as well. Release 4 Access Manager includes new interfaces and new services to support the integration of multiple identity repositories.

On the front end, a new Access Manager Console is used to configure the new Access Manager services and identity repositories.

The new functional capabilities and interfaces make Release 4 Access Manager a major new release. In order to provide backward compatibility, Release 4 can be run in legacy mode, which supports the Java ES components that depend on Release 3 Access Manager services (for more information, see Compatibility Issues).

Access Manager Upgrade Roadmap

Table 11-1 shows the supported Access Manager upgrade paths to Java ES Release 4. The table applies to both Solaris and Linux operating systems.

Table 11-1  Upgrade Paths to Java ES Release 4: Sun Java System Access Manager 7 2005Q4

Java ES Release

Access Manager Version

General Approach

Re-configuration Required

Release 3

Sun Java System Access Manager
6.3 2005Q1

Direct upgrade:
Performed by removing the Release 3 version and then doing a full installation and re-configuration of Release 4.

Configuration data

Customized JSPs for Access Manager console and authentication UI

Directory schema

Release 2

Sun Java System Identity Server
6.2 2004Q2
and also 6.2 SP1

Direct upgrade:
Performed by removing the Release 2 version and then doing a full installation and re-configuration of Release 4.

Configuration data

Customized JSPs for Access Manager console and authentication UI

Directory schema

Release 1

Sun ONE Identity Server 6.1

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

Then upgrade from Release 3 to Release 4.

Configuration data

Customized JSPs for Access Manager console and authentication UI

Directory schema

Pre-dates Java ES releases

Sun ONE Identity Server 6.0 or 6.0 SP 1 or

iPlanet Directory Server Access Management Edition (DSAME) 5.1

No direct upgrade.

 

Access Manager Data

Access Manager, like other Java ES components, makes use of various kinds of data that for any specific upgrade might need to be migrated to an upgraded version. The following table shows the type of data that could be impacted by an upgrade of Access Manager software.

Table 11-2  Access Manager Data Usage

Type of Data

Location

Usage

Configuration data

AccessManagerConfig-base/config/AMConfig.properties

AccessManagerConfig-base/config/serverconfig.xml

JAR files for authentication and customized modules
AccessManager-base/lib

Configuration of Access Manager and its integration with a back-end data store.

Web container configuration

Web Server:
server.policy and server.xml files in
WebServer-base/https-hostname/config

Application Server (Java ES Release 3 and 4):
server.policy and domain.xml files in
AppServer8Config-base/domains/domainName/config

Application Server (Java ES Release 2):
server.policy and server.xml files in
AppServer7Config-base/domains/domainName/config

WebSphere and WebLogic:
Respective policy and configuration files are modified when Access Manager is configured for these web containers.

Configuration of Access Manager web container instance.

Customization data
(Web container customized JSP files)

Admin Console: AccessManager-base/web-src/applications

Authentication UI: AccessManager-base/web-src/services

Configuration of Access Manager administration interfaces.

Directory schema

Services configuration

User data

Directory Server

Access Manager provides authentication and authorization services for end users, based on services configuration, user, and policy data that is stored in a directory.

Dynamic application data

None

Access Manager does not persistently store application data such as session state.

Compatibility Issues

The new functional capabilities of Release 4 Access Manager involve the following new interfaces:

Access Manager support for these new interfaces is enabled by configuring Access Manager to run in enhanced (Realm) mode. However, Realm mode is not compatible with the earlier Java ES Release 3 or Release 2 Access Manager. For example, directory data has to be migrated to support Realm mode operation. The enhanced Access Manager Console is needed to support enhanced Access Manager services.

In addition, Realm mode does not support other Java ES components, such as Portal Server, Communications Express, Messaging Server, and others.

To support backward compatibility, Release 4 Access Manager can be configured to run in Legacy mode. With some minor exceptions (see Sun Java System Access Manager 7 2005Q4 Release Notes (http://docs.sun.com/doc/819-2134), Legacy mode is backwardly compatible with Release 3 Access Manager.

Legacy mode is necessary to support other Java ES components, as well as older versions of Access Manager policy agents, which cannot interoperate with Access Manager in Realm mode. This incompatibility is an important upgrade consideration, and means in most Java ES deployments, that Access Manager should be upgraded to Release 4 Legacy mode.

Even when configured to run in Legacy mode, however, Release 4 Access Manager is incompatible with Release 3 Delegated Administrator. If Access Manager is upgraded to Release 4, then Delegated Administrator also must be upgraded to Release 4 to provision users for Messaging Server and Calendar Server. However, Messaging Server and Calendar Server do not, themselves, have to be upgraded to Release 4.

Access Manager Dependencies

Access Manager dependencies on other Java ES components can impact the procedure for upgrading and re-configuring Access Manager software. Changes in Access Manager interfaces or functions, for example, could require upgraded version of components upon which Access Manager depends. The need to upgrade such components depends upon the specific upgrade path.

Access Manager has dependencies on the following Java ES components:


Upgrading Access Manager from Java ES Release 3

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

Introduction

When upgrading Java ES Release 3 Access Manager to Release 4, consider the following aspects of the upgrade process:

Full Release 3 Access Manager Upgrade

This section describes how to perform a full Access Manager upgrade from Java ES Release 3 to Java ES Release 4:

Pre-Upgrade Tasks

Before you upgrade Access Manager, perform the procedures described in the following sections.

Verify Current Version Information

You can verify the current version of Access Manager using the following command:

Upgrade Access Manager 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 Access Manager does not require upgrading the Java ES Release 3 components upon on which it depends, this task is optional.

However, if you choose to upgrade all Access Manager dependencies, they should be upgraded in the following order, all before you upgrade Access Manager. You can skip any that might already have been upgraded.

  1. Shared Components.  Instructions for upgrading Java ES shared components to Release 4 are provided in Chapter 2, "Upgrading Java ES Shared Components".
  2. Directory Server.  Instructions for upgrading Directory Server to Release 4 are provided in Chapter 4, "Directory Server and Administration Server".
  3. Web Container Software.  Instructions for upgrading Web Server or Application Server are provided in Chapter 6, "Web Server" and Chapter 9, "Application Server", respectively.
  4. If web container software is not upgraded before Access Manager, the upgrade procedure (using the amconfig script) will configure and re-deploy Access Manager to the existing web container.

Back Up Directory Server Data

The Access Manager upgrade process uses scripts that modify Directory Server schema. Therefore, before you upgrade Access Manager, back up your Directory Server 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).

Back Up Release 3 Access Manager Configuration Information

Because the re-configuration of Release 4 Access Manager software requires the re-configuration of the Release 3 version, it is important to back up configuration files to a known location. The following files should be backed up:

Back Up Web Container Customized Files

If you have any web container customized files referenced by Access Manager, you should back them up. These customizations might include the following:

Back Up Release 3 Access Manager Log and Debug Files

For the purpose of analyzing system state information, it is a good idea to back up log and debug files so they are not lost. These files are at the following locations:

Obtain Required Configuration Information and Passwords

To upgrade Access Manager, you must provide specific configuration information, including:

Upgrading Release 3 Access Manager

The upgrade of Access Manager software to Java ES Release 4 includes procedures for re-configuring Access Manager and for migrating Access Manager data.

Upgrade Summary

The procedure for upgrading Access Manager consists of the following steps:

  1. Install the Java ES Release 4 Version of Access Manager. Use the Java ES Release 4 installer with the Configure Later option.

These steps are each documented in the following procedures.

Upgrade Procedures
  1. Remove the Java ES Release 3 Version of Access Manager.
    1. Log in as root to the computer hosting Release 3 Access Manager or become superuser.
    2. su -

    3. Change directory to the platform/Product/identity_svr/Tools directory in the Java ES Release 4 distribution.
    4. Obtain the values of the following parameters to be requested by the ampre70upgrade script:
    5. Table 11-4  Access Manager Configuration Parameters: ampre70upgrade

      Parameter

      Value

      Directory Server Host

      Set the fully-qualified name: hostname.domian

      Directory Server Port

      Specify a non-SSL port number1
      Default: 389

      Top-Level Administrator DN

      Default: uid=amadmin,ou=People,dc=iplanet,dc=com

      Top-Level Administrator Password

       

      1The pre-upgrade process will not complete successfully if you specify a Directory Server SSL port such as the default SSL value of 636.

    6. Make sure that Directory Server is running or start it if it is not.
    7. Run the ampre70upgrade script.
    8. ./ampre70upgrade

      The script backs up Access Manager configuration files and removes Release 3 base packages (localized packages must be removed manually per Step f).

    9. Manually remove localized Access Manager packages on your computer.
    10. The ampre70upgrade script does not remove localized Access Manager packages. They must be removed by hand to perform a properly localized upgrade.

      • Use pkgrm on Solaris platforms to remove: SUNWamlLocale, SUNWLocaleammmap
      • Use rpm -e on Linux to remove: sun-identity-sdk-Locale
  2. Install the Java ES Release 4 Version of Access Manager.
    1. Run the Java ES installer on the computer hosting Release 3 Access Manager.
    2. Select Access Manager from the selection panel.
    3. If a “Conflict” message appears on the screen, it means the Installer has found Access Manager configuration information from the previous version, which is expected. Re-configuration will be performed in subsequent steps. You can ignore this “Conflict” message and proceed.

    4. Specify the same installation directory in which Release 3 was installed.
    5. Select the Configure Later option.
    6. Quit the Java ES installer when installation is complete.

    7. Note

      If you are using the Java ES Installer command line interface to install Access Manager, it will automatically install Directory Server software as well. If you are using a remote Directory Server you can uninstall the local Directory Server software using the procedures in the Java Enterprise System Installation Guide for UNIX.


  3. Upgrade mobile access software.
  4. Access Manager mobile access software needs to be upgraded by patching the Release 3 version. The patches needed are shown in the following table:

    Table 11-5  Patches1 to Upgrade Access Manager Mobile Access software 

    Description

    Solaris Patch ID

    Linux Patch ID

    Mobile Access software

    119530-01 (SPARC)

    119531-01 (x86)

    119532-01

    • sun-identity-mobileaccess-6.2-25.i386.rpm
    • sun-identity-mobileaccess-config-
      6.2-25.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.

    1. Obtain the required patches using the patch numbers from Table 11-5.
    2. Patches can be downloaded to /tmp from: http://sunsolve.sun.com/pub-cgi/show.pl?target=patches/patch-access

    3. Log in as root or become superuser.
    4. su -

    5. Apply the patches in Table 11-5.
    6. On Solaris:

      patchadd patch_ID

      On Linux:

      rpm -Fvh sun-identity-mobileaccess-6.2-25.i386.rpm
      rpm -Fvh sun-identity-mobileaccess-config-6.2-25.i386.rpm

  5. Re-customize JSPs for Access Manager.
  6. Re-apply the Release 3 customizations to JSPs for the Access Manager Console and authentication user interface (UI) that you saved under Back Up Web Container Customized Files.

    Then, copy the customized JSP files to the correct directories. For example, on Solaris systems:

    • Console: AccessManager-base/web-src/applications/console
    • Authentication UI: AccessManager-base/web-src/services/config/auth/default or AccessManager-base/web-src/services/config/auth/default_Locale (where Locale is a locale indicator like ja)
    • For more information, see the Sun Java System Access Manager Developer's Guide (http://docs.sun.com/doc/819-2139).

  7. Undeploy Access Manager, re-configure, and re-deploy into a Web Container.
  8. Configure Access Manager for your specific web container by running the amconfig script. The amconfig script (and the associated amsamplesilent template input file) resides in the following directory:

    AccessManager-base/bin

    For information about the amconfig script and the amsamplesilent template file, see the Sun Java System Access Manager Administration Guide (http://docs.sun.com/doc/817-7647).

    Perform the following steps to re-configure and re-deploy Access Manager to the web container:

    1. If you choose to upgrade your web container software, as described in Upgrade Access Manager Dependencies, make sure the upgrade is complete.
    2. Check that Directory Server and the appropriate web container are running.
    3. Create an amconfig input file based on the amsamplesilent template input file:
    4. cp amsamplesilent config-file

    5. Set the configuration parameters in config-file.
    6. All the parameters need to be set correctly. Some of the values can be migrated from the AMConfig.properties file and others are more specific to the upgrade procedure, as shown in the following table.

      Table 11-6   Access Manager Configuration Parameters 

      Parameter

      Value

      Upgrade Parameters

      DEPLOY_LEVEL

      26 (for undeploy) or 1 (for re-configure and deploy)

      DIRECTORY_MODE

      5 (Existing Upgrade)

      AM_REALM

      set to disabled (Realm Mode is disabled, Legacy Mode is therefore enabled)
      (Default = enabled)

      JAVA_HOME

      set to JDK Release 4 directory: /usr/java/jdk1.5.0_04/

      WEB_CONTAINER

      set to the value appropriate to the web container type you are using and fill out only the corresponding section of config-file.

      WS61_INSTANCE
      (If using Web Server as the web container)

      =https-<hostname>.<domain>
      where the value above matches the instance name in /WebServer-base/SUNWsbsvr/
      The values is case-sensitive.

      Migrated from AMConfig.properties

      SERVER_PROTOCOL

      com.iplanet.am.server.protocol

      SERVER_PORT

      com.iplanet.am.server.port

      SERVER_HOST

      com.iplanet.am.server.host

      DS_HOST

      com.iplanet.am.directory.host

      DS_PORT

      com.iplanet.am.directory.port

      ROOT_SUFFIX

      com.iplanet.am.defaultOrg

      CONSOLE_DEPLOY_URI

      com.iplanet.am.console.deploymentDescriptor

      SERVER_DEPLOY_URI

      com.iplanet.am.services.deploymentDescriptor

      PASSWORD_DEPLOY_URI

      com.sun.identity.password.deploymentDescriptor

      AM_ENC_PWD

      am.encryption.pwd

      For other parameters, provide the same values that were used in the Release 3 configuration that you are upgrading, unless you are changing web container or passwords.

    7. Run amconfig to undeploy Access Manager
    8. Set the value of DEPLOY_LEVEL in config-file to 26.

      cd /AccessManager-base/bin
      ./amconfig -s
      AccessManager-base/bin/config-file

    9. Run amconfig to reconfigure Access Manager and deploy into web container.
    10. Set the value of DEPLOY_LEVEL in config-file to 1.

      cd /AccessManager-base/bin
      ./amconfig -s
      AccessManager-base/bin/config-file

  9. Update the directory structure and schema.
  10. Release 4 Access Manager co-exists with the Release 3 directory structure, but the structure must be modified to support Release 4 capabilities. Update the Access Manager directory structure and schema to Release 4 by running the amupgrade script, which is installed in the following directory:

    • Solaris:
      AccessManager-base/upgrade/scripts
    • Linux:
      AccessManager_base/identity/upgrade/scripts
    • Obtain the values of the following parameters to be requested by the amupgrade script:
    • Table 11-7   Access Manager Configuration Parameters: amupgrade 

      Parameter

      Value

      Directory Server Host

      Set the fully qualified name: hostname.domain

      Directory Server Port

      Specify a non-SSL port number1
      Default: 389

      Directory Manager DN

      Default: cn=Directory Manager

      Directory Manager Password

       

      Top-Level Administrator DN

      Default: uid=amadmin,ou=People,dc=iplanet,dc=com

      Top-Level Administrator Password

       

      Enable Realm Mode

      Y/N: Yes means Realm Mode is enabled and services data is migrated to new Realm tree. No (default) means services data remain in Legacy Mode.

      1The upgrade process will not complete successfully if you specify a Directory Server SSL port such as the default SSL value of 636.

    • Run the amupgrade script.
    • cd AccessManager-base/upgrade/scripts
      ./amupgrade

      If the upgrade is successful, the script displays “Upgrade completed.”

    • Check the following upgrade log file for information about the directory schema extensions:
    • Solaris:
      /var/sadm/install/logs/
             Sun_Java_System_Access_Manager_upgrade_dit_log.mmddhhmm

      Linux:
      /var/log/Sun_Java_System_Access_Manager_upgrade_dit_log.mmddhhmm

  11. Start Access Manager.
  12. Re-start the web container in which Access Manager is deployed.

Verifying the Access Manager Upgrade

After you finish the upgrade procedure, verify that it was successful as follows:

  1. Log in to the Access Manager console as amadmin using the following URL:
  2. http://hostname.domain:port/amconsole

    where hostname.domain:port is the fully qualified host name and port number of the web container hosting Access Manager.

    Verify that new Release 4 services referred to in About Java ES Release 4 Access Manager are available under the “Service Configuration” tab.

  3. Review the status of the upgrade by checking the following upgrade log files in the /var/sadm/install/logs directory:
  4. Sun Java Enterprise System installer:

    • Java_Shared_Component_Install.timestamp
    • Java_Enterprise_System_install.Atimestamp
    • Java_Enterprise_System_install.Btimestamp
    • Java_Enterprise_System_Summary_Report_install.timestamp
    • amupgrade script:

    • Sun_Java_System_Identity_Server_upgrade_dit_log.timestamp
  5. Review Access Manager trouble shooting files for errors.
  6. The files are located at /var/opt/SUNWam/debug

Post-Upgrade Tasks

If you are using the Security Assertion Markup Language (SAML) service, you must add and enable a SAML authentication module using the Access Manager console. For information on creating a SAML authentication module instance, refer to the Sun Java System Access Manager Administration Guide (http://docs.sun.com/doc/817-7647).

Rolling Back the Upgrade

No scripts are provided for rolling back Access Manager to its pre-upgrade state. The process must be performed manually using Access Manager data that was backed up as part of the pre-upgrade tasks (see Back Up Release 3 Access Manager Log and Debug Files). Rollback is too difficult to be practical.

Multiple Instance Upgrades: Release 3 and Release 4 Co-existence

In some deployment architectures Access Manager is deployed on multiple computer systems to provide for high availability and scalability. The Access Manager instances access the same Directory Server. It is often desirable to upgrade the Access Manager instances sequentially without interrupting service. This section discusses the procedure for performing such rolling upgrades.


Note

Upgrading multiple instances of Access Manager installed on the same host system is not supported in the current release. If you have multiple instances on the same host, after you upgrade the main instance, you must then recreate the additional instances.


The procedure for upgrading Access Manager from Release 3 includes a step for migrating directory schema to support Release 4. Release 3 Access Manager does not support Release 4 directory schema, however Release 4 Access Manager does support Release 3 directory schema.

Java ES Release 4 Access Manager and Release 3 Access Manager instances can coexist and run concurrently against the same Directory Server only if the directory schema has not yet been migrated to Release 4. Therefore, in rolling upgrades, the directory schema should not be migrated to Release 4 until all Access Manager instances have been first upgraded to Release 4.

In performing rolling upgrades, upgrade each instance of Access Manager as described in Upgrading Release 3 Access Manager, except for Update the directory structure and schema.step on (more...) . When all instances have been upgraded, then that step can be performed.

Release 3 Access Manager SDK-only Upgrades

In some deployment architectures, the Access Manager SDK component is installed on one or more computer systems without installing other Access Manager components on those computers. Access Manager SDK serves as a remote interface to Access Manager and must be re-configured for the same operational mode as Access Manager: Legacy or Realm. As a remote interface to Access Manager, the SDK does not need to be configured to access Directory Server.

If Access Manager SDK is being used to support a web component, such as Portal Server or Communications Express, which depends upon web container services, Access Manager SDK must be configured for the corresponding web container. However, Access Manager SDK can also support non-web components, and no web container is needed.

The procedure for upgrading Access Manager SDK is a subset of the procedure for the full Access Manager upgrade, based on the above characteristics.

This section describes how to perform an Access Manager SDK-only upgrade from Java ES Release 3 to Java ES Release 4:

Pre-Upgrade Tasks

The pre-upgrade tasks for Access Manager SDK are the same as for the full Access Manager upgrade, but exclude those related to Directory Server and administration tool customizations. The pre-upgrade tasks needed for Access Manager SDK are the following:

Upgrading Release 3 Access Manager SDK

The upgrade procedures for Access Manager SDK are the same as for the full Access Manager upgrade, but exclude those related to administration tool customizations and migrating directory schema.

  1. Remove the Java ES Release 3 version of Access Manager SDK.
  2. Follow the instructions in Remove the Java ES Release 3 Version of Access Manager., except remove only Access Manager SDK.

  3. Install Java ES Release 4 version of Access Manager SDK.
  4. Follow the instructions in Install the Java ES Release 4 Version of Access Manager., except install only Access Manager SDK.

  5. Re-configure Access Manager SDK.
  6. Follow the instructions in Undeploy Access Manager, re-configure, and re-deploy into a Web Container., except set the DIRECTORY_MODE=5 and the DEPLOY_LEVEL parameter as follows:

    • If Access Manager SDK is configured for a web container:
      DEPLOY_LEVEL=4 (upgrade the SDK and configure the web container)
    • If Access Manager SDK is not configured for a web container:
      DEPLOY_LEVEL=3 (upgrade the SDK only)

Verifying the Access Manager SDK Upgrade

There are three ways you can verify a successful Access Manager SDK upgrade:

Upgrade Rollback

No scripts are provided for rolling back Access Manager to its pre-upgrade state. The process must be performed manually using Access Manager data that was backed up as part of the pre-upgrade tasks (see Back Up Release 3 Access Manager Log and Debug Files). Rollback is too difficult to be practical.


Upgrading Access Manager from Java ES Release 2

The procedure for upgrading Java ES 2004Q2 (Release 2) Access Manager to Release 4 is the same as that for upgrading Release 3 Access Manager to Release 4, with a couple of exceptions, noted below.

Pre-Upgrade Tasks

Before you upgrade Access Manager, perform the procedures described in Pre-Upgrade Tasks, except replace Upgrade Access Manager Dependencies with the following section and add the Upgrade Directory Schema section below.

Upgrade Access Manager Dependencies

As compared to the upgrade from Release 3, the Release 2 to Release 4 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 Access Manager depends.

When upgrading Access Manager dependencies, they should be upgraded in the following order, all before you upgrade Access Manager. You can skip any that might already have been upgraded.

  1. Shared Components.  Instructions for upgrading Java ES shared components to Release 4 are provided in Chapter 2, "Upgrading Java ES Shared Components".
  2. Directory Server.  Directory Server rarely resides on the same computer as Access Manager, however, instructions for upgrading Directory Server to Release 4 are provided in Upgrading Directory Server and Administration Server from Java ES Release 2.
  3. Web Container Software.  Instructions for upgrading Web Server or Application Server are provided in Upgrading Web Server from Java ES Release 2 and Upgrading Application Server from Java ES Release 2, respectively.

Upgrade Directory Schema

If Directory Server was configured with Directory Preparation Tool (comm_dssetup.pl) to support Messaging Server, Calendar Server, or other communications components, you must first upgrade the directory schema using the Release 4 version of Directory Preparation Tool before upgrading Access Manager. Perform this pre-upgrade task after you have upgraded Access Manager dependencies. The procedure for upgrading Directory Preparation Tool is described in Upgrading Directory Preparation Tool from Java ES Release 2.

Release 2 Access Manager Upgrade

The procedure for upgrading Access Manager from Release 2 to Release 4 depends on the web container in which you are deploying Access Manager software.

Upgrading Release 2 Access Manager: Web Server Web Container

To upgrade Release 2 Access Manager to Release 4, when deploying into a Web Server web container, follow the instructions in Upgrading Release 3 Access Manager, except substitute Release 2 wherever Release 3 is referenced.

Upgrading Release 2 Access Manager: Application Server Web Container

To upgrade Release 2 Access Manager to Release 4, when deploying into a Application Server web container, there are two cases:

To upgrade Access Manager when deployed in an upgraded Application Server web container, you follow Step 1 through Step 4, except substitute Release 2 wherever Release 3 is referenced.

To summarize, Step 1 through Step 4 are as follows:

  1. Remove the Release 2 Version of Access Manager.
  2. Use the ampre70upgrade script. Follow the instructions in Remove the Java ES Release 3 Version of Access Manager..

  3. Install the Java ES Release 4 Version of Access Manager. Use the Java ES Release 4 installer with the Configure Later option.

The Release 2 Application Server instance in which Access Manager was originally deployed (instanceName), when upgraded to Release 4, was migrated under a node agent created by the upgrade process. Upgrade of Access Manager in this upgraded Application Server instance requires the following additional steps:

  1. Make sure that the following components that support Access Manager are running.
    1. Check that Directory Server is running.
    2. Start the Domain Administration Server (DAS) if it is not already started.
    3. AppServer8-base/bin/asadmin start-domain --user admin_ID
           --password password domainName

    4. Start the upgraded Application Server instance in which Access Manager is deployed (instanceName), if that server instance is not already running.
    5. Do this by starting the node agent under which the upgraded Application Server instance has been migrated:

      AppServer8-base/bin/asadmin start-node-agent --user admin_ID
           --password password nodeagentName

      In the above commands, and in subsequent steps, the following conventions are used:

    6. nodeAgentName has the form hostName_domainName.
    7. The default domainName is domain1
    8. The default instanceName is server1
  2. Undeploy Access Manager, reconfigure, and re-deploy into the Application Server instance. Use the amconfig script.
    1. Create an amconfig input file based on the amsamplesilent template input file:
    2. cp amsamplesilent config-file

    3. Set the configuration parameters in config-file.
    4. All the parameters need to be set correctly. Some of the values can be migrated from the AMConfig.properties file and others are more specific to the upgrade procedure, as shown in the following table.

      Table 11-8   Access Manager Configuration Parameters 

      Parameter

      Value

      Upgrade Parameters

       

      DEPLOY_LEVEL

      26 (for undeploy) or 1 (for re-configure and deploy)

      DIRECTORY_MODE

      5 (Existing Upgrade)

      AM_REALM

      set to disabled (Realm Mode is disabled, Legacy Mode is therefore enabled); Default = enabled

      JAVA_HOME

      set to JDK Release 4 directory: /usr/java/jdk1.5.0_04/

      WEB_CONTAINER

      set to the value for Application Server web container and fill out only the corresponding section of config-file.

      AS81_INSTANCE

      =instanceName

      AS81_ADMIN_IS_SECURE

      =false

      Migrated from AMConfig.properties

      SERVER_PROTOCOL

      com.iplanet.am.server.protocol

      SERVER_PORT

      com.iplanet.am.server.port

      SERVER_HOST

      com.iplanet.am.server.host

      DS_HOST

      com.iplanet.am.directory.host

      DS_PORT

      com.iplanet.am.directory.port

      ROOT_SUFFIX

      com.iplanet.am.defaultOrg

      CONSOLE_DEPLOY_URI

      com.iplanet.am.console.deploymentDescriptor

      SERVER_DEPLOY_URI

      com.iplanet.am.services.deploymentDescriptor

      PASSWORD_DEPLOY_URI

      com.sun.identity.password.deploymentDescriptor

      AM_ENC_PWD

      am.encryption.pwd

      For other parameters, provide the same values that were used in the Release 2 configuration that you are upgrading, unless you are changing web container or passwords.

    5. Run amconfig to undeploy Access Manager.
    6. Set the value of DEPLOY_LEVEL in config-file to 26.

      cd /AccessManager-base/bin
      ./amconfig -s
      AccessManager-base/bin/config-file

    7. Run amconfig to reconfigure Access Manager and deploy into web container.
    8. Set the value of DEPLOY_LEVEL in config-file to 1.

      cd /AccessManager-base/bin
      ./amconfig -s
      AccessManager-base/bin/config-file

  3. Copy the server.policy file from the following directory:
  4. AppServer8Config-base/domains/domainName/config

    to the following target directory:

    AppServer8Config-base/nodeagents/nodeagentName/
    instanceName/config

  5. Modify the Release 4 Application Server domain.xml file.
    1. Copy the Access Manager classpath-suffix and server-classpath information in the server.xml file of the Release 2 Application Server instance in which Access Manager was originally deployed:
    2. AppServer7Config-base/domains/domainName/instanceName/config/server.xml

    3. Append the copied classpath information to the classpath-suffix and server-classpath entries, respectively, of the domain.xml file of the upgraded Application Server instance in which Access Manager is deployed:
    4. AppServer8Config-base/nodeagents/nodeagentName/instanceName/
      config/domain.xml

      The classpath information should be added to the instanceName-config block of the Release 4 Application Server domain.xml file. This block begins with the following line:

      <config dynamic-reconfiguration-enabled="true" name="instanceName-config">

      When making an addition to a classpath entry, be sure to include a colon (“:”), or whatever path separator is being used in classpath entries, between the old and new information. You can also delete all entries with the AppServer7-base path (be careful not to introduce errors).

  6. Restart the DAS.
  7. AppServer8-base/bin/asadmin stop-domain --user admin_ID
         --password password domainName

    AppServer8-base/bin/asadmin start-domain --user admin_ID
         --password password domainName

  8. Restart the server instance in which Access Manager is deployed.
  9. AppServer8-base/bin/asadmin stop-node-agent --user admin_ID
         --password password nodeagentName

    AppServer8-base/bin/asadmin start-node-agent --user admin_ID
         --password password nodeagentName

  10. Update the directory structure and schema as described in Step 6.

Verifying the Access Manager Upgrade

After you finish the upgrade procedure, verify that it was successful, as described in Verifying the Access Manager Upgrade.

Post-Upgrade Tasks

If you are using the Security Assertion Markup Language (SAML) service, you must add and enable a SAML authentication module using the Access Manager console. For information on creating a SAML authentication module instance, refer to the Sun Java System Access Manager Administration Guide (http://docs.sun.com/doc/817-7647).

Rolling Back the Upgrade

No scripts are provided for rolling back Access Manager to its pre-upgrade state. The process must be performed manually using Access Manager data that was backed up as part of the pre-upgrade tasks (see Back Up Release 3 Access Manager Log and Debug Files). Rollback is too difficult to be practical.



Previous      Contents      Index      Next     


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