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

Installing PATROL Agents

This topic provides instructions for installing PATROL Agents.

Important

To configure the forward proxy server during the installation of PATROL Agent, see Configuring-PATROL-Agents-to-support-multiple-forward-proxy-servers.

Installing a PATROL Agent by using the API Key

Step 1: Creating 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:

    • PATROL Agent for Windows
    • PATROL Agent for Unix

    To install any monitoring solutions with the PATROL Agent, select the required monitoring solutions.

  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. (UNIX only) Enter the root or sudo use credentials with root privileges.

    Important

    The use of the root account may introduce potential security risks. It is strongly recommended to use a sudo account for enhanced security measures.

    If you do not want to enter the root password, leave the field blank. After installation, you must run the hostname_port_install.log_rootscripts script file. For more information, see the post-installation steps.

  6.  Enter the PATROL Agent account credentials.
    • (Windows) DOMAIN_NAME\account name
    • (Linux) DOMAIN_NAME\\account name
      Double slash before the account name ensures that the account name is parsed correctly. While editing the package, if the double slash is deleted, type it again.

      To configure the PATROL Agent to use the Local System account by default, leave the username and password fields empty.

       

  7. Select one of the following security options:

    Important

    This configuration is only applicable to TrueSight Operations Management environment. For BMC Helix Operations Management, communication takes place via the HTTPS channel.

    Follow the instructions in the Important Instructions section of the wizard.

    • No Certificate Validation (default): PATROL Agent uses TLS 1.2 communication channels but does not validate the certificate.
    • Certificate Validation: PATROL Agent uses TLS 1.2 communication channels and validates the certificate received from the server.
  8. Enter the PATROL Agent port number.
  9. Select one of the following levels of access control.
    • Restricted Access Control (default)

    • Full Access Control
      The Restricted Access Control option is selected by default and is applicable for the default account only. You can modify the access control list to give PATROL Agent access to specific users by setting up the pconfig variable, /AgentSetup/accessControlList.

      If you select the Full Access Control option, all users will have access to PATROL Agent from pconfig and PatrolCli.

      Important

      To retain the old access control list, when you upgrade PATROL Agent to 23.3 or a later version, select Full Access Control, which keeps the old /AgentSetup/accessControlList that you used in the older version of PATROL Agent.

  10. Choose to restart the PATROL agent automatically or manually, and click Next.

    Note

    If you have not provided the root credentials, do not choose to restart the PATROL Agent automatically during package creation.

  11. Specify the streaming endpoint details. This will be used for automatic registration of the PATROL Agent with BMC Helix Operations Management. Enter the details in the following format:
    https:<FQDN of the load balancer>:<port_no>
  12. Enter a comma-separated list of tags for associating PATROL Agents with monitoring policies.
    PATROL Agents use the specified tags to get configuration details from BMC Helix Operations Management. Enter the tag name in the following format:
    <Tag Name>:<Description>
    Note: If the description contains a blank space, enclose it within double quotes.
    For example, WinOS: "Windows OS Monitoring"
  13. Select to manage the PATROL Agent configuration via a monitoring policy, and click Next.

  14. Configure the firewall settings.
    You can select to automatically add the components to the firewall exception list.

    Note

    Ensure that you enable the outbound connection to the default port 443 for HTTPS communication between PATROL Agent and BMC Helix Operations Management.

  15. Review the package details.
  16. Enter a name and an optional description for the package.
    The description is displayed when the Deployable Packages tab lists the packages.
  17. Select the package file format. 
  18. Save the deployable package.
  19. Select one of the following:
    • Save: Save the package for future installation on the current host or other hosts.
    • 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.
    • Close: Cancel the package creation and return to the Administration > Repository page.

Step 2: Downloading deployable packages

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

  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.
  3. On the Administration > Repository > Deployable Packages page, click Copy API Key and note the information. You will need this information while performing Step 3. 

