Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Access Manager 6 2005Q1 Migration Guide 

Chapter 2
Upgrading to Access Manager 6 2005Q1

This chapter describes how to upgrade to Sun Java™ System Access Manager 6 2005Q1 from previous versions of Access Manager:

For information about upgrading other Sun Java Enterprise System components, see the Sun Java Enterprise System 2005Q1 Upgrade and Migration Guide (http://docs.sun.com/doc/819-0062).

For a roadmap about upgrading Access Manager, see the Access Manager Upgrade Roadmap.

Before You Begin the Access Manager Upgrade

Before you upgrade Access Manager, perform these preliminary steps:

  1. Obtain the Java Enterprise System 2005Q1 Installation Software
  2. Obtain All Required Patches
  3. Obtain the Required Information and Passwords
  4. Back Up Your Directory Server Data
  5. Back Up Any Web Container Customized Files
  6. Upgrade the Shared Components
  7. Upgrade the Web Container Software
  8. Use a Non-SSL Port for Directory Server
  9. Upgrade Directory Server (Optional)

Obtain the Java Enterprise System 2005Q1 Installation Software

Obtain the Sun Java Enterprise System (Java ES) 2005Q1 installation software. You can download the software from the Sun Download Center:

http://wwws.sun.com/software/download/

Or, request a media kit containing the software on CDs or a DVD from your Sun sales representative.

For more information about obtaining the Java ES installation software, see the Sun Java Enterprise System 2005Q1 Installation Guide (http://docs.sun.com/doc/819-0056).

Obtain All Required Patches

If you plan to upgrade to Access Manager 6 2005Q1, you need the following patches:

For information about other patches that might be required, see the Access Manager Release Notes (http://docs.sun.com/doc/817-7642).

To obtain the required patches, download them from the SunSolve site:

http://sunsolve.sun.com/

Obtain the Required Information and Passwords

To upgrade Access Manager, you must provide specific information, including administrator names and passwords. For example, you must know the Access Manager administrator and password and Directory Manager name and password for the Directory Server that Access Manager is using.

Before you upgrade, refer to the worksheets in Appendix A, "Access Manager Upgrade Worksheets" to record the required information.

Back Up Your Directory Server Data

The upgrade process uses scripts that modify the Directory Server schema (DIT). Therefore, before you upgrade, 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 Any Web Container Customized Files

Before you upgrade, back up any web container customized files related to previous versions of Access Manager, including:

Tip Make a list of your customizations so you can redo them after you upgrade and then verify that they work correctly.

Upgrade the Shared Components

Patches to upgrade the shared components are not required to upgrade Access Manager, but they are required when you upgrade other Java ES components such as the Access Manager web containers.

Note: If you upgrade to JDK 1.5 you must upgrade the Netscape Security Services (NSS) and Java Security Services (JSS) packages, including SUNWtls, SUNWjss, and SUNWpr, by applying the shared component cluster for your specific operating system.

For information about upgrading the shared components, see the Sun Java Enterprise System 2005Q1 Upgrade and Migration Guide (http://docs.sun.com/doc/819-0062).

Upgrade the Web Container Software

If you are upgrading both the web container (Web Server or Application Server) and Access Manager, upgrade the web container first, or the Access Manager amconfig script will configure and redeploy Access Manager to the existing (old) web container. Access Manager 6 2005Q1 supports these web containers:

For information about upgrading the web container, refer to the respective web container documentation in the Sun Java Enterprise System 2005Q1 Upgrade and Migration Guide (http://docs.sun.com/doc/819-0062).

Also, if you saved any customized files under Back Up Any Web Container Customized Files, redo the customizations after you upgrade the web container.

Use a Non-SSL Port for Directory Server

When you upgrade Access Manager, the upgrade process does not finish successfully if you specify the Directory Server SSL port (for example, the default value of 636) when you run the pre61to62upgrade, Upgrade61DitTo62, or amupgrade script.

Therefore, when you run these scripts, specify a non-SSL port such as the 389 default value.

Upgrade Directory Server (Optional)

Upgrading Directory Server is optional. To upgrade from Identity Server 2004Q2 to Access Manager 6 2005Q1, you can be running either of these versions:

If you plan to upgrade Directory Server, refer to the Sun Java Enterprise System 2005Q1 Upgrade and Migration Guide (http://docs.sun.com/doc/819-0062).

Upgrading Identity Server 2004Q2

In this scenario, you want to upgrade Identity Server 2004Q2 (6.2) or Identity Server 2004Q2 (6.2) SP1 to Access Manager 6 2005Q1 (6.3).

To upgrade Identity Server 2004Q2 to Access Manager 6 2005Q1

  1. Log in as or become superuser (root).
  2. Make sure you have performed the steps listed under Before You Begin the Access Manager Upgrade.
  3. If you have installed Identity Server 2004Q2 SP1, you must first back out SP1 before you apply the upgrade patches.

    4. To determine the release you are running use the amserver version command on either a Solaris or Linux system. On Solaris systems, you can also use the showrev command with the -p option to display patch information. For example:

    # showrev -p | grep SUNWam

  4. On the Solaris 8 or 9 SPARC and x86 platforms, remove the SUNWamjwsdp Solaris package. On Linux systems, remove the sun-identity-jwsdp RPM package. For example, on a Solaris system:

    5. # pkgrm SUNWamjwsdp

    These packages contain Access Manager 2004Q2 (6.2) components such as JAXP and JAXB for the Java Web Services Developer Pack (JWSDP). Access Manager 2005Q1 (6.3) uses the Java ES shared component packages and RPMs for the JWSDP products instead of bundling its own.

  5. Apply the following Access Manager upgrade patches or RPMs, depending on your platform. If you have a multi-server configuration, apply the respective patches or RPMs to each server running an instance of Access Manager.
    • Solaris™ OS, SPARC� Platform Edition: 118217, 118218, 117112, 117585
    • Solaris OS, x86 Platform Edition: 118217, 118218, 117584, 117585

      • Note 118217, 118218 and 117585 are common patches that applies to both the SPARC and x86 platforms. Apply patches 118217 and 118218 first, before you apply 117585.

    • Linux OS: 117588 (patch that contains the required Linux RPMs)
      To upgrade:

      • a. Unzip the 117588 patch file.

      b. Read the README file.

      c. Run the installpatch script, which adds the RPMs.

  6. Reapply any customized JSPs for the Access Manager console and authentication user interface (UI) that you saved under Back Up Any Web Container Customized Files. Then, copy the customized JSP files to the correct directories. For example, on Solaris systems:
    • Console: AccessManager-Base/SUNWam/web-src/applications/console
    • Authentication UI: AccessManager-Base/SUNWam/web-src/services/config/auth/default

      • For more information, see the Sun Java System Access Manager Developer's Guide (http://docs.sun.com/doc/817-7649).

  7. Configure Access Manager for your specific web container by running the amconfig script.

    8. Note Before you run amconfig, make sure that you have upgraded the Access Manager web container, as described in Upgrade the Web Container Software.

    Before you run amconfig, set the configuration variables in the configuration script input file, which is based on the amsamplesilent template file:

    • Set DEPLOY_LEVEL=21 and DIRECTORY_MODE=4.
    • The default JDK version for Sun Java Enterprise System 2005Q1 release is 1.5, so make sure you set the JAVA_HOME variable in the configuration script input file to the correct directory.
    • Make sure to set the AM_ENC_PWD variable to the same value you specified when you ran the Java ES installer (which is also the value of the am.encryption.pwd parameter in the AMConfig.properties file.
    • For other values in the configuration script input file, provide the same values that were used for the Identity Server 6.1 configuration that you are upgrading (unless you have changed specific items such as your web container or passwords).

      • To set the configuration values, consider using the worksheets in Appendix A, "Access Manager Upgrade Worksheets."

      The amconfig script and the amsamplesilent file are installed in the following directories:

    • Solaris systems: AccessManager-base/SUNWam/bin
    • Linux systems: AccessManager-base/identity/bin

      • The default AccessManager-base installation directory is /opt on Solaris systems and /opt/sun on Linux systems.

      For example, to run amconfig on a Solaris system with Access Manager installed in the base installation directory:

      # cd /opt/SUNWam/bin
      # ./amconfig -s config-file

      where config-file is the configuration script input file.

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

  8. Upgrade the Access Manager schema (DIT) to Access Manager 6 2005Q1 by running the amupgrade script, which is installed in the following directory:
    • Solaris systems: AccessManager-base/SUNWam/upgrade/scripts
    • Linux systems: AccessManager-base/identity/upgrade/scripts

      • The default AccessManager-base installation directory is /opt on Solaris systems and /opt/sun on Linux systems.

      Before you run amupgrade, you will need to know the following information:

    • Fully-qualified host name and non-SSL port number of the Directory Server that Access Manager is using
    • Directory Manager name (default: cn=Directory Manager) and password for the Directory Server
    • Access Manager administrator (default: amadmin) and password

      • Run the amupgrade script. For example, on Solaris systems:

      # cd /opt/SUNWam/upgrade/scripts
      # ./amupgrade

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

  9. The amupgrade script writes status information to the following log file:

    10. /var/sadm/install/logs/Sun_Java_System_Identity_Server_upgrade_dit_log. mmddhhmm

    Check this log file for information about the upgrade.

  10. Restart the Access Manager web container for the upgrade changes to take effect.
  11. If you are using the Security Assertion Markup Language (SAML) service, you must add and enable the SAML authentication module using the Access Manager console. For the steps involved, refer to the Sun Java System Access Manager Administration Guide (http://docs.sun.com/doc/817-7647).

    12. Note

    In the Access Manager 6 2005Q1 release, the default value for the “Default success login URL” attribute in the core service has changed from “%protocol://%host:%port/amconsole” to “/amconsole”.

    Consequently, The %protocol, %host and %port variables are not supported. For a remote console, you must modify the “Default success login URL” to point to the console page on the actual remote console host, if the console page is expected after a login.

     

Upgrading Identity Server 6.1

In this scenario, you want to upgrade Identity Server 6.1 to Access Manager 6 2005Q1.

To upgrade Identity Server 6.1 to Access Manager 6 2005Q1

  1. Log in as or become superuser (root).
  2. Make sure you have performed any required steps listed under Before You Begin the Access Manager Upgrade.
  3. Before you run the pre-upgrade script, consider using the Pre-Upgrade Script Worksheet to record the information you will need to provide.
  4. To run the pre-upgrade script in the next step, Directory Server must be running. To verify that Directory Server is running:

    5. # ps -ef | grep slapd

    If Directory Server is not running, start it. For example:

    # cd /var/opt/mps/serverroot/slapd-instance-name
    # ./start-slapd

  5. Run the Identity Server 2004Q2 pre-upgrade script (pre61to62upgrade) to perform these functions:
    • Backs up Identity Server 2004Q2 by running the am2bak script
    • Removes the Identity Server 2004Q2 packages (but not the Directory Server or web container packages) and then updates the /var/sadm/install/productregistry file to reflect that the packages have been removed
    • Writes the Sun_Java_System_Identity_Server_upgrade_log.timestamp log file to the /var/sadm/install/logs directory

      • The pre61to62upgrade script is part of the Java ES installation software and is available in the following directory:

      JavaES-base/Solaris_sparc/Product/identity_srv/Tools

      The JavaES-base is the directory where you uncompressed the archive. For example:

      # cd JavaES2005Q1/Solaris_sparc/Product/identity_srv/Tools
      # ./pre61to62upgrade

  6. When you are prompted by the script, enter the following information:
    • Directory Server fully qualified host name. For example: ds.example.com
    • Directory Server non-SSL port number. Default is 389.
    • Distinguished name (DN) and password of the top-level Identity Server administrator. For example: uid=amAdmin,ou=People,dc=example,dc=com
    • Directory where the script should back up the Identity Server 6.1 files. For example: /opt/is_backup
    • Certificate directory of the web container. For example: /opt/SUNWwbsvr/alias
  7. Install Access Manager 6 2005Q1 by running the Java ES 2005Q1 installer. On the Configuration Type panel, choose the Configure Later option.

    8. The Java ES installer then installs the component packages but does not configure the components. For information about the Java ES installer, refer to the Sun Java Enterprise System 2005Q1 Installation Guide (http://docs.sun.com/doc/819-0056).

  8. Configure Access Manager for your specific web container by running the amconfig script.

    9. Note Before you run amconfig, make sure that you have upgraded the Access Manager web container, as described in Upgrade the Web Container Software.

    • Set DEPLOY_LEVEL=21 and DIRECTORY_MODE=4.
    • The default JDK version for Sun Java Enterprise System 2005Q1 release is 1.5, so make sure you set the JAVA_HOME variable in the configuration script input file to the correct directory.
    • Make sure to set the AM_ENC_PWD variable to the same value you specified when you ran the Java ES installer (which is also the value of the am.encryption.pwd parameter in the AMConfig.properties file.
    • For other values in the configuration script input file, provide the same values that were used for the Identity Server 6.1 configuration that you are upgrading (unless you have changed specific items such as your web container or passwords).

      • To set the configuration values, consider using the worksheets in Appendix A, "Access Manager Upgrade Worksheets."

      The amconfig script and the amsamplesilent file are installed in the following directories:

    • Solaris systems: AccessManager-base/SUNWam/bin
    • Linux systems: AccessManager-base/identity/bin

      • The default AccessManager-base installation directory is /opt on Solaris systems and /opt/sun on Linux systems.

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

  9. To run the post-upgrade script in the next step, Directory Server must be running. To verify that Directory Server is running:

    10. # ps -ef | grep slapd

    If Directory Server is not running, start it. For example:

    # cd /var/opt/mps/serverroot/slapd-instance-name
    # ./start-slapd

  10. Run the Identity Server 2004Q2 post-upgrade script (Upgrade61DitTo62) to upgrade the Directory Server schema (DIT) to Identity Server 2004Q2.

    11. This script is available in the following directories:

    • Solaris systems: AccessManager-base/SUNWam/migration/61to62/scripts
    • Linux systems: AccessManager-base/identity/migration/61to62/scripts

      • The default AccessManager-base installation directory is /opt on Solaris systems and /opt/sun on Linux systems.

      For example, to run the script on Solaris systems:

      # cd opt/SUNWam/migration/61to62/scripts
      # ./Upgrade61DitTo62

  11. When you are prompted by the Upgrade61DitTo62 script, provide the following information:
    • Directory Server fully qualified host name. For example: ds.example.com
    • Directory Server non-SSL port number. Default is 389.
    • Distinguished name (DN) and password of the Directory Manager
    • Distinguished name (DN) and password of the top-level Identity Server administrator. For example: uid=amAdmin,ou=People,dc=example,dc=com
  12. When you are prompted by the Upgrade61DitTo62 script, restart Directory Server. The script pauses for you to perform the restart.
  13. After the Upgrade61DitTo62 script finishes, restart both Directory Server and the web container for the schema changes to take effect.
  14. Upgrade the Access Manager schema (DIT) to Access Manager 6 2005Q1 by running the amupgrade script, which is installed in the following directory:
    • Solaris systems: AccessManager-base/SUNWam/upgrade/scripts
    • Linux systems: AccessManager-base/identity/upgrade/scripts

      • The default AccessManager-base installation directory is /opt on Solaris systems and /opt/sun on Linux systems.

      Before you run amupgrade, you will need to know the following information:

    • Fully-qualified host name and non-SSL port number of the Directory Server that Access Manager is using
    • Directory Manager name (default: cn=Directory Manager) and password for the Directory Server
    • Access Manager administrator (default: amadmin) and password

      • Run the amupgrade script. For example, on Solaris systems:

      # cd opt/SUNWam/upgrade/scripts
      # ./amupgrade

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

  15. The amupgrade script writes status information to the following log file:

    16. /var/sadm/install/logs/Sun_Java_System_Identity_Server_upgrade_dit_log. mmddhhmm

    Check this log file for information about the upgrade.

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

You have now upgraded to Access Manager 6 2005Q1.

Upgrading an Access Manager SDK Installation

This section describes how to upgrade an SDK only installation to the Access Manager 6 2005Q1 SDK, including:

To upgrade an Identity Server 6.1 SDK only installation

  1. Log in as or become superuser (root).
  2. Make sure you have saved the Identity Server 6.1 AMConfig.properties and serverconfig.xml configuration files.
  3. Uninstall the Identity Server 6.1 SDK by following the instructions in the Sun Java Enterprise System 2003Q4 Installation Guide (http://docs.sun.com/doc/816-6874).
  4. Install the Access Manager 6 2005Q1 SDK by following the instructions in the Sun Java Enterprise System 2005Q1 Installation Guide (http://docs.sun.com/doc/819-0056).

    5. You can also install the Identity Server 2004Q2 SDK and then apply the patches described in To upgrade an Identity Server 2004Q2 (6.2) SDK only installation.

  5. Incorporate the configuration changes you saved in Step 2 into the new Access Manager 6 2005Q1 configuration files.

To upgrade an Identity Server 2004Q2 (6.2) SDK only installation

  1. Make sure you have saved the Identity Server 2004Q2 AMConfig.properties and serverconfig.xml configuration files.
  2. Apply the following Access Manager upgrade patches on the server where the SDK is installed, depending on your platform:
    • Solaris™ OS, SPARC� Platform Edition: 118217, 118218, 117112, 117585
    • Solaris OS, x86 Platform Edition: 118217, 118218, 117584, 117585

      • Note 118217, 118218 and 117585 are common patches that applies to both the SPARC and x86 platforms. Apply patches 118217 and 118218 first, before you apply 117585.

    • Linux OS: 117588 (patch that contains the required Linux RPMs)
      To upgrade:

      • a. Unzip the 117588 patch file.

      b. Read the README file.

      c. Run the installpatch script, which adds the RPMs.

  3. Configure the Access Manager SDK for your specific deployment by running the amconfig script. Before you run amconfig, set the configuration variables in the configuration script input file, which is based on the amsamplesilent template file. Set DEPLOY_LEVEL as follows:
    • DEPLOY_LEVEL=3 to upgrade the SDK only
    • DEPLOY_LEVEL=4 to upgrade the SDK and configure the web container

      • For other values in the configuration script input file, provide the same values that were used for the Identity Server 6.1 SDK configuration that you are upgrading (unless you have changed specific items such as your web container or passwords).

      The default JDK version for Sun Java Enterprise System 2005Q1 release is 1.5, so make sure you set the JAVA_HOME variable in the configuration script input file to the correct directory.

      To set the configuration values, consider using the worksheets in Appendix A, "Access Manager Upgrade Worksheets."

      The amconfig script and the amsamplesilent file are installed in the following directories:

    • Solaris systems: AccessManager-base/SUNWam/bin
    • Linux systems: AccessManager-base/identity/bin

      • The default AccessManager-base installation directory is /opt on Solaris systems and /opt/sun on Linux systems.

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

  4. Incorporate the configuration changes you saved in Step 1 into the new Access Manager 6 2005Q1 configuration files.
  5. If you are using the Security Assertion Markup Language (SAML) service, you must add and enable the SAML authentication module using the Access Manager console. For the steps involved, refer to the Sun Java System Access Manager Administration Guide (http://docs.sun.com/doc/817-7647).

    6. Note

    In the Access Manager 6 2005Q1 release, the default value for the “Default success login URL” attribute in the core service has changed from “%protocol://%host:%port/amconsole” to “/amconsole”.

    Consequently, The %protocol, %host and %port variables are not supported. For a remote console, you must modify the “Default success login URL” to point to the console page on the actual remote console host, if the console page is expected after a login.

 

Upgrading Multiple Instances

This section describes how to upgrade multiple Identity Server instances running on different hosts that share the same Directory Server.

The upgrade process supports multiple instances of Identity Server installed on different host systems. Upgrading multiple instances of Identity Server 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.

To Upgrade an Instance

  1. Log in as or become superuser (root).
  2. Stop all Identity Server instances that access Directory Server. For example, on a Solaris system that uses the default installation directory:

    3. # cd /opt/SUNWam/bin
    # ./amserver stop

    Stopping all instances prevents Identity Server from making changes to the Directory Server while you are performing the upgrade.

  3. Start the Identity Server instance you want to upgrade.
  4. Upgrade the Identity Server instance you started in Step 3, following the process shown in the Access Manager Upgrade Roadmap.

    5. During the upgrade of the first instance, the post-upgrade scripts upgrade the Directory Server to include the Access Manager 6 2005Q1 schema elements. During subsequent upgrades of other instances, however, the scripts detect that Directory Server has already been upgraded and do not try to upgrade it again.

  5. Restart the instance you just upgraded.
  6. Repeat Step 3 through Step 5 for each Identity Server instance on a different host that you want to upgrade.
  7. If there are any Identity Server 2004Q2 instances you did not upgrade, restart those instances. For information about the co-existence of Identity Server 2004Q2 and Access Manager 6 2005Q1, see Access Manager Coexistence.

Verifying the Upgrade

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

  1. Log in to the Access Manager 6 2005Q1 console as amadmin using the following URL:

    2. http://host-name.domain-name:port/amconsole

    where host-name.domain-name:port is the fully qualified host name and port number of the web container you are using.

    Verify that new services under the “Service Configuration” tab are available.

  2. Review the status of the upgrade by checking the following log files in the /var/sadm/install/logs directory:

    3. pre61to62upgrade script: Sun_Java_System_Identity_Server_upgrade_log.timestamp

    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

    Upgrade61DitTo62 script: Sun_Java_System_Identity_Server_upgrade_dit_log.timestamp

    amupgrade script: Sun_Java_System_Identity_Server_upgrade_dit_log.timestamp

Access Manager Coexistence

The coexistence of Access Manager 6 2005Q1 and Identity Server 2004Q2 is a transitional phase during an Access Manager upgrade. These two versions can coexist and run concurrently against the same shared Directory Server, with these considerations:



Previous      Contents      Index      Next     

Part No: 817-7645-10.   Copyright 2005 Sun Microsystems, Inc. All rights reserved.