Configuring the Agent

Monitoring Studio X allows you to manage the main configuration properties of the PATROL Agent directly from its Web interface, that is:

  • Defining a default user account
  • Managing user access rights
  • Preloading KMs
  • Configuring data retention periods
  • Managing TrueSight Integration properties
  • Configuring advanced settings

Once the PATROL Agent is properly configured, you need to review and customize the settings for:

  • Java
  • HTTP server

Default Account

You can configure the Default Account that the agent uses for parameter collects, recovery actions, and discovery procedures. By default, this account is the one used to install the PATROL Agent.

On Windows systems, if the Run As LOCALSYSTEM option is activated, the PATROL Agent uses the LocalSystem account, that is the predefined account on the server running the PATROL Agent which grants extensive privileges. This account does not have a password.

Access Control List

You can restrict user access to a PATROL Agent by creating an Access Control List (ACL) in which you can specify the allowed or denied users, hosts that are authorized or denied access to the agent and the granted access modes.

An Access Control List consists in a comma-separated list of entries of the following format: <username>/<hostname>/mode.

Preloaded KMs

The Preloaded KMs section lists all the KMs that are automatically loaded at startup by the PATROL Agent. Preloaded KMs run as long as the PATROL Agent runs.

Tip: Preload the KMs that you regularly use and for which you want to maintain a continuous data collection history.

If you want the PATROL Agent to only execute the KMs configured to be preloaded, set the Prevent Dynamic Loading of Other KMs to PREVENT to keep a BMC PATROL Classic Console from loading unlisted KMs.

Data Retention Periods

The Parameters Retention option sets the number of days that collected parameter values are retained in the history database. After this retention period has expired, the retained information is deleted.

The Events Retention option controls the maximum size in bytes of the event log. The PATROL Agent’s local event log is a circular file, therefore, when the file fills up, the agent deletes older events to accommodate new ones.

TrueSight and Helix Integration

This section describes how to configure the PATROL Agent for integration with BMC TrueSight Operations Management or BMC Helix Operations Management.

Terminology

Depending on the version of the PATROL Agent, the terminology varies slightly:

  • For PATROL Agent versions up to 11.3.02, you can specify Integration Services to integrate the agent with BMC TrueSight.
  • For PATROL Agent versions from 20.02 and higher, you can specify Streaming Endpoints to integrate the agent with either BMC TrueSight or BMC Helix.

While the interface reflects the terminology applicable to the agent, the actual configuration variable is the same in both cases: /AgentSetup/integration/integrationServices.

BMC TrueSight Integration

To connect a PATROL Agent to BMC TrueSight Operations Management, use the below syntax:

tcp:<is1Hostname>:3183,tcp:<is2Hostname>:3183,...

where <is1Hostname> and <is2Hostname> are the hostnames to the Integration Services of your BMC TrueSight environment. You can specify several Integration Services in a comma-separated list. When the PATROL Agent fails to connect to the first Integration Service in the list, it tries the next one.

BMC Helix Integration

To connect a PATROL Agent (version 20.02 and higher) to BMC Helix Operations Management, use the below syntax:

https:<endpointHostname>:443

where <endpointHostname> is the address of your BMC Helix Operations Management environment, or an in-between load balancer.

For the PATROL Agent to self-register with a specific BMC Helix environment (and/or load balancer), it will need to use the associated API Key. When integrating the PATROL Agent with a new environment, make sure to update the API Key field accordingly (the API Key value can be retrieved in your BMC Helix environment interface). The PATROL Agent needs to be restarted for the new API Key to be taken into account and the auto-registration to be attempted.

Starting from v20.08, the PATROL Agent can be configured to communicate with BMC Helix Operations Management through a forward proxy server. If this is the configuration you opted for, enable the option Use a Proxy Server and specify the Hostname or IP Address, the Port, and the Username and Password to connect to the forward proxy server.

