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 of global and system-level settings are defined here.

On the host where the UDMG Server is installed, the file is located at:

/opt/udmg/etc/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
  }
}

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

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.

HCL Argument Name	Description	Value Type	Default Value
instanceName	Name of the UDMG Server instance. Only used for observability.	string	"udmg-server"
autoMigrate	When enabled, UDMG automatically applies any required database schema migrations during startup. This is typically needed when upgrading to a more recent UDMG version.	bool	false
workDirectoryPath	Defines the current working directory for the UDMG Server. For Endpoints, this path acts as a hard root (similar to a chroot jail). Endpoint paths are always resolved inside this directory and cannot reference absolute paths outside of it. Exceptionally, this can be disabled by setting the base working directory to /. For other Configuration Items and arguments, it serves as the base directory for resolving relative paths. In these cases, you may still specify an absolute path to override it.	string	""
permissions	Permissions for created files or folders, specified as a standard Linux file mode.	string	"0o700"
dashboard	The Admin UI can be served with an embedded web server. Enable the dashboard to start the Admin UI with the instance. Keep it disabled if the Admin UI is not required or is served by an external web server (Nginx, Caddy, etc.).	bool	false
dashboard_path	Path to the dashboard's static files. Requires dashboard enabled.	string	""

log

The log block controls how UDMG Server emits operational logs. Configure it to meet your observability and retention requirements. For more information, refer to Logging.

HCL Argument Name	Description	Value Type	Default Value
log.level	Configures the log level. Options: "debug" "info" "warn" "error"	string	"info"
log.format	Format of the log output. Options: "plain" "json"	string	"plain"
log.file	Log file name. Supports environment variable expansion.	string	udmg-server.log
log.rotate.enable	Enables or disables the log rotation feature. When enabled, log files are rotated as soon as one of the configured rotation conditions is met: The defined log.rotate.frequency interval has elapsed. The log file reaches the configured log.rotate.size. Only the size-based condition can be disabled.	bool	false
log.rotate.frequency	Time interval that triggers log rotation. Rotation occurs when this interval is reached, unless rotation is disabled. Options: "daily" "weekly" "monthly" "quarterly"	string	"daily"
log.rotate.size	Maximum log file size (in megabytes) before rotation is triggered. Checked every hour.	number	5
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)	string	"{YYYY}-{MM}-{DD}-{HH}-{mm}-{ss}-{ns}"

jwt

The jwt block configures token-based authentication for the UDMG Admin UI and UDMG REST API.Use strong, unique keys and tune durations to balance security and usability.

HCL Argument Name	Description	Value Type	Default Value
jwt.signingKey	The secret key used for signing both access and refresh tokens. warning Change this default value to ensure the security of your system.	string	"secure-signing-key-goes-here"
jwt.accessToken.duration	The validity duration of the access token. Allowed time units: m for minutes (e.g., "15m") h for hours (e.g., "1h")	string	"15m"
jwt.refreshToken.duration	The validity duration of the refresh token. Allowed time units: h for hours (e.g., "12h") d for days (e.g., "7d")	string	"15m"

api

The api block configures the HTTP server that exposes the UDMG Admin UI and UDMG REST API (set api.secure.enable = true to serve them over HTTPS).

