Skip to main content

USP Manager Installation

This guide details the steps required to install the USP Manager on Debian-based and RHEL-based systems using the provided .deb and .rpm packages.

Prerequisites​

  • Root access.
  • 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.

openssl genrsa -out usp-manager-key.pem

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. Download the .rpm package​

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​

Use the following command to install the package:

sudo rpm -ivh usp-manager_{VERSION}_linux_amd64.rpm
info

Replace {VERSION} with the version of USP you are installing (e.g., 1.0).

3. Confirm creation of config and env files​

USP Manager utilizes a configuration file located at /opt/udmg/etc/usp-manager.hcl. Additionally, the systemctl unit loads environment variables from a file located at /opt/udmg/etc/usp-manager.env. Verify that these files have been created correctly by running the following commands:

cd /opt/udmg/etc/ 
ls

4. Set the USP Manager's configuration file​

Edit the /opt/udmg/etc/usp-manager.hcl file by opening it in a text editor. For example:

vi usp-manager.hcl
warning

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

Set the following arguments in the USP Manager Configuration File:

/opt/udmg/etc/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"
  dsn = "/home/udmg/usp-manager.db"
}

auth {
  # Path to the RSA private key used to authenticate this USP Server with the USP Manager. 
  key = "/opt/udmg/etc/usp-manager-key.pem" # Use this if you used the command specified in the Prerequisites section.
}

log {
  # (Optional) Recommended for troubleshooting.
  # Specify a file path to write logs to a dedicated log file.
  path = "/var/opt/udmg/usp-manager.log"
}
info

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

5. Start the USP Manager systemd service​

Once the required configuration fields have been configured, start the service using the following command:

sudo systemctl start usp-manager

6. Verify that the service is running​

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

sudo systemctl status usp-manager
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: admin:admin_password.