How To

How do I perform a high availability two-server upgrade from OpenAM 10.x to a later version (Embedded Configuration)?

Last updated Jan 5, 2021

The purpose of this article is to provide information on performing a high availability two-server upgrade from OpenAM 10.x to a later version (Embedded Configuration). This is one of a series of articles intended to provide a known and tested methodology for upgrading OpenAM in a specific scenario. This procedure can be used as a reliable starting point for creating deployment-specific upgrade plans.


This article has been archived and is no longer maintained by ForgeRock.


Before performing this upgrade, you should read the Release Notes and Upgrade Guide applicable to the new release to improve your understanding of the upgrade process. In particular, you should refer to these sections (links provided for OpenAM 13):

If you are upgrading to OpenAM 13, you must ensure you are running the correct version of Java as per Java Requirements; OpenAM 13 does not function with Java 6. You should also be aware of the following important changes that will occur as a result of this upgrade:

  • The token store between OpenAM 10.x and later releases is not compatible. If session persistence is in use, these sessions will be lost and users will need to re-authenticate when they next access the service.
  • There is a significant OpenDJ upgrade included. This upgrade occurs automatically during the first initialization of the new WAR file, not during the upgrade wizard.

The --disableAll replication command does not work correctly in the older 2.4.5 version of OpenDJ, which is why it is not used in favor of individual commands for each prefix.

Some extra optional steps and precautions to consider

Check replication is really stopped after running the disable command.

Consider completely firewalling the OpenAM servers in each group from each other. Crosstalk can occur and still works to some extent between 10.x and later versions. It should not pose a major problem, particularly if only one set of servers is being used, but may be worth eliminating if the system is likely to be running in a partially upgraded state for an extended period of time.

Performing a high availability two-server upgrade

This procedure is recommended if a downtime maintenance window is not acceptable or only a very short window is acceptable. The upgrade will still not be completely seamless as the persistent session store schema has been changed between OpenAM 10.x and later versions. This means all your existing sessions will be lost, so at the point of switch-over, all users will be prompted to re-authenticate before carrying on as normal.


These instructions rely on a load balancer of some sort used in between your OpenAM site and end-users. If you are using some other kind of balancing method such as DNS round robin you will need to use a different methodology.

Rollback plan

As per the Upgrade Guide, you will need to take a LDIF backup of the configuration data store in the directory servers as well as a file system backup.

You will need to take copies of:

  • The OpenAM instance directory (default ~/openam) while OpenAM is not running.
  • The web container with the deployed OpenAM, for example, /path/to/tomcat/webapps/openam for Apache Tomcat™.
  • The $HOME/.openamcfg/ directory of the user running the web application container where OpenAM is deployed.

Since OpenAM needs to be stopped to take the instance directory backup, the best time to take this is just after bringing down the instance. This also ensures the configuration is as up to date as possible.


  1. Check and make a note of the output from dsreplication status as a base reference using the following command: $ ./dsreplication status -h [host] -p [port] -I [adminUID] -j [bindpasswordfile] -X replacing [host], [port], [adminUID] and [bindpasswordfile] with appropriate values.
  2. Disable the first OpenAM server from the load balancer. You can optionally stop the OpenAM server, take a backup and then restart it to give you a backup before disabling replication.
  3. Disable replication on this OpenAM server using the following command: $ ./dsreplication disable -h [host] -p [port] -D [configsuffix] --disableReplicationServer replacing [host], [port] and [configsuffix] with appropriate values.

Optionally you could firewall the two servers from each other instead of disabling replication.

  1. Shut down this instance and take a backup if not done already.
  2. Apply the new OpenAM WAR file and restart it.
  3. Run through the OpenAM upgrade wizard.

If you are upgrading from OpenAM 10.1.0 Xpress, you must update the Dashboard service LDAP schema to complete the upgrade. This is detailed in the OpenAM Upgrade Guide › Upgrading OpenAM Servers › To Complete Upgrade from OpenAM 10.1.0 Xpress.

  1. Restart OpenAM and check as far as possible that normal operation is occurring.
  2. Enable the upgraded server and disable the old server using your load balancer.
  3. Monitor as required. This could be a period of minutes, hours or days depending on your specific requirements. It is a lot easier to rollback when it is a case of enabling/disabling servers on a load balancer; once you commit further to the upgrade, the rollback process becomes more involved.
  4. Disable replication on the second server (see step 3).
  5. Shut down this instance and take a backup if not done already.
  6. Apply the new OpenAM WAR file and restart it.
  7. Re-enable replication with the first upgraded OpenAM server as the source and then initialize using the following commands: $ ./dsreplication enable --host1 [server1] --port1 [port1] --host2 [server2] --port2 [port2] $ ./dsreplication initialize --hostSource [server1] --portSource [port1] --hostDestination [server2] --portDestination [port2] replacing [server1], [port1], [server2] and [port2] with appropriate values.
  8. Restart this OpenAM to complete the procedure.

See Also

Best practice for upgrading to OpenAM 13.x

Best practice for upgrading to OpenAM 12.x

Best practice for migrating policies when upgrading to OpenAM 12.x or 13.x

How do I perform a high availability multi-server upgrade from OpenAM 10.x to a later version (Embedded Configuration)?

How do I perform a multi-server upgrade from OpenAM 10.x to a later version (Embedded configStore/ctsStore)?

How do I upgrade AM (All versions) with minimal downtime when replication is used?

How do I upgrade AM 5.x or 6.x if I am using a site configuration?

How do I make a backup of configuration data in AM 5.x or 6.x?

FAQ: Upgrading AM

OpenAM 13 Release Notes

OpenAM 13 Upgrade Guide

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

OPENAM-2110 (Upgrade fails if external configstore is using non-default user)

OPENAM-3173 (The dash.ldif contains bad order for the Upgrade from OpenAM 10.1.0 Xpress)

OPENAM-3192 (OpenAM 10 does not support OpenAM 11 schema)

OPENAM-3947 (Upgrade removes user-added Advanced Properties from Default Server Settings )

Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.