Configuring the Agent

This section explains how to configure the main properties of the PATROL Agent from the Agent menu of the Monitoring Studio X user interface. Detailed information about the PATROL Agent properties itself is available from the BMC Documentation, see the Related Topics section.

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.

TrueSight Integration Services, Helix Streaming Endpoint

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

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


where <is1Hostname> and <is2Hostname> are the hostnames to the Integration Services (or Streaming Endpoints with version 20.02) of your BMC TrueSight environment. As in the example, you can specify several Integration Services (or Streaming Endpoints) 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

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


where <endpointHostname> is the hostname of BMC Helix itself, or a reverse proxy in your environment configured to forward HTTP requests to BMC Helix.

Agent Tags

Tags are a practical way to specify which Infrastructure Policies defined in TrueSight or Helix will be applicable 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
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 -jar … 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.

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.


  • 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 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).
studio km patrol develop web