Version: 3.3

Configuration File

The Configuration File is the central setup point for UDMG. While Endpoints, Pipelines, and other Configuration Items are managed through the UDMG Admin UI or UDMG REST API, most global and system-level settings are defined here.

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

Linux
Windows

/opt/udmg/etc/udmg-server.hcl

C:\Program Files\Stonebranch\UDMG Server\udmg-server.hcl

This file uses HCL (HashiCorp Configuration Language) to express structured configuration in a clear, declarative format.

UDMG also supports a set of custom functions (not part of standard HCL) for dynamic values (see Custom Functions below).

What Is HCL?

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

Value Types

Each argument accepts one of the following types of value:

Type	Description	Example
`string`	Text enclosed in double quotes. Single quotes are not supported.	`"my-instance"`
`number`	A whole or decimal number, written without quotes.	`5000`
`bool`	Either `true` or `false`, written without quotes.	`true`
List of strings	A comma-separated list of double-quoted strings, enclosed in square brackets.	`["node1.my-company.com:7946", "node2.my-company.com:7946"]`

HCL vs Environment Variables

Environment Variables override any value specified in the HCL configuration when both are present. For instructions on setting them on a Linux host or on a Windows host, refer to Setting Environment Variables.

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

Directory Paths

When specifying directory paths in the Configuration File, follow these guidelines for clarity and predictable behavior.

Absolute Over Relative Paths

All path arguments in the Configuration File support both absolute and relative paths:

Absolute paths start at the filesystem root and are independent of the work_directory_path value.
Relative paths are resolved against the work_directory_path value.

tip

For predictability and separation of concerns, we recommend using absolute paths for credential files and store those in a directory isolated from transfer data.

Platform-Specific Separators

Use the appropriate path separator for your operating system:

Linux: use forward slashes (/).
- Example: /var/udmg/data/
Windows: use backslashes (\\). Because HCL strings interpret \\ as an escape, write Windows paths with doubled backslashes in the HCL file.
- Example: C:\\Program Files\\Stonebranch\\UDMG Server\\data\\.

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

Custom Functions

The configuration loader in UDMG provides a set of custom functions (these are not part of standard HCL syntax). You can use them to dynamically generate values inside the Configuration File.

Function	Description	Usage	Result
`upper`	Converts a string to upper case.	`${upper("string")}`	`"STRING"`
`lower`	Converts a string to lower case.	`${lower("STRING")}`	`"string"`
`env`	Retrieves an environment variable, with a mandatory fallback default.	`${env("HOSTNAME", "default")}`	`"my-hostname"` or `"default"` if unset

For the env function, a default value is mandatory. If the referenced environment variable does not exist, UDMG uses the provided default instead of throwing an error.

Example of env function usage
database {
  engine   = "postgres"
  hostname = "localhost"
  user     = "udmg"
  password = "${env("DB_PASSWORD", "default-password")}"
}

Arguments by Block

This section lists all configurable arguments available in udmg-server.hcl. Arguments are grouped by configuration block (including the root level). For every argument, the documentation lists its description, type, and default value, which helps 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

Top-level arguments define global behavior for the UDMG Server. These settings apply across all domains and act as defaults for path resolution and runtime behavior.

`auto_migrate`

When enabled, UDMG automatically applies any required database schema migrations during startup. This is typically needed when upgrading to a more recent UDMG version.

Type: bool

Default: true

Environment Variable: UDMG_DATABASE_AUTO_MIGRATE

`instance_name`

Name of the UDMG Server instance used in observability metrics and logs. In High-Availability deployments, set a unique value per Cluster Node so telemetry can be attributed correctly.

Type: string

Default: "udmg-server"

Environment Variable: UDMG_INSTANCE_NAME

`work_directory_path`

Root directory for relative paths used in configuration and MFT services, including Endpoints and Pipelines.

warning

This is a major configuration argument. Before setting it, see Folder Management.

Type: string

Default: ""

Environment Variable: UDMG_WORK_DIRECTORY_PATH

admin_app

The admin_app block enables or disables the embedded web server that hosts the UDMG Admin UI.

`admin_app.enable`

Enables or disables the embedded web server for the UDMG Admin UI.

Type: bool

Default: true

Environment Variable: UDMG_ADMIN_APP_ENABLE

api

The api block configures the main UDMG Server API, including network binding, security features, CORS settings, logging, and rate limiting.

`api.cors`

Enables or disables Cross-Origin Resource Sharing headers.

info

Required if accessing the API from a web frontend hosted on a different domain/port.

Type: bool

Default: true

Environment Variable: UDMG_API_CORS_ENABLE

`api.cors_domain`

Specifies the allowed origin domain(s) for CORS requests when api.cors is enabled. Use "*" for any domain (less secure).

Type: string

Default: "*"

Environment Variable: UDMG_API_CORS_DOMAIN

`api.csrf`

Enables or disables Cross-Site Request Forgery protection middleware. Required by the UDMG Admin UI.

