How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

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

Last updated Jan 16, 2023

The purpose of this article is to provide information on upgrading AM with minimal downtime when replication is used. This article includes information on upgrading AM with an external or embedded DS configuration store, regardless of whether you have a load balancer in place or not.

3 readers recommend this article

Upgrading AM with minimal downtime

Note

As with any software upgrade, we strongly recommend testing the procedure in your own development 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.

This article covers upgrading AM with minimal downtime in the following scenarios, where you should follow the steps according to which DS version you are using because of replication changes in DS 7:

External DS - with a load balancer (DS 7 and later)

If you have a load balancer in place, you can do a High Availability upgrade. The following details the steps you would need to follow with an example two AM servers (AM1 and AM2) and two external DS configuration stores (DS1 and DS2):

  1. Remove AM1 from the load balancer.
  2. Temporarily stop replication on DS2 using a dsconfig command, for example:
    • DS 7.1 and later: $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN uid=admin --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:false --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --no-prompt
    • DS 7: $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN uid=admin --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:false --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --no-prompt
  3. Perform the following steps on AM1:
    • Deploy the new AM war file and restart the server.
    • Run the upgrade process.
    • Restart the server.
  4. Restore AM1 to the load balancer.
  5. Remove AM2 from the load balancer.
  6. Deploy the new AM war file on AM2.
  7. Resume replication on DS2 using a dsconfig command, for example:
    • DS 7.1 and later: $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN uid=admin --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:true --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --no-prompt
    • DS 7: $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN uid=admin --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:true --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --no-prompt
  8. Initialize the contents of DS1 to DS2 to allow the new upgrade changes to be replicated to DS2. Use a dsrepl initialize command on DS1, for example:
    • DS 7.1 and later: $ ./dsrepl initialize --baseDN dc=example,dc=com --toAllServers --hostname ds1.example.com --port 4444 --bindDN uid=admin --bindPassword password --trustStorePath /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --no-prompt
    • DS 7: $ ./dsrepl initialize --baseDN dc=example,dc=com --toAllServers --hostname ds1.example.com --port 4444 --bindDN uid=admin --bindPassword password --trustStorePath /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --no-prompt
  9. Restart AM2.
  10. Restore AM2 to the load balancer.

External DS - no load balancer (DS 7 and later)

If you do not have a load balancer in place, you can use a similar procedure to upgrade AM. The following details the steps you would need to follow with an example two AM servers (AM1 and AM2) and two external DS configuration stores (DS1 and DS2); if you have more than two servers, perform the steps for AM2 / DS2 on each additional server:

  1. Temporarily stop replication on DS2 using a dsconfig command, for example:
    • DS 7.1 and later: $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN uid=admin --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:false --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --no-prompt
    • DS 7: $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN uid=admin --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:false --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --no-prompt
  2. Perform the following steps on AM1:
    • Deploy the new AM war file and restart the server.
    • Run the upgrade process.
    • Restart the server.
  3. Deploy the new AM war file on AM2.
  4. Resume replication on DS2 using a dsconfig command, for example:
    • DS 7.1 and later: $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN uid=admin --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:true --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --no-prompt
    • DS 7: $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN uid=admin --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:true --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --no-prompt
  5. Initialize the contents of DS1 to DS2 to allow the new upgrade changes to be replicated to DS2. Use a dsrepl initialize command on DS1, for example:
    • DS 7.1 and later: $ ./dsrepl initialize --baseDN dc=example,dc=com --toAllServers --hostname ds1.example.com --port 4444 --bindDN uid=admin --bindPassword password --trustStorePath /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --no-prompt
    • DS 7: $ ./dsrepl initialize --baseDN dc=example,dc=com --toAllServers --hostname ds1.example.com --port 4444 --bindDN uid=admin --bindPassword password --trustStorePath /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --no-prompt
  6. Restart AM2.

External DS - with a load balancer (DS 6.x)

If you have a load balancer in place, you can do a High Availability upgrade. The following details the steps you would need to follow with an example two AM servers (AM1 and AM2) and two external DS configuration stores (DS1 and DS2):

  1. Remove AM1 from the load balancer.
  2. Temporarily stop replication on DS2 using a dsconfig command, for example: $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:false --trustAll --no-prompt
  3. Perform the following steps on AM1:
    • Deploy the new AM war file and restart the server.
    • Run the upgrade process.
    • Restart the server.
  4. Restore AM1 to the load balancer.
  5. Remove AM2 from the load balancer.
  6. Deploy the new AM war file on AM2.
  7. Resume replication on DS2 using a dsconfig command, for example: $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:true --trustAll --no-prompt
  8. Initialize the contents of DS1 to DS2 to allow the new upgrade changes to be replicated to DS2. Use a dsreplication initialize-all command on DS1, for example: $ ./dsreplication initialize-all --adminUID admin --adminPassword password --baseDN dc=example,dc=com --hostname ds1.example.com --port 4444 --trustAll --no-prompt
  9. Verify that replication was successful enabled by checking the number of entries present on both DS servers using a dsreplication status command. For example: $ ./dsreplication status --adminUID admin --adminPassword password --hostname ds1.example.com --port 4444 --trustAll --no-prompt Suffix DN : Server : Entries : Replication enabled : DS ID : RS ID : RS Port (1) : Delay (ms) : Security (2) ------------------:----------------------:---------:---------------------:-------:-------:-------------:------------:-------------- dc=example,dc=com : ds1.example.com:4444 : 2518 : true : 933 : 17014 : 8989 : 0 : false dc=example,dc=com : ds2.example.com:4444 : 2518 : true : 24857 : 8513 : 9989 : 0 : falseThe Delay (ms) metric replaces the M.C.and A.O.M.C. metrics returned in DS 6.
  10. Restart AM2.
  11. Restore AM2 to the load balancer.

