Version: 3.3

USP Manager Configuration File

The Configuration File is the central setup point for USP Manager instances.

On the host where USP Manager is installed, the default location of the file is:

Linux
Windows

/opt/udmg/etc/usp-manager.hcl

C:\Program Files\Stonebranch\USP Manager\usp-manager.hcl

This file uses HCL (HashiCorp Configuration Language) to express structured settings such as encryption keys, database connections, web server options, and authentication parameters.

What Is HCL?

The USP Manager configuration file is written in HCL (HashiCorp Configuration Language), a human-friendly syntax for structured configuration.

Key points about HCL:

Blocks group related settings inside curly braces ({}). For example, the api block contains all API-related options.
Arguments are key-value pairs defined within blocks. Each argument has a name (the key) and a value.
Argument names are unique within their block and describe the purpose of the setting.

Dot Notation

Throughout this documentation we use dot notation to reference nested arguments.

This notation is used only in the documentation for clarity. In the actual HCL file, arguments are defined within their respective blocks, not as dot-separated keys.

Dot notation examples
api {
  port =          # Referenced as: api.port
  
  secure {
    enable =    # Referenced as: api.secure.enable
  }
}

HCL vs Environment Variables

Environment Variables override any value specified in the HCL configuration when both are present.

tip

Use HCL arguments for persistent, auditable configuration. Reserve environment variables for temporary overrides or sensitive values such as passwords or keys (for example, in containerized deployments).

Time Duration Format and Allowed Units

Several configuration arguments accept time durations, which are specified as a string with:

a decimal number (optionally with a fraction), followed by
a time unit.

The allowed time units are:

ns for nanoseconds
us for microseconds
ms for milliseconds
s for seconds
m for minutes
h for hours

You can also combine multiple number+unit segments in a single value to express more precise durations.

Examples:

"250ms" = 250 milliseconds
"0.5s" = half a second
"30s" = 30 seconds
"2h45m" = 2 hours and 45 minutes

Arguments by Block

This section lists all configurable arguments available in usp-manager.hcl. Arguments are grouped by configuration block. For every argument, the table shows its name, description, type, and default value—helping you quickly understand what it controls and how to set it.

info

All HCL arguments described on this page use dot notation to reference their full path from the root of the configuration file.

auth

The auth block configures JWT-based authentication for the USP Manager Admin UI and REST API.

`auth.access_token.duration`

The validity duration of the access token.

For allowed time units, see Time Duration Format and Allowed Units.

Type: string

Default: "15m"

`auth.key`

Path to the private key in PEM format for API authentication. Must be RSA PEM encoded PKCS1 or PKCS8.

Type: string

Default: n/a

`auth.refresh_token.duration`

The validity duration of the refresh token.

For allowed time units, see Time Duration Format and Allowed Units.

Type: string

Default: "24h"

database

The database block configures the USP Manager database connection and connection pool settings.

`database.dsn`

Data Source Name (DSN) connection string used by USP Manager to connect to its database. If provided, this overrides the individual connection fields.

DSN is not supported in SQLite databases.

Oracle supported formats and examples:

TNS (fill in the database.username and database.password arguments for credentials): (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=hostname)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=service)))
URL: oracle://username:password@hostname:port/service_name
SID: oracle://username:password@hostname:port/?sid=service_name

Microsoft SQL Server formats and examples:

URL: sqlserver://username:password@hostname:port?database=name
ODBC: server=hostname,port;user id=username;password=password;database=name

Type: string

Default: ""

`database.engine`

Database engine used by USP Manager to store configuration and operational data.

Options:

"mssql"
"oracle"
"sqlite" (not recommended for production use)

Type: string

Default: ""

`database.hostname`

Hostname or IP address of the USP Manager database server.

Ignored if database.dsn is provided.

For SQLite, this argument specifies the path to the database file. The path can be absolute or relative to the USP Manager working directory.

Type: string

Default: ""

`database.name`

Name of the USP Manager database.

Ignored if database.dsn is provided.

Type: string

Default: ""

`database.options.connection_idle_time`

Maximum time a connection may remain idle before being closed.

For allowed time units, see Time Duration Format and Allowed Units.

Type: string

Default: "10m"

`database.options.connection_lifetime`

Maximum lifetime of a single database connection before it is recycled.

For allowed time units, see Time Duration Format and Allowed Units.

Type: string

Default: "5m"

`database.options.idle_connections`

Maximum number of idle (unused) connections to keep in the pool.

Type: number

Default: 5

`database.options.max_connections`

Maximum number of open connections that USP Manager can maintain to its database.

