Windows Host Installation

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

Prerequisites

Administrator privileges on the Windows host where UDMG Server will be installed.
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 Windows installer that performs the following actions:

Deployment of the application files under C:\Program Files\Stonebranch\UDMG Server\
Configuration of a system service called udmg-server

To install UDMG Server, follow these steps:

1. Get the installer file

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:

Get-FileHash -Algorithm SHA256 udmg-server_3.2.1-setup.exe

3. Run the Installer

Run the UDMG Server installer and follow the prompts in the installation wizard to complete the installation.

Select the desired installation path or accept the default (C:\Program Files\Stonebranch\UDMG Server\).

4. Check the Installation

After installation, the binaries and configuration files are located in the installation folder.

You can verify their existence by running:

Command:

Get-LocalUser -Name udmg

Example output:

Name              : udmg
Description       : UDMG Server user
SID               : S-1-5-21-1234567890-1234567890-1234567890-1001
AccountDomainSid  : S-1-5-21-1234567890-1234567890-1234567890
Enabled           : True

Command:

Get-LocalGroup -Name udmg

Example output:

Name              : udmg
Description       : UDMG Server group
SID               : S-1-5-21-1234567890-1234567890-1234567890-1001
AccountDomainSid  : S-1-5-21-1234567890-1234567890-1234567890

Command:

"C:\Program Files\Stonebranch\UDMG Server\udmg-server.exe" --version

Example output:

udmg-server version 3.3.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 software, the next step is to configure the UDMG Server instance by editing the Configuration File (by default at C:\Program Files\Stonebranch\UDMG Server\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 = "C:\\Program Files\\Stonebranch\\UDMG Server\\"

info

For more context, refer to Work Directory Path.

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

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

2. `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:

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 single line string.

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

udmg-server.hcl
database {
    engine   = "oracle"
    user     = "udmg"
    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, the database.hostname, database.port, and database.name arguments values are ignored.

3. `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.

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  = "C:\\Program Files\\Stonebranch\\UDMG Server\\certs\\db-client-cert.pem"
        priv_key = "C:\\Program Files\\Stonebranch\\UDMG Server\\certs\\db-client-key.pem"
    }
}

4. `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 Windows PowerShell Get-Random:

$UDMG_SECURITY_PASSPHRASE_KEY=(1..64|%{'{0:X}'-f(Get-Random -Max 16)})-join''
$UDMG_SECURITY_PASSPHRASE_KEY

A more secure method is to use RandomNumberGenerator:

$UDMG_SECURITY_PASSPHRASE_KEY = & {
  $b=[byte[]]::new(32);
  [Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($b);
  try { ([BitConverter]::ToString($b)-replace '-','').ToLowerInvariant() }
  finally { [Array]::Clear($b,0,$b.Length) };
}
$UDMG_SECURITY_PASSPHRASE_KEY

Then set it in the Configuration File:

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

warning

For production environments, we strongly recommend to provide 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.

5. `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:

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  = "C:\\Program Files\\Stonebranch\\UDMG Server\\certs\\udmg-api-cert.pem"
        priv_key = "C:\\Program Files\\Stonebranch\\UDMG Server\\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:

Set-Service -Name "udmg-server" -StartupType Automatic
Start-Service -Name "udmg-server"

Install Verification

1. Verify That the Service Started Correctly

To confirm that the Windows service is installed and currently running, run the following command:

Get-Service -Name "udmg-server"

Example output:

Status   Name         DisplayName
------   ----         -----------
Running  udmg-server  Stonebranch UDMG Server

2. Verify Listening Ports

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

Get-NetTCPConnection -State Listen |
  Where-Object { $_.OwningProcess -eq (Get-Process -Name "udmg-server").Id } |
  Select-Object LocalAddress, LocalPort, OwningProcess |
  Sort-Object LocalPort

Example output:

LocalAddress LocalPort OwningProcess
------------ --------- ------------
0.0.0.0      4222      3772
0.0.0.0      6222      3772
0.0.0.0      7070      3772
0.0.0.0      8080      3772

3. Test UDMG REST API

Test the UDMG REST API port by running:

(Invoke-WebRequest -Uri "http://localhost:8080/auth/login/_csrf").Content

Example output:

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

4. Test UDMG Observability API

Test the UDMG Observability API port by running:

(Invoke-WebRequest -Uri "http://localhost:7070/_/ping").Content

Example output:

ACTIVE

5. Test the Web Server

Test the UDMG Admin UI web server port by running:

(Invoke-WebRequest -Uri "http://localhost:8080/ui/").Content |
  Select-String -Pattern "<title>"

Expected output:

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

6. Open the UDMG Admin UI in Your Browser

In a web browser, navigate to:

http://<UDMG_SERVER_HOST>:<PORT>/ui/, or
https://<UDMG_SERVER_HOST>:<PORT>/ui/ (if HTTPS is enabled).

Replace <UDMG_SERVER_HOST> with the 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 installer file​

2. Verify the Checksum​

3. Run the Installer​

4. Check the Installation​

Configuration​

1. Work Directory Path​

1. jwt Block​

2. database Block​

a. Specifying Individual Parameters (Any Engine)​

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

3. database.secure Block​

4. security Block​

5. api 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​

6. Open the UDMG Admin UI in Your Browser​

Default Port Numbers​

Prerequisites

Installation

1. Get the installer file

2. Verify the Checksum

3. Run the Installer

4. Check the Installation

Configuration

1. Work Directory Path

1. `jwt` Block

2. `database` Block

a. Specifying Individual Parameters (Any Engine)

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

3. `database.secure` Block

4. `security` Block

5. `api` 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

6. Open the UDMG Admin UI in Your Browser

Default Port Numbers