Step 3: Deploying packages

  1. Log on to the host computer on which you plan to install the PATROL Agent.
  2. Copy the API key that you saved in Step 2 to a temporary text file.
  3. Copy the package that you downloaded in Step 2 to a temporary directory.
  4. Extract the package. It is extracted to the <PA_EXTRACTED_PACKAGE>\bmc_products directory.
  5. From the bmc_products\Install\instbin directory, run the following command in the command prompt to generate an encrypted password. This step is optional and can be used for encrypting the password for the forward proxy:

    • For Windows:

      thorinst.exe -encrypt

      When prompted, type the password. 
      Example output: $-2$-$70C650C09FB294BAED5AD01E49EF0F9F

    • For Linux:

      sh thorinst.sh -encrypt

      When prompted, type the password. 
      Example output: $-2$-$70C650C09FB294BAED5AD01E49EF0F9F

       

  2. From the bmc_products directory, run the following command in the command prompt: 

    #Syntax
    RunSilentInstall.exe -apikey=<api key TOKEN> -forwardProxyServer=<FQDN of the PATROL Agent forward proxy server>:<port> -forwardProxyUser=<Proxy Username> --forwardProxyPassword=<password for the proxy server>

    #Example 1 - Install with API key and forward proxy server option
    RunSilentInstall.exe -apikey=a1236789-123f-1d23-12d4-1234abc12345 -forwardProxyServer=proxyServer.bmc.com:3128


    #Example 2 - Install with API key and forward proxy server options that include forward proxy credentials
    RunSilentInstall.exe -apikey=a1236789-123f-1d23-12d4-1234abc12345 -forwardProxyServer=http://proxyServer1.bmc.com:3128 -forwardProxyUser=user2 --forwardProxyPassword=<password>


    #Example 3 - Install with API key and without forward proxy server options
    RunSilentInstall.exe -apikey=a1236789-123f-1d23-12d4-1234abc12345

    Note

    API key

    PATROL Agents use the API key to encrypt message requests sent to BMC Helix Operations Management. You can set the API key in one of the following ways:

    • During the installation of PATROL Agents: As explained in the preceding example, provide the API key details when you run the RunSilentInstall command.
    • After the installation of PATROL Agents: You can update the API key after the installation. For details, see Support-for-HTTP-communication.

    PATROL Agent forward proxy server

    You can set up one or more proxy servers in your infrastructure environment so that PATROL Agents can communicate with BMC Helix Operations Management via the proxy server. Setting up a proxy server is optional.

    You can configure the proxy server details in one of the following ways:

    • During the installation of PATROL Agents: As explained in the preceding example, provide the proxy server details, user name, and password when you run the RunSilentInstall command.
    • After the installation of PATROL Agents: You can configure the forward proxy server details in the PATROL Agent after the installation. For details, see Configuring-PATROL-Agents-to-support-multiple-forward-proxy-servers.
  3. Review the log file to check the installation status.

The root user must add one of the entries below to the /etc/sudoers file for sudo users, depending on the use case:

  • Specifying a group name:
    %<groupname> ALL=/tmp/install_script.sh
  • Specifying a user name:
    <sudousername> ALL=/tmp/install_script.sh
  • Specifying a specific host name:
    <sudouser> <hostname>=/tmp/install_script.sh

If you are using Solaris, add the below entry to the /etc/sudoers file for sudo users:

ALL=/tmp/install_script.sh, /bin/cp, /usr/bin/cp, /bin/ln

Installing the PATROL Agent by using the Copy Install Script option

  1. From the predefined or custom package Actions menu, select Copy Install Script.
    Default predefined packages:

    • (Microsoft Windows) Predefined_Package_For_Windows_x64
    • (Linux) Predefined_Package_For_Linux_x64

    Note: If you plan to run the copy install script using a custom package, ensure that the package includes the PATROL Agent component.

  2. Log in to the host computer on which you want to deploy the package and create a new PATROL Agent user.
  3. In the home directory of the new user, create a directory.
  4. Provide read/write/execution permission to the PATROL user for the directory.
  5. Paste and run the install script in this directory. For pre-defined packages, the default directory is:
    (Microsoft Windows) <installation_directory>\BMC Software
    (Linux) /opt/bmc
  6. Provide the following information when prompted:
    • (Linux) Root login name and password
    • PATROL default account login name and password
  7. (Linux) In the directory that has read/write/execute permission for the PATROL user, paste and run the install script.
  8. (Microsoft Windows) Open the Windows PowerShell, paste and run the install script.

(UNIX only) Run hostname__install.log_rootscripts

Perform the steps in this section after installing or upgrading a package.

