Version: 3.3

Linux Host Custom Installation

This guide explains how to install UDMG Server 3.3.x on Linux from a .tar.gz archive and how to configure it to connect to a supported database and start the service.

Use this method in any of the following situations:

You need to install to a custom directory path.
You need to run UDMG Server under a specific OS user or group.
You do not have to or prefer to avoid root access or running sudo commands.
Package manager access is restricted by company policy.
You are deploying with Configuration Management or Deployment Automation tools such as Ansible.

Prerequisites

A supported database (Oracle, MySQL, Microsoft SQL Server, or PostgreSQL). For setup instructions, see Database Installation.
An existing directory to use as the installation directory (<udmg-install-dir>).
An existing directory to use as the work directory (<udmg-work-dir>).
An existing directory to use as the log directory (<udmg-log-dir>).

info

Before proceeding, ensure that your database version and OS are supported, and that you meet the hardware recommendations. For more details, see System Requirements.

Installation

The .tar.gz archive is a flat bundle containing only the server binary and a sample configuration file. This section walks through extracting the archive and setting up the directory layout.

In the commands and configuration snippets below, replace <udmg-install-dir>, <udmg-work-dir>, and <udmg-log-dir> with your chosen directories as defined in Prerequisites.

1. Get the `.tar.gz` Package

To obtain the installation package, contact your Stonebranch representative. If you do not have a representative, reach out to support@stonebranch.com.

2. Verify the Checksum

info

In all commands on this page, replace 3.3.x with the exact UDMG Server version you are installing.

The checksums file is provided by your Stonebranch representative alongside the installation files. Place it in the same directory as the downloaded installation package before proceeding.

To ensure the integrity of the downloaded package, run the following command from that directory:

sha256sum -c udmg-server_3.3.x_checksums.txt

If the package is valid, the output will include:

udmg-server_3.3.x_linux_amd64.tar.gz: OK

info

The checksums file covers all release artifacts. Warnings about files you did not download are expected and can be ignored.

3. Extract the Archive

Extract the archive to the installation directory. Run the following command from the directory where you downloaded the archive:

tar -xzf udmg-server_3.3.x_linux_amd64.tar.gz -C <udmg-install-dir>

To verify that the archive was extracted correctly, list the contents of the installation directory:

Command:

ls -l <udmg-install-dir>

Example output:

-rw-r--r-- 1 <user> <group> ... THIRD_PARTY_LICENSES
drwxr-xr-x 2 <user> <group> ... docs
-rw-r--r-- 1 <user> <group> ... ops_unv_event_tmplt_udmg_transfer.xml
-rwxr-xr-x 1 <user> <group> ... udmg-server
-rw-r--r-- 1 <user> <group> ... udmg-server.hcl

info

Permission bits may vary depending on your system's umask setting. The archive file will also appear in the listing. You can remove it once the extraction is verified:

rm <udmg-install-dir>/udmg-server_3.3.x_linux_amd64.tar.gz

4. Make the Binary Executable

The binary is extracted with execute permissions. If they were lost during transfer, restore them by running:

chmod +x <udmg-install-dir>/udmg-server

5. Verify the Installation

Confirm that the UDMG Server binary is accessible and working by checking its version:

Command:

<udmg-install-dir>/udmg-server --version

Example output:

udmg-server version 3.3.x-b5685:97ef93098f83e747e064691af7acd2a1f0ac19a5:HEAD:2026-02-02T14:12:19Z

info

Exact version and build information may differ.

Configuration

info

All HCL arguments described on this page use dot notation to reference their full path from the root of the configuration file.

The next step is to configure the UDMG Server instance by editing the Configuration File at <udmg-install-dir>/udmg-server.hcl.

The Configuration File includes baseline settings. However, other arguments (such as database connection, working directory, and security keys) must be edited before the instance can start successfully.

To perform a basic configuration of UDMG Server, open <udmg-install-dir>/udmg-server.hcl in a text editor, then edit it as follows:

1. Work Directory Path

Configure the work_directory_path argument to set the root working directory for UDMG Server:

udmg-server.hcl
work_directory_path = "<udmg-work-dir>"

warning

work_directory_path is a sensitive setting. See Work Directory Path.

2. `jwt` Block

Configure the jwt block to set the signing key used to sign access and refresh tokens for the UDMG Admin UI, UDMG REST API, and WTC UI. This key must be a strong secret of at least 30 characters and can contain only letters, numbers, and underscores.

You can generate a suitable value with:

openssl rand -base64 32 | tr -dc 'A-Za-z0-9_' | head -c 40

warning

Treat this value as a secret. Do not commit the populated configuration file to version control.

Then set it in the Configuration File:

udmg-server.hcl
jwt {
  signing_key = "<signing-key>"

  # ...
}

3. `database` Block

