Skip to main content
Version: 3.4

Upgrading UDMG

This guide explains how to upgrade UDMG Server to 3.4.x on Linux and Windows, a straightforward process that replaces the installed package without affecting your existing Configuration File or data.

Most changes are applied automatically on first startup. However, some configurations should be reviewed to ensure they behave as expected after the upgrade.

Follow the platform-specific upgrade steps for Linux or Windows, then review the specific changes between 3.3.x and 3.4.x that require attention.

Linux​

Upgrade Command​

Upgrading UDMG requires a single command, which varies by package format.

To upgrade the installed package, run one of the following commands:

The -U flag upgrades the existing package, replacing the current version with the new one. Unlike -i (used in the Linux Host Standard Installation guide), it does not fail if a previous version is already installed.

sudo rpm -Uvh udmg-server_3.4.x_linux_amd64.rpm

Configuration File Handling​

On Linux, the existing Configuration File is preserved during the upgrade. By default, it is located at /opt/udmg/etc/udmg-server.hcl.

Additionally, the new package ships an updated sample file at:

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

Windows​

Installer​

Run the UDMG Server installer (udmg-server_3.4.x_setup.exe) and follow the prompts to complete the upgrade.

Configuration File Handling​

On Windows, the existing Configuration File is preserved during the upgrade. Its default location is C:\Program Files\Stonebranch\UDMG Server\udmg-server.hcl. The installer does not place a new sample alongside.

To review any new arguments, refer to the Configuration File page.

Upgrading from 3.3.x to 3.4.x​

This section covers the configuration updates required after upgrading from UDMG 3.3.x, and the behavioral changes that take effect automatically on first startup.

Configuration File Changes​

If you are reusing your existing 3.3.x Configuration File, apply the following changes.

New (and Mandatory)​

The cluster.secure block is now required. UDMG Server does not start without it.

If you do not want to configure TLS on the internal NATS bus, add an empty secure block inside a cluster block:

udmg-server.hcl
cluster {
  # ...
  secure {}
}

Obsolete (Safe to Remove)​

The following arguments are no longer read by UDMG Server and can be removed:

  • The security.password block was deprecated in UDMG 3.3.x when password policy was migrated to the database. It is no longer read. See Password Policy.
  • The api.csrf argument is no longer read. CSRF protection is now handled internally.
  • The api.trusted_domains argument is deprecated and no longer read.

New (and Optional)​

The following arguments are new in UDMG 3.4.x and can be added to your existing Configuration File:

  • transfer.scheduler_max_concurrent_transfers: maximum number of scheduled transfers that can run concurrently. Defaults to 10.
  • protocol.cloud_stream_buffer_size: buffer size (in bytes) for remote cloud storage streaming transfers. Defaults to 16777216.
  • versioning: new block for managing Configuration Item version history. See Version History.
  • healthcheck: new block for configuring subsystem health monitoring. See UDMG Status.
  • cluster: new optional sub-keys for HA cluster configuration:
    • cluster.token: shared secret all Nodes must present when connecting to the internal NATS bus. Strongly recommended in production; prefer providing via environment variable.
    • cluster.transient: treats the Node as ephemeral, removing it from the cluster table when it goes offline instead of marking it as offline. Useful in containerized environments.
    • cluster.client_inet: bind address for the NATS client port (4222). Defaults to "127.0.0.1".
    • cluster.cluster_inet: bind address for the inter-node route port (6222). Defaults to "0.0.0.0".

Domain Names: Case-Insensitive Uniqueness​

warning

Before upgrading, verify that no two Domains in your instance share the same name (case-insensitively). If duplicates exist, the upgrade migration fails and UDMG Server does not start.

Starting in UDMG 3.4.x, Domain names are case-insensitive. On upgrade, a migration enforces this uniqueness constraint at the database level.

If duplicates exist, rename or delete the conflicting Domain before proceeding with the upgrade.

To check for duplicate Domain names, navigate to Global > Domains in the sidebar and look for any Domains with the same name differing only in case.

You can also use the UDMG REST API to retrieve the full list of Domains.

API Endpoint​

GET /api/v1/domains

Authentication​

This endpoint requires authentication using a valid UDMG User username and password.

Permissions​

The authenticated User must be the udmg.sys-admin User.

Example​

curl -X GET \
"https://<udmg-host>:<port>/api/v1/domains" \
-u "<username>:<password>"

Response​

Returns 200 OK with a JSON object containing a domains array. Check the name field of each item for names that match case-insensitively.

Example​
JSON
{
  "domains": [
    {
      "uuid": "635bab3f-3a39-4969-93fc-519801feea6e",
      "createdAt": "2026-09-19T20:07:12.1956873Z",
      "version": 1,
      "name": "primary",
      "description": "The Primary Domain or default Domain is created upon initial installation and provides core functionality and management of the UDMG system.",
      "enabled": true
    },
    {
      "uuid": "8d87ca6b-5362-4c89-b638-e83a9fdfab13",
      "createdAt": "2026-09-23T14:53:26.8814597Z",
      "version": 1,
      "name": "secondary-domain",
      "description": "A secondary domain",
      "enabled": true
    }
  ],
  "totalItems": 2,
  "page": 1,
  "pageSize": 2,
  "totalPages": 1
}

WTC Endpoint: File Integrity Check​

In UDMG 3.3.x, the File Integrity Check field was not configurable for Local HTTPS Server (WTC) Endpoints through the UDMG Admin UI (it was only available through the UDMG REST API). Internally, the UDMG Server computed MD5 checksums by default.

Starting in UDMG 3.4.x, the File Integrity Check field is available in the Endpoint configuration.

What Happens on Upgrade​

On first startup of UDMG 3.4.x, a migration runs automatically and sets File Integrity Check to MD5 on each Local HTTPS Server (WTC) Endpoint that did not have an explicit value set, preserving the previous default behavior.

Endpoints that already have an explicit File Integrity Check value are not changed.

To verify the migration results, review each Local HTTPS Server (WTC) Endpoint and confirm that File Integrity Check reflects your intent by following these steps.

Pipeline Relative Paths: Runtime Variables​

For UDMG as Server Pipelines, the following variables changed in UDMG 3.4.x:

VariableChange
${ACCOUNT_NAME}Resolves to the Account's Name instead of Username.
${ACCOUNT_USERNAME}New variable that resolves to the Account's Username.
${ACCOUNT_ID}Replaced by ${ACCOUNT_UUID}.
${DOMAIN_ID}Replaced by ${DOMAIN_UUID}.

For the full list of supported runtime variables, see Replacement Variables.

What Happens on Upgrade​

On first startup of UDMG 3.4.x, a migration runs automatically before UDMG Server begins serving requests and updates existing Pipeline Relative Path configurations:

  • ${ACCOUNT_NAME} is replaced with ${ACCOUNT_USERNAME}, preserving the resolved value (Account username).
  • ${ACCOUNT_ID} is replaced with ${ACCOUNT_UUID}.
  • ${DOMAIN_ID} is replaced with ${DOMAIN_UUID}.

No action is required, as the migration handles all affected Pipelines automatically.

Default Admin Password Reset​

UDMG 3.4.x introduces an enforced password reset for the default System Administrator User (udmg.sys-admin). On a fresh install, the System Administrator is required to change its default password before accessing UDMG Admin UI.

What Happens on Upgrade​

When upgrading from UDMG 3.3.x, no forced password reset is enforced. The udmg.sys-admin can continue using the default password if it was never changed.

warning

If the udmg.sys-admin User's password has never been changed from its default value, change it now by following these steps. The default password is publicly known and poses a security risk if left unchanged.