test

Sun Java Enterprise System 5 Upgrade Guide for Microsoft Windows

Access Manager Upgrade

This section describes how to perform a Access Manager upgrade from Java ES 4 to Java ES 5. The section covers the following topics:

Pre-Upgrade Tasks

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

Upgrading Access Manager Dependencies

All Java ES components on a computer system and in a computing environment should be upgraded to Java ES Release 5. Access Manager has hard upgrade dependencies on only a couple of shared components.

If you choose to upgrade Access Manager product component dependencies, you should do so in the order below,skipping any components that might already have been upgraded, before you upgrade Access Manager. Upgrade of shared components is normally achieved automatically by the Java ES installer.

  1. Shared Components. All shared components required by Access Manager are upgraded automatically by the Java ES installer when you perform an upgrade of Access Manager to Release 5.

  2. Directory Server (optional). Instructions for upgrading Directory Server to Release 5 are provided in Chapter 2, Directory Server.

    Make sure that the Release 5 Directory Server uses the same port as of Release 4 Directory Server.

  3. Web Container Software (optional). Instructions for upgrading Web Server or Application Server are provided in Chapter 4, Web Server and Chapter 6, Application Server respectively.

    If web container software is not upgraded before Access Manager, the upgrade procedure will configure and redeploy Access Manager to the existing web container.

    Make sure that the Release 5 web container uses the same port as of Release 4 web container.

Backing 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.

Back Up Release 4 Access Manager Configuration Information

Because the reconfiguration of Release 5 Access Manager software requires the reconfiguration of the Release 4 version, you should back up configuration files to a known location. The following Web container configuration files should be backed up:

ProcedureTo Verify Current Version Information

    Type the following command.

    AccessManager-base\bin\amadmin --version

    The outputs that indicate the Access Manager version are:

    Release 5

    Access Manager 7.1

    Release 4

    Access Manager 7 2005Q4

ProcedureTo Upgrade Access Manager

Before You Begin

  1. Log in as administrator to the machine where Java ES 4 Access Manager is installed.

  2. Manually backup the Access Manager DIT (Directory Server data).

  3. Stop the following Java ES 4 services:

    • Web Server

    • Directory Server

    • Directory Proxy Server

    • Application Server

    • Instant Messaging

    • Calender Server

    • Messaging Server

  4. Install the Java ES 5 Access Manager.

    For Java ES 5 Access Manager installation instructions, see the Sun Java Enterprise System 5 Installation Guide for Microsoft Windows.

    Note –

    Restart the machine after installing Java ES 5 Access Manager.

  5. Re-customize JavaServer Pages for Access Manager.

    1. Re-apply the Release 4 customization to JavaServer Pages for the Access Manager Console and authentication user interface (UI) present in the Release 4 installation location.

    2. Copy the customized JSP files to the correct directories.

      • 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.

  6. Configure Access Manager.

    Configure Access Manager for your specific web container by running the amconfig.bat file. The amconfig.bat file and the associated AMConfigurator.properties input file resides in the AccessManager-base\setup directory.

    For information about the amconfig.bat file and the AMConfigurator.properties file, see the Sun Java System Access Manager Administration Guide.

    Perform the steps to reconfigure and redeploy Access Manager to the web container as described in To Reconfigure and Redeploy Access Manager.

  7. Update the directory structure and schema.

    Release 5 Access Manager coexists with the Release 4 directory structure, but the structure must be modified to support Release 5 capabilities. Update the Access Manager directory structure and schema to Release 5 by running the amupgrade.bat file, which is installed in the AccessManager-base\upgradedirectory.

    1. Obtain the values of the following parameters to be requested by the amupgrade.bat:

      Parameter  

      Value  

      Directory Server Host 

      Set the fully qualified name: hostname.domain.

      Directory Server Port 

      Specify a non-SSL port number Default: 389.

      Directory Manager DN 

      Default: cn=Directory Manager.

      Directory Manager Password 

      		 

      Access Manager Administrator User ID Default: amadmin

      Default: amadmin.

      Access Manager 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.

    2. Run the AccessManager-base\upgrade\amupgrade.bat file.

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

    3. Check the following upgrade log file for information about the directory schema extensions:

      AccessManager-base\setup\AccessManager_upgrade_num.log

  8. Enable the components disabled during reconfiguration of Access Manager.

  9. Start Access Manager.

    Restart the web container in which Access Manager is deployed.