HCL Argument Name	Description	Value Type	Default Value
api.inet	The IP address the API server listens on. 0.0.0.0 listens on all available network interfaces.	string	"0.0.0.0"
api.port	The port number the API server listens on.	string	"8080"
api.spec	Enables or disables serving the OpenAPI specification (at /spec and /swagger/index.html).	bool	false
api.csrf	Enables or disables Cross-Site Request Forgery protection middleware. tip It is recommended to keep enabled.	bool	false
api.trustedDomains	List of UDMG Admin UI hostnames (including the port when it's not the default 443) that the UDMG Server accepts as trusted sources.	list(string)	No default Example with default port: ["udmg.my-company.com"] Example with custom port number: ["udmg-staging.my-company.com:9180"] Example with several hostnames when the UDMG Admin UI can be reached through several URLs: ["udmg.my-company.com", "udmg-staging.my-company.com:9180"]
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.	bool	false
api.corsDomain	Specifies the allowed origin domain(s) for CORS requests when api.cors is enabled. Use "*" for any domain (less secure).	string	""
api.verbose	Increase the verbosity for the logging of the API requests and responses (can be noisy).	bool	false
api.allowConcurrentUserLogin	Controls whether multiple simultaneous sessions are permitted for the same User. When set to false, any existing user sessions will be terminated when a new login occurs. info This improves security by preventing multiple concurrent logins, but may disrupt legitimate multi-device usage.	bool	false
api.secure.enable	Enables or disables HTTPS for the API server. info If enabled, api.secure.pubKey and api.secure.privKey are required.	bool	false
api.secure.pubKey	Path to the public SSL/TLS certificate file (PEM format). This certificate is presented by the UDMG Server to clients to validate the Server's identity and establish a secure HTTPS connection. The path is relative to the workDirectoryPath of the UDMG Server.	string	""
api.secure.privKey	Path to the private SSL/TLS key file (PEM format). This key is used by the UDMG Server to prove ownership of the certificate and to complete the TLS handshake, enabling encrypted communication over HTTPS. The path is relative to the workDirectoryPath of the UDMG Server.	string	""

transfer

The transfer block arguments only apply when UDMG is acting as a client. For related documentation, refer to Pipeline Types.

HCL Argument Name	Description	Value Type	Default Value
transfer.retryDelay	The base wait time before retrying a transfer after a connection or transfer error. Each retry restarts the transfer from the beginning. Allowed time units: s for seconds (e.g., "10s") m for minutes (e.g., "5m")	string	"5m"
transfer.maxRetryDelay	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. Allowed time units: m for minutes (e.g., "30m") h for hours (e.g., "1h")	string	"1h"
transfer.retryBackoff	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.maxRetryDelay. Each retry restarts the transfer from the beginning. Delay for retry attempt n = retryDelay x (retryBackoff ^ n), where n is the retry attempt number, starting at 0. Example with retryDelay = 5m: retryBackoff = 1 → 5m, 5m, 5m, ... retryBackoff = 2 → 5m, 10m, 20m, ... retryBackoff = 3 → 5m, 15m, 45m, 135m, ...	number	2.0
transfer.maxRetries	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.	number	3
transfer.checkInterval	Interval at which UDMG polls for pending transfers that were scheduled through the Transfers Scheduled API. Allowed time units: s for seconds (e.g., "30s") m for minutes (e.g., "1m")	string	"1m"

observability

The observability block enables health and diagnostics endpoints and optional debug access. Use it to integrate UDMG Server with monitoring stacks and to expose a separate, minimal API for status and metrics collection.

HCL Argument Name	Description	Value Type	Default Value
observability.api.inet	Address for the observability API.	string	"0.0.0.0"
observability.api.port	Port for the observability API.	string	"7070"
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).	bool	true
observability.api.enable	Enables or disables the observability API.	bool	true
observability.api.debug.enable	Enable or disable debug mode for observability API.	bool	false
observability.api.debug.user	Debug username for observability API.	string	"admin"
observability.api.debug.password	Debug password for observability API.	string	""
observability.prometheus.enable	Enables or disables Prometheus metrics.	bool	true

database

The database block defines the backend. Configure it to point UDMG Server to your production database and to enforce secure connections where required.

HCL Argument Name	Description	Value Type	Default Value
database.engine	The type of database engine to use. Options: "mysql" "oracle" "sqlserver" "postgresql"	string	"sqlite3"
database.instance	The database name.	string	""
database.hostname	The hostname or IP address of the database server.	string	""
database.port	The port number for the database server.	number	5432
database.user	The username for connecting to the database.	string	""
database.password	The password for connecting to the database.	string	""
database.options.maxConnections	The maximum number of open connections to the database.	number	30
database.options.idleConnections	The maximum number of connections in the idle connection pool.	number	5
database.options.maxRetries	The maximum number of times to retry an operation if the database is locked.	number	5
database.options.initialInterval	The initial time duration to wait before retrying a locked operation. Allowed time units: ms for milliseconds (e.g., "50ms")	string	"50ms"
database.options.maxInterval	The maximum time duration to wait between retries for a locked operation. Allowed time units: ms for milliseconds (e.g., "500ms") s for seconds (e.g., "2s")	string	"1s"
database.secure.enable	Enables or disables secure (TLS/SSL) connection to the database.	bool	false
database.secure.mode	The SSL mode to use. Allowed values: "disable" "allow" "prefer" "require" "verify-ca" "verify-full" info Refer to PostgreSQL docs for details.	string	require
database.secure.pubKey	Path to the CA certificate file (used when database.secure.mode is verify-ca or verify-full).	string	""
database.secure.privKey	Path to the client private key file (used for client certificate authentication, if required by the server).	string	""

security

The security block provides system-wide hardening toggles and recovery options. Use these settings to control what is exposed via the UDMG REST API and to guard against accidental lockouts.