Type: bool

Default: true

Environment Variable: UDMG_API_CSRF_ENABLE

`api.inet`

IP address to bind for UDMG REST API connection requests. 0.0.0.0 listens on all available network interfaces.

Type: string

Default: "0.0.0.0"

Environment Variable: UDMG_API_LISTEN_INET

`api.log_level`

Log level for UDMG REST API operations.

Options:

"" (inherits from global logger)
"debug"
"info"
"warn"
"error"

Type: string

Default: ""

Environment Variable: UDMG_API_LOG_LEVEL

`api.port`

The port number the API server listens on.

Type: string

Default: "8080"

Environment Variable: UDMG_API_LISTEN_PORT

`api.rate_limit`

Global rate limiting for all UDMG REST API requests per minute.

Type: number

Default: 5000

Environment Variable: UDMG_API_RATE_LIMIT

`api.secure.enable`

Enables or disables HTTPS for the API server.

info

If enabled, api.secure.pub_key and api.secure.priv_key are required.

Type: bool

Default: false

Environment Variable: UDMG_API_SECURE

`api.secure.priv_key`

Path to the private SSL/TLS key file (PEM format).

This key must match the certificate configured in api.secure.pub_key. UDMG Server uses it during the TLS handshake to establish HTTPS connections.

Example:

-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----

info

The path is relative to the work_directory_path unless an absolute path is provided. For more details, see Absolute Over Relative Paths.

Type: string

Default: ""

Environment Variable: UDMG_API_PRIV_KEY

`api.secure.pub_key`

Path to the SSL/TLS certificate file (PEM format).

This certificate must match the private key configured in api.secure.priv_key. UDMG Server presents it to clients during the TLS handshake to establish HTTPS connections.

Example:

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

info

The path is relative to the work_directory_path unless an absolute path is provided. For more details, see Absolute Over Relative Paths.

Type: string

Default: ""

Environment Variable: UDMG_API_PUB_KEY

`api.spec`

Enables or disables serving the OpenAPI specification (at /spec and /swagger/index.html).

Type: bool

Default: false

Environment Variable: UDMG_API_SPEC_ENABLE

`api.trusted_domains`

List of UDMG Admin UI origin hostnames accepted as trusted sources. Only required when using an external web server for the Admin UI. Values must match the HTTP Origin request header.

Examples:

Default HTTPS port: ["udmg.my-company.com"]
Custom port: ["udmg-staging.my-company.com:9180"]
Multiple trusted origins: ["udmg.my-company.com", "udmg-staging.my-company.com:9180"]

Type: List of strings

Default: []

Environment Variable: UDMG_API_TRUSTED_DOMAINS

`api.verbose`

Adds an error field to API error log messages containing the raw error from the failing operation (for example, a database query error, an authentication provider error, or an input validation error). Useful during initial environment setup to diagnose configuration issues.

Type: bool

Default: false

Environment Variable: UDMG_API_VERBOSE

as2

The as2 block configures AS2 protocol support. AS2 is used for secure and reliable file transfer over HTTP or HTTPS.

For more information, refer to AS2.

`as2.enable`

Enables or disables the AS2 service.

Type: bool

Default: true

Environment Variable: UDMG_AS2_ENABLE

`as2.message_id_expiry`

Number of days to retain AS2 message IDs for replay protection.

Type: number

Default: 0 (unlimited)

Environment Variable: UDMG_AS2_MESSAGE_ID_EXPIRY

`as2.replay_protect`

Enables or disables replay protection for AS2 messages.

Type: bool

Default: true

Environment Variable: UDMG_AS2_REPLAY_PROTECT

cluster

The cluster block configures high-availability clustering for multiple UDMG Server nodes, including operating mode, node health timing, peer discovery, and cluster communication ports.

For more information, refer to High Availability.

`cluster.client_port`

Port used by UDMG Server for client communication in a cluster.

Type: number

Default: 4222

Environment Variable: UDMG_CLUSTER_CLIENT_PORT

`cluster.cluster_port`

Port used for inter-node communication within the UDMG Server cluster.

Type: number

Default: 6222

Environment Variable: UDMG_CLUSTER_CLUSTER_PORT

`cluster.deadline`

The time duration after which a node is considered down if no heartbeat is received.

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

Type: string

Default: "30s"

Environment Variable: UDMG_CLUSTER_DEADLINE

`cluster.heartbeat`

The time interval between heartbeat signals sent between nodes.

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

Type: string

Default: "10s"

Environment Variable: UDMG_CLUSTER_HEARTBEAT

`cluster.mode`

The operational mode of the cluster.

Allowed values:

"AA" (Active-Active).
"AP" (Active-Passive).

Type: string

Default: "AA"

Environment Variable: UDMG_CLUSTER_MODE

`cluster.seeds`

Comma-separated list of seed node addresses in the format host:client_port, used for cluster bootstrapping. Not required for standard setup.

Type: string

Default: ""

