Skip to main content
Version: 3.4

Upgrading UDMG

This guide explains how to upgrade UDMG Server from 3.3.x to 3.4.x on Linux and Windows. It does not cover upgrades from any other version.

The upgrade replaces the installed version and migrates your existing data to the new database schema.

Although most changes are applied automatically on first startup, some configurations must be updated before starting UDMG Server, and others should be reviewed afterward to ensure they behave as expected.

To upgrade UDMG Server from 3.3.x to 3.4.x, complete the following steps in order:

  1. Complete the pre-upgrade checks.
  2. Stop UDMG Server.
  3. Back up your data.
  4. Install the new version of UDMG Server for your platform.
  5. Update the Configuration File, whether you kept your original file or it was replaced by the default one.
  6. Validate the Configuration File before starting UDMG Server.
  7. If auto_migrate is set to false, run the database migration manually.
  8. Start UDMG Server.
  9. Verify that UDMG Server is running.
  10. Review the post-upgrade changes and complete any recommended follow-up actions.

Step 1: Pre-Upgrade Checks​

Before installing the new version, review the following items.

Required Privileges​

On Linux, the upgrade commands in this guide use sudo, so the operating system user running them must be allowed to use it.

On Windows, run the upgrade from a PowerShell session opened with Run as administrator. Stopping and starting the service and running the installer require Administrator privileges.

Current Version and Package​

This guide applies only to UDMG Server 3.3.x. To check the installed version, run the following command (Linux shell or Windows PowerShell):

udmg-server --version

For more details, see the --version option.

Download the platform-specific file from the Stonebranch Customer Portal. A customer account and credentials, provided by Stonebranch, Inc., are required to access the Customer Portal.

Auto Migrate Setting​

Check whether auto_migrate is set to false in your Configuration File, or whether the UDMG_DATABASE_AUTO_MIGRATE environment variable is set to false.

If it is, you must run Step 7: Run the Database Migration during the upgrade. If it is not set, or set to true, UDMG Server applies the migrations automatically on startup.

Downtime and Active Transfers​

Upgrading requires stopping UDMG Server, which interrupts any Transfer in progress and makes UDMG unavailable until it is started again. Schedule the upgrade for a maintenance window.

Configuration File Handling​

During the upgrade, UDMG Server preserves the existing Configuration File on both platforms. On Linux, if you modified the Configuration File, the new package also saves an updated sample file next to it.

By default, the Configuration File is located at /opt/udmg/etc/udmg-server.hcl.

If you modified the Configuration File, the new package also saves an updated sample file next to it, at one of the following paths depending on the package format:

  • RHEL-based systems (e.g., CentOS, Fedora): 
    /opt/udmg/etc/udmg-server.hcl.rpmnew
  • Debian-based systems (e.g., Ubuntu): 
    /opt/udmg/etc/udmg-server.hcl.dpkg-dist
info

On Debian-based systems, dpkg asks whether to keep the existing Configuration File during installation. To preserve it, answer N, as described in Step 4. The sample file is created only when you answer N. If you answer Y or I, the default file replaces your Configuration File instead.

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 "<udmg-username>:<udmg-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
}

Account Names: Case-Insensitive Uniqueness​

warning

Before upgrading, verify that no two Accounts in the same Domain 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, Account names are case-insensitive within a Domain. On upgrade, a migration enforces this uniqueness constraint at the database level.

This applies to Accounts of every authentication type, including Accounts created through SSO and LDAP.

To check for duplicate Account names, for each Domain:

  1. Sign in to the Domain with a Domain Administrator's credentials.
  2. Navigate to Configuration > Accounts in the sidebar.
  3. Look for any Accounts whose Account Name differs only in case.

If duplicates exist, resolve each conflict before proceeding with the upgrade. The steps depend on the Account's authentication method:

Step 2: Stop All UDMG Server Instances​

Stop UDMG Server before installing the new version. If you run UDMG in a High Availability cluster, stop UDMG Server on every Node before continuing.

To stop UDMG Server, run the following command on each Node:

sudo systemctl stop udmg-server

Then confirm that the service is stopped by checking its status with the following command:

sudo systemctl status udmg-server

The output should show Active: inactive (dead).

Step 3: Back Up Your Data​

warning

As a precautionary measure, it is highly recommended that you back up:

danger

Do not lose the security.passphrase_key value. UDMG Server uses it to encrypt secret values, such as passwords and Private Key Credentials, stored in the database. If the key is lost, UDMG Server cannot decrypt that data and you lose access to the database contents.

The key is not necessarily in the Configuration File. If you provided it through the UDMG_SECURITY_PASSPHRASE_KEY environment variable, as recommended in the Linux Host Standard Installation guide, the upgrade does not change it and backing up the Configuration File does not back it up. Before continuing, confirm that you have a copy of the key stored separately and securely.

In a High Availability cluster, all Cluster Nodes share a single database, so you only need to back it up once. Back up the Configuration File from each Node, unless all Nodes use the same shared file.

