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

Overview

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:

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

5. 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 am1.example.com:443/am SiteB am2.example.com:8443/am
6. Add servers AM3 and AM4 to SiteB.
7. 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
8. Pause replication on ds4, for example: $ ./dsreplication suspend --hostname ds4.example.com --port 7444 --adminUid admin --adminPassword password --trustAll --no-prompt
9. 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.
10. 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.
11. Transfer traffic from SiteA to the newly upgraded SiteB at the load balancer.
12. 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.
13. Transfer traffic from SiteB back to SiteA at the load balancer.
14. Delete SiteB; this removes servers AM3 and AM4 from the site.
15. 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
16. Add servers AM3 and AM4 back in to the original SiteA and restart both servers:
17. 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
18. 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
19. 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
20. 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:

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