Environment Variable: UDMG_CLUSTER_NODE_SEEDS

database

The database block configures the database connection used by UDMG Server for persistent storage of configuration, Users, and Transfer Records.

`database.dsn`

Connection string override.

When set, overrides database.name, database.hostname, and database.port, and invalidates the database.secure block.

Type: string

Default: n/a

Environment Variable: UDMG_DATABASE_DSN

`database.engine`

The type of database engine to use.

Options:

"mysql"
"oracle"
"mssql"
"postgres"

Type: string

Default: ""

Environment Variable: UDMG_DATABASE_ENGINE

`database.hostname`

The hostname or IP address of the database server.

Type: string

Default: ""

Environment Variable: UDMG_DATABASE_HOSTNAME

`database.log_level`

Log level for database operations.

Options:

"" (inherits from global logger)
"debug"
"info"
"warn"
"error"

Type: string

Default: ""

Environment Variable: UDMG_DATABASE_LOG_LEVEL

`database.name`

The database name.

Type: string

Default: ""

Environment Variable: UDMG_DATABASE_NAME

`database.options.idle_connections`

The maximum number of connections in the idle connection pool.

Type: number

Default: 5

Environment Variable: UDMG_DATABASE_IDLE_CONNECTIONS

`database.options.initial_interval`

The initial time duration to wait before retrying a locked operation.

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

Type: string

Default: "50ms"

Environment Variable: UDMG_DATABASE_INITIAL_INTERVAL

`database.options.max_connections`

The maximum number of open connections to the database.

Type: number

Default: 30

Environment Variable: UDMG_DATABASE_MAX_CONNECTIONS

`database.options.max_interval`

The maximum time duration to wait between retries for a locked operation.

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

Type: string

Default: "1s"

Environment Variable: UDMG_DATABASE_MAX_INTERVAL

`database.options.max_retries`

The maximum number of times to retry an operation if the database is locked.

Type: number

Default: 5

Environment Variable: UDMG_DATABASE_MAX_RETRIES

`database.password`

The password for connecting to the database.

Type: string

Default: ""

Environment Variable: UDMG_DATABASE_PASSWORD

`database.port`

The port number for the database server.

Type: number

Default: 0

Environment Variable: UDMG_DATABASE_PORT

`database.secure.enable`

Enables or disables secure (TLS/SSL) connection to the database.

Type: bool

Default: false

Environment Variable: UDMG_DATABASE_SECURE_ENABLE

`database.secure.mode`

The SSL mode to use. Availability depends on database engine.

Allowed values:

"disable"
"require"
"verify-ca"
"verify-full"

info

Refer to PostgreSQL docs for details.

Type: string

Default: "require"

Environment Variable: UDMG_DATABASE_SECURE_MODE

`database.secure.priv_key`

Path to the client private key file (used for client certificate authentication, if database.secure.enable is true).

info

The path is relative to the work_directory_path unless an absolute path is provided. For more details, see Absolute Over Relative Paths.

Type: string

Default: ""

Environment Variable: UDMG_DATABASE_PRIV_KEY

`database.secure.pub_key`

Path to certificate in PEM format for client authentication (required if enabled).

info

The path is relative to the work_directory_path unless an absolute path is provided. For more details, see Absolute Over Relative Paths.

Type: string

Default: ""

Environment Variable: UDMG_DATABASE_PUB_KEY

`database.secure.tls_server_cert_dn`

Optional server certificate distinguished name used for verify-full mode (Oracle only).

Type: string

Default: ""

Environment Variable: UDMG_DATABASE_TLS_SERVER_CERT_DN

`database.secure.wallet_location`

Path to Oracle wallet directory. Required if database.engine is "oracle" and database.secure.mode is "verify-ca" or "verify-full".

Type: string

Default: ""

Environment Variable: UDMG_DATABASE_WALLET_LOCATION

`database.user`

The username for connecting to the database.

Type: string

Default: ""

Environment Variable: UDMG_DATABASE_USER

hook_server

The hook_server block configures the HTTP server that handles callbacks such as AS2 Message Disposition Notifications (MDNs), enabling asynchronous receipt confirmations for file transfers.

`hook_server.enable`

Enables or disables the hook server.

Type: bool

Default: false

Environment Variable: UDMG_HOOK_SERVER_ENABLE

`hook_server.enable_mdn`

Enables or disables the hook server for AS2 MDN callbacks.

Type: bool

Default: false

Environment Variable: UDMG_HOOK_SERVER_ENABLE_MDN

`hook_server.inet`

Interface address for hook server to listen on.

Type: string

Default: "0.0.0.0"

Environment Variable: UDMG_HOOK_SERVER_INET

`hook_server.log_level`

Log level for hook server operations.

Options:

"" (inherits from global logger)
"debug"
"info"
"warn"
"error"

Type: string

Default: ""

Environment Variable: UDMG_HOOK_SERVER_LOG_LEVEL

`hook_server.port`

Port for the hook server.