The corresponding configuration variables for these settings are:

  • /AgentSetup/integration/forwardProxyServer
  • /AgentSetup/integration/forwardProxyUser
  • /SecureStore/mca/tenant/forwardProxyPasswd

Agent Tags

Tags are used to specify which Infrastructure Policies set in TrueSight or Helix applies to the agent. Infrastructure Policies can be associated to specific Agent Tags.

You can assign Tags to a PATROL Agent to decide which Infrastructure Policies will be applied to it. For each Tag, you can add an optional description.

Events Routing

Several options are available to define how PATROL events are routed to TrueSight Event Management:

Options Description
Send Events to BMC Helix (Only for PATROL Agents v20.08 and higher integrated to BMC Helix)
Enable this option if you wish the PATROL Agent to send the monitoring events to BMC Helix Operations Management. The corresponding configuration variable is /AgentSetup/integration/HelixMonitorEvents.
TrueSight Event Management Cells Specifies where the events generated by the BMC PATROL Agents must be routed. The primary host is used by default. A secondary host (comma-separated), can be added to create a cluster configuration.
Encryption Key Defines the encryption key used to send events to TrueSight Event Management.
Event Format Container String that is added to the name of the PATROL generated events to identify the format of the event that is sent to a TrueSight Event Management Cell. By default, the string is BiiP3.
Route Events Through the Integration Service Prevents events to be sent directly to the TrueSight Event Management cell.
Send the STD/41 Event to TrueSight By default, STD/41 events are not sent to TrueSight. However, some KMs, including Monitoring Studio X, leverage this class of event to provide useful information, such as threshold breaches, for example.

Advanced Settings

When you configure Monitoring Studio X from the Web interface, you may want to block any updates from CMA policies that could interfere or supersede your settings. To prevent changes from Infrastructure Policies on the PATROL Agent, simply set the Disable Configuration Updates from TrueSight CMA Policies to YES.

Additionally, you can fine-tune the integration with BMC TrueSight with the following configuration variables:

  • Publish Hostname
  • Integration Service Connection Timeout
  • Retries
  • Retries per Integration Services
  • Wait Before Retries
  • Text Parameter Maximum Length
Warning: Most of the Agent settings require a restart of the PATROL Agent to take effect.

Java Settings

To operate properly, Monitoring Studio X requires that Java 1.8.00 or higher and a Java Runtime Environment (JRE) are installed on the same system that runs the PATROL Agent.

The Java Settings page displays information about the JRE currently in use and a list of all the JREs installed on the monitored system. You can also configure the following options to fine-tune the Java properties:

Options Description
Automatically Select Appropriate JRE To let Monitoring Studio X automatically find and use the most compatible JRE at the initial discovery that occurs when the PATROL Agent and Monitoring Studio X start.
Execute the JVM as an Alternate User By default, the Java process is launched with the same credentials as the PATROL Agent. If the PATROL Agent’s default account does not have sufficient privileges to perform the operations required by the Java Collection Hub, another user account can be provided.
Java Minimum Heap Size To customize the minimum size (in MB) of the Java Hub Heap Memory according to your environment requirements. By default, the minimum size is set to 128 MB.
Java Maximum Heap Size To customize the maximum size (in MB) of the Java Hub Heap Memory according to your environment requirements. By default, the maximum size is set to 512 MB.
Disable JRE Pre-Validation By default, Monitoring Studio X checks that the selected JRE meets the requirements. However, you can disable this option to bypass the compatibility check. Use this option only if you are certain that the provided JRE is compatible even if the compatibility check fails. An unsuitable JRE will prevent Monitoring Studio X to operate properly.
JVM Arguments To provide arbitrary arguments to the Java command line that Monitoring Studio X uses to launch the Java Collection Hub in the Command line options field.

The JVM needs to be restarted for your new settings to be taken in account.

HTTP Server

The HTTP Server page enables you to configure the connection properties for your HTTP Server. The HTTP Server configuration applies to the Monitoring Studio X Web Interface as well as the REST API.