When deploying the package silently, if you did not enter the root password, you need to run the <hostname>_<port>_install.log_rootscripts script and make some other small modifications. 

  1. Stop the PATROL Agent process if it is running:
    For more information, see Starting and stopping the PATROL Agent .

  2. Navigate to the unpacked installation files directory:
       cd <installation_directory>/log/<date_time_of_install>_install/
         Example: /opt/bmc/log/2021_07_08_05_57_59_install/
  3. For the root user:
    1. Switch to the root user by using the following command and entering the root password:
         su
    2. As root user, rename the <hostname>_<port>_install.log_rootscripts file to <hostname>_<port>_install.log_rootscripts.sh by running the following command:
         mv <hostname>_<port>_install.log_rootscripts <hostname>_<port>_install.log_rootscripts.sh
           Example: mv myhostname_3181_install.log_rootscripts myhostname_3181_install.log_rootscripts.sh
    3. As root user, assign the permissions to run the <hostname>_<port>_install.log_rootscripts.sh file:
          chmod 755 <hostname>_<port>_install.log_rootscripts.sh
            Example: chmod 755 myhostname_3181_install.log_rootscripts.sh
    4. As root user, run <hostname>_<port>_install.log_rootscripts.sh:
         ./<hostname>_<port>_install.log_rootscripts.sh
               Example: ./myhostname_3181_install.log_rootscripts.sh
  4. For the sudo user:
    1. Log in using the sudo user credentials.
    2. Ensure that one of the entries below is added by the root user to the /etc/sudoers file, depending on the use case:
      1. Specifying a group name:
        %<groupname> ALL=/tmp/install_script.sh
      2. Specifying a user name:
        <sudousername> ALL=/tmp/install_script.sh
      3. Specifying a specific hostname:
        <sudouser> <hostname>=/tmp/install_script.sh
    3. As the sudo user, run the script. /tmp/install_script.sh using the sudo command. Enter the sudo password when prompted, as illustrated in the example below:
      Example:
      $ sudo /tmp/install_script.sh
      [sudo] password for patdev1:

  5. Verify the PatrolAgent/snmpmagt binaries are owned by the root account and that the sticky bit is set:
        ls -tl PatrolAgent
    The following output is displayed:
        -rws r-xr-x 1 root patrol 12641000 Jan 10 10:39 PatrolAgent
     The s indicates that the sticky bit is set successfully on the PatrolAgent binary. (The same is true for the snmpmagt binary, if present.)

    Learn more about the sticky bit

  6. Ensure the access file is owned by the default account:
      sudo chown <default_account>:<default_account> <install_directory>/common/security/keys/access
          Example: sudo chown patrol:patrol /opt/bmc/common/security/keys/access

  7. As the default account, start the PATROL Agent.
     For more information, see Starting and stopping the PATROL Agent .

Installing PATROL Agent by using MSI package

To install PATROL Agent by using MSI package, first create a deployable package. For more information, see Create a deployable package.

  1. Log on to the host computer on which you want to install PATROL Agent.
  2. Copy the API key that you saved in Step 2 to a temporary text file.
  3. Copy the package that you downloaded in Step 2 to a temporary directory.
  4. Extract the package.
    The package is extracted to the <PA_EXTRACTED_PACKAGE>\bmc_products directory. This directory contains the Setup.msi file.
  5. To install the package from the UI:
    1. Double-click Setup.msi or open the command prompt as an administrator user and run the following command:
      msiexec /i Setup.msi /l*v log.txt
      The installer setup wizard is displayed.
    2. Click Next.
    3. Enter the configuration details, such as the API key, proxy server, proxy user ID, proxy password, and publish host name.
    4. Click Next and Install.
      Review the log file to check the installation status.
  6. To install the package silently, open the command prompt as an administrator user and run one of the following commands:
    • start /wait msiexec /i Setup.msi /l*v log.txt /qn
    • start /wait msiexec /i Setup.msi [APIKEY=<API key for connecting to the Operations Management server>] [FORWARDPROXYSERVER=<PROXY Server hostname>] [FORWARDPROXYUSER =<PROXY Server username>] [FORWARDPROXYPASSWORD =<PROXY Server password>] [PUBLISHHOST =<host name that will be displayed in the Operations Management server >] /l*v log.txt /qn
      The installation process starts in the silent mode. Review the log file to check the installation status.

 

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