Type: string

Default: "9090"

Environment Variable: UDMG_HOOK_SERVER_PORT

`hook_server.secure.enable`

Enables or disables HTTPS. Requires hook_server.secure.pub_key and hook_server.secure.priv_key.

Type: bool

Default: false

Environment Variable: UDMG_HOOK_SERVER_SECURE_ENABLE

`hook_server.secure.priv_key`

Path to private SSL/TLS key file in PEM format. Required if hook_server.secure.enable is true.

info

The path is relative to the work_directory_path unless an absolute path is provided. For more details, see Absolute Over Relative Paths.

Type: string

Default: ""

Environment Variable: UDMG_HOOK_SERVER_PRIV_KEY_PATH

`hook_server.secure.pub_key`

Path to public SSL/TLS certificate file in PEM format. Required if hook_server.secure.enable is true.

info

The path is relative to the work_directory_path unless an absolute path is provided. For more details, see Absolute Over Relative Paths.

Type: string

Default: ""

Environment Variable: UDMG_HOOK_SERVER_PUB_KEY_PATH

`hook_server.spec`

Enables or disables serving the API specification.

Type: bool

Default: false

Environment Variable: UDMG_HOOK_SERVER_SPEC

icap

The icap block configures general content scanning through an ICAP server. For more information, refer to ICAP Scanner.

`icap.retry`

Number of retry attempts when connecting to or communicating with the ICAP server fails.

Type: number

Default: 0

Environment Variable: UDMG_ICAP_RETRY

`icap.timeout`

The maximum time duration to wait for a response from the ICAP server.

If you plan to scan large files, you may need to increase this value to give the ICAP server enough time to respond. Be aware that if this timeout exceeds the connected client's own timeout, the client may disconnect before the scan completes. If you increase this value, coordinate with your partners, as they may need to increase their client-side timeouts accordingly.

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

Type: string

Default: "10s"

Environment Variable: UDMG_ICAP_TIMEOUT

jwt

The jwt block configures token-based authentication for the UDMG Admin UI, UDMG REST API, and WTC UI.

tip

Use strong, unique keys and tune durations to balance security and usability.

`jwt.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"

Environment Variable: UDMG_JWT_ACCESS_TOKEN_DURATION

`jwt.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"

Environment Variable: UDMG_JWT_REFRESH_TOKEN_DURATION

`jwt.signing_key`

Secret key for signing both access and refresh tokens. Must be at least 30 \[a-zA-Z0-9_] characters.

Type: string

Default: ""

Environment Variable: UDMG_JWT_SIGNING_KEY

ldap

The ldap block defines LDAP synchronization intervals for Users and Accounts. For more information, refer to LDAP for Users and LDAP for Accounts.

`ldap.ldap_account_sync_interval`

Defines how often UDMG synchronizes LDAP-provisioned Accounts. Leave empty ("") to disable synchronization.

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

Type: string

Default: "24h"

Environment Variable: UDMG_LDAP_ACCOUNT_SYNC_INTERVAL

`ldap.ldap_user_sync_interval`

Defines how often UDMG synchronizes LDAP-provisioned Users. Leave empty ("") to disable synchronization.

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

Type: string

Default: "24h"

Environment Variable: UDMG_LDAP_USER_SYNC_INTERVAL

log

The log block controls logging behavior for the UDMG Server instance, including log level, format, output destination, and rotation settings. For more information, refer to Logging.

`log.file`

Log file path. Supports environment variable expansion.

Type: string

Default: "" (stdout)

Environment Variable: UDMG_LOG_FILE

`log.format`

Format of the log output.

Options:

"plain"
"json"

Type: string

Default: "plain"

Environment Variable: UDMG_LOG_FORMAT

`log.level`

Log verbosity level. Messages at the specified severity level and higher are written to the log.

Options:

"TRACE"
"DEBUG"
"INFO"
"WARN"
"ERROR"

Type: string

Default: "INFO"

Environment Variable: UDMG_LOG_LEVEL

`log.rotate.enable`

When enabled, log files are rotated based on the configured log.rotate.frequency. If log.rotate.size is greater than 0, log files are also rotated when the configured size is reached.

Type: bool

Default: false

Environment Variable: UDMG_LOG_ROTATE

`log.rotate.file_format`

Format for rotated log filenames. It can include directory structure and the following placeholders:

{YYYY} (year)
{MM} (month)
{DD} (day)
{HH} (hour)
{mm} (minute)
{ss} (second)
{ns} (nanosecond)

info

The path is relative to the work_directory_path unless an absolute path is provided. For more details, see Absolute Over Relative Paths.

Type: string

Default: "{YYYY}{MM}{DD}/udmg-server{HH}{mm}{ss}{ns}.log"

Environment Variable: UDMG_LOG_ROTATE_FORMAT

`log.rotate.frequency`

Time interval used for time-based log rotation.

Options:

"daily"
"weekly"
"monthly"
"quarterly"

Type: string

Default: "daily"