If you need to prevent access to the Web UI and REST API provided by Monitoring Studio X, you can disable the HTTP server entirely.

Define the HTTP Server authentication properties to control the access to the PATROL Agent, the REST API and the Monitoring Studio X Web interface:

Properties Description
Must Be Listed in the PATROL Agent’s ACL Restricts access to users allowed by the PATROL Agent’s ACL.
Only These Users Can Sign In
Only Members of These Groups Can Sign In
Restricts access to specific users or user groups. User names and groups must be comma-separated. Leave both lists empty if you do not want to restrict access to specific users or groups.
Always Allow the PATROL Agent’s Default Account to Sign In Grants access to the PATROL Agent’s default account regardless of any other user access restrictions. This option supersedes other access restrictions settings.
Allow Anonymous Access (Read-Only) Grants read-only access to user without prompting them for a user name or password. Use this option in trusted environments only.

If needed, you can tune the Advanced Settings of the HTTP server:

Properties Description
HTTPS Port Defines the port number of the HTTP server. Using + or -, you can specify a relative port number based on the PATROL Agent port number to avoid having to change the HTTPS port number if the PATROL Agent port changes. By default, this value is set to +262 and sets the HTTPS port to PATROL Agent Port: 3181 + 262, that is 3443.
SSL Certificate - PKCS#12 Keystore Path to the PKCS#12 Keystore file (on the PATROL Agent) that stores the SSL certificate to be used by the HTTP server. Only the PKCS#12 standard format is supported. The associated password to open the keystore is mandatory. The specified path can be relative to $PATROL_HOME. Example: ./keystore.p12 will be expected to be found as $PATROL_HOME/keystore.p12.
Keystore Password Mandatory password associated to the PKCS#12 Keystore file specified above.
Bind to IP Address Assigns a static IP address to the HTTP server.
Number of HTTP Server Threads Defines the maximum number of simultaneous transactions that the HTTP Server can handle. By default, this option is set to 20 threads.
Session Timeout Specifies the duration that a session can remain idle before the server terminates it automatically and the user is required to authenticate again.

The JVM needs to be restarted for your new settings to be taken in account.

SSL Certificate of the HTTP Server

Out of the box, Monitoring Studio X uses a self-signed SSL certificate to operate its HTTPS server. Your browser will warn you that the connection to this HTTPS server is unsecure, because it cannot verify the identity of the server.

To avoid giant security warnings in your browser when you connect to Monitoring Studio X Web Interface, you can configure the HTTP server to use a proper SSL certificate corresponding to its hostname and domain name with the below procedure:

  1. Obtain a certificate from a Certificate Authority (external or in your organization) and the associated private key. The certificate file is typically a *.crt, *.cer or *.pem file.

  2. Store the certificate and the associated private key in a PKCS#12 keystore file. This can be done with several tools like OpenSSL or keytool.

    Example with OpenSSL:

    $ openssl pkcs12 -export -inkey yourdomain.key -in yourdomain.crt -out mystore.p12 -name "My Certificate" -password p4ssw0rd
    
  3. Save the *.p12 file on the host running the PATROL Agent, typically in the $PATROL_HOME directory.

  4. Configure Monitoring Studio X HTTP Server to use this *.p12 file as the SSL Certificate PKCS#12 Keystore and specify the password to open, decrypt and verify the integrity of the keystore.

  5. Restart the JVM. The next screen should show you that the HTTP server is responding. However, due to security measures in browsers, the Web application will probably not be able to properly report when the HTTP server starts responding with the new certificate. After a few seconds, simply refresh the page of the browser and make sure the certificate of the HTTP server is the one you configured.

Prometheus Exporter

Monitoring Studio X provides a PATROL Agent exporter that can be easily integrated into the Prometheus ecosystem. When enabled, the Prometheus exporter scrapes the PATROL Agent numeric parameters and exposes them to Prometheus as standard metrics.

For more information, refer to Exposing PATROL parameters in Prometheus

Agent and System Information