Step 4: Install the New Package​

Install the new version of UDMG Server for your platform. In a High Availability cluster, repeat this step on every Node.

Linux​

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

Windows​

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

Step 5: Update the Configuration File​

The steps to follow depend on which Configuration File is active after installing the new package:

In a High Availability cluster, all Cluster Nodes must share the same configuration. If the Nodes use a single shared Configuration File, update it once. If each Node has its own copy, apply the same changes to every copy.

Update Your Original Configuration File​

Apply the following changes to your existing Configuration File.

New (and Mandatory)​

warning

The cluster.secure block is required in UDMG 3.4.x. If it is missing from your Configuration File, UDMG Server does not start after the upgrade.

If you do not want to configure TLS on the internal NATS bus, add the secure block inside the cluster block, as shipped in the default Configuration File:

udmg-server.hcl
cluster {

  # ...

  secure {
    enable   = false
    pub_key  = ""
    priv_key = ""
    ca_file  = ""
  }
}

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 Transfers that can run concurrently within a single wildcard Scheduled Transfer. 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".

Restore Your Settings in the Default Configuration File​

This scenario applies only to Debian-based systems on which you answered Y or I to the dpkg prompt. dpkg replaced your Configuration File (/opt/udmg/etc/udmg-server.hcl) with the default file shipped in the package and saved a copy of your previous file.

The default file includes the mandatory cluster.secure block and the new optional arguments, but it does not contain required settings such as jwt.signing_key, security.passphrase_key, and the database connection arguments, which are empty in the default file. UDMG Server cannot start until you restore them.

To restore your settings:

  1. Open your backup of the original Configuration File from Step 3. If you did not back it up, dpkg saved your previous file next to the active one as /opt/udmg/etc/udmg-server.hcl.dpkg-old.
  2. Copy each value you customized in the backup into the matching argument of the active Configuration File. Do not overwrite the active file with the backup, so that the new cluster.secure block and the other new arguments are preserved.
  3. Skip any argument listed under Obsolete (Safe to Remove), as UDMG Server no longer reads them.
  4. If you use the cluster block, review the new optional sub-keys listed under New (and Optional).
tip

Alternatively, copy your backup over the active file and then follow Update Your Original Configuration File to apply the changes.

Step 6: Validate the Configuration File​

After updating the Configuration File, validate it before starting UDMG Server. The test command checks the file without starting UDMG and reports each problem with its file, line, and column. To validate it, run the following command:

udmg-server test --file <config-file>

For more details, see the test command.

Step 7: Run the Database Migration​

UDMG Server applies pending database migrations automatically on startup, unless auto_migrate is set to false in the Configuration File or the UDMG_DATABASE_AUTO_MIGRATE environment variable is set to false. Run this step only in that case, because UDMG Server does not apply the pending migrations itself and needs them applied before it starts. Otherwise, skip this step.

danger

The migrate command modifies the UDMG Server database schema and is not rolled back automatically. Back up the database before running it, and do not interrupt the command once it starts.

info

Run the migrate command as the same user that runs UDMG Server, with the same privileges and the same environment variables. The command must read the Configuration File and the UDMG_* environment variables the same way UDMG Server does, so a different user or environment can use different settings or be unable to connect to the database.

Apply the pending migrations by running the following command (in a High Availability cluster, all Cluster Nodes share a single database, so run the migration only once, from any Node):

udmg-server migrate --config <config-file>

Expected output:

Database migration completed successfully

If the command fails with the message NOTICE: ERROR: Setup logger:, see Setup Logger Error.

For more details, see the migrate command.

Step 8: Start UDMG Server​

Start UDMG Server with the updated Configuration File by running the following command. In a High Availability cluster, run it on every Node:

sudo systemctl start udmg-server
tip

If UDMG Server does not start, verify that the cluster.secure block is present, that no Domain or Account names are duplicated, and that the database migration step has completed successfully if auto_migrate is false.

Step 9: Verify That UDMG Server Is Running​

After starting UDMG Server, confirm that the service is running on each Node by checking its status with the following command:

sudo systemctl status udmg-server

The output should show Active: active (running).

On RHEL-based systems, the output also ends with a log line in the following form:

<date> <time> <hostname> systemd[1]: Started Stonebranch UDMG Server.

Then sign in to the UDMG Admin UI and confirm that the resources on the UDMG Status page are healthy.

tip

If the service is not running, review the UDMG Server logs and see the tip in Step 8.

Step 10: Review Post-Upgrade Changes​

UDMG 3.4.x introduces the following changes. Some take effect on first startup (or when you run the database migration manually), while others only change how new installations behave. Review each one and complete any recommended actions.

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.

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​

When the database migration is applied (on first startup, or when you run it manually), UDMG 3.4.x 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​

When the database migration is applied (on first startup, or when you run it manually), UDMG 3.4.x updates existing Pipeline Relative Path configurations before UDMG Server begins serving requests:

  • ${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.