This documentation space contains information about PATROL Agents when deployed in a BMC Helix Operations Management environment. If you are a TrueSight Operations Management user, see PATROL Agent 22.1. Open link

Troubleshooting PATROL Agent to BMC Helix Operations Management connection issues

Connection issues due to API key error

The PATROL Agent fails to establish a connection with BMC Helix Operations Management and returns an API key error in the <PATROL Agent Installation Directory>\log file as shown in the following example:

Initializing curlbase websession ''
https server '' has valid certificate.
AGENT_HANDSHAKE request received : HTTP request error 401 : 'Authentication Failed!!!'
socket error = The operation completed successfully. (0)
failed to deliver 'AGENT_HANDSHAKE' message.

Probable cause

The API key used while installing the PATROL Agent is invalid.


Update the API key in the /SecureStore/mca/tenant/apiKey pconfig variable:

  1. On the BMC Helix Operations Management console, go to the Administration > Repository page, and click Copy API Key.
    Note the API key.
  2. Log in to the host computer on which you have installed the PATROL Agent.
  3. Do the following: 

    • (Windows) Do the following to update the pconfig variable:

      1. Create the config_file.cfg file and edit the configuration variables as shown in the following example: 

        PATROL_CONFIG "/SecureStore/mca/tenant/apiKey" = {REPLACE = "MCA/<API Key>"}
      2. Save the config_file.cfg file.
      3. Run the following command to reload the configuration variable changes:  

        pconfig +Reload -p <port> -host <hostName> <config_file.cfg>
      4. Restart the PATROL Agent.

    • (Unix) Do the following to update the pconfig variable:

      1. Go to the PATROL Agent installation directory and run the following script: 

        #For Korn and Bourne shell: 
        . ./
        #For C shell: 
        source .patrolrc
      2. Create the config_file.cfg file and edit the configuration variable as shown below: 

        PATROL_CONFIG "/SecureStore/mca/tenant/apiKey" = {REPLACE = "MCA/<API Key>"}
      3. Save the config_file.cfg file.
      4. Run the following command to reload the configuration variable changes: 

        pconfig +Reload -p <port> -host <hostName> <config_file.cfg>
      5. Restart the PATROL Agent.

Connection issues due to package deployment error

After deployment on Linux, the PATROL Agent may fail to connect with BMC Helix Operations Management and display the following error:

socket error = Connection reset by peer (104)
failed to deliver 'AGENT_HANDSHAKE' message.
SSL routines:SSL3_GET_RECORD:decryption failed or bad record mac

You get this error in the PatrolAgent-<hostName>-<port>#.errs log file present in the PATROL_HOME/log directory.

Probable cause

The deployment package contains PATROL Agent only.


Do one of the following:

  • Create a package consisting of both PATROL Agent and OS Knowledge Module (KM) and deploy the package. For more information, see: 
    • Configuring deployable packages. Open link
    • Deploying packages using the API key. Open link
  • Deploy the package by clicking the Deploy and Install Packages option on the BMC Helix Operations Management console. For more information, see  Deploying packages using the action menu. Open link

Connection issues due to root script execution and PATROL Agent restart

For Linux, the PATROL Agent fails to connect with BMC Helix Operations Management after executing root scripts and restarting the PATROL Agent.

Probable cause

The root credentials are not provided and the Start the PATROL Agent automatically after the installation is completed option is chosen during package creation. This disables the root script execution and the api key is not pushed to the secure store.


Clear the PATROL Agent config details in the $PATROL_HOME/config directory and restart the PATROL Agent.

Was this page helpful? Yes No Submitting... Thank you