Environment Variable: UDMG_LOG_ROTATE_FREQUENCY

`log.rotate.size`

Maximum log file size (in megabytes) before rotation is triggered. Checked every hour.

Type: number

Default: 0 (disabled)

Environment Variable: UDMG_LOG_ROTATE_SIZE

observability

The observability block configures experimental features for metrics, tracing, debugging, and the observability API. Use it to integrate UDMG Server with monitoring stacks and to expose a separate, minimal API for status and metrics collection.

`observability.api.debug.enable`

Enables or disables debug mode for the observability API.

Type: bool

Default: false

Environment Variable: UDMG_OBSERVABILITY_DEBUG_ENABLE

`observability.api.debug.password`

Debug password for observability API.

Type: string

Default: ""

Environment Variable: UDMG_OBSERVABILITY_DEBUG_PASSWORD

`observability.api.debug.user`

Debug username for observability API.

Type: string

Default: ""

Environment Variable: UDMG_OBSERVABILITY_DEBUG_USER

`observability.api.enable`

Enables or disables the observability API.

Type: bool

Default: false

Environment Variable: UDMG_OBSERVABILITY_API_ENABLE

`observability.api.inet`

Address for the observability API.

Type: string

Default: "0.0.0.0"

Environment Variable: UDMG_OBSERVABILITY_API_LISTEN_INET

`observability.api.log_level`

Log level for observability API operations.

Options:

"" (inherits from global logger)
"debug"
"info"
"warn"
"error"

Type: string

Default: ""

Environment Variable: UDMG_OBSERVABILITY_API_LOG_LEVEL

`observability.api.port`

Port for the observability API.

Type: string

Default: "7070"

Environment Variable: UDMG_OBSERVABILITY_API_LISTEN_PORT

`observability.api.rate_limit`

Global rate limiting for observability API requests per minute.

Type: number

Default: 5000

Environment Variable: UDMG_OBSERVABILITY_API_RATE_LIMIT

`observability.api.secure.enable`

Enables or disables HTTPS for the observability API. Requires observability.api.secure.pub_key and observability.api.secure.priv_key.

Type: bool

Default: false

Environment Variable: UDMG_OBSERVABILITY_API_SECURE

`observability.api.secure.priv_key`

Path to private SSL/TLS key file in PEM format. Required if observability.api.secure.enable is true.

info

The path is relative to the work_directory_path unless an absolute path is provided. For more details, see Absolute Over Relative Paths.

Type: string

Default: ""

Environment Variable: UDMG_OBSERVABILITY_API_SECURE_PRIV_KEY

`observability.api.secure.pub_key`

Path to public SSL/TLS certificate file in PEM format. Required if observability.api.secure.enable is true.

info

The path is relative to the work_directory_path unless an absolute path is provided. For more details, see Absolute Over Relative Paths.

Type: string

Default: ""

Environment Variable: UDMG_OBSERVABILITY_API_SECURE_PUB_KEY

`observability.api.spec`

Enables or disables serving the observability OpenAPI specification (at /spec and /swagger/index.html, at the port defined in observability.api.port).

Type: bool

Default: false

Environment Variable: UDMG_OBSERVABILITY_API_SPEC

`observability.opentelemetry.enable`

Enables or disables OpenTelemetry.

Type: bool

Default: false

Environment Variable: UDMG_OPENTELEMETRY_ENABLE

`observability.opentelemetry.host`

Host for OpenTelemetry collector.

Type: string

Default: ""

Environment Variable: UDMG_OPENTELEMETRY_HOST

`observability.opentelemetry.port`

Port for OpenTelemetry collector.

Type: string

Default: ""

Environment Variable: UDMG_OPENTELEMETRY_PORT

`observability.prometheus.enable`

Enables or disables Prometheus metrics.

Type: bool

Default: false

Environment Variable: UDMG_PROMETHEUS_ENABLE

protocol

The protocol block defines default settings for supported transfer protocol services, including authentication timeout, session idle timeout, and connection limits.

`protocol.auth_timeout`

Authentication timeout before dropping the connection.

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

Type: string

Default: "30s"

Environment Variable: UDMG_PROTOCOL_AUTH_TIMEOUT

`protocol.cloud_stream_buffer_size`

An optional Remote Cloud Storage streaming buffer size (in bytes).

Type: number

Default: 16777216

Environment Variable: n/a

`protocol.max_connections`

Maximum number of concurrent connections.

Type: number

Default: 120

Environment Variable: UDMG_PROTOCOL_MAX_CONNECTIONS

`protocol.session_idle_timeout`

Defines how long an authenticated protocol session may remain open with no activity before UDMG automatically terminates it.

For more information, refer to Timeout for Idle Sessions.

For the timeout that governs unauthenticated connection attempts, see protocol.auth_timeout.

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

Type: string

Default: "15m"

Environment Variable: UDMG_PROTOCOL_SESSION_IDLE_TIMEOUT

security

