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 --helplists the command groups.DbTool database --helplists the commands in a group.DbTool database upgrade --helplists the options for a command, and usually includes an example.DbTool --versionshows 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.