Installing

To install PATROL Agent, you create a deployable package that contains the imported PATROL Agent. You then deploy the package to the host computer from where you want to collect data.

Before you begin

Before installing PATROL Agent, perform the following:

1. Create a PATROL default account.
   For more information, see PATROL default account.

2. Ensure that you have the repository imported to your TrueSight console.
   For downloading instructions, see Downloading the Repository.
   If you do not have the repository, perform the following actions:

   1. Download the PATROL Agent files from the Electronic Product Distribution (EPD) website:
   2. Import the downloaded file to the repository by performing the following steps:

1. 
   
   1. 
      
      1. Log in to the TrueSight console.
      2. Click Administration > Repository > Installation Components.
      3. Click  Import.
      4. In the Import a Repository or Solution dialog box, select Single Solution.
      5. Click Browse to browse and select the downloaded files (PATROL Agent and PATROL Installation Utility).
         The selected files are displayed in the File Selected box.
      6. Click Import.
         The selected archive file is imported to the repository and extracted. You can close the window during the import process.

Task 1: Create a deployable package

1. In the TrueSight console, click Administration > Repository > Deployable Packages.
2. Click  Create Deployable Package.
   The Create Deployable Package wizard is displayed.
3. On the Installation Package Solution Selection page, select the operating system and platform on which you want to install the package.
   The list of components in the repository that are supported on the specified operating system and platform is displayed.
4. Select one of the following PATROL Agent components and any monitoring solutions that you want to install with PATROL Agent:
   • PATROL Agent for Windows
   • PATROL Agent for UNIX
5. From the Version list, select the version of the solution that you want to add to the package.
   If you select latest, latest version of the solution is added to the package automatically and the package is updated with the latest versions of these solutions when their new versions are added to the repository.
   

6. Enter the PATROL Agent configuration details:

   a.	Enter the installation directory by performing one of the following actions: Proceed with the default installation directory. Enter a different directory location for installation. Leave the field blank and proceed with the installation. When you leave the field blank, the correct directory is automatically selected by using the BMC_BASE variable. If you are using other BMC products, it can use the same default installation directory, which may cause uninstallation issue. For more information, see the Knowledge Article,
   b.	Specify the PATROL 3.x product directory, and click Next.
   c.	(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 / sudo password, leave the field blank. You must run the hostname_port_install.log_rootscripts script file post installation. For more information, see post-installation steps.
   d.	Enter the PATROL default account or local account credentials. Important To allow the PATROL Agent to use the local system account as the PATROL default account, leave the username and password fields blank. To use domain account, enter any of the following: (Windows) DOMAIN_NAME\account name (UNIX) DOMAIN_NAME\\account name Note the double slash before the account name that are used to ensure that the account name is parsed correctly. When you are editing the package and the double slash is deleted, enter it again.
   e.	Select one of the following security options: No Certificate Validation (default) - PATROL Agent uses TLS 1.2 communication channels, but PATROL Agent does not validate the certificate. Certificate Validation - PATROL Agent uses TLS 1.2 communication channels, and PATROL Agent validates the certificate received from server. For more information, see Security certificate options.
   f.	Enter the PATROL Agent port number. The default port number is 3181.
   g.	Select whether you want to restart PATROL Agent automatically or manually after installation, and click Next.
   h.	Enter the streaming endpoint details in the following format: tcp:<IP address or FQDN of the Integration Service>:<port_no> This information will be used to register PATROL Agent with TrueSight Operations Management.
   i.	Enter a comma-separated list of tags to associate PATROL Agents to infrastructure policies. PATROL Agents use the specified tags to get configuration details from TrueSight Operations Management. For example,  WinOS:"Windows OS Monitoring"
   j.	Select whether you want to manage the PATROL Agent configurations via infrastructure policies, and click Next.
   k.	(Optional) Enter the Infrastructure Management encryption key and the cell details in the format: Host/Port. You can opt to route events through an Integration Service. To route events via an Integration Service, set the /EventSetup/Configuration/ForwardEventsToIS PATROL Agent pconfig variable to Yes.  Ensure that you provide the correct Cell name in the Infrastructure Management - Primary Cell and Infrastructure Management - Secondary Cell fields in the Infrastructure Management Performance Management Cell Configurations installation screen. Proceeding with the default value resets the Event Destination of the PATROL Agent to localhost/1828. If /EventSetup/Configuration/ForwardEventsToIS is set to Yes and Infrastructure Management - Primary Cell is set to localhost/1828, the PATROL Agent sends events to the local Cell of the Integration Service.
   l.	Configure the firewall. You can opt to add the solutions to the firewall exception list automatically.

7. Review the deployable package details.
   If you added a monitoring solution that contains sub-components, view the included sub-components by clicking the plus sign.
8. In the Installation Package Details window, enter the following information:
   • Name — The name of the deployable package. It can contain only A-Z, a-z, 0-9, and underscore (_).
   • (Optional) Description — Enter a description of the package.
     The description is displayed in the list of deployable packages.
   • Format — Select a file compression format for the installation package.
9. Click Save and Download.
   To save the package for future installation on the current or other hosts, click Save and download it later from Repository> Deployable package.
   A template of the package is saved to the installationDirectory\truesightpserver\data\pproxy\installer_templates folder and is listed in the Deployable Packages tab.

Task 2: Deploy the package

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.

Task 3: (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 / sudo 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 Feb 10 10:39 PatrolAgent
    The s indicates the sticky bit is set successfully on the PatrolAgent binary. (Same for the snmpmagt binary, if present.)

   Learn more about the sticky bit

6. Make sure 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 API key, forward proxy server, forward proxy user, forward proxy password, publish host name, and additional arguments.
   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 >] [ADDITIONALCMDARGS="<additional arguments>"] /l*v log.txt /qn
    The installation process starts in the silent mode. Review the log file to check the installation status.