Chapter 2. Upgrading OpenAM Servers
Prev |  | Next

# Chapter 2. Upgrading OpenAM Servers

This chapter covers upgrade from OpenAM core server 9.5 or later to the current version. For other OpenAM components, see Upgrading OpenAM Components.

OpenAM server upgrade relies on the Upgrade Wizard to make the necessary changes to the configuration store. You must then restart OpenAM or the container in which it runs. Even a version number change requires that you run the Upgrade Wizard, so needing to run the Upgrade Wizard says nothing about the significance of the changes that have been made to OpenAM. You must run the Upgrade Wizard even for maintenance releases.

Make sure you try upgrading OpenAM in a test environment before applying the upgrade in your production environment.

Procedure 2.1. To Upgrade From OpenAM 9.5 or Later

Follow these steps to upgrade a site of OpenAM servers (version 9.5 or later). 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 `` command-line tool to upgrade the server configuration. The procedure, To Set Up Configuration Tools, describes how to install the tool.

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

9. Validate that the service is performing as expected.

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

Procedure 2.2. To Complete Upgrade from OpenAM 10.1.0 Xpress

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

Prev |  | Next
Chapter 1. About Upgrading OpenAM | Home | Chapter 3. Migrating Legacy Servers