ProcedureTo Reconfigure and Redeploy Access Manager

  1. If you chose to upgrade your web container software, as described in Upgrading Access Manager Dependencies, make sure the upgrade is complete

  2. Make sure that the administrative instance of your web container is running, and is in a mode supported by the amconfig.bat file, as indicated in the table below:

    Web Container 

    Supported Mode 

    Default Port Number 

    Application Server (8.x):

    Java ES 4 and 5 

    SSL (secure)  

    non-SSL 

    4849 

    Web Server (7.0): 

    Java ES 5 

    SSL (secure) 

    8989 

    Web Server (6.x):

    Java ES 4 

    non-SSL 

    8888 

  3. If the web container is running in SSL mode, make sure that the container's SSL certificates have not expired and are still valid.

  4. If Access Manager is deployed in Release 5 Web Server, disable all Java ES components depending on Access Manager that are running in the same instance as Access Manager.

    These components would likely be components such as Portal Server or Sun Java Communications Suite; Communications Express, Instant Messaging, or Delegated Administrator. The procedure is as follows:

    1. Log in as administrator at https://host:8989

    2. Go to Edit Virtual Server.

    3. Select the Web Applications tab.

    4. Select all Access Manager dependent applications.

    5. Click Disable.

    6. Click Save.

    7. Click deployment pending | Deploy Config.

      The configuration change will propagate to the Web Server instance

  5. Check that Directory Server and the appropriate web container are running.

  6. Set the configuration parameters in the AMConfigurator.properties file.

    Some of the parameter values can be migrated from the AMConfig.properties file and others are more specific to the upgrade procedure, as shown in the following table.

    Parameter  

    Value  

    Upgrade Parameters 

    		 

    DEPLOY_LEVEL

    Set to 26 for undeploy 

    Set to 1 for reconfigure and deploy 

    DIRECTORY_MODE

    Set to 5 (Existing Upgrade) 

    AM_REALM

    Set to disabled. Because Realm Mode is disabled, Legacy Mode is therefore enabled

    JAVA_HOME

    Set to the JDK Release 5 directory 

    WEB_CONTAINER

    Set to the value appropriate to the web container type you are using and fill out only the corresponding section of the configuration file. 

    WS61_INSTANCE

    (If using Web Server as the web container) 

    Set to https-hostname.domain where the value above matches the instance name in install-dir\webserver

    The value is case-sensitive. 

    AS81_INSTANCE

    (Using Application Server 8.x as the web container)

    Set to Application Server.x instanceName

    Default: server

    AS81_INSTANCE _DIR

    (Using Application Server 8.x as the web container)

    Set to Application Server.x domain directory for the instance

    Default: AppServer8Config-base\domains\domain1

    AS81_DOCS_DIR

    (Using Application Server 8.x as the web container)

    Set to Application Server.x docroot directory for the instance

    Default: AppServer8Config-base\domains\domain1\docroot

    AS81_ADMIN_IS_SECURE 

    (Using Application Server 8.x as the web container)

    Set to false

    Default: true

    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 4 configuration that you are upgrading, unless you are changing web container or passwords. For example, if you have upgraded Web Server to Release 5, provide the values from the following table.

    Parameter  

    Value  

    WS_CONFIG

    The name of the Web Server configuration: configName

    WS_INSTANCE

    https-configName

    WS_HOME

    WebServer7-base

    WS_PROTOCOL

    http or https

    WS_HOST

    Fully qualified host name on which Web Server instance is listening for connections 

    WS_PORT

    Port on which Web Server instance is listening for connections 

    WS_ADMINPORT

    Port on which Web Server administration instance is listening for connections  

    WS_ADMIN

    Web Server administrator user ID 

    WS_ADMINPASSWORD

    Web Server administrator password 

  7. Run AccessManager-base\setup\amconfig.bat to undeploy Access Manager.

    1. Set the value of DEPLOY_LEVEL to 26 in the AccessManaget-base\setup\AMConfigurator.properties file.

    2. Change to the setup directory.

      cd AccessManager-base\setup

    3. Run amconfig.bat file.

  8. Run AccessManager-base\setup\amconfig.bat to reconfigure Access Manager and deploy into web container.

    1. Set the value of DEPLOY_LEVEL to 1 in the AccessManager-base\setup\AMConfigurator.properties file.

    2. Change to the setup directory.

      cd AccessManager-base\setup

    3. Run amconfig.bat file.

ProcedureTo Verify the Access Manager Upgrade

    Type the following command.

    AccessManager-base\bin\amadmin --version

    The outputs that indicate the Access Manager version are:

    Release 5

    Access Manager 7.1

    Release 4

    Access Manager 7 2005Q4

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, see the Sun Java System Access Manager Administration Guide.