Skip to main content
Version: 3.3

USP Server Configuration File

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

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

# Linux
/opt/udmg/etc/usp-server.hcl
# Windows
C:\Program Files\Stonebranch\USP Server\usp-server.hcl

What is HCL?​

The USP Server 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-server.hcl. Arguments are grouped by configuration block (including the root level). 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.

Root Level​

Defines the top-level attributes of the USP Server.

name​

Name of the Proxy Server instance.

Type: string

Default: N/A

connection​

The connection block configures USP Server connection settings.

connection.idle_timeout​

IDLE timeout for inbound connections. Set to 0 to disable.

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

Type: string

Default: "60s"

connection.max_connections​

Maximum number of concurrent connections allowed across all listeners. Set to 0 to disable.

Type: number

Default: 0

icap​

The icap block configures global parameters for the Internet Content Adaptation Protocol (ICAP) integration.

icap.timeout​

Defines how long the USP Server will wait for a response from the ICAP server during scan operations.

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

Type: string

Default: "30s"

log​

The log block configures USP Server 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)

web​

Configures the embedded HTTP(S) services used by USP Server for:

  • Configuration updates (the control plane endpoint that USP Manager uses to configure and monitor the Proxy Server), and
  • Operational endpoints (health check and metrics).

web.api_host​

IP address and port where the Proxy Server exposes health check and metrics endpoints.

Type: string

Default: "0.0.0.0:8901"

web.config_host​

IP address and port (management port) where the Proxy Server listens for configuration requests from the USP Manager.

Type: string

Default: "0.0.0.0:8900"

web.cors_allowed_origins​

Allowed origins for CORS.

Type: List of strings

Default: ["*"]

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

web.idle_timeout​

Web idle timeout.

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​

Web read timeout.

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

Type: string

Default: "5s"

web.shutdown_timeout​

Web shutdown timeout.

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

Type: string

Default: "20s"

web.tls.ca​

Path to the USP Server's TLS CA(s) for mTLS config API authentication.

Type: string

Default: N/A

web.tls.cert​

Path to the USP Server's TLS Certificate for mTLS config API authentication.

Type: string

Default: N/A

web.tls.key​

Path to the USP Server's TLS Private Key for mTLS config API authentication.

Type: string

Default: N/A

web.write_timeout​

Web write timeout.

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

Type: string

Default: "10s"