Type: number

Default: 25

`database.params`

Additional engine-specific connection parameters for the USP Manager database. Defined as key/value pairs, for example: { "TIMEOUT" = "30", "TRACE FILE" = "trace.log" }.

Type: map[string]string

Default: {}

`database.password`

Password for connecting to the USP Manager database.

Required if database.dsn is not provided, or when the DSN uses an Oracle TNS format without embedded credentials.

Type: string

Default: ""

`database.port`

TCP port of the USP Manager database server.

Ignored if database.dsn is provided.

Type: number

Default: 0

`database.schema`

Schema or service name of the USP Manager database (engine-specific).

Ignored if database.dsn is provided.

Type: string

Default: ""

`database.username`

Username for connecting to the USP Manager database.

Required if database.dsn is not provided, or when the DSN uses an Oracle TNS format without embedded credentials.

Type: string

Default: ""

deprecated_key_janitor

The deprecated_key_janitor block configures a background process that automatically migrates encrypted Records from deprecated DEKs to the active DEK.

For more information, refer to the Record Re-Encryption Mechanisms.

`deprecated_key_janitor.interval`

How often to run a re-encryption cycle.

For allowed time units, see Time Duration Format and Allowed Units.

Type: string

Default: "30m"

`deprecated_key_janitor.limit`

Maximum number of Records to re-encrypt during a single re-encryption cycle.

Type: number

Default: 100

encryption

The encryption block configures the Key Encryption Key (KEK) used by USP Manager to protect sensitive data stored in its database.

`encryption.kek`

Key Encryption Key (KEK) used to encrypt and decrypt Data Encryption Keys (DEKs).

Provide a Base64-encoded value that decodes to exactly 32 bytes (256-bit).

This key secures all DEKs stored in the database and can be rotated using the rotate command.

Type: string

Default: n/a

`encryption.kek_source`

Source of the Key Encryption Key (KEK). This defines how the KEK is obtained.

Currently, only "config" is supported, meaning the KEK must be provided directly in this configuration file (encryption.kek argument).

Type: string

Default: "config"

`encryption.rotation.kek`

New Key Encryption Key (KEK) used to encrypt and decrypt Data Encryption Keys (DEKs).

Provide a Base64-encoded value that decodes to exactly 32 bytes (256-bit).

Leave empty if key rotation is not being performed.

Type: string

Default: ""

`encryption.rotation.kek_source`

Source of the new Key Encryption Key (KEK) to be used during rotation.

Currently, only "config" is supported, meaning the rotated KEK must be provided directly in this configuration file (encryption.rotation.kek argument).

Type: string

Default: "config"

log

The log block configures USP Manager logging output, verbosity level, and log rotation settings.

`log.level`

Controls the verbosity of logs.

Options (every option contains the messages from the ones below it):

TRACE: The most detailed logging level, used to record fine-grained information about internal operations (e.g., database queries).
DEBUG: Detailed internal information for troubleshooting.
INFO: General operational messages.
WARN: Unexpected errors that are not critical.
ERROR: Critical errors.

tip

Use INFO for normal operation and DEBUG when troubleshooting.

Type: string

Default: "INFO"

`log.max_age`

Rotates logs that are older than a specified number of days.

Each Component checks the age of each log file every time a log message is written, and when the configured threshold is reached, it archives the current log as the original log file plus the time at which the log was rotated (name-timestamp.extension).

For example: if manager.log is the original log file and a rotation happens at 3:00pm on May 10th 2025, the archived file would be named: manager-2025-05-10-T15-00-00.000.log.

Type: number

Default: 0 (disabled)

`log.max_backups`

Defines how many rotated log files must be kept. Once the number is exceeded, the older log file gets deleted when a new log rotation takes effect.

Type: number

Default: 0 (disabled)

`log.max_size`

Rotates logs when the log file grows beyond a threshold measured (in MB).

Type: number

Default: 0 (disabled)

`log.path`

The path to the log file. If no value is set, logs are written to standard output.

Type: string

Default: "" (standard output)

server_monitoring_job

The server_monitoring_job block configures how USP Manager monitors registered USP Server instances.

`server_monitoring_job.interval`

How often USP Manager checks the health/status of registered servers.

For allowed time units, see Time Duration Format and Allowed Units.

Type: string

Default: "1m"

Minimum: "10s"

`server_monitoring_job.worker_timeout`

Timeout for an individual server health-check attempt.

For allowed time units, see Time Duration Format and Allowed Units.

Type: string

Default: "15s"

Minimum: "10s"

`server_monitoring_job.workers`

