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.
Prepare your customized OpenAM server .war file.
Back up the deployment.
Route client application traffic to another site during the upgrade.
For servers in the site, stop OpenAM, or if necessary stop the container where OpenAM runs.
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.
For servers in the site, restart OpenAM or the container where it runs.
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.
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.
Validate that the service is performing as expected.
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.
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
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.