How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated Apr 13, 2021

The purpose of this article is to provide information on upgrading AM if you have a site configuration with multiple servers and require minimal downtime.


2 readers recommend this article

AM 7 and later

This article only applies to pre-AM 7 because there have been a lot of changes in AM 7 and DS 7.

You should follow the steps detailed in Upgrade Guide › To Upgrade From a Supported Version, which includes details on upgrading sites.

Overview

Note

As with any software upgrade, we strongly recommend testing the procedure in your own staging environment first and ensuring you have up to date backups and recovery plans in case you encounter any issues. You should also make sure you read the Release Notes relating to the new version of AM so that you are fully aware of all the changes.

If you are using a Site configuration with multiple servers, it is recommended that you temporarily split your site into two prior to upgrading and then upgrade per this article. This example has 4 AM servers in a site configuration (SiteA) with each AM server pointing to its own DS configuration store. The following table gives the corresponding hostnames and port numbers used in this article:

AM Host              DS Host  Admin Port  Replication Port
AM1 ds1 4444 50989
AM2 ds2 5444 58989
AM3 ds3 6444 59989
AM4 ds4 7444 60989

Upgrading a site configuration

  1. Take servers AM3 and AM4 out of your load balancer configuration. Traffic should now only to go to servers AM1 and AM2.
  2. Split servers AM3 and AM4 out of your site (SiteA) as follows:
    1. Navigate to Deployment > Servers and click the name of the server you want to remove from the site (AM3).
    2. Set the Parent Site field to [empty] and click Save Changes.
    3. Repeat steps 1 and 2 for the other server (AM4).
  3. Stop replication on ds3 and ds4 using the dsreplication command, for example: $ ./dsreplication unconfigure --unconfigureAll --port 6444 --hostname ds3.example.com --adminUID admin --adminPassword password --trustAll --no-prompt $ ./dsreplication unconfigure --unconfigureAll --port 7444 --hostname ds4.example.com --adminUID admin --adminPassword password --trustAll --no-prompt
  4. Verify that ds3 and ds4 have been removed from the replication configuration in ds1 and ds2 using the dsreplication status command, for example: $ ./dsreplication status --port 4444 --hostname ds1.example.com --adminUID admin --adminPassword password --trustAll $ ./dsreplication status --port 5444 --hostname ds2.example.com --adminUID admin --adminPassword password --trustAll
Note

