Skip to main content

USP Manager Windows Installation

This guide details the steps required to install the USP Manager on Windows using the provided installer.

Prerequisites​

  • Administrator privileges on the Windows host where USP Manager will be installed.
  • An RSA PEM-encoded key that USP Manager uses to sign JWT tokens for authenticating admin users accessing the UI and/or the REST API.
  • A base64-encoded 256-bit key (32 bytes) for the Key Encryption Key (KEK). For more information, refer to Encryption Key Rotation.
tip

You can generate a new key using the following command.

[System.IO.File]::WriteAllText(".\usp-manager-key.pem", ([System.Security.Cryptography.RSA]::Create(2048)).ExportRSAPrivateKeyPem(), [System.Text.Encoding]::ASCII)

This command creates a 2048-bit RSA private key and saves it in PEM format as usp-manager-key.pem. The key will be unencrypted and suitable for use in USP Manager configuration.

Installation​

1. Get the Windows installer​

To obtain the installation package, contact your Stonebranch representative. If you do not have a representative, reach out to support@stonebranch.com.

2. Install the package​

Run the USP Manager installer and follow the prompts in the installation wizard to complete the installation.

Select the desired installation path or accept the default (C:\Program Files\Stonebranch\USP Manager\).

3. Confirm creation of configuration file​

USP Manager utilizes a configuration file located at C:\Program Files\Stonebranch\USP Manager\usp-manager.hcl.

Verify that this file has been created correctly by running the following commands:

cd "C:\Program Files\Stonebranch\USP Manager\"
dir

4. Set the USP Manager's configuration file​

warning

All files that are going to be used by USP Manager need to be owned by the appropriate user and group (udmg). For more information, refer to File Ownership and Permissions.

Set the following arguments in the USP Manager Configuration File:

usp-manager.hcl
encryption {
    # Defines the source of the KEK (Key Encryption Key).
    # Must always be set to "config".
    kek_source = "config"
    # Base64-encoded 256-bit (32-byte) KEK value.
    # Used to encrypt and decrypt DEKs (Data Encryption Keys).
    kek = "my-secret-encoded-key"
}

database {
    # Use SQLite built-in DB only for non-HA deployments.
    engine = "sqlite"
    # Windows file path (use escaped backslashes).
    hostname = "C:\\ProgramData\\usp-manager\\usp-manager.db"
}

auth {
    # Path to the RSA private key used to authenticate this USP Server with the USP Manager. 
    key = "C:\\Program Files\\Stonebranch\\USP Manager\\usp-manager-key.pem" # Use this if you used the command specified in the Prerequisites section.
}

log {
    # Specify a file path to write logs to a dedicated log file.
    path = "C:\\Program Files\\Stonebranch\\USP Manager\\log\\usp-manager.log"
}
info

For a complete list of available configuration parameters, refer to USP Manager Configuration File.

5. Enable and start the USP Manager Windows service​

On Windows, "enabling" the USP Manager service means configuring it to start automatically when the system boots. You do this by setting the service StartupType to Automatic with the following command:

Set-Service -Name "usp-manager" -StartupType Automatic

Then, start the service:

Start-Service -Name "usp-manager"

6. Verify that the service is running​

Verify that the service is running by executing the following command:

Get-Service "usp-manager" | Select Name, Status, StartType
info

If there is any issue, refer to our Troubleshooting where we cover the most commonly encountered issues.

Post-Installation​

After successful installation, configuration, and startup, you should be able to access the USP Admin UI through a web browser or interact with the USP REST API using the default credentials:

  • Username: admin
  • Password: admin_password.