Using the TppConfiguration command line tool

Venafi Platform includes a command-line utility that allows system admins to perform installation and configuration actions through the command line or through script files. It provides administrators with greater flexibility and automation capabilities when managing the platform, especially when dealing with multiple environments or large-scale deployments.

The utility is called TppConfiguration.exe and exists in the installation directory, in the following location (assuming you used the default installation directory):

C:\Program Files\Venafi\Platform\TppConfiguration.exe

This utility requires you to use an elevated command prompt.

Using the TppConfiguration command, administrators can:

  • Script the installation or upgrade of Venafi Platform on servers.

  • Update the database connection information for a Venafi Platform server.

  • Enable access to the MMC snapins for the current Windows user.

  • Update the company name or installation type of a server.

  • Uninstall Venafi Platform.

  • Update the HSM pin.

When using the command line utility to install, configure, upgrade, or uninstall Trust Protection Platform, there are a number of allowed switches. This utility requires you to use an elevated command prompt.

The command line argument is:

TppConfiguration.exe -<switch>=<value> -<switch2>=<value>

Some switches require master admin authentication. They are noted in the table below. When you use a switch that requires master admin authentication, you can either:

  • Provide the -username and -password inline in the command. (Required if you are scripting the command.)
  • Wait until prompted by the application to enter the master admin credentials.

TPPConfiguration syntax

  • The command line tool uses a flexible syntax. Simply run the TppConfiguration program with parameters to perform specific tasks.

    For example, TppConfiguration -errorcodes will output a list of return codes and a description of the error. Neither commands or parameters are case sensitive, meaning tppconfiguration -errorcodes and TppConfiguration -errorcodes and TPPCONFIGURATION -ERRORCODES are all interpreted the same.

  • To perform specific tasks, type a parameter directly after typing the TppConfiguration command. For instance, Tpponfiguration -enablemmc.

  • When running the program with no parameters, you will see the inline help. There, you will see that some characters in parameter names are bolded and some are not. The bolded characters are a short-cut syntax that makes it quicker and easier to type commands. For example, the add parameter is displayed in the inline help as -add. The bolded part, in this case -a, is the short cut.

    This short-cut syntax can make it quicker and easier to type commands; however, to ensure compatibility with future versions of TPPConfiguration, you should use full parameter names when scripting.

    TIP  The hyphen (-) is technically optional, but is recommended for forwards compatibility.

  • Command options are additional modifiers that provide further instructions or information to the TPPConfiguration command being executed. For example, -username=<master-admin-user> is used to indicate the username of the master administrator account needed to perform the action. The tool accepts the following operators: =, :, and   (space). Thus the following examples are all treated the same: -username=venafi, -username:venafi, and -username venafi

Combining these principles, the following commands are all interpreted the same:

TppConfiguration -enablemmc -username=george.washington -password=Passw0rd!11

tppconfiguration enablemmc username george.washington -password Passw0rd!11

TppConfiguration.exe -ENABLEMMC -username:george.washington pa:Passw0rd!11

tppconfiguration ena us:george.washington pa Passw0rd!11

Configuration switches for TppConfiguration.exe command line tool

Click a column header to sort by that column.

Parameter

Type

Auth1

Description

-errorcodes

Common Options No Show all error codes that may be returned.

-password:<pw>

Common Options

Yes

Password to decrypt the answer file.

-username=<name>

Common Options No User name of local Venafi Platform admin account.

-keyexport=<pem>

Configuraiton

Yes

Exports the default software key. (Requires -password)

-dboconfig=<cfg>

Configuration

No

Allows changing the SQL database owner account connection information from the command line. You can use this, for example, for automated updating of the SQL database owner account password.

For details on the connection string and its proper syntax, see Obtaining the SQL database connection string.

-keyimport=<pem>

Configuration

Yes

Imports the default software key. (Requires -password)

-sqlconfig:<cfg>

Configuration

No

Allows changing the SQL operational account connection information from the command line. You can use this, for example, for automated updating of the SQL operational account password.

For details on the connection string and its proper syntax, see Obtaining the SQL database connection string.

-add

Installation

No

Runs the installer in the mode that adds this Venafi server to an existing Venafi server cluster (servers that share a single database).

-install=<xml> -password=<pw>

Installation

No

Runs the installer (fresh install if DB is empty; upgrade if DB is not empty) with the configuration options specified in the answer file, and supplies the password to decrypt the answer file.

For example, if the answer file is located at c:\answerfile.xml and the decryption password for the file is Example"Password, this switch would be:

-install:C:\answerfile.xml -password:Example\"Password

NOTE  The quotation mark " and backslash \ characters are special characters, and if included in the password, you need to include a backslash to escape them. So if the password is pas"sw\ord, you would enter it as pas\"sw\\ord.

-log=<file>

Installation

No

Allows you to override the default location of the log file where the results of the configuration process are stored. If you want to save the log file at C:\Temp\VenafiLog.txt, the switch would be:

-log:C:\Temp\VenafiLog.txt

-uninstall

Installation

No

Uninstalls Trust Protection Platform from the Venafi server by doing the following:

  • Removes Venafi registry values, and backs up settings to a registry file stored in the same folder as the log file.

  • Removes the Venafi website from IIS.

This switch is used by Windows when you use Program Features to uninstall Trust Protection Platform.

NOTE  This does not remove the files or Windows Services installed by the .msi. It only removes the websites and registry entries.

-company=<name>

Misc.

Yes

Sets the company name for the system.

-decrypt=<xml>

Misc.

Yes

Decrypts the specified XML file. (Requires -password)

-deployment=<t>

Misc.

Yes

Sets the deployment type for the system. Allowed values for <t> are:

  • D - Development

  • T - Test

  • S - Staging (pre-production)

  • U - User Acceptance Test (UAT)

  • P - Production

-encrypt=<xml>

Misc.

Yes

Encrypts the specified XML file. (Requires -password)

-help

Misc.

No

Shows a help file in the command line window, describing these features and settings.

-dbgrant=<user>

Recovery

Yes

Provides the necessary grants to the Venafi database for the specified user to be an operational database service accounts. This is helpful when using Windows Authentication and users need to launch WebAdmin or Venafi Support Tool.

-driverpwd=<new-pw>

Recovery

Yes

Requests to change the service account password of an identity connector. <new-pw> is the new password. Uses -name, -username, and -password and will prompt if any are omitted.

-enablemmc

Recovery

Yes

Adds or replaces MMC access grant for the current user. Use -username: and -password: to provide Trust Protection Platform user credentials on the command line. Otherwise, you will be prompted for credentials.

-hsmpin=<pin>

Recovery

No

Allows setting the HSM PIN in an HSM-only environment. This is necessary if the HSM pin has been changed, and needs to be updated in Trust Protection Platform.

Note: When used without the <pin> argument, you will be prompted for the pin.

-name=<cn>

Recovery

Yes

The common name of an identity connector object.

-distrust=<dll>

Trust

No

Allows you to remove a DLL from being a trusted resource.

-trust=<dll>

Trust

No

The path to a custom DLL, allowing it to be added as a trusted resource.

For custom development modules, this feature adds the signature of the custom module as trusted resource so the custom features can be added to Trust Protection Platform.

You can combine the switches as needed. For example, here is a command line argument that installs the software on this Venafi Trust Protection Platform server, while connecting to an existing database using a configuration file, and overwriting the default log file location:

TppConfiguration.exe -in=C:\answerfile.xml -add -pa=Washington -l=C:\Temp\VenafiLog.txt