The security block configures system-wide security settings, including secret encryption, path resolution behavior, file permissions, and recovery options.

`security.directory_permissions`

Permissions for created folders, specified as a standard Linux file mode.

Type: string

Default: "700"

Environment Variable: UDMG_SECURITY_DIRECTORY_PERMISSIONS

`security.domain_chroot`

Defines the path resolution behavior for Local Filesystem Endpoints.

Allowed values:

"NONE"
"WORKDIR"
"WORKDIR+DOMAIN"

warning

This is a major configuration argument. Before setting this up, we recommend reading Folder Management.

Type: string

Default: "WORKDIR+DOMAIN"

Environment Variable: UDMG_SECURITY_DOMAIN_CHROOT

`security.file_permissions`

Permissions for created files, specified as a standard Linux file mode.

Type: string

Default: "600"

Environment Variable: UDMG_SECURITY_FILE_PERMISSIONS

`security.ignore_system_user_ip_filter`

Bypasses the IP Filtering - Admin UI restriction. Use this option only to recover from an accidental lockout.

Type: bool

Default: false

Environment Variable: UDMG_SECURITY_IGNORE_SYSTEM_USER_IP_FILTER

`security.passphrase_key`

Root encryption key (K0) used to encrypt secret values, such as passwords and Private Key Credentials. Must be a valid 32-byte hexadecimal string. Store securely and back up for disaster recovery.

Type: string

Default: ""

Environment Variable: UDMG_SECURITY_PASSPHRASE_KEY

`security.password.min_length`

Deprecated since UDMG 3.3.0. This configuration argument remains in the default HCL file for backward compatibility. For the current Password Policy configuration, see Password Policy.

Environment Variable: UDMG_SECURITY_PASSWORD_POLICY_MIN_LEN (deprecated)

`security.password.min_lower_case`

Deprecated since UDMG 3.3.0. This configuration argument remains in the default HCL file for backward compatibility. For the current Password Policy configuration, see Password Policy.

Environment Variable: UDMG_SECURITY_PASSWORD_POLICY_MIN_LOWER (deprecated)

`security.password.min_numbers`

Deprecated since UDMG 3.3.0. This configuration argument remains in the default HCL file for backward compatibility. For the current Password Policy configuration, see Password Policy.

Environment Variable: UDMG_SECURITY_PASSWORD_POLICY_MIN_NUMBERS (deprecated)

`security.password.min_symbols`

Deprecated since UDMG 3.3.0. This configuration argument remains in the default HCL file for backward compatibility. For the current Password Policy configuration, see Password Policy.

Environment Variable: UDMG_SECURITY_PASSWORD_POLICY_MIN_SYMBOLS (deprecated)

`security.password.min_upper_case`

Deprecated since UDMG 3.3.0. This configuration argument remains in the default HCL file for backward compatibility. For the current Password Policy configuration, see Password Policy.

Environment Variable: UDMG_SECURITY_PASSWORD_POLICY_MIN_UPPER (deprecated)

`security.work_directory_key_display`

If enabled, the work_directory_path is exposed under the UDMG REST API.

Type: bool

Default: false

Environment Variable: UDMG_SECURITY_WORK_DIRECTORY_KEY_DISPLAY

tls

The tls block applies to all services (API, Observability, WTC, HookServer, AS2, etc.). Only FTP can override these global TLS settings, using tls.allow_protocol_override.ftp.

`tls.allow_protocol_override.ftp`

Allows FTP to override TLS settings.

Type: bool

Default: false

Environment Variable: n/a

`tls.cipher_suites`

Optional list of cipher suites to use. Leave empty for secure defaults. If not specified, uses secure cipher suites recommended by Go crypto/tls providing forward secrecy and modern cryptographic standards.

Type: List of strings

Default: []

Example: ["TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256", "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384"]

Environment Variable: n/a

`tls.curve_preferences`

Optional list of curve preferences. Leave empty for secure defaults.

Options:

"CurveP256"
"CurveP384"
"CurveP521"
"X25519"
"X25519MLKEM768"

Type: List of strings

Default: ["X25519", "CurveP256", "CurveP384"]

Environment Variable: n/a

`tls.max_version`

Maximum TLS version to support.

Options:

1.0
1.1
1.2
1.3 (recommended)

Type: string

Default: "1.3"

Environment Variable: n/a

`tls.min_version`

Minimum TLS version to support.

Options:

1.0
1.1
1.2 (recommended)
1.3

Type: string

Default: "1.2"

Environment Variable: n/a

transfer

The transfer block configures file transfer retry behavior and status checking intervals. These settings apply only when UDMG acts as a Client.

`transfer.check_interval`

Interval at which UDMG polls for pending transfers that were scheduled through the Transfers Schedules Endpoint.

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

Type: string

Default: "1m"

Environment Variable: UDMG_TRANSFER_CHECK_INTERVAL

`transfer.max_retries`

