Advanced command line configuration
This section provides information on using advanced methods to set up the collection server and the database server, and running the LDBUpdate utility. We recommend following the simplified procedures provided in earlier sections.
Configure Collectors using the shell prompt
You can use the shell prompt as an alternative to configuring the collector services using the BeyondTrust Management Console.
Note
For information about configuration using the console, see Set up the admin machine.
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.
Configure the Reaper service
BTEventDBReaper gathers events from a collector (forwarded by endpoints) and writes the events to the database. BTCollector stores incoming events in a local, intermediate database while BTEventDBReaper writes the events to the central SQL Server database.
BTEventDBReaper runs as a Windows service, but can be run from the command line to set up parameters for the service.
To view BTEventDBReaper arguments, run the following command:
C:\\Program Files\\BeyondTrust\\PBIS\\Enterprise\\DBUtilities>BTEventDBReaper /?
| Option | Description |
|---|---|
| /? | Displays help. |
| /gui | Opens a GUI where you can set the database provider and connection string. Use as an alternative to command-line. |
| /d PROVIDER | Sets the database provider: System.Data.SqlClient for SQL Server (default) |
| /c DBSTRING | Sets the database connection string to connect to the BeyondTrust database. |
| /f NUMBER | Sets the earliest record ID that should be copied when the agent runs. Use this parameter with caution. The /f parameter is used to control the point at which the first event in the local collector database is written to the central AD Bridge database. Under normal circumstances, it should not be necessary to set this parameter. |
| /r | Refreshes the agent with new registry settings. |
| /s | Shows the current status. |
| /debug | Runs as command line application with logging. |
Any parameters set from the command line take effect the next time the BTEventDBReaper runs. To apply the settings immediately, run BTEventDBReaper with the /r argument.
To display the current configuration settings for the service, use the /s option:
C:\\Program Files\\BeyondTrust\\PBIS\\Enterprise\\DBUtilities>BTEventDBReaper /s
Current settings:
Database provider: System.Data.SqlClient
Connection string: Data Source=RVLN-BUILD;
Initial Catalog=LikewiseEnterprise;
Integrated Security=True
Record id last copied: 1794
Records per period: 300
Seconds in a period: 1200
Although the settings include records per period and seconds in a period, the parameters cannot be configured from the command line. The default values can be changed using the Enterprise Database Management plug-in.
Verify the Collector processes are running
BTCollector and BTEventDBReaper are started automatically. You can run the following commands to confirm the processes are running.
Verify BTCollector is running
- Run the following command on the Windows computer running the collector:
C:\Program Files\BeyondTrust\PBIS\Enterprise\DBUtilities>sc query BTCollector
SERVICE_NAME: BTCollector
TYPE : 10 WIN32_OWN_PROCESS
STATE : 4 RUNNING
(STOPPABLE, NOT_PAUSABLE, IGNORES_SHUTDOWN))
WIN32_EXIT_CODE : 0 (0x0)
SERVICE_EXIT_CODE : 0 (0x0)
CHECKPOINT : 0x0
WAIT_HINT : 0x0
If the collector is not running, run the following command:
C:\Program Files\BeyondTrust\PBIS\Enterprise\DBUtilities>sc start BTCollector
Verify BTEventDBReaper is running
- Run the following command:
C:\Program Files\BeyondTrust\PBIS\Enterprise\DBUtilities>sc query BTEventDBReaper
SERVICE_NAME: BTEventDBReaper
TYPE : 10 WIN32_OWN_PROCESS
STATE : 4 RUNNING
(STOPPABLE, NOT_PAUSABLE, ACCEPTS_SHUTDOWN)
WIN32_EXIT_CODE : 0 (0x0)
SERVICE_EXIT_CODE : 0 (0x0)
CHECKPOINT : 0x0
WAIT_HINT : 0x0
If the collector is not running, run the following command:
C:\Program Files\BeyondTrust\PBIS\Enterprise\DBUtilities>sc start BTEventDBReaper
Set up the database server using the command line
Important
Active Directory groups must be created before you run through this procedure.
To create the AD Bridge Reporting Database using SQL Server:
- Create a database named LikewiseEnterprise.
- Copy the SQL Server database creation script (CreateLikewiseEnterpriseDatabase.sql) to a location accessible from SQL Server.
- In SQL Server Management Studio, on the File menu, click Open and load the database creation script: CreateLikewiseEnterpriseDatabase.sql.
- Connect to the LikewiseEnterprise database and run the script. If the script executes with errors, run the script again.
Note
For more information, see Configure auditing and reporting
To assign recommended roles to the database:
- Copy ReportingPermissions.sql to a location accessible from SQL Server.
- In SQL Server Management Studio, expand the Databases node, right-click LikewiseEnterprise and click New Query.
- Open the ReportingPermissions.sql file and execute.
Note
You can create the database through the Reporting Database Connection Manager. See Set up the admin machine.
Run the database update script from the command line
To view the command line options for LDBUpdate, run the following command:
C:\Program Files\BeyondTrust\PBIS\Enterprise>ldbupdate.exe /?
Usage: LDBUpdate OPTIONS
Where OPTIONS include:
-f LDAPPATH Path of the forest to synchronize; required
-d FQDN Domain (in forest or in trusts) to process; can repeat
-o FILE Send output to FILE
-p PROVIDER Use PROVIDER as the database type(default: System.Data.SqlClient)
-c STRING Use STRING as the database connection parameter
-nogpo Don't analyze GPOs (faster)
-v Display verbose output
--force Ignore the database status and perform update even if marked as busy
--debug Display debug level output
--transaction Perform all database operations under a single transaction.
Allow interactions to the database with reporting tools while
update is performed in the background.
--class STRING Identify the objects to update, leaving others as is from a
previous update.(Examples: Users, Groups, GPOLinks, GPOs, Computers).
Can be repeated to identify several class types
LDBUpdate --class Users --class Groups -f <domain>...
--help Displays this usage information
If the -d option is not specified, all the domains in the forest and in any trusted forests will be processed.
Example
Use the command-line utility to set the provider and the connection string for a SQL Server database:
ldbupdate.exe -f dc=example,dc=com -p System.Data.SqlClient -c "Data Source=RVLN-BUILD; Initial Catalog=LikewiseEnterprise; Integrated Security=True" --force
Updated about 1 month ago