How to upgrade APM Plugin in Failover with OPM Smart upgrade without Authtoken encryption error?

How to upgrade APM Plugin in Failover with OPM Smart upgrade without Authtoken encryption error?

Overview

This guide covers the upgrade procedure for APM Plugin to build 179200 or above in a Failover environment using the OpManager Upgrade Manager, and the steps to resolve the authtoken encryption error that occurs after upgrade.

Compatibility:
  • OpManager Version: 12.8.628 and above
  • APM Plugin Version: 178100 and above

Upgrade Flow

For OpManager versions 12.8.628 and above, the Upgrade Manager provides a fully automated upgrade flow for Failover setups. The entire process runs without manual intervention:

  1. Navigate to Settings > General Settings > Upgrade Manager Settings > Upgrade Manager.
  2. Click Upgrade, upload the service pack (.ppm file), and allow the health check to complete.
  3. Click Start Upgrade. The upgrade starts automatically for both the Active and Standby servers.
  4. The APM Plugin upgrade starts automatically once OpManager has been successfully upgraded on the respective server.
  5. After the upgrade, the Standby (Secondary) server is started first and enters active mode temporarily.
  6. The Standby server is then stopped automatically.
  7. The Primary server is started automatically — it takes over active mode.
  8. The Standby server is started again automatically in standby/listening mode.
Note: All start/stop operations of Primary and Standby servers during the upgrade are handled automatically by the Upgrade Manager. No manual intervention is required during this process.

Issue After Upgrade

Once the upgrade completes and the Primary server is running, accessing the Applications tab in OpManager UI will display the following error:

Problem in fetching AuthToken from OpManager DB.
Hint: Applications Manager plugin might be facing an issue with connecting OpManager database.

This happens because the Standby server started first during the upgrade and used its MasterEncryptionKey to migrate and encrypt data in the shared database. The Primary server has a different MasterEncryptionKey and cannot decrypt this data.

Resolution: MasterEncryptionKey Synchronization

To resolve this, synchronize the MasterEncryptionKey from the Standby server to the Primary server:

Prerequisite: Before replacing the key, take a backup of DB_Crypt.properties from both Primary and Standby servers (<APM_Plugin_Home>\conf\DB_Crypt.properties). This preserves the unique MasterEncryptionKey generated on each server during upgrade, allowing recovery if needed.

Steps

  1. Stop both the Primary and Standby OpManager services.
  2. Open <APM_Plugin_Home>\conf\DB_Crypt.properties on the Standby server.
  3. Copy the value of MasterEncryptionKey.
  4. Open the same file on the Primary server.
  5. Replace the MasterEncryptionKey value with the one copied from Standby.
  6. Save the file.
  7. Start the Primary server.
  8. Start the Standby server — it will enter standby/listening mode.
Important: The Standby server started first during the upgrade and performed data migration using its MasterEncryptionKey. The key must be copied from Standby to Primary. Only replace the MasterEncryptionKey value — do not modify AMCryptKey or replace the entire file.
Note:
  • Do not replace the entire DB_Crypt.properties file — only copy the MasterEncryptionKey value. The AMCryptKey is instance-specific and must remain unchanged on each server.
  • This key synchronization step needs to be performed only once after the first upgrade to APM Plugin build 179200+. Subsequent upgrades do not require this step again.

Verification

After restarting both servers, confirm:

  1. The APM Plugin web console is accessible on both Primary and Standby servers.
  2. No NullPointerException or "EARKey is null" errors in <OPM_Home>\AppManager\logs\stderr.txt.
  3. No "EARKey is null" messages in <OPM_Home>\AppManager\logs\syncout.txt.
  4. Monitors are active and collecting data.
Expected Result: APM Plugin starts without errors on both servers, web console is accessible, and monitoring resumes normally after failover.

For further clarification on the encryption key behavior, troubleshooting fresh installations, or other related scenarios, refer to the KB article: "How to resolve APM Plugin authtoken encryption errors on Standby server in Failover".




        New to M365 Manager Plus?
        New to M365 Manager Plus?
          New to RecoveryManager Plus?
          New to RecoveryManager Plus?
            New to Exchange Reporter Plus?
            New to Exchange Reporter Plus?
              New to SharePoint Manager Plus?
              New to SharePoint Manager Plus?
                  See all integrations
                  New to ADManager Plus?
                  See all integrations
                  New to ADManager Plus?

                    New to ADSelfService Plus?

                    Start your free trial
                    Start your free trial
                      Related Products