HCL Argument Name	Description	Value Type	Default Value
security.workDirectoryKeyDisplay	If enabled, the workDirectoryPath is exposed under the API	bool	false
security.password.minLength	Minimum password length.	number	8
security.password.minUpperCase	Minimum number of uppercase characters in password.	number	0
security.password.minLowerCase	Minimum number of lowercase characters in password.	number	0
security.password.minNumbers	Minimum number of numbers in password.	number	0
security.password.minSymbols	Minimum number of symbols in password.	number	0
security.ignoreSystemUserIPFilter	Bypasses the IP Filtering - Admin UI restriction. Use this option only to recover from an accidental lockout.	bool	false

ldap

The ldap block integrates UDMG with an external LDAP directory for user authentication and lookup. Configure servers, binding, and attribute mapping here to centralize identity management. For more information, refer to LDAP Authentication.

HCL Argument Name	Description	Value Type	Default Value
ldap.ldapAccountSyncInterval	Defines how often UDMG synchronizes LDAP users that are linked to UDMG Users. Leave empty ("") to disable synchronization. Allowed time units: m for minutes (e.g., "15m") h for hours (e.g., "1h")	string	"1h"
ldap.ldapUserSyncInterval	Defines how often UDMG synchronizes LDAP users that are linked to UDMG Accounts. Leave empty ("") to disable synchronization. Allowed time units: m for minutes (e.g., "15m") h for hours (e.g., "1h")	string	"1h"

icap

The icap block configures general content-scanning via an ICAP server. Use it to enforce malware scanning on inbound file flows. For more information, refer to ICAP Scanner.

HCL Argument Name	Description	Value Type	Default Value
icap.timeout	The maximum time duration to wait for a response from the ICAP server. Allowed time units: s for seconds (e.g., "60s") m for minutes (e.g., "2m")	string	"10s"
icap.vendor.name	An optional, descriptive name to identify the vendor configuration block (e.g., "c-icap", "mcafee-gw").	string	No default
icap.vendor.headers	A list of ICAP response header names that UDMG Server should inspect to determine if a file is infected or requires action based on the ICAP server's response.	list(string)	No default

uac

The uac block connects UDMG to Universal Automation Center (UAC) for orchestration and scheduling. Configure it to allow UAC to trigger or react to file transfer events within UDMG. For more information, refer to Universal Event Integration.

HCL Argument Name	Description	Value Type	Default Value
uac.enable	Enables or disables globally the feature to publish Universal Event.	bool	false
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.	list(string)	No default Example: ["http://host_name1/uc/resources/universalevent/publish", "http://host_name2/uc/resources/universalevent/publish"]
uac.username	The username for authenticating with the Universal Controller REST API. The user must have the required permissions to call the Universal Event Web Services.	string	""
uac.password	The password for authenticating with the Universal Controller REST API.	string	""
uac.eventName	The name of the Universal Event to trigger in UAC when a relevant action occurs.	string	""
uac.eventTTL	An optional Time-To-Live for the Universal Event (in minutes).	string	""

protocol

The protocol block sets SFTP-level defaults. Tune these values to control connection lifecycle and resource usage.

HCL Argument Name	Description	Value Type	Default Value
protocol.sessionIdleTimeout	The idle timeout SFTP protocol sessions. Allowed time units: m for minutes (e.g., "5m") h for hours (e.g., "1h")	string	"5m"

cluster

The cluster block enables high-availability operation across multiple UDMG Server nodes and defines how nodes discover peers and coordinate. All nodes in a cluster must use a consistent configuration for stable behavior.

HCL Argument Name	Description	Value Type	Default Value
cluster.mode	The operational mode of the cluster. Allowed value: "AA" (Active-Active). "AP" (Active-Passive).	string	"AP"
cluster.heartbeat	The time interval between heartbeat signals sent between nodes. Allowed time units: ms for milliseconds (e.g., "500ms") s for seconds (e.g., "10s")	string	"10s"
cluster.deadline	The time duration after which a node is considered down if no heartbeat is received. Allowed time units: s for seconds (e.g., "30s") m for minutes (e.g., "1m")	string	"30s"
cluster.client_port	The port number used by UDMG Server for client communication in a cluster.	number	4222
cluster.cluster_port	The port number used for inter-node communication within the UDMG Server cluster.	number	6222

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   = "postgresql"
  hostname = "localhost"
  user     = "udmg"
  password = "${env("DB_PASSWORD", "default-password")}"
}

tip

Environment variables take precedence over HCL arguments when both are provided. It is generally recommended to configure settings in HCL files to maintain clarity, consistency, and ease of management.

Use environment variable overrides sparingly (typically for temporary adjustments, containerized deployments, or sensitive values such as passwords and secrets).