Configuring the xMatters Agent installation to use the same UUID

Question 

We use Docker to spin up a container which houses the xMatters Agent. This container occasionally needs to be rebuilt, but we want to make sure the agent that's created is registered with the same name as the previous build to maintain functionality in our integrations. Is it possible to do this?

Environment

xMatters Agent

Answer

Yes. The UUID is stored in the Java preferences of the host machine, and you can register an xMatters Agent in the xMatters web UI by removing or replacing the new value and restarting the agent. 

To amend the xMatters Agent UUID on Linux machines:

1. Go to /home/xmatters/.java/.userPrefs/com/xmatters/xagent/services.
2. Open prefs.xml.
3. Delete the row entry for id or replace the value of UUID.
   • If deleted, a new entry will be generated when the xMatters Agent restarts.
   • If replaced, the agent will use this UUID to register itself to xMatters. 
4. Restart the xMatters Agent.

To amend the xMatters Agent UUID on Windows machines:

1. Open Registry Editor
2. Go to HKEY_USERS/.DEFAULT/xAgentUUID (see the note below for more information).
3. Delete or replace the "xAgentUUID" value.
   1. If deleted, a new entry will be generated when the agent restarts.
   2. If replaced, the agent will use this UUID to register itself to xMatters. 
4. Restart the the agent.

NOTE: when the Windows host starts up, the UUID is copied from HKEY_USERS/.DEFAULT/xAgentUUID to HKEY_USERS/.DEFAULT/Software/JavaSoft/Prefs/com/xmatters/xagent/services/id .  The agent accesses the UUID from the JavaSoft/Prefs location at startup time.  It isn't clear why it doesn't access the UUID from HKEY_USERS/.DEFAULT/xAgentUUID directly, but if you modify the UUID in the JavaSoft/Prefs location, your change will get overwritten at startup time.

To learn more about how the xMatters Agent works, see our online help.