You can configure the database block in two ways: by specifying individual connection parameters, or by using a TNS-format DSN (Oracle only).

Individual Parameters (Any Engine)
DSN in TNS Format (Oracle)

For any supported database engine, you can configure the database block using individual parameters such as database.hostname, database.port, and database.name.

In this example, we followed the Database Installation guide for MySQL and have a MySQL database running on the same host as UDMG Server, with the default MySQL port:

udmg-server.hcl
database {
  engine   = "mysql"
  name     = "udmg"
  hostname = "localhost"
  port     = 3306
  user     = "udmgadm"
  password = "udmg-mysql-password"

  # ...
}

For Oracle databases, you can also configure the database block using a DSN, instead of individual arguments. For this, UDMG supports TNS descriptors as a single-line string.

In this case, you must still specify database.user and database.password separately:

udmg-server.hcl
database {
  engine   = "oracle"
  user     = "udmgadm"
  password = "udmg-oracle-password"
  dsn      = "(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=hostname)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=service_name)))"

  # ...
}

When using the TNS descriptor format:

The database.user and database.password fields are required.
When database.dsn is set, it overrides database.hostname, database.port, and database.name.

4. `database.secure` Block (Optional)

Use the database.secure block to configure optional TLS/SSL for the database connection.

To enable TLS/SSL, set database.secure.enable to true and adjust the database.secure.mode according to your database security requirements.

If your database requires client certificate authentication, provide the paths to the client certificate and private key files.

udmg-server.hcl
database {

  secure {
    enable   = true
    mode     = "require"
    pub_key  = "<udmg-install-dir>/certs/db-client-cert.pem"
    priv_key = "<udmg-install-dir>/certs/db-client-key.pem"
  }

  # ...
}

5. `security` Block

Set the security.passphrase_key field to define the root encryption key used to protect secret values (passwords, credential private keys, etc.).

This key:

Must be a valid 32-byte (64-character) hexadecimal string.
Must be kept secret and backed up securely (it is required for decryption and disaster recovery).

You can generate a suitable value with, for example:

openssl rand -hex 32

warning

Treat this value as a secret. Do not commit the populated configuration file to version control.

Then set it in the Configuration File:

udmg-server.hcl
security {
  passphrase_key = "<passphrase-key>"

  # ...
}

tip

For production environments, we strongly recommend providing the passphrase key via the UDMG_SECURITY_PASSPHRASE_KEY environment variable using Custom Functions.

info

See Encryption Key Rotation for instructions on how to rotate this key securely.

6. `api` Block

Use the api block to configure how the UDMG Server API listens for incoming connections.

api.inet controls the bind address (default is 0.0.0.0, which listens on all interfaces).
api.port sets the TCP port for the API (default is "8080").

If you are upgrading from UDMG 3.2.0 or UDMG 3.2.1, you must also remove the api.allow_concurrent_user_login argument from the Configuration File.

This argument is no longer supported in the Configuration File. Starting with UDMG 3.3.0, concurrent administrative sessions are controlled by the Maximum Concurrent User Sessions setting.

7. `api.secure` Block (Recommended)

Use the api.secure block to enable HTTPS and configure the TLS certificate and key used by the UDMG REST API.

While optional, enabling HTTPS is highly recommended to secure client communication with the UDMG REST API, especially in production environments or when the server is exposed beyond localhost.

When api.secure.enable is set to true, the UDMG REST API listens over HTTPS on the configured api.port using the provided certificate and key.

To enable HTTPS, set api.secure.enable to true and provide the paths to your certificate (api.secure.pub_key) and private key (api.secure.priv_key):

For example:

udmg-server.hcl
api {
  # ...

  secure {
    enable   = true
    pub_key  = "<udmg-install-dir>/certs/udmg-api-cert.pem"
    priv_key = "<udmg-install-dir>/certs/udmg-api-key.pem"
  }
}

info

For details on the PEM certificate and key files, see the api block.

8. `log` Block

Use the log block to configure the logging behavior of UDMG Server. In particular, set log.file to a valid file path to enable file-based logging during installation and configuration.

For example:

udmg-server.hcl
log {  
  file = "<udmg-install-dir>/logs/udmg-server.log"

  # ...
}

Validate the Configuration

Before starting the service, validate the Configuration File syntax by running:

<install-dir>/udmg-server test -f <install-dir>/udmg-server.hcl

If the configuration is valid, the command exits with no output. Fix any reported errors before continuing.

info

The test command validates HCL syntax only. It does not verify database connectivity or catch semantic errors such as an unsupported database.engine value.

Run Database Migration

info

This step is optional. On a first install, UDMG Server creates the database schema automatically on startup, unless auto_migrate is set to false in the Configuration File.

You can run the migration explicitly to get clear feedback if there are any issues:

<udmg-install-dir>/udmg-server migrate -c <udmg-install-dir>/udmg-server.hcl

Expected output:

Database migration completed successfully

Start

Start UDMG Server by running:

<udmg-install-dir>/udmg-server start -c <udmg-install-dir>/udmg-server.hcl

The server runs in the foreground and blocks the terminal. Press Ctrl+C to stop it.

Install Verification

info

The commands below use https://. If you did not configure TLS in the api.secure block, replace https:// with http://.

1. Verify Listening Ports

Verify that UDMG Server is listening on the expected ports by running:

ss -ntalp | grep udmg

Example output:

LISTEN 0      4096               *:7070             *:*    users:(("udmg-server",pid=8424,fd=8))
LISTEN 0      4096               *:8080             *:*    users:(("udmg-server",pid=8424,fd=9))
LISTEN 0      4096               *:4222             *:*    users:(("udmg-server",pid=8424,fd=10))
LISTEN 0      4096               *:6222             *:*    users:(("udmg-server",pid=8424,fd=11))

2. Test UDMG REST API

Test the UDMG REST API port by running:

curl https://localhost:8080/auth/primary

Expected output:

{}

info

If the endpoint returns an error immediately after starting the service, wait a few seconds and retry. Domain initialization completes a short time after the server starts.

3. Test UDMG Observability API

Test the UDMG Observability API port by running:

curl https://localhost:7070/_/ping

Expected output:

ACTIVE

4. Test the Web Server Port

Test the UDMG Admin UI web server port by running:

curl -s https://localhost:8080/ui/ | grep title

Expected output:

    <title>Stonebranch Universal Data Mover Gateway</title>

5. Open the UDMG Admin UI in Your Browser

Open your web browser and navigate to https://<udmg-server-host>:<port>/ui/ (or http://<udmg-server-host>:<port>/ui/ if HTTPS is not enabled).

Note that <udmg-server-host> should be replaced with the actual hostname or IP address of your UDMG Server, and <port> with the configured api.port value.

info

For detailed guidance on navigating and using the Admin UI, see the Admin UI Interface section.

Post-Installation

1. Change the Default Admin Password

Access the UDMG Admin UI at https://<udmg-server-host>:<port>/ui/ and enter the Primary Domain name: primary.

Then, log in using the default System Administrator credentials:

Default username: udmg.sys-admin
Default password: udmg.sys-admin_password

danger

Change the default System Administrator password immediately after logging in for the first time to prevent unauthorized access. If the password is lost, the System Administrator User cannot be restored.

2. Apply a Valid License

UDMG requires a valid license key to enable file transfer functionality. After a fresh installation, the server starts in an Unlicensed state. This is expected and is indicated by the following entry in the server log:

WARN: skipping endpoint startup: unlicensed

The UDMG Admin UI remains accessible and you can proceed with configuration, but file transfers are not operational until a license is applied.

To obtain a license, contact your Stonebranch representative. If you do not have a representative, reach out to support@stonebranch.com.

For instructions on how to apply a license and details on license states, expiration, and renewal, see Licensing.

Default Port Numbers

Default Port Number	Description	Configuration File Argument
`8080`	UDMG Server API Port	`api.port`
`7070`	UDMG Server Observability API Port	`observability.api.port`
`4222`	UDMG Server Cluster Client Port	`cluster.client_port`
`6222`	UDMG Server Cluster Server Port	`cluster.cluster_port`

Prerequisites​

Installation​

1. Get the .tar.gz Package​

2. Verify the Checksum​

3. Extract the Archive​

4. Make the Binary Executable​

5. Verify the Installation​

Configuration​

1. Work Directory Path​

2. jwt Block​

3. database Block​

4. database.secure Block (Optional)​

5. security Block​

6. api Block​

7. api.secure Block (Recommended)​

8. log Block​

Validate the Configuration​

Run Database Migration​

Start​

Install Verification​

1. Verify Listening Ports​

2. Test UDMG REST API​

3. Test UDMG Observability API​

4. Test the Web Server Port​

5. Open the UDMG Admin UI in Your Browser​

Post-Installation​

1. Change the Default Admin Password​

2. Apply a Valid License​

Default Port Numbers​

Prerequisites

Installation

1. Get the `.tar.gz` Package

2. Verify the Checksum

3. Extract the Archive

4. Make the Binary Executable

5. Verify the Installation

Configuration

1. Work Directory Path

2. `jwt` Block

3. `database` Block

4. `database.secure` Block (Optional)

5. `security` Block

6. `api` Block

7. `api.secure` Block (Recommended)

8. `log` Block

Validate the Configuration

Run Database Migration

Start

Install Verification

1. Verify Listening Ports

2. Test UDMG REST API

3. Test UDMG Observability API

4. Test the Web Server Port

5. Open the UDMG Admin UI in Your Browser

Post-Installation

1. Change the Default Admin Password

2. Apply a Valid License

Default Port Numbers