If ds3 and/or ds4 still appear in the dsreplication status output from ds1 or ds2, you need to repair your replication configuration. See How do I repair replication configuration in DS 5.x or 6.x when dsreplication has failed? for further details.

  1. Create a new temporary site (SiteB). You must use a DNS alias for the load balancer as AM will not allow the same primary URL for both sites. For example, you could have something similar to the following where both hostnames point to the same host IP: SiteA host1.example.com:8080/openam SiteB  openam.example.com:8080/openam
  2. Add servers AM3 and AM4 to SiteB.
  3. Re-enable replication between ds3 and ds4 in this site using the dsreplication command, for example:$ ./dsreplication configure --adminUid admin --adminPassword password --baseDn dc=example,dc=com --host1 ds3.example.com --port1 6444 --bindDn1 "cn=Directory Manager" --bindPassword1 password --replicationPort1 59989 --host2 ds4.example.com --port2 7444 --bindDn2 "cn=Directory Manager" --bindPassword2 password --replicationPort2 60989 --trustAll --no-prompt
  4. Pause replication on ds4, for example: $ ./dsreplication suspend --hostname ds4.example.com --port 7444 --adminUid admin --adminPassword password --trustAll --no-prompt
  5. Upgrade AM3 in SiteB:
    1. Deploy the new AM war file and restart AM3.
    2. Navigate to the AM URL, for example: http://AM3.example.com:8080/openam and follow the instructions in the Upgrade Wizard.
    3. Restart AM3 once the upgrade finishes.
  6. Upgrade AM4 in SiteB:
    1. Resume replication on ds4, for example: $ ./dsreplication resume --hostname ds4.example.com --port 7444 --adminUid admin --adminPassword password --trustAll --no-prompt
    2. Deploy the new AM war file and restart AM4.
  7. Transfer traffic from SiteA to the newly upgraded SiteB at the load balancer.
  8. Repeat steps 8 to 10 to upgrade AM1 and AM2 in SiteA; in summary:
    1. Pause replication on ds2.
    2. Upgrade AM1.
    3. Resume replication on ds2.
    4. Deploy new war file on AM2.
    5. Restart AM2.
  9. Transfer traffic from SiteB back to SiteA at the load balancer.
  10. Delete SiteB; this removes servers AM3 and AM4 from the site.
  11. Stop replication on ds3 and ds4 using the dsreplication command, for example: $ ./dsreplication unconfigure --unconfigureAll --port 6444 --hostname ds3.example.com --adminUID admin --adminPassword password --trustAll --no-prompt $ ./dsreplication unconfigure --unconfigureAll --port 7444 --hostname ds4.example.com --adminUID admin --adminPassword password --trustAll --no-prompt
  12. Add servers AM3 and AM4 back in to the original SiteA and restart both servers:
  13. Re-enable replication between ds3 and ds4 using the dsreplication command, for example: $ ./dsreplication configure --adminUid admin --adminPassword password --baseDn dc=example,dc=com --host1 ds3.example.com --port1 6444 --bindDn1 "cn=Directory Manager" --bindPassword1 password --replicationPort1 59989 --host2 ds4.example.com --port2 7444 --bindDn2 "cn=Directory Manager" --bindPassword2 password --replicationPort2 60989 --trustAll --no-prompt
  14. Enable replication between ds1 and ds3 using the dsreplication command, for example: $ ./dsreplication configure --adminUid admin --adminPassword password --baseDn dc=example,dc=com --host1 ds1.example.com --port1 4444 --bindDn1 "cn=Directory Manager" --bindPassword1 password --replicationPort1 50989 --host2 ds3.example.com --port2 6444 --bindDn2 "cn=Directory Manager" --bindPassword2 password --replicationPort2 59989 --trustAll --no-prompt
  15. Reinitialize all the DS servers from one of the servers that remained on SiteA (ds1 or ds2) to ensure the re-added servers have all the changes that have occurred since you split the site: $ ./dsreplication initialize-all --adminUID admin --adminPassword password --baseDN dc=example,dc=com --hostname ds1.example.com --port 4444 --trustAll --no-prompt
  16. Add the two servers AM3 and AM4 back in to your load balancer configuration. Traffic should now go to all four servers again.

Agent sessions

If agent sessions were created on a server in the temporary site that you created during upgrade (SiteB in this example), those sessions will not be valid once the upgrade is complete. AM cannot process any requests for sessions that contain invalid server IDs for security reasons.

You will see errors in the agent debug log to indicate this, for example:

2017-08-16 12:03:19.430   Info 18236:159d470 NamingService: NamingService::parseNamingResponse() server side error: Invalid sessionid format:[AQIC5wM2LY4Sfcxwo1cOJAMRkbIsn0bS8Pm1IB623MLBCnM.*AAJTSQACMDIAAlNLABMxOTM5OTEyMDI1MjY3NzE4OTc0AAJTMQACMDE.* ]java.lang.IllegalArgumentException: Invalid server id in session id:[02]com.iplanet.services.naming.ServerEntryNotFoundException: Cannot find server.

Decoding the session cookie in this error per FAQ: Cookies in AM (Q. What information is contained in the AM session cookie?) indicates the site and server on which the cookie was created.

In this situation, users can just log in again to create a new valid session.

See Also

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

FAQ: Upgrading AM

​​​​FAQ: Backing up AM

Upgrading AM

Release Notes

Upgrade Guide

Related Training

N/A

Related Issue Tracker IDs

N/A


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