Number of concurrent worker routines used to poll server status.

Type: number

Default: 10

Minimum: 1

web

The web block configures the HTTP/HTTPS server that powers the USP Admin UI and REST API.

`web.cors_allowed_origins`

List of allowed origins for cross-origin resource sharing (CORS) requests to the USP REST API.

The default ["*"] allows requests from any origin; in production, restrict this to trusted domains.

Type: List of strings

Default: ["*"]

Example: ["https://my-company.com"]

`web.host`

Bind address and port where the USP Manager web server listens for incoming connections.

Examples:

"0.0.0.0:8800" (listen on all interfaces).
"127.0.0.1:8800" (allow only local connections).

Type: string

Default: "0.0.0.0:8800"

`web.idle_timeout`

Maximum time that an idle HTTP connection may remain open before being closed by the USP Manager web server.

For allowed time units, see Time Duration Format and Allowed Units.

Type: string

Default: "120s"

`web.rate_limit.global`

Global limit for all endpoints in requests per minute.

Type: number

Default: 5000

`web.read_timeout`

Maximum time that the USP Manager web server waits to read an entire HTTP request.

For allowed time units, see Time Duration Format and Allowed Units.

Type: string

Default: "5s"

`web.shutdown_timeout`

Maximum time allowed for the USP Manager web server to complete in-flight requests before shutting down gracefully.

For allowed time units, see Time Duration Format and Allowed Units.

Type: string

Default: "20s"

`web.tls.cert`

Path to the TLS certificate file (PEM format) used by the USP Manager web server.

Required when web.tls.enable is set to true.

Type: string

Default: ""

`web.tls.enable`

Enables HTTPS for the USP Manager web server.

When set to true, both the Admin UI and REST API will be served over TLS, and web.tls.cert / web.tls.key must be configured.

Type: bool

Default: false

`web.tls.key`

Path to the TLS private key file (PEM format) corresponding to web.tls.cert.

Required when web.tls.enable is set to true.

Type: string

Default: ""

`web.write_timeout`

Maximum time that the USP Manager web server allows for writing an HTTP response.

For allowed time units, see Time Duration Format and Allowed Units.

Type: string

Default: "10s"

What Is HCL?​

Dot Notation​

HCL vs Environment Variables​

Time Duration Format and Allowed Units​

Arguments by Block​

auth​

auth.access_token.duration​

auth.key​

auth.refresh_token.duration​

database​

database.dsn​

database.engine​

database.hostname​

database.name​

database.options.connection_idle_time​

database.options.connection_lifetime​

database.options.idle_connections​

database.options.max_connections​

database.params​

database.password​

database.port​

database.schema​

database.username​

deprecated_key_janitor​

deprecated_key_janitor.interval​

deprecated_key_janitor.limit​

encryption​

encryption.kek​

encryption.kek_source​

encryption.rotation.kek​

encryption.rotation.kek_source​

log​

log.level​

log.max_age​

log.max_backups​

log.max_size​

log.path​

server_monitoring_job​

server_monitoring_job.interval​

server_monitoring_job.worker_timeout​

server_monitoring_job.workers​

web​

web.cors_allowed_origins​

web.host​

web.idle_timeout​

web.rate_limit.global​

web.read_timeout​

web.shutdown_timeout​

web.tls.cert​

web.tls.enable​

web.tls.key​

web.write_timeout​

What Is HCL?

Dot Notation

HCL vs Environment Variables

Time Duration Format and Allowed Units

Arguments by Block

auth

`auth.access_token.duration`

`auth.key`

`auth.refresh_token.duration`

database

`database.dsn`

`database.engine`

`database.hostname`

`database.name`

`database.options.connection_idle_time`

`database.options.connection_lifetime`

`database.options.idle_connections`

`database.options.max_connections`

`database.params`

`database.password`

`database.port`

`database.schema`

`database.username`

deprecated_key_janitor

`deprecated_key_janitor.interval`

`deprecated_key_janitor.limit`

encryption

`encryption.kek`

`encryption.kek_source`

`encryption.rotation.kek`

`encryption.rotation.kek_source`

log

`log.level`

`log.max_age`

`log.max_backups`

`log.max_size`

`log.path`

server_monitoring_job

`server_monitoring_job.interval`

`server_monitoring_job.worker_timeout`

`server_monitoring_job.workers`

web

`web.cors_allowed_origins`

`web.host`

`web.idle_timeout`

`web.rate_limit.global`

`web.read_timeout`

`web.shutdown_timeout`

`web.tls.cert`

`web.tls.enable`

`web.tls.key`

`web.write_timeout`