The maximum number of times a transfer will be retried after a connection or transfer error. Each retry restarts the transfer from the beginning. Once this limit is reached, the transfer is marked as failed.

Type: number

Default: 3

Environment Variable: UDMG_TRANSFER_MAX_RETRIES

`transfer.max_retry_delay`

The maximum wait time allowed between retries after a connection or transfer error. Each retry restarts the transfer from the beginning. This value acts as an upper limit when exponential backoff is applied.

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

Type: string

Default: "1h"

Environment Variable: UDMG_TRANSFER_MAX_RETRY_DELAY

`transfer.retry_backoff`

The exponential backoff factor applied to the retry delay. After each failed attempt, the wait time is multiplied by this factor, up to the limit set by transfer.max_retry_delay. Each retry restarts the transfer from the beginning.

Delay for retry attempt n = retry_delay x (retry_backoff ^ n), where n is the retry attempt number, starting at 0.

Example with retry_delay = 5m:

retry_backoff = 1 → 5m, 5m, 5m, ...
retry_backoff = 2 → 5m, 10m, 20m, ...
retry_backoff = 3 → 5m, 15m, 45m, 135m, ...

Type: number

Default: 2.0

Environment Variable: UDMG_TRANSFER_RETRY_BACKOFF

`transfer.retry_delay`

The base wait time before retrying a transfer after a connection or transfer error. Each retry restarts the transfer from the beginning.

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

Type: string

Default: "5m"

Environment Variable: UDMG_TRANSFER_RETRY_DELAY

uac

The uac block configures publishing Universal Events from UDMG to Universal Controller. For more information, refer to Universal Event Publishing.

`uac.enable`

Enables or disables globally the feature to publish Universal Event.

Type: bool

Default: false

Environment Variable: UDMG_UAC_REST_ENABLE

`uac.event_name`

The default Universal Event Template name used by Publish Event Tasks when no task-level event name override is configured.

Type: string

Default: ""

Environment Variable: UDMG_UAC_REST_EVENT_NAME

`uac.event_ttl`

An optional Time-To-Live for the Universal Event (in minutes).

Type: string

Default: ""

Environment Variable: UDMG_UAC_REST_EVENT_TTL

`uac.override_publish_event`

Enables Publish Event Tasks to override the default Universal Event configuration defined in the uac block.

Type: bool

Default: false

Environment Variable: UDMG_UAC_OVERRIDE_PUBLISH_EVENT

`uac.password`

The default password used by Publish Event Tasks to authenticate with the Universal Controller REST API when no task-level Credentials override is configured.

Type: string

Default: ""

Environment Variable: UDMG_UAC_REST_PASSWORD

`uac.urls`

A list of URIs for the Publish Universal Event API on the target Universal Controllers. UDMG will attempt to connect to these in order if one fails.

Example: ["http://host1/uc", "https://host2/uc"]

Type: List of strings

Default: []

Environment Variable: UDMG_UAC_REST_URLS

`uac.username`

The default username used by Publish Event Tasks to authenticate with the Universal Controller REST API when no task-level Credentials override is configured. The user must have the required permissions to call the Universal Event Web Services.

Type: string

Default: ""

Environment Variable: UDMG_UAC_REST_USERNAME

wtc

The wtc block configures the Web Transfer Client (WTC) service, which provides HTTPS-based browser file transfer capabilities.

`wtc.default_domain`