External DS - no load balancer (DS 6.x)

If you do not have a load balancer in place, you can use a similar procedure to upgrade AM. The following details the steps you would need to follow with an example two AM servers (AM1 and AM2) and two external DS configuration stores (DS1 and DS2); if you have more than two servers, perform the steps for AM2 / DS2 on each additional server:

  1. Temporarily stop replication on DS2 using a dsconfig command, for example: $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:false --trustAll --no-prompt
  2. Perform the following steps on AM1:
    • Deploy the new AM war file and restart the server.
    • Run the upgrade process.
    • Restart the server.
  3. Deploy the new AM war file on AM2.
  4. Resume replication on DS2 using a dsconfig command, for example: $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:true --trustAll --no-prompt
  5. Initialize the contents of DS1 to DS2 to allow the new upgrade changes to be replicated to DS2. Use a dsreplication initialize-all command on DS1, for example: $ ./dsreplication initialize-all --adminUID admin --adminPassword password --baseDN dc=example,dc=com --hostname ds1.example.com --port 4444 --trustAll --no-prompt
  6. Verify that replication was successful enabled by checking the number of entries present on both DS servers using a dsreplication status command. For example: $ ./dsreplication status --adminUID admin --adminPassword password --hostname ds1.example.com --port 4444 --trustAll --no-prompt Suffix DN : Server : Entries : Replication enabled : DS ID : RS ID : RS Port (1) : Delay (ms) : Security (2) ------------------:----------------------:---------:---------------------:-------:-------:-------------:------------:-------------- dc=example,dc=com : ds1.example.com:4444 : 2518 : true : 933 : 17014 : 8989 : 0 : false dc=example,dc=com : ds2.example.com:4444 : 2518 : true : 24857 : 8513 : 9989 : 0 : falseThe Delay (ms) metric replaces the M.C.and A.O.M.C. metrics returned in DS 6.
  7. Restart AM2.

Embedded DS - with a load balancer (DS 6.x)

If you have a load balancer in place, you can do a High Availability upgrade. The following details the steps you would need to follow with an example two AM servers (AM1 and AM2) and two embedded DS configuration stores (DS1 and DS2):

  1. Remove AM1 from the load balancer.
  2. Temporarily stop replication on DS2 using a dsconfig command, for example: $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:false --trustAll --no-prompt
  3. Perform the following steps on AM1:
    • Deploy the new AM war file and restart the server.
    • Run the upgrade process.
    • Restart the server.
  4. Restore AM1 to the load balancer.
  5. Remove AM2 from the load balancer.
  6. Resume replication on DS2 using a dsconfig command, for example: $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:true --trustAll --no-prompt
  7. Perform the following steps on AM2:
    • Deploy the new AM war file.
    • Restart the server.
  8. Verify that replication was successful enabled by checking the number of entries present on both DS servers using a dsreplication status command. For example: $ ./dsreplication status --adminUID admin --adminPassword password --hostname ds1.example.com --port 4444 --trustAll --no-prompt Suffix DN : Server : Entries : Replication enabled : DS ID : RS ID : RS Port (1) : Delay (ms) : Security (2) ------------------:----------------------:---------:---------------------:-------:-------:-------------:------------:-------------- dc=example,dc=com : ds1.example.com:4444 : 2518 : true : 933 : 17014 : 8989 : 0 : false dc=example,dc=com : ds2.example.com:4444 : 2518 : true : 24857 : 8513 : 9989 : 0 : falseThe Delay (ms) metric replaces the M.C.and A.O.M.C. metrics returned in DS 6.
  9. Restore AM2 to the load balancer.

Embedded DS - no load balancer (DS 6.x)

If you do not have a load balancer in place, you can use a similar procedure to upgrade AM. The following details the steps you would need to follow with an example two AM servers (AM1 and AM2) and two embedded DS configuration stores (DS1 and DS2); if you have more than two servers, perform the steps for AM2 / DS2 on each additional server:

  1. Temporarily stop replication on DS2 using a dsconfig command, for example: $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:false --trustAll --no-prompt
  2. Perform the following steps on AM1:
    • Deploy the new AM war file and restart the server.
    • Run the upgrade process.
    • Restart the server.
  3. Resume replication on DS2 using a dsconfig command, for example: $ ./dsconfig set-synchronization-provider-prop --hostname ds2.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --provider-name "Multimaster Synchronization" --set enabled:true --trustAll --no-prompt
  4. Perform the following steps on AM2:
    • Deploy the new AM war file.
    • Restart the server.
  5. Verify that replication was successful enabled by checking the number of entries present on both DS servers using a dsreplication status command. For example: $ ./dsreplication status --adminUID admin --adminPassword password --hostname ds1.example.com --port 4444 --trustAll --no-prompt Suffix DN : Server : Entries : Replication enabled : DS ID : RS ID : RS Port (1) : Delay (ms) : Security (2) ------------------:----------------------:---------:---------------------:-------:-------:-------------:------------:-------------- dc=example,dc=com : ds1.example.com:4444 : 2518 : true : 933 : 17014 : 8989 : 0 : false dc=example,dc=com : ds2.example.com:4444 : 2518 : true : 24857 : 8513 : 9989 : 0 : falseThe Delay (ms) metric replaces the M.C.and A.O.M.C. metrics returned in DS 6.

See Also

FAQ: Backing up AM

FAQ: Upgrading AM

Upgrading AM

Upgrade

Related Training

N/A

Related Issue Tracker IDs

N/A
Copyright and Trademarks Copyright © 2023 ForgeRock, all rights reserved.