Important 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 24.3.01

Updating PATROL Agent certificate

Server-side certificate authentication is used to ensure secure communication between PATROL Agents and BMC Helix Operations Management. PATROL Agent hosts require a valid root certificate to authenticate the tenant as part of this process. Root certificates must be updated to maintain secure communication. When a certificate on the Load Balancer is updated, it is crucial to apply it to all PATROL Agents in the environment to ensure uninterrupted communication.

BMC Helix Operations Management automates the certificate update process through a preconfigured server-side job. This job ensures that the latest certificate is automatically deployed to all PATROL Agents, eliminating the need for manual intervention. While the automated update process typically ensures a smooth transition, there are scenarios where the certificate update might fail on some PATROL Agents. If the new certificate is not successfully updated, the affected agents may lose connectivity to BMC Helix Operations Management, leading to potential monitoring disruptions.

Several factors can contribute to a failure in the server-side job, preventing the successful update of certificates on PATROL Agents. This issue may occur in several common scenarios, such as:

  • Disconnected agents:  If a PATROL Agent is not connected to BMC Helix Operations Management at the time of the update, it will not receive the new certificate.
  • Permission issues: If the folder where the certificate is deployed has restrictive permissions, the update process may be blocked.
  • Network or accessibility issues: If the agent is unreachable due to firewall restrictions, network outages, or other connectivity problems, it cannot receive the updated certificate.

If the automated process fails to update the certificate on certain PATROL Agents, administrators must manually update the certificate by using a deployable package. This package needs to be applied directly to the affected PATROL Agent machines.

Important

If you had downloaded the deployment packages from BMC Helix Operations Management before the new certificate was added to the deployment repository, those packages would not contain the updated certificate. Deploying such outdated packages can cause agents to lose connectivity. To avoid this issue, ensure that you redownload the package from the repository after the certificate update.

For agents that have failed, one of the following two solutions must be applied:

For disconnected agents, only one solution is applicable:


Changing permissions on the PATROL Agent certificate directory

A common reason for certificate update failures on PATROL Agents is insufficient permissions on the directory where the certificate is deployed. If the PATROL Agent lacks the necessary write permissions for this directory, the automated update process will fail, preventing the new certificate from being applied and potentially causing the agent to lose connectivity with BMC Helix Operations Management, which may disrupt monitoring activities. To resolve this issue, you must manually update the directory permissions on the affected PATROL Agent systems to ensure the agent has the required write access, and then retry the certificate update process.

To change permissions on the PATROL Agent certificate directory on Linux

  1. Log in to the Linux system where the PATROL Agent is installed using a user account with administrative privileges.

  2. Use the following command to navigate to the directory where the certificates are stored:

    cd $PATROL_HOME/security

  3. Run the following command to grant full read, write, and execute permissions to all users for the certificates folder:

    chmod -R 777 certificates/

  4. Use the ls -ld command to confirm that the permissions have been updated correctly:

    ls -ld certificates/

To change permissions on the PATROL Agent certificate directory on Windows

  1. Log in to the Windows system where the PATROL Agent is installed using a user account with administrative privileges.
  2. Open File Explorer and go to the following directory: %PATROL_HOME%\security\certificates.
  3. Modify the directory permissions
    1. Right-click the certificates folder and select Properties.
    2. In the Properties window, go to the Security tab and click Edit.
    3. In the Permissions window, click Add, enter the PATROL Default Account username, and click OK.
    4. Select the PATROL Default Account from the list, and check the Full control box under Allow.
    5. Click Apply and then OK to save the changes.
  4. Reopen the Properties window for the certificates folder, navigate to the Security tab, and make sure Full control is granted to all necessary user accounts.

Updating PATROL Agent certificate by using a deployable package

To ensure secure communication between PATROL Agents and BMC Helix Operations Management, you must create, download, and deploy certificate packages. This process involves generating deployable packages tailored to your system’s operating environment, downloading the prepared packages, and deploying them on the target hosts. Follow the steps below to complete the process.

  1. Create deployable packages: Create packages for your specific operating system.
  2. Download deployable packages: Download the created packages for installation on target hosts.
  3. Deploy packages: Install the downloaded packages on the designated hosts by using command line utilities.

Step 1: To create deployable packages

On the Administration > Repository > Deployable Packages tab, click Create, and do the following:

  1. Select the operating system and platform for which you want to create a package. The list of platforms changes according to the operating system that you select.
  2. Select one of the following PATROL Agent components and select a version:
    • BHOM Certificate for Unix
    • BHOM Certificate for Windows
  3. Specify the PATROL Agent installation directory:
    • Proceed with the default installation directory.
    • Enter a different directory for installation.
    • Leave the field blank and proceed with the installation.
      The correct directory is automatically selected through the BMC_BASE variable when you leave the field blank.
  4. Specify the PATROL 3.x product directory and click Next.
    Follow the instructions in the Important Instructions section of the wizard.
  5. Review the package details.
  6. Enter a name and an optional description for the package.
  7. Select the package file format. 
  8. Select one of the following options:
    1. Save: Save the package for future installation on the current host or other hosts.
    2. Save and Download: Save and download the package and note the downloaded package location. You will need the downloaded package location details while deploying the package.
    3. Close: Cancel the package creation and return to the Administration > Repository page.

Step 2: To download deployable packages

On the Administration > Repository > Deployable Packages tab, and perform the following steps:

  1. Click the Download download_icon.jpg icon next to a package.
  2. From the package menu, select Download and note the location. You will need this information during Step 3.

Step 3: To deploy packages

  1. Log on to the host computer by using the PATROL default account on which you plan to install the PATROL Agent.
    If you are using your host computer username, ensure that you have administrator privileges.
  2. Copy the package that you downloaded to a temporary directory location.
  3. Extract the package.
    It is extracted to the <PA_EXTRACTED_PACKAGE>\bmc_products directory.
  4. From the bmc_products directory, run one of the following commands:
    • Windows: RunSilentInstall.exe
    • UNIX: ./RunSilentInstall.sh

          Installation status is displayed.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*