Use iapassword to secure Integration Agent passwords

The Integration Agent stores passwords in encrypted files on the local file system. This KBA discusses how to use the iapassword utility to create these password files and discusses how to troubleshoot issues that can occur when encrypting passwords that contain special characters.

Running iapassword

The iapassword tool is a command-line program that creates encrypted password files. Each file contains a single password and is named according to the password it represents. The iapassword tool is included with Integration Agents and can be found in the <IAHome>\bin folder (where <IAHome> represents the location where the Integration Agent is installed).  

To create a new password file, open a command prompt, navigate to the <IAHome>\bin folder and type one of the following commands. It is recommended (but not mandatory) to surround the password with double quotes, since it prevents failures that can occur when non-alphanumeric characters are present in the password.

iapassword --new "mypassword01" --file conf/filename.passwd

Linux, AIX etc.

./ --new "mypassword01" --file conf/filename.passwd


Non-alphanumeric characters in passwords

Passwords that contain non-alphanumeric characters must be escaped so that they are not misinterpreted on the command line. 

When the password is surrounded by double-quotes, iapassword correctly handles punctuation characters and alphanumeric characters from the "English (United States)" locale. This includes the characters A-Z, a-z, 0-9 and the following characters:


Passwords that contain space or caret (^) characters must be enclosed in double quotes. Passwords that contain the double quote (") character must be escaped in order to be handled correctly on the command line.

There are two methods for escaping double quote characters. The method that you choose depends on the character that immediately precedes the double quote character (owing to how Windows parses commands). 

  • Precede the double quote character with a backslash, for example, replace abc"123 with abc\"123.
  • Precede the double quote character with another double quote character, for example, replace test["]ing with test[""]ing

It is recommended to first attempt to escape the double quote by using the backslash character (\), and if that doesn't work then try the second method of escaping the double quote with another double quote.


To encode password abc" 123, which contains a double quote character and a space, you must enclose it in double quotes and then escape the inner double quote character.

iapassword --new "abc\" 123" --file conf/filename.passwd

To encode the password test["], escape the double quote with another double quote.

iapassword --new test[""]ing --file conf/filename.passwd

Verifying the password encryption

If you would like to verify that the password is being encrypted accurately, you can temporarily enable debug-level logging, which records the decrypted password in plain text. Once you have verified that the logged password matches the original password, turn off debug-level logging and delete the password from the logs to ensure that the it is not stored in plain text on your file system.

If the password that you want to verify is not an xMatters web service user password you first need to modify the IAConfig.xml file to point to the password file you want to debug. If the password you want to verify is an xMatters web service user password (such as those used for IA heartbeat connections to xMatters) then you can skip to step 7.  

For passwords that are not xMatters web service passwords, complete the following steps:

  1. Create a backup copy of <IAHome>\conf\IAConfig.xml.
  2. Open IAConfig.xml in a text editor.
  3. In the <web-services-auth> section, look for the <password><file> tags.  
  4. Replace the file name with the name of the file that you want to troubleshoot.  (You will need to revert this change after you finish troubleshooting.)
  5. Save IAConfig.xml.
  6. Restart the Integration Agent. This step causes the Integration Agent to temporarily lose its connection to the xMatters server.

For all passwords, complete the following steps:

  1. Create a backup copy of <IAHome>\conf\log4j.xml.
  2. Open <IAHome>\conf\log4j.xml in a text editor.
  3. Turn on debug-level logging by uncommenting the following command. 
    Replace this text:
      <logger name="com.alarmpoint.integrationagent.heartbeat">
        <level value="DEBUG"/>

    with this text:

      <logger name="com.alarmpoint.integrationagent.heartbeat">
        <level value="DEBUG"/>

  4. Save the file. (It is not necessary to restart the Integration Agent).
  5. Open the Integration Agent log at <IAHome>\log\alarmpoint.txt with a text editor and search for the following line:
    DEBUG - Sent the following SOAP request: <ns1:RegisterConfigureIntegrationAgent>
  6. On the same line, look for  </ns1:password>. The plain-text password from your file immediately precedes this text.

When you have finished troubleshooting, revert your changes and, if necessary, restart the Integration Agent:

  1. Replace log4j.xml with the backup copy.
  2. If you modified IAConfig.xml, replace it with the backup copy and then restart the integration agent.


Common error messages

There are some common error messages that can occur when running iapassword.

"Attempt to change password aborted: wrong password provided."

This message occurs when there is an error in the password (such as an unescaped double quote) or if you attempt to create a new password file when one already exists.  In the latter case, you can either manually delete the original file before running iapassword with the --new option, or you can run iapassword with the --old option and provide the existing password to authorize overwriting the password. The following example shows how to change the password by overwriting the old one:

iapassword --old "the-old-password" --new "some-password" --file conf/filename.passwd

"The system cannot find the path specified"

This indicates that the destination folder does not exist, for example the following command fails if there is not a folder named "cong" in the <IAHome>directory. 

iapassword --new "some-password" --file cong/test-passwd

 xMatters internal reference: DOC-7744

Have more questions? Submit a request


Please sign in to leave a comment.
Powered by Zendesk