Follow these steps to upgrade a site of OpenAM servers. For information on the versions of OpenAM that are supported for upgrade, see Section 3.7, "Supported Upgrade Paths" in the Release Notes.

During the upgrade process, you must take the OpenAM servers in the site out of production, instead redirecting client application traffic elsewhere. This is required because upgrade involves making changes to OpenAM's configuration model. If the upgrade fails, you must be able to roll back before the configuration changes impact other sites.

1. Prepare your customized OpenAM server .war file.

2. Back up the deployment.

3. Route client application traffic to another site during the upgrade.

4. For servers in the site, stop OpenAM, or if necessary stop the container where OpenAM runs.

5. For servers in the site, deploy your customized server .war file.

   When you deploy the new .war file, you might have to delete working files left by the old installation. For example, if you deploy on Apache Tomcat, replacing /path/to/tomcat/webapps/openam.war, then also recursively delete the /path/to/tomcat/webapps/openam/ and /path/to/tomcat/work/Catalina/localhost/openam/ directories before restarting the server.

6. For servers in the site, restart OpenAM or the container where it runs.

7. For the first server in the site, follow the instructions in the Upgrade Wizard.

   Alternatively, you can use the openam-upgrade-tool-11.0.0.jar command-line tool to upgrade the server configuration. The procedure, To Set Up Configuration Tools in the Installation Guide, describes how to install the tool.

8. (Optional) If you want to configure the upgraded system with a different directory service for the Core Token Service (CTS), read Configuring the Core Token Service in the Installation Guide.

9. Validate that the service is performing as expected.

10. Allow client application traffic to flow to the upgraded site.

When upgrading from OpenAM 10.1.0 Xpress, the upgrade tool does not change the Dashboard service LDAP schema, although the object IDs used in the Dashboard service LDAP schema definitions are not correct.

You can fix the object IDs manually using the OpenDJ ldapmodify command. The command is delivered with OpenDJ directory server.

1. Update the LDAP schema defined in the OpenDJ directory server where OpenAM stores its configuration.

   Make the change on one of the replicated OpenDJ configuration directory servers.

   The example command shown below uses the ldapmodify command delivered with the embedded OpenDJ configuration directory server for OpenAM with deployment URI /openam. When you use the embedded OpenDJ configuration directory server, the password for the cn=Directory Manager account is the same password used by amadmin.

   The LDAP schema definitions are stored on the LDAP subentry with distinguished name cn=schema. You use the following LDIF format definitions to correct the object IDs in the definitions.

   $ cd ~/openam/opends/bin
   $ cat dash.ldif
   dn: cn=schema
   changetype: modify
   delete: objectClasses
   objectClasses: ( 1.3.6.1.4.1.1466.101.120.1433 NAME
     'forgerock-am-dashboard-service' AUXILIARY MAY (
      assignedDashboard ) X-ORIGIN 'Forgerock' )
   -
   delete: attributeTypes
   attributeTypes: ( 1.3.6.1.4.1.36733.2.1.9.2.811 NAME ( 'assignedDashboard' )
     DESC 'Dashboard App registry' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
     X-ORIGIN 'OpenAM' )
   -
   add: attributeTypes
   attributeTypes: ( 1.3.6.1.4.1.36733.2.2.1.3.1 NAME ( 'assignedDashboard' )
     DESC 'Dashboard App registry' SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
     X-ORIGIN 'OpenAM' )
   -
   add: objectClasses
   objectClasses: ( 1.3.6.1.4.1.36733.2.2.2.3.1 NAME
     'forgerock-am-dashboard-service' AUXILIARY MAY (
     assignedDashboard ) X-ORIGIN 'Forgerock' )
   
   $ ./ldapmodify -p 50389 -D "cn=Directory Manager" -w password -f ./dash.ldif
   Processing MODIFY request for cn=schema
   MODIFY operation successful for DN cn=schema

2. (Optional) If you want to configure the upgraded system with a different directory service for the Core Token Service (CTS), read Configuring the Core Token Service in the Installation Guide.

1. Prepare your customized OpenAM server .war file.

2. Prepare a new deployment, installing servers from the new, customized .war file as described in the Installation Guide, starting with the instructions in Installing OpenAM Core Services in the Installation Guide.

3. After installation, configure the new servers in the same way as the old servers, adapting as necessary.

   You can use the ssoadm do-batch command to apply multiple changes with one command.

4. Validate that the new service is performing as expected.

5. Redirect client application traffic from the old deployment to the new deployment.

1. Back up the policy agent installation and configuration directories.

   Also back up the configuration if it is stored centrally in OpenAM.

2. Redirect client traffic away from the protected application.

3. Stop the web server where the policy agent is installed.

4. Extract the new files over the old installation.

5. Start the web server where the policy agent is installed.

   For new features, the policy agent uses the default configuration until you make changes.

6. Validate that the policy agent is performing as expected.

7. Allow client traffic to flow to the protected application.

1. Back up the policy agent installation and configuration directories.

   Also back up the configuration if it is stored centrally in OpenAM.

2. Redirect client traffic away from the protected application.

3. Uninstall the old policy agent.

4. Install the new policy agent.

   For new features, the policy agent uses the default configuration until you make changes.

5. Validate that the policy agent is performing as expected.

6. Allow client traffic to flow to the protected application.

Since OpenAM 10.1, the session tools are no longer needed. Upgrading other tools consists of installing new tools and customizing tools scripts as necessary.

1. Install new versions of the tools.

2. Apply any customizations you made to the scripts, referring to the old tools installation as necessary.

3. Once the new tools are working, you can delete the old tools.

If you deployed the distributed authentication server (DAS) .war file, then you should upgrade the DAS when you upgrade other OpenAM servers.

1. Redirect client application traffic away from the server.

2. Stop the DAS or the container in which it runs.

3. Deploy the new DAS .war file.

   When you deploy the new .war file, you might have to delete working files left by the old installation.

4. Restart the DAS or the container in which it runs.

5. Validate that the DAS is working as expected.

6. Allow client application traffic to flow back to the server.