DbTool Command-Line Utility

DbTool is a command-line utility installed with Cygna Auditor. Use it to perform administrative and maintenance tasks from a command prompt or a script, such as upgrading and maintaining databases, starting and stopping services and agents, rolling back Active Directory objects in bulk, moving reports between systems, and collecting diagnostic information for Cygna Labs Technical Support.

Running DbTool

DbTool is installed in the Tools folder of the Cygna Auditor installation folder. In a default installation, the path is:

C:\Program Files\Cygna Labs\Tools\DbTool.exe

Run DbTool on the Cygna Auditor server, from a command prompt opened in the Tools folder. Commands that start or stop services or change the configuration of the server need local administrator rights, so run the command prompt as administrator.

Commands are organized into groups. Enter the group, then the command, then any options:

DbTool <group> [<subgroup>] <command> [options]

For example:

DbTool database list
DbTool agent ad start --domain contoso.com
DbTool support package --output C:\temp\support.zip

Command and option names are not case-sensitive.

Getting Help

Help is available at every level of the command structure:

  • DbTool --help lists the command groups.
  • DbTool database --help lists the commands in a group.
  • DbTool database upgrade --help lists the options for a command, and usually includes an example.
  • DbTool --version shows the DbTool version.

Common Options

The following options are available for every command:

Option Description
-h, --help Show help for DbTool, a command group, or a command.
-v, --verbose Write additional progress details to the console while the command runs.
--diagnostic Write the internal diagnostic log to the console. Use this option when a command fails and the reason is not clear.

Permissions and Licensing

  • Many commands can be run only by a Cygna Auditor Global Administrator. DbTool checks the Windows account that runs the command, including its group memberships. If the account is not a Global Administrator, DbTool reports that the tool may only be run by a Global Administrator and the command does not run. The reference for each command states whether this is required.

  • The agent and recovery commands require the corresponding Cygna Auditor license. If the module is not licensed, DbTool reports that it is not licensed and makes no changes.

Passwords

Options that take a password accept ? instead of the password. DbTool then prompts for the password and masks it as you type, so that the password is not saved in the command history or in a script. For example:

DbTool agent file-system start --user CONTOSO\svc_auditor --password ?

Exit Codes and Output

DbTool returns exit code 0 when a command succeeds and -1 when it fails, so that scripts can check the result. Error messages, the Global Administrator check, and the elapsed time (shown for commands that take longer than two seconds) are written to the standard error stream. This keeps the standard output of commands such as status list --json clean when you redirect it to a file or another tool.

Command Groups

Group Description
account Check and repair the sign-in details of a single user account. See DbTool Account Commands.
agent Start, stop, and update the remote Active Directory and File System agents. See DbTool Agent Commands.
config Read and change the internal settings stored in the database. See DbTool Configuration Commands.
database Create, register, upgrade, and maintain the SQL Server databases. See DbTool Database Commands.
event Inspect and reprocess the audit events already stored in the database. See DbTool Event Commands.
recovery Search Active Directory snapshots and the Recycle Bin, and roll back or recover objects in bulk. See DbTool Recovery Commands.
report List, export, and import saved report definitions. See DbTool Report Commands.
risk Run the Risk Radar detectors and produce standalone risk reports. See DbTool Risk Radar Commands.
service Start and stop the Windows services on this server. See DbTool Service Commands.
status Read the health and progress entries that the product records about itself. See DbTool Status Commands.
support Collect diagnostic information for Cygna Labs Technical Support. See DbTool Support Commands.

Earlier Command Names

Earlier versions of DbTool used single-word command names, such as ListDatabases and BulkRollback. These names still work, so existing scripts continue to run, but they are no longer listed in the help. Use the current command names in new scripts.

Earlier name Current command
VerifyAccount DbTool Account Commands
ResetTotp DbTool Account Commands
StartAdAgent DbTool Agent Commands
StopADAgent DbTool Agent Commands
UpdateAdAgent DbTool Agent Commands
StartFSAgent DbTool Agent Commands
StopFSAgent DbTool Agent Commands
SetConfiguration DbTool Configuration Commands
ResetAlertConfiguration DbTool Configuration Commands
ListDatabases DbTool Database Commands
CreateAuditorDatabase DbTool Database Commands
AddDatabase DbTool Database Commands
RemoveDatabase DbTool Database Commands
RenameDatabase DbTool Database Commands
SetCoreDatabase DbTool Database Commands
TestConnection DbTool Database Commands
UpgradeDatabaseSchema DbTool Database Commands
RunMaintenance DbTool Database Commands
RunPurgeCleanup DbTool Database Commands
ApplyUserCategoryRules DbTool Event Commands
ClearAllEventCategories DbTool Event Commands
ListExclusionRules DbTool Event Commands
ListInternalAuditEventNames DbTool Event Commands
RunDataManagement DbTool Event Commands
SearchSnapshots DbTool Recovery Commands
SearchRecycleBin DbTool Recovery Commands
BulkRollback DbTool Recovery Commands
CompressADSnapshots DbTool Recovery Commands
ListReports DbTool Report Commands
ExportReport DbTool Report Commands
ImportReport DbTool Report Commands
RunRiskReport DbTool Risk Radar Commands
GenerateStaleAccountReport DbTool Risk Radar Commands
StartAuditorServices DbTool Service Commands
StopAuditorServices DbTool Service Commands
GetStatus DbTool Status Commands
GenerateSupportPackage DbTool Support Commands