The Information page, as its name suggests, provides any relevant information about the PATROL Agent such as its version, the port it is running on, the Operating System, etc. From this page, you can also preview and download the PATROL Agent log files (current and past). Messages sent to the error log include both error messages that result from a failed action, and informational messages that result from successful action.

Note about times

The Agent Information displays various information about time, notably the current time of the system where the PATROL Agent is running. As this system clock may not be synchronized with your own system (where your browser is running), this page highlights the clock skew between the agent and your browser.

For consistency, all times about events and data on the agent are adjusted to your local time, taking into account time zones and clock skew.

Example:

  • Agent time is 9:15:00
  • Browser time is 9:20:07
  • There is a 307-second (5 minutes and 7 seconds) clock skew between the agent and the browser (agent is 307 seconds behind your browser).
  • An alarm was triggered at 9:12:00 on the agent. At this time, it was already 9:17:07 on your browser.
  • This event will be displayed in your browser as happening at 9:17:07 (2 minutes ago) (which is more logical than displaying 9:12:00 (2 minutes ago) while your clock says it’s currently 9:20:07).

Agent Thresholds

The Agent Thresholds page summarizes all the alert thresholds configured, applicable and currently set on the PATROL Agent.

Agent thresholds are displayed in a sortable table and can be downloaded as a .CFG or .CSV file

3 types of thresholds are displayed separately:

Type Description
Persistent Alert thresholds stored in the agent’s configuration
CMA Alert thresholds that have been set in an Infrastructure Policy in TrueSight CMA that applies to this PATROL Agent
Current In-effect alert thresholds on currently monitored instances and parameters

Persistent Thresholds

These alert thresholds are stored in the PATROL Agent’s configuration under /___tuning___.

These thresholds definitions may apply to a parameter of a specific instance, or to a parameter of an entire class (i.e. all of its instances). In the latter case, the table shows the number of instances that the threshold definition apply to.

Thresholds can be edited by clicking on the corresponding thresholds definitions. Depending on the available information and type of thresholds, the editing dialog may display different information.

Orphaned Thresholds

Some thresholds definitions may not be applicable to any existing instance or parameter. This will typically happen when you unload or uninstall a KM, or simply when monitored instances are no longer monitored. We call these thresholds “Orphaned”.

Orphaned thresholds are displayed in light grey in the table. You can filter the table to display only the orphaned thresholds, or applicable thresholds.

You can mass-delete all thresholds definitions that are displayed in the table with the DELETE ALL button.

You can also use the search box and the Orphaned/Applicable filter to select a subset of thresholds and then delete them with the DELETE ALL button. This is a very practical way to clean up all Orphaned thresholds definitions that clutter your agent’s configuration.

Warning: Before you do something you may regret, we strongly recommend that you backup the agent's configuration with the BACKUP button. Configuration backups can be retrieved and restored from the Tools > Config Backup & Restore menu.

CMA

Thresholds displayed in the CMA tab all come from Infrastructure Policies defined in TrueSight CMA, and applied to this PATROL Agent.

These thresholds definitions cannot be modified or deleted. But because the table is a practical summary of all thresholds defined in all applicable policies for this agent, it allows you to quickly troubleshoot policy issues.

Current

The thresholds displayed in the Current tab summarizes all alert thresholds on all parameters for all instances of all classes monitored on this PATROL Agent. Only the parameters listed in this table will trigger alerts and events.

This table will differ from the Persistent table as some KMs programmatically set alerts thresholds using the set_alarm_ranges() PSL function. These supersede thresholds definitions in the /___tuning___ configuration tree, and even those defined through CMA policies.

You can edit these thresholds right from the table by clicking on the thresholds definitions.

Editing alert thresholds with a dynamic view of how much time the parameter will spend in ALARM or WARN state

If you enable the Persistent Thresholds in this dialog, your settings will also be saved in the /___tuning___ configuration tree. You may need to manually refresh the Persistent tab to get the new thresholds definitions.

No results.