Overview of the Database Management Console
The AnyCAGateway DCOM Database Management Console (DatabaseManagementConsole.exe) is a text-based, command line application for managing all database tasks related to the AnyCAGateway DCOM database, along with other database maintenance activities.
The Database Management Console (DatabaseManagementConsole.exe) can receive input in three possible ways:
Command-Line Flags
To provide parameters via the command-line, provide the function first (e.g., create) and then the parameters to the function. For example:
.\DatabaseManagementConsole.exe create --server sqlsrvr.keyexample.com --database CAGateway
JSON Configuration File
The default JSON configuration file is called dbConfig.json and is located in the install directory. To specify a different JSON file path or file name, use the --config command-line flag. If you're using the default JSON configuration file, you only need to provide the function when running the Database Management Console command. For example:
.\DatabaseManagementConsole.exe create
The default JSON configuration file contains commented-out examples of all the possible parameters. Data in the file is given in the following format:
"parameter":"value",
The example file also contains comments indicating which function a parameter can be used with, whether it is required, and what it does. For example:
"server":"sqlsrvr.keyexample.com", // Create/Populate/Upgrade: REQUIRED, The FQDN of the machine hosting SQL server.
"database":"CAGateway", // Create/Populate/Upgrade: REQUIRED, The name of the database to be created/populated/upgraded.
"username":"john_smith", // Create/Populate/Upgrade: OPTIONAL, The username of the SQL account to use for creating/populating/upgrading the database, if not using integrated authentication.
"password":"MySecurePassword", // Create/Populate/Upgrade: OPTIONAL, The password of the SQL account to use for creating/populating/upgrading the database, if not using integrated authentication.
Environment Variables
To provide arguments via environment variables, the variables should be given the same names as the fields in the sample json file (see Table 1085: Database Management Console Parameters, except the variable names should have a prefix of KeyfactorGateway- (e.g., KeyfactorGateway-server).
If you're using environment variables to set the parameters, you only need to provide the function when running the Database Management Console command. For example:
.\DatabaseManagementConsole.exe create
Figure 628: DatabaseManagementConsole Parameters Provided as Environment Variables
The function operation (create, populate, upgrade, or migrate) must be provided as a command line . The parameters to the function can come for any or all of these sources. If the same parameter exists in more than one source (command line, JSON file, or environment variable), the order of priority is command line > JSON file > environment variables, meaning the parameters provided at the command line take precedence over those of the same names provided in the JSON file, which takes precedence over those of the same names set in the environment variables. When the command is run, the parameters from all three sources are combined and the rules of precedence are used to remove duplicates. Anything remaining, from whatever source, is used for the command, so if you specify a command-line value for one parameter but happen to have an environment variable set for another parameter, both parameters will be used in the command.
Database Management Console Functions and Parameters
Major functions of the Database Management Console are shown in Table 1084: .Database Management Console Functions. Parameters to the functions are shown in Table 1085: Database Management Console Parameters.
Table 1084: .Database Management Console Functions
| Create |
Create a new database. |
Create the Database
|
| Populate |
Populate an existing, empty database. |
|
| Upgrade |
Upgrade an existing database from a previous version of the AnyCAGateway DCOM. |
Upgrading from AnyCAGateway DCOM Version 20.x or Later
|
| Migrate |
Migrate an exiting ESENT database to a new, empty AnyCAGateway DCOM SQL database. |
|
| Help, --help |
Display information on a specific command. |
|
| Version, --version |
Display version information. |
|
Table 1085: Database Management Console Parameters
| -s, --server |
server |
Create, Populate, Upgrade |
The FQDN of the machine hosting SQL server. This parameter is required for create, populate, and upgrade tasks. For example:
sqlsrvr .keyexample .com
|
| -d, --database |
database |
Create, Populate, Upgrade |
The name of the database to be created, populated, or upgraded. This parameter is required for create, populate, and upgrade tasks. For example:
CA Gateway
|
| -u, --username |
username |
Create, Populate, Upgrade |
The username of the SQL server account to be used for creating, populating, or upgrading the database. This parameter does not apply if Windows integrated authentication is used. The SQL account must exist before the command is executed (unlike the service-user parameter). This parameter is optional. For example:
john_ smith
|
| -p, --password |
password |
Create, Populate, Upgrade |
The password of the SQL server account to be used for creating, populating, or upgrading the database. This parameter does not apply if Windows integrated authentication is used. This parameter is optional. |
| --dacpac- path |
dacpac path |
Create, Populate |
The path and filename of the DACPAC to override the default location of DACPAC. Defaults to the install directory. This parameter is optional. For example:
C:\\MyFiles \\Custom .dacpac
OR
C:\MyFiles \Custom .dacpac
Note: When provided in the JSON configuration file, the backslashes in this value must be escaped (e.g., C:\\MyFiles \\Custom.dacpac). When used from the command-line or configured as an environment variable, the backslashes in this value should not be escaped (e.g., C:\MyFiles \Custom.dacpac).
|
| --logging- path |
logging path |
Create, Populate, Upgrade, Migrate |
The path and filename of an NLog configuration file that applies specifically to database create, populate, upgrade and migrate logging and overrides the default location of the NLog config file. Defaults to the NLog.config in the install directory. This configuration does not apply to future logging by the gateway once database create, populate, upgrade, or migrate tasks are complete. This parameter is optional. For example:
C:\\MyFiles \\NLog .config
OR
C:\MyFiles \NLog .config
Note: When provided in the JSON configuration file, the backslashes in this value must be escaped (e.g., C:\\MyFiles \\NLog.config). When used from the command-line or configured as an environment variable, the backslashes in this value should not be escaped (e.g., C:\MyFiles \NLog.config).
|
| --service- default |
service default |
Create, Populate |
A Boolean that specifies whether the gateway service database permissions should be granted to the default NETWORK SERVICE account (true). The default is true unless the username or service-user parameter is specified. This is primarily used when SQL authentication is used to create the database (the username and password parameters), but you want to revert to using NETWORK SERVICE to operate the gateway rather than the SQL account specified to create the database. This parameter is optional. |
| --service- user |
service username |
Create, Populate |
The username of the Active Directory or SQL account to grant read/write permissions to, for use by the gateway service. If not specified, permission will be granted to either the account specified by the username flag or to the NETWORK SERVICE account. If you specify a SQL account, it will be created in SQL if it does not already exist. Active Directory users must have a pre-existing login in SQL. This parameter is optional. For example:
KEYEXAMPLE \svc_gateway
OR
SQL_gateway_svc
|
| --service- password |
service password |
Create, Populate |
The password of the Active Directory or SQL account to be used by the gateway service. This parameter is optional. |
| --script- path |
script path |
Upgrade |
The path to a directory containing the gateway upgrade scripts that overrides the default location of database upgrade scripts. Defaults to the install directory. This parameter is optional. For example:
C:\\MyFiles \\Upgrade Scripts
OR
C:\MyFiles \Upgrade Scripts
Note: When provided in the JSON configuration file, the backslashes in this value must be escaped (e.g., C:\\MyFiles \\UpgradeScripts). When used from the command-line or configured as an environment variable, the backslashes in this value should not be escaped (e.g., C:\MyFiles \UpgradeScripts).
|
| --esent- path |
esent path |
Migrate |
The path to a directory containing the ESENT database that overrides the default location of the ESENT database. Defaults to C:\ProgramData\CertSvcProxy\TemplateDB. This parameter is optional. For example:
C:\\MyFiles \\Template DB
OR
C:\MyFiles \Template DB
Note: When provided in the JSON configuration file, the backslashes in this value must be escaped (e.g., C:\\MyFiles \\TemplateDB). When used from the command-line or configured as an environment variable, the backslashes in this value should not be escaped (e.g., C:\MyFiles \TemplateDB).
|
| --logical- name |
logical name |
Migrate |
The logical name of the CA that is being upgraded. This parameter is required for migration tasks. For example:
CA Gateway
|
