Skip to main content

UDMG Server Installation

This guide explains how to install UDMG Server 3.2 on RHEL-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 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 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 following command:

sha256sum -c udmg-server_3.2_checksums.txt

3. Install the Package​

Install the UDMG Server RPM package using the following command:

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

4. Check the Installation​

After installation, the binaries and configuration files are located under /opt/udmg. The installer also creates the dedicated system user and group udmg. You can verify their existence by running:

Command:

getent passwd udmg

Example output:

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

Command:

getent group udmg

Example output:

udmg:x:993:

Command:

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

Example output:

udmg-server version 3.2.0-b2168:2d0192f4:HEAD:2025-05-30T20:49:20+00:00
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, follow these steps:

1. Open the Configuration File​

Open the /opt/udmg/etc/udmg-server.hcl file in your preferred text editor. For example:

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

2. jwt Block​

Configure the jwt block to set the JWT signing key used to sign access and refresh tokens for the UDMG REST API. This key must be a strong secret (at least 30 characters, using only letters, numbers, and underscores).

/opt/udmg/etc/udmg-server.hcl
jwt {
    signing_key = "your-long-random-jwt-signing-key-here"
}

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

a. Specifying Individual Parameters (Any Engine)​

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

/opt/udmg/etc/udmg-server.hcl
database {
    engine   = "mysql"
    name     = "udmg"
    hostname = "localhost"
    port     = 3306
    user     = "udmg"
    password = "udmg-mysql-password"
}

b. Using a DSN in TNS Format (Only for Oracle)​

For Oracle databases, you can also configure the database block using a DSN, instead of individual arguments. For this, UDMG supports TNS descriptors using a multiline string (heredoc).

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

/opt/udmg/etc/udmg-server.hcl
database {
    engine   = "oracle"
    user     = "udmg"
    password = "udmg-oracle-password"
    dsn = <<-EOT
        (DESCRIPTION=
            (ADDRESS=(PROTOCOL=TCP)(HOST=hostname)(PORT=1521))
            (CONNECT_DATA=(SERVICE_NAME=service_name)))
    EOT
}

When using the TNS descriptor format:

  • The database.dsn value is a multiline string defined with heredoc syntax (<<-EOT ... EOT).
  • Replace hostname, 1521, and service_name with your Oracle listener host, port, and service name.
  • The database.user and database.password fields are required.
  • When database.dsn is set, the database.hostname, database.port, and database.name arguments values are ignored.

4. database.secure Block​

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

Set database.secure.enable to true to enforce encrypted connections 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.

/opt/udmg/etc/udmg-server.hcl
database {
    engine   = "postgres"
    name     = "udmg"
    hostname = "db.example.com"
    port     = 5432
    user     = "udmg"
    password = "your-db-password"

    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).
  • Is recommended to be provided via the UDMG_SECURITY_PASSPHRASE_KEY environment variable in production.

You can generate a suitable value with, for example:

openssl rand -hex 32

Then set it in the Configuration File:

/opt/udmg/etc/udmg-server.hcl
security {
    passphrase_key = "your-64-character-hexadecimal-string-here"
}

6. api Block​

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

  • api.inet controls the bind address (for example, 0.0.0.0 to listen on all interfaces).
  • api.port sets the TCP port for the API (default: "8080").
  • api.trusted_domains defines the allowed origins for the Admin UI when it is served from an external web server.
  • The nested api.secure block enables HTTPS and configures the TLS certificate and key used by the API.

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) in PEM format:

/opt/udmg/etc/udmg-server.hcl
api {
    inet = "0.0.0.0"
    port = "8080"

    trusted_domains = [
        "udmg.my-company.com",
        "udmg-staging.my-company.com:9180",
    ]

    secure {
        enable   = true
        pub_key  = "/opt/udmg/certs/udmg-api-cert.pem"
        priv_key = "/opt/udmg/certs/udmg-api-key.pem"
    }
}

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

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: disabled) Active: active (running) since Wed 2025-12-17 09:42:14 UTC; 7h ago Main PID: 838900 (udmg-server) Tasks: 9 (limit: 47631) Memory: 37.9M CPU: 48.627s CGroup: /system.slice/udmg-server.service └─838900 /opt/udmg/bin/udmg-server start -c /opt/udmg/etc/udmg-server.hcl

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.

Login

info

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

Default Port Numbers​

Default Port NumberDescriptionConfiguration File Argument
8080UDMG Server API Portapi.port
7070UDMG Server Observability API Portobservability.api.port
4222UDMG Server Cluster Client Portcluster.client_port
6222UDMG Server Cluster Server Portcluster.cluster_port