Specifies the default UDMG Domain that the root WTC URL (for example, https://example.com:4433) redirects to when no domain path is provided.

Type: string

Default: "primary"

Environment Variable: UDMG_WTC_DEFAULT_DOMAIN

`wtc.enable`

Enables or disables the WTC service. When disabled, the WTC listener does not start.

Type: bool

Default: false

Environment Variable: UDMG_WTC_ENABLE

`wtc.inet`

The IP address that the WTC listener binds to.

Use "0.0.0.0" to listen on all network interfaces, or specify a local IP address to restrict the listener to that interface.

Type: string

Default: "0.0.0.0"

Environment Variable: UDMG_WTC_LISTEN_INET

`wtc.log_level`

Log level for WTC operations.

Options:

"" (inherits from global logger)
"debug"
"info"
"warn"
"error"

Type: string

Default: ""

Environment Variable: UDMG_WTC_LOG_LEVEL

`wtc.max_public_connections`

Defines the maximum number of concurrent connections allowed for Shared Public Links (Web Transfer Client).

The counter is maintained per UDMG Server node and is not shared across a Cluster.

info

For more information, refer to Maximum Public Connections (WTC)

Type: number

Default: 1000

Environment Variable: UDMG_WTC_MAX_PUBLIC_CONNECTIONS

`wtc.port`

The TCP port number on which the WTC service listens for connections. Must be between 1 and 65535.

Type: string

Default: "8443"

Environment Variable: UDMG_WTC_LISTEN_PORT

`wtc.secure.enable`

Enables HTTPS for the Web Transfer Client (WTC).

When set to true, WTC serves all traffic over TLS and requires wtc.secure.pub_key and wtc.secure.priv_key.

Type: bool

Default: false

Environment Variable: UDMG_WTC_SECURE_ENABLE

`wtc.secure.priv_key`

Path to the private key file (PEM format) associated with wtc.secure.pub_key. Required if wtc.secure.enable is true.

info

The path is relative to the work_directory_path unless an absolute path is provided. For more details, see Absolute Over Relative Paths.

Type: string

Default: ""

Environment Variable: UDMG_WTC_PRIV_KEY

`wtc.secure.pub_key`

Path to the SSL/TLS certificate file (PEM format) presented to clients for HTTPS connections. Required if wtc.secure.enable is true.

info

The path is relative to the work_directory_path unless an absolute path is provided. For more details, see Absolute Over Relative Paths.

Type: string

Default: ""

Environment Variable: UDMG_WTC_API_PUB_KEY

`wtc.spec`

Enables or disables serving the OpenAPI specification at /spec and /swagger/index.html.

Type: bool

Default: false

Environment Variable: UDMG_WTC_SPEC_ENABLE

What Is HCL?
- Dot Notation
- Value Types
HCL vs Environment Variables
Directory Paths
- Absolute Over Relative Paths
- Platform-Specific Separators
Time Duration Format and Allowed Units
Custom Functions
Arguments by Block

What Is HCL?​

Dot Notation​

Value Types​

HCL vs Environment Variables​

Directory Paths​

Absolute Over Relative Paths​

Platform-Specific Separators​

Time Duration Format and Allowed Units​

Custom Functions​

Arguments by Block​

Root Level​

auto_migrate​

instance_name​

work_directory_path​

admin_app​

admin_app.enable​

api​

api.cors​

api.cors_domain​

api.csrf​

api.inet​

api.log_level​

api.port​

api.rate_limit​

api.secure.enable​

api.secure.priv_key​

api.secure.pub_key​

api.spec​

api.trusted_domains​

api.verbose​

as2​

as2.enable​

as2.message_id_expiry​

as2.replay_protect​

cluster​

cluster.client_port​

cluster.cluster_port​

cluster.deadline​

cluster.heartbeat​

cluster.mode​

cluster.seeds​

database​

database.dsn​

database.engine​

database.hostname​

database.log_level​

database.name​

database.options.idle_connections​

database.options.initial_interval​

database.options.max_connections​

database.options.max_interval​

database.options.max_retries​

database.password​

database.port​

database.secure.enable​

database.secure.mode​

database.secure.priv_key​

database.secure.pub_key​

database.secure.tls_server_cert_dn​

database.secure.wallet_location​

database.user​

hook_server​

hook_server.enable​

hook_server.enable_mdn​

hook_server.inet​

hook_server.log_level​

hook_server.port​

hook_server.secure.enable​

hook_server.secure.priv_key​

hook_server.secure.pub_key​

hook_server.spec​

icap​

icap.retry​

icap.timeout​

jwt​

jwt.access_token.duration​

jwt.refresh_token.duration​

jwt.signing_key​

ldap​

ldap.ldap_account_sync_interval​

What Is HCL?

Dot Notation

Value Types

HCL vs Environment Variables

Directory Paths

Absolute Over Relative Paths

Platform-Specific Separators

Time Duration Format and Allowed Units

Custom Functions

Arguments by Block

Root Level

`auto_migrate`

`instance_name`

`work_directory_path`

admin_app

`admin_app.enable`

api

`api.cors`

`api.cors_domain`

`api.csrf`

`api.inet`

`api.log_level`

`api.port`

`api.rate_limit`

`api.secure.enable`

`api.secure.priv_key`

`api.secure.pub_key`

`api.spec`

`api.trusted_domains`

`api.verbose`

as2

`as2.enable`

`as2.message_id_expiry`

`as2.replay_protect`

cluster

`cluster.client_port`

`cluster.cluster_port`

`cluster.deadline`

`cluster.heartbeat`

`cluster.mode`

`cluster.seeds`

database

`database.dsn`

`database.engine`

`database.hostname`

`database.log_level`

`database.name`

`database.options.idle_connections`

`database.options.initial_interval`

`database.options.max_connections`

`database.options.max_interval`

`database.options.max_retries`

`database.password`

`database.port`

`database.secure.enable`

`database.secure.mode`

`database.secure.priv_key`

`database.secure.pub_key`

`database.secure.tls_server_cert_dn`

`database.secure.wallet_location`

`database.user`

hook_server

`hook_server.enable`

`hook_server.enable_mdn`

`hook_server.inet`

`hook_server.log_level`

`hook_server.port`

`hook_server.secure.enable`

`hook_server.secure.priv_key`

`hook_server.secure.pub_key`

`hook_server.spec`

icap

`icap.retry`

`icap.timeout`

jwt

`jwt.access_token.duration`

`jwt.refresh_token.duration`

`jwt.signing_key`

ldap

`ldap.ldap_account_sync_interval`