Configure the Collectors Using the Shell Prompt

You can use the shell prompt as an alternative to configuring the collector services using the BeyondTrust Management Console.

For information about configuration using the console, see Configure Agents to Forward Events to the Collector Service.

Configure the Collector Service

You can configure the following performance and security settings on BTCollector:

  • Set the maximum number of events that an endpoint can send.
  • Set how frequently the endpoints connect to the collector and send data.
  • Set permissions on a collector that services more than one domain.

A provider name and a connection string are the only required parameters to run the BTCollector, which is auto-started as a Windows process at C:\Program Files\BeyondTrust\PBIS\Enterprise\DBUtilities.

To view the arguments, run the following command:

C:\Program Files\BeyondTrust\PBIS\Enterprise\DBUtilities>BTCollector /h

 

Option Description
/h Displays help.
/p <integer>

Sets the maximum number of events that an endpoint can send to a collector per period. A period consists of sending multiple batches and then sleeping until the period is over.

This number, in combination with the /t parameter, can be set to control the load on endpoints imposed by the event forwarding service (eventfwd) sending events to collectors.

If this number is large, the event forwarder might consume excessive CPU time and network bandwidth.

If the number is small, however, the endpoint might fall behind with the incoming event rate and end up with a large backlog of uncollected events.
/b <integer>

Sets the records that the event forwarder can send per batch. A batch is sent with a single RPC call, so setting this too high delays adding any records in the batch until the entire batch is sent.

The collector sends events in batches until the number of sent events reaches the value that you set (or until there are no more left to send, whichever number is smaller).

If set too high, the network transaction might fail because of a connection that times out.

If set too low, the event forwarding service might consume too much CPU time and bandwidth because there are more network transactions.
/t <integer>

Sets the forwarding period in seconds. If an event forwarder finishes sending its events before this length of time is up, it will sleep to finish the period.

The parameter controls how often the endpoint connects to the collector to forward events.

If the forwarding period is set to 300 seconds, for example, the endpoint event forwarder service sends events to a collector once every 5 minutes.

The smaller the number is, the more frequently endpoints communicate with collectors and the smaller the latency between the time when an event is generated and when it appears in the database.

If the number is too small, however, it can result in excessive load on the endpoints and in excessive network traffic.
/a <string>

Sets the access control list (ACL) of the computers allowed to communicate with the collector. The remote access security descriptor uses SDDL syntax. The default value is O:LSG:BAD:PAR(A;;CCDCRP;;;BA)(A;;CCDCRP;;;DA)(A;;CC;;;DC).

The parameter sets configuration information that affects the collector rather than the endpoints that communicate with it. By default, the ACL for the collector's RPC port is set to allow computers in the Active Directory Domain Computers group to write to the collector. This is the permission set by the long SDDL formatted string shown in the usage information for the /a parameter.

In the case of collectors that are servicing multiple domains, however, this ACL is insufficient, because it allows only endpoints joined to the same domain as the collector to write to it. In such cases, you can use the /a parameter to specify a more inclusive ACL.
/l <level> Sets the log level to error, warning, info, verbose, or debug.
/s Shows the current settings.

The /s parameter displays the default settings:

C:\Program Files\BeyondTrust\PBIS\Enterprise\DBUtilities>BTCollector /s
Current settings:
Records per period        10000
Records per batch         100
Seconds in a period       10
Database location C:\Program Files\BeyondTrust\PBIS\Enterprise\DBUtilities\BTCollector.db
Remote access security descriptor O:LSG:BAD:P(A;;CC;;;DC)(A;;CC;;;DA)(A;;RP;;;DA)(A;;DC;;;DA)(A;;CC;;;BA)(A;;RP;;;BA)(A;;DC;;;BA)(A;;CC;;;S-1-5-21-418081286-1191099226-2202501032-515)

Remote Access Permissions

The remote access security descriptor shown in the above output is the default. It provides the following group accounts with these permissions:

  • Domain Computers are allowed to create children (add events).
  • Domain Administrators are allowed to create children (add events).
  • Domain Administrators are allowed to read properties (read events).
  • Domain Administrators are allowed to delete children (delete events).
  • Built-in AD Bridge Administrators are allowed to create children (add events).
  • Built-in AD Bridge Administrators are allowed to read properties (read events).
  • Built-in AD Bridge Administrators are allowed to delete children (delete events).

The ACL is stored in the Windows registry of the collection server. The AD Bridge Console writes the ACL to the AD Bridge database. The BTEventDBReaper service pulls it from the database and writes it to the registry.