Skip to main content

USP Manager Configuration File

The USP Manager configuration file, located at /opt/udmg/etc/usp-manager.hcl, defines how the USP Manager service operates.

USP Manager is the component responsible for providing the USP Admin UI and USP REST API, managing USP Server instances, and pushing configuration updates.

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
  }
}

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.

encryption​

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

HCL Argument NameDescriptionValue TypeDefault Value
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).

string"config"
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.

string
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).

string"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.

string""

database​

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

HCL Argument NameDescriptionValue TypeDefault Value
database.engine

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

Options:

  • "oracle"
  • "sqlite" (not recommended for production use)
string""
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.

Oracle supported formats and examples:

  • TNS (fill in the database.username and database.password parameters 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

SQLite supported formats and examples:

  • Simple path: /path/to/database.db
  • File URI: file:/path/to/database.db
  • File URI with parameters: file:/path/to/database.db?_pragma=foreign_keys(ON)&_pragma=journal_mode(WAL)
string""
database.hostname

Hostname or IP address of the USP Manager database server.

Ignored if database.dsn is provided.

string""
database.port

TCP port of the USP Manager database server.

Ignored if database.dsn is provided.

number0
database.name

Name of the USP Manager database.

Ignored if database.dsn is provided.

For SQLite, this is the file name of the database.

string""
database.schema

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

Ignored if database.dsn is provided.

string""
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.

string""
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.

string""
database.options.max_connections

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

number25
database.options.idle_connections

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

number5
database.options.connection_lifetime

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

Allowed time units:

  • ms for milliseconds (e.g., "500ms")
  • s for seconds (e.g., "30s")
  • m for minutes (e.g., "5m")
  • h for hours (e.g., "1h")
string"5m"
database.options.connection_idle_time

Maximum time a connection may remain idle before being closed.

Allowed time units:

  • ms for milliseconds (e.g., "500ms")
  • s for seconds (e.g., "30s")
  • m for minutes (e.g., "5m")
  • h for hours (e.g., "1h")
string"10m"
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" }.

map[string]string{}

web​

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

HCL Argument NameDescriptionValue TypeDefault Value
web.read_timeout

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

Allowed time units:

  • ms for milliseconds (e.g., "750ms")
  • s for seconds (e.g., "30s")
  • m for minutes (e.g., "2m")
  • h for hours (e.g., "1h")
string"5s"
web.write_timeout

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

Allowed time units:

  • ms for milliseconds (e.g., "750ms")
  • s for seconds (e.g., "30s")
  • m for minutes (e.g., "2m")
  • h for hours (e.g., "1h")
string"10s"
web.idle_timeout

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

Allowed time units:

  • ms for milliseconds (e.g., "750ms")
  • s for seconds (e.g., "30s")
  • m for minutes (e.g., "2m")
  • h for hours (e.g., "1h")
string"120s"
web.shutdown_timeout

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

Allowed time units:

  • ms for milliseconds (e.g., "750ms")
  • s for seconds (e.g., "30s")
  • m for minutes (e.g., "2m")
  • h for hours (e.g., "1h")
string"20s"
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.

[]string["*"]
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).
string"0.0.0.0:8800"
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.

boolfalse
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.

string""
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.

string""
web.ui.system_identifier

Optional short label displayed in the header of the USP Manager Admin UI (for example, to indicate environment or region).

string""
web.ui.banner_logo

Path to a custom logo image file displayed in the banner of the USP Manager Admin UI. Relative paths are resolved from the USP Manager working directory.

string""

auth​

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

HCL Argument NameDescriptionValue TypeDefault Value
auth.keyPath to the private key in PEM format for API authentication. Must be RSA PEM encoded PKCS1 or PKCS8.string
auth.access_token.durationstring"15m"
auth.refresh_token.durationstring"24h"

deprecated_key_janitor​

The deprecated_key_janitor block configures how USP Manager handles KEK rotation. Background process that looks for stored secrets still encrypted with a now deprecated key

HCL Argument NameDescriptionValue TypeDefault Value
deprecated_key_janitor.intervalHow often to run a re-encryption cycle.string"1m"
deprecated_key_janitor.limitMaximum number of records to process per rotation cycle.number"100"

server_monitoring_job​

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

HCL Argument NameDescriptionValue TypeDefault Value
server_monitoring_job.interval

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

Allowed time units:

  • ms for milliseconds (e.g., "750ms")
  • s for seconds (e.g., "30s")
  • m for minutes (e.g., "1m")
  • h for hours (e.g., "1h")
string"1m"
server_monitoring_job.workersNumber of concurrent worker routines used to poll server status.number10
server_monitoring_job.worker_timeout

Timeout for an individual server health-check attempt.

Allowed time units:

  • ms for milliseconds (e.g., "750ms")
  • s for seconds (e.g., "15s")
  • m for minutes (e.g., "1m")
  • h for hours (e.g., "1h")
string"15s"

log​

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

HCL Argument NameDescriptionValue TypeDefault Value
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.

string"INFO"
log.pathThe path to the log file. If no value is set, logs are written to standard output.string"" (standard output)
log.max_size

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

number0 (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.

number0 (disabled)
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.

number0 (disabled)