Linux Host Installation

This guide explains how to install UDMG Server 3.2 on RHEL-based and Debian-based systems and how to configure it to connect to a supported database and start the service.

Prerequisites

Root access.
A supported database (Oracle, MySQL, Microsoft SQL Server, or PostgreSQL). For setup instructions, see Database Installation.

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

UDMG Server is distributed as a standard RPM or DEB package that performs the following actions:

Creation of a dedicated system user udmg and group udmg
Deployment of the application files under /opt/udmg/
Configuration of a system service called udmg-server

To install UDMG Server, follow these steps:

1. Get the `.rpm` or `.deb` 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

To ensure the integrity of the downloaded package, verify its SHA256 checksum using the provided checksums file:

sha256sum -c udmg-server_3.2.1_checksums.txt

If the package is valid, the output will show:

# For RHEL-based systems
udmg-server_3.2.1_linux_amd64.rpm: OK
# For Debian-based systems
udmg-server_3.2.1_linux_amd64.deb: OK

3. Install the Package

Install the UDMG Server package using the following command:

RHEL-Based Systems (e.g., CentOS, Fedora)
Debian-Based Systems (e.g., Ubuntu)

sudo rpm -ivh udmg-server_3.2.1_linux_amd64.rpm

sudo dpkg -i udmg-server_3.2.1_linux_amd64.deb

4. Verify the Installation

After installation, the binaries and configuration files are located under /opt/udmg. To verify that the installation directory was created successfully, list its contents by running:

ls -l /opt/udmg

Example output:

total 12
drwxr-xr-x 2 root root 4096 Mar  9 15:14 bin
drwxr-xr-x 2 root udmg 4096 Mar  9 15:14 etc
drwxr-xr-x 4 root root 4096 Mar  9 15:14 share

The installer also creates a dedicated system group named udmg. Verify that it exists by running:

Command:

getent group udmg

Example output:

udmg:x:993:

The installer also creates a dedicated system user named udmg. Verify that it exists by running:

Command:

getent passwd udmg

Example output:

udmg:x:996:993:UDMG Server user:/home/udmg:/bin/bash

You can also confirm that the UDMG Server binary is installed and accessible by checking its version:

Command:

sudo -u udmg /opt/udmg/bin/udmg-server --version

Example output:

udmg-server version 3.2.1-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.

After installing the package, the next step is to configure the UDMG Server instance by editing the Configuration File at /opt/udmg/etc/udmg-server.hcl.

The default 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, edit the Configuration File 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 = "/home/udmg/"

info

For more context, refer to 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 and UDMG REST API. This key must be a strong secret of at least 30 characters and can contain only letters, numbers, and underscores.

udmg-server.hcl
jwt {
    signing_key = "<REPLACE_WITH_YOUR_LONG_RANDOM_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  = "/opt/udmg/certs/db-client-cert.pem"
        priv_key = "/opt/udmg/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

Then set it in the Configuration File:

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

    ...

}

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").
api.trusted_domains defines the allowed origins for the UDMG Admin UI when it is served from an external web server.

For example:

udmg-server.hcl
api {
    inet = "0.0.0.0"
    port = "8080"
    trusted_domains = [
        "udmg.my-company.com",
        "udmg-staging.my-company.com:9180",
    ]

    ...
}

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  = "/opt/udmg/certs/udmg-api-cert.pem"
        priv_key = "/opt/udmg/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 = "/opt/udmg/logs/udmg-server.log"

    ...
}

Ensure that the directory containing the log file exists and that the udmg user has write permissions to it.

You can create the log directory and assign the correct ownership and permissions with the following commands:

sudo mkdir -p /opt/udmg/logs
sudo chown -R udmg:udmg /opt/udmg/logs
sudo chmod 755 /opt/udmg/logs

Service Start

Once the configuration is complete, enable and start the UDMG Server service by running these commands:

sudo systemctl enable udmg-server
sudo systemctl start udmg-server

Install Verification

1. Verify That the Service Started Correctly

To verify that the UDMG Server started correctly, run the following command:

sudo systemctl status udmg-server

Example output:

 udmg-server.service - Stonebranch UDMG Server
     Loaded: loaded (/etc/systemd/system/udmg-server.service; enabled; preset: enabled)
     Active: active (running) since Mon 2026-03-09 16:17:17 -03; 13s ago
   Main PID: 8424 (sh)
      Tasks: 11 (limit: 12117)
     Memory: 13.1M (peak: 13.1M)
        CPU: 291ms
     CGroup: /system.slice/udmg-server.service
             ├─8424 /bin/sh -c "/opt/udmg/bin/udmg-server start -c /opt/udmg/etc/udmg-server.hcl"
             └─8425 /opt/udmg/bin/udmg-server start -c /opt/udmg/etc/udmg-server.hcl

Mar 09 16:17:17 victortomas-VirtualBox systemd[1]: Started udmg-server.service - Stonebranch UDMG Server.

2. Verify Listening Ports

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

sudo ss -ntalp | grep udmg

Example output:

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

3. Test UDMG REST API

Test the UDMG REST API port by running:

curl http://localhost:8080/auth/login/_csrf

Example output:

{"csrfToken":"e07df0cd-dabe-43dc-93cd-8a2fd4582e52"}

4. Test UDMG Observability API

Test the UDMG Observability API port by running:

curl http://localhost:7070/_/ping

Example output:

ACTIVE

5. Test the Web Server Port

Test the UDMG Admin UI web server port by running:

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

Expected output:

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

6. Open the UDMG Admin UI in Your Browser

Open your web browser and navigate to http://<UDMG_SERVER_HOST>:<PORT>/ui/ (or https://<UDMG_SERVER_HOST>:<PORT>/ui/ if HTTPS is 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.

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 .rpm or .deb Package​

2. Verify the Checksum​

3. Install the Package​

4. 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​

Service Start​

Install Verification​

1. Verify That the Service Started Correctly​

2. Verify Listening Ports​

3. Test UDMG REST API​

4. Test UDMG Observability API​

5. Test the Web Server Port​

6. Open the UDMG Admin UI in Your Browser​

Default Port Numbers​

Prerequisites

Installation

1. Get the `.rpm` or `.deb` Package

2. Verify the Checksum

3. Install the Package

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

Service Start

Install Verification

1. Verify That the Service Started Correctly

2. Verify Listening Ports

3. Test UDMG REST API

4. Test UDMG Observability API

5. Test the Web Server Port

6. Open the UDMG Admin UI in Your Browser

Default Port Numbers