UDMG for Linux Installation
- 1 Upgrading Universal Data Mover Gateway
- 2 Installing and Configuring the Components
- 2.2 Performing a manual installation
- 2.2.1 UDMG User Setup
- 2.2.2 UDMG Server
- 2.2.3 UDMG Authentication Proxy
- 2.2.4 UDMG Admin UI
- 2.2.5 UDMG Agent Proxy
- 2.2.5.1 Agent Proxy Server Configuration
- 2.2.5.2 Agent Proxy Client Configuration
- 2.2.6 Setup the Systemd Services
- 2.2.6.1 UDMG Server
- 2.2.6.2 UDMG Authentication Proxy
- 2.2.6.3 UDMG Agent Proxy
- 3 License application
- 4 Ports Configuration
- 5 Using UDMG with SELinux
- 6 References
For the UDMG Web Transfer Client, please refer to UDMG Web Transfer Client for Linux Installation.
Upgrading Universal Data Mover Gateway
Upgrading UDMG refers to the increase of a currently installed pre-2.0.x Version, Release, or Modification level of UDMG (1.5.x, 1.4.x, 1.3.x, 1.2.x) to UDMG 2.0.x.
As a precautionary measure, it is highly recommended that you back up the UDMG database prior to upgrading.
Upgrading from a pre-2.0 UDMG release
If you are upgrading an installation of UDMG from any release before 2.0.0.0, the following changes must be reviewed carefully.
License Key
Starting with UDMG version 2.0, a license key must be provided to enable file transfers.
Contact your Stonebranch representative or Customer Support to receive the license key before upgrading to version 2.0 or later.
Shared Account
(1) Local Accounts are converted to Shared Accounts
Before this change, a local account was only defined for a given local server and not allowed to have the same account for multiple protocols. For instance, to allow a partner to transfer files over SFTP and FTP, it was required to have both an SFTP and FTP local server, each with their own local account. Each account was then maintained independently, which created additional overhead in configuration and maintenance (password or key updates). A shared Account is created once and can be assigned to several Local Servers, sharing the same login, password, and authentication records.
A migrated account has the following characteristics:
Linked to the Local Server that owned the Local Account. The new Shared Account can later be assigned to other servers.
Member of the same Business Services as the Local Server. The Shared Account membership to Business Services can be modified later but must retain compatibility between Server memberships and Shared Account memberships
Account name is composed of the original server name and the login: <local_server name>-<local_account login>,for example, if the local account has a login of "common" and belongs to the local server "sftp", the new account name is "common-sftpr". The Share Account name can be edited later, it is only for internal use and does not affect the login that is used for authentication.
UDMG 1.5 local account
UDMG 2.0 migrated shared account
Enabled by default.
(2) New permission for Shared Account management
A new User and User Group permission, "sharedAccount", is created for the management of Shared Accounts.
The UDMG users and user groups are assigned these permissions by copying the existing server permissions. The refinement of server and sharedAccount permissions for the Users and User Groups can be done after the migration.
For example, if a UDMG user has server read and write permission, it is allowed to manage servers and local accounts. With the migration, it also obtains the sharedAccount read and write permissions to continue the management of accounts.
Start parameters
The start parameters for several services have changed.
Please review the start scripts, especially for manual installation or if the Systemd service files have been edited.
For a standard upgrade with the provided Linux packages, the service configuration is updated automatically
The following modules now require a 'start' command in server mode.
udmg-auth-proxy start -f configuration_file
udmg-agent-client start -f configuration_file
udmg-agent-server start -f configuration_file
Without it, they will only display the command line usage information.
In addition, a 'test' command allows the syntax of the configuration file to be verified without starting the server.
New configuration parameter with UDMG 2.0.0.0
Configuration Parameters
UDMG Server
Adds new database timeout option
[database]
; Threshold before warning for long-running queries, the default is 10 seconds
WarningTimeout=10sAdds a parameter to disable the implicit assignment of Transfer Rules. Before this change, a Transfer Rule was allowed for all servers, partners, and accounts right after creation. It was only restricted after an explicit assignment (whitelisting) to at least one server, partner, or account. The prior functionality created confusion and allowed unauthorized access to files and folders for third-party accounts during the time between the rule creation and its explicit assignment. The change allows the functionality to be disabled with the new UDMG Server configuration parameter
ExplicitRuleAssignment. When set to true, a Transfer Rule is only effective when it is explicitly linked with the intended target (local server, remote partner, remote or local account).
[rule]
; Disables global rules, requiring rules to be explicitly allowed to be used.
; ExplicitRuleAssignment = falseUDMG Admin UI
The recommended security settings for NGINX have been modified, with the inclusion of the following header directives. Please review the sample configuration on Installing NGINX Server page.
# Server Banner
server_tokens off;
# DEPRECATED Security Headers
add_header X-XSS-Protection "0";
add_header X-Frame-Options "SAMEORIGIN";
# Security Headers
add_header Content-Security-Policy "frame-ancestors 'self'";
add_header X-Content-Type-Options nosniff;
add_header Referrer-Policy "strict-origin";
add_header Strict-Transport-Security 'max-age=31536000; includeSubDomains; preload';
add_header Permissions-Policy "geolocation=(),midi=(),sync-xhr=(),microphone=(),camera=(),magnetometer=(),gyroscope=(),fullscreen=(self),payment=()";
add_header X-Permitted-Cross-Domain-Policies none;
location /service/ {
proxy_pass http://udmg_auth_proxy/;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
Agent Proxy Client
The section for the configuration of the target UDMG Server is renamed from
[gateway]to[server].New
secureoption to support HTTPS for the connection to the UDMG Server API
[server]
# UDMG Server Hostname or IP, and port
hostname = "localhost"
port = "8080"
# UDMG API protocol, set to true to select https, default is false for http
secure = false
# UDMG Server Username/Password
username = "admin"
password = "admin_password"Upgrading from a pre-1.3 UDMG release
Note
If you are upgrading an installation of UDMG from any release before 1.3.0.0, you must uninstall the older version before installing the new version.
Migration from releases before 1.2.1.1 (0.7.1-sb.3) is not supported anymore.
The installation packages, binaries, services, and environment variables have changed, and this does not allow for a standard upgrade.
It may be required to modify the work and data directories ownership or access rights and to update UDMG Server transfer rules to use paths that are accessible by the 'udmg' user.
The configuration files must be reviewed and compared between the old and new locations.
Special attention is required for the AESpassphrase parameter for UDMG Server. It must be the path for the file that was used by the previous release and must be accessible by the new service user. It is recommended to set an absolute path in the configuration file.
Pre-Installation / Upgrade Backups
The installation process overwrites the current files (exception: the configuration files are kept), this may affect your modifications.
Backing up the configuration files optimizes the time it takes you to get up and running after installing or upgrading.
/opt/udmg/etc/udmg/nginx/udmg.conf/opt/udmg/etc/udmg/agent/client.toml/opt/udmg/etc/udmg/agent/server.toml/opt/udmg/etc/udmg/auth-proxy/config.toml/opt/udmg/etc/udmg/web-transfer/config.toml/opt/udmg/etc/udmg-server/server.ini
After upgrading RPM or DEB packages, review the new configuration file templates (with the extension .rpmnew or .dpk-new) and edit the current configuration files to add new parameters or remove deprecated parameters.
Release Migration
The UDMG release version is stored in the database to ensure the data structure is compatible with the version of the UDMG components.
After upgrading the component binaries and before starting the UDMG Server, it is required to perform the release migration step.
Note
The release migration is altering the database structure and requires the database user to have the DDL privileges fore creating, altering and deleting database its own objects.
Please refer to Installing a Database section for the requires privileges for each the database vendor.
The udmg-server "migrate" command handles the necessary database updates and the setting of the internal version.
$ /opt/udmg/bin/udmg-server migrate --help
Usage:
udmg-server [OPTIONS] migrate [migrate-OPTIONS] [version]
Help Options:
-h, --help Show this help message
[migrate command options]
-c, --config= The configuration file to use
-d, --dry-run Simulate the migration but does not commit the changes
-l, --list List Migrations
-f, --file= Writes the migration commands into a file instead of sending them to the database
-v, --verbose Show verbose debug information. Can be repeated to increase verbosity
[migrate command arguments]
version: The version to which the database should be migratedThe configuration file is used for the server mode, with the parameter for accessing the target database.
To get the list of supported target versions, use the list parameter. The last value is the release version of the udmg-server and the default target version. The current version of the UDMG database structure is shown with the [DATABASE] tag:
$ /opt/udmg/bin/udmg-server migrate -c /opt/udmg/etc/udmg-server/server.ini --list | tail -n 2
1.5.0 [DATABASE]
2.0.0
2.0.1 [DEFAULT]It is recommended to set the verbose parameter (3 times) to follow the progress. If not specified on the command line, the target version is the latest release number.
$ /opt/udmg/bin/udmg-server migrate -c /opt/udmg/etc/udmg-server/server.ini -vvv
2025/06/10 20:01:51 [INFO ] Migration: Starting upgrade migration from 1.5.0 to 2.0.1
2025/06/10 20:01:51 [INFO ] Migration: Applying migration 'Drop the normalized transfer view'
2025/06/10 20:01:51 [INFO ] Migration: Applying migration 'Add a "src_filename, dest_filename" columns to the transfers table'
2025/06/10 20:01:51 [INFO ] Migration: Applying migration 'Add a "src_filename, dest_filename" columns to the history table'
2025/06/10 20:01:51 [INFO ] Migration: Applying migration 'Restore and update the normalized transfer view with the new filename'
2025/06/10 20:01:51 [DEBUG ] Migration: Skipped migration 'Check for required MySQL permissions'
2025/06/10 20:01:51 [INFO ] Migration: Applying migration 'Add a 'local_storage' column to the 'local_accounts' table'
2025/06/10 20:01:51 [INFO ] Migration: Applying migration 'Fix the 'sb_user_session' table'
2025/06/10 20:01:51 [INFO ] Migration: Applying migration 'Create the 'sb_license' table'
2025/06/10 20:01:51 [INFO ] Migration: Applying migration 'Drop the normalized transfer view'
2025/06/10 20:01:51 [INFO ] Migration: Applying migration 'Add a 'local_agent_id' column to the 'transfers' table'
2025/06/10 20:01:51 [INFO ] Migration: Applying migration 'Update the 'sb_generic_group_join' table'
2025/06/10 20:01:51 [INFO ] Migration: Applying migration 'Update the 'sb_user_group_permission' table'
2025/06/10 20:01:51 [INFO ] Migration: Applying migration 'Update the 'users' table'
2025/06/10 20:01:51 [INFO ] Migration: Applying migration 'Create the 'sb_local_account_auth' table'
2025/06/10 20:01:52 [INFO ] Migration: Applying migration 'Drop the 'local_agent_id' column from the 'local_accounts' table'
2025/06/10 20:01:52 [INFO ] Migration: Applying migration 'Restore and update the normalized transfer view with the new local agent id'
2025/06/10 20:01:52 [INFO ] Migration: Applying migration 'Create the 'sb_adhoc_share' table'
2025/06/10 20:01:52 [INFO ] Migration: Applying migration 'Create the 'sb_adhoc_download' table'
2025/06/10 20:01:52 [INFO ] Migration: Applying migration 'Bump database version to 2.0.1'After the migration, the services for UDMG components can be started.
Upgrading Universal Data Mover Gateway for Linux
Upgrading with Linux Software Packages
Step 1 | Contact your Stonebranch representative or Customer Support to receive the software package for the intended operating system. |
|---|---|
Step 2 | Perform the recommended backup of configuration files. |
Step 3 | Stop the components services. The exact steps depend on the system architecture and the deployed components, for example: On the main UDMG host:
On the Proxy host: |
Step 4 | Upgrade the UDMG packages (RPM or DEB). For RPM based Linux: On the main UDMG host:
On the Proxy host:
For Debian based Linux: On the main UDMG host:
On the Proxy host:
|
Step 5 | Review the component configuration files. On the main UDMG host: On the Proxy host:
Note that new configuration file templates (with the extension .rpmnew or .dpk-new) that contain all the allowed parameters are added during the software package upgrade. Note The default upstream port to reach the UDMG Authentication Proxy is set to 5775 in Please review and make sure that the same port (either 5000 or 5775) is also defined in |
Step 6 | Perform the release migration. |
Step 7 | Review the component service configuration files. For instance, the UDMG Authentication Proxy service file ( udmg-auth-proxy.service (Version 1.5)[Unit]
Description=Stonebranch UDMG Authentication Proxy
[Service]
Type=simple
User=udmg
Group=udmg
WorkingDirectory=/home/udmg
Environment="UDMG_AUTH_PROXY_CONFIG=/opt/udmg/etc/udmg/auth-proxy/config.toml"
ExecStart=/bin/sh -c 'exec /opt/udmg/bin/udmg-auth-proxy'
Restart=on-failure
SyslogIdentifier=udmg-auth-proxy
SyslogFacility=local0
[Install]
WantedBy=multi-user.target
Note the addition of the udmg-auth-proxy.service (Version 2.0)[Unit]
Description=Stonebranch UDMG Authentication Proxy
[Service]
Type=simple
User=udmg
Group=udmg
WorkingDirectory=/home/udmg
Environment="UDMG_AUTH_PROXY_CONFIG=/opt/udmg/etc/udmg/auth-proxy/config.toml"
ExecStart=/bin/sh -c 'exec /opt/udmg/bin/udmg-auth-proxy start'
Restart=on-failure
SyslogIdentifier=udmg-auth-proxy
SyslogFacility=local0
[Install]
WantedBy=multi-user.targetThe same applies for the other components:
|
Step 8 | Start the components services. The exact steps depend on the system architecture and the deployed components, for example: On the Proxy host:
On the main UDMG host:
|
Step 9 | Verify or apply the license; see UDMG Licensing. |
Upgrading a Manual Installation
Step 1 | Contact your Stonebranch representative or Customer Support to receive the software package for the intended operating system. |
|---|---|
Step 2 | Perform the recommended backup of configuration files. |
Step 3 | Stop the components services. The exact steps depend on the system architecture and the deployed components, for example: On the main UDMG host: On the Proxy host: |
Step 4 | Replace the component binaries:
Change ownership/permissions on new files:
Upgrade the Admin UI:
|
Step 5 | Review the component configuration files. Refer to each component installation section below for the list of parameters. |
Step 6 | Perform the release migration. |
Step 7 | Review the component service configuration files. For instance, the UDMG Authentication Proxy service file ( udmg-auth-proxy.service (Version 1.5)[Unit]
Description=Stonebranch UDMG Authentication Proxy
[Service]
Type=simple
User=udmg
Group=udmg
WorkingDirectory=/home/udmg
Environment="UDMG_AUTH_PROXY_CONFIG=/opt/udmg/etc/udmg/auth-proxy/config.toml"
ExecStart=/bin/sh -c 'exec /opt/udmg/bin/udmg-auth-proxy'
Restart=on-failure
SyslogIdentifier=udmg-auth-proxy
SyslogFacility=local0
[Install]
WantedBy=multi-user.target
Note the addition of the udmg-auth-proxy.service (Version 2.0)[Unit]
Description=Stonebranch UDMG Authentication Proxy
[Service]
Type=simple
User=udmg
Group=udmg
WorkingDirectory=/home/udmg
Environment="UDMG_AUTH_PROXY_CONFIG=/opt/udmg/etc/udmg/auth-proxy/config.toml"
ExecStart=/bin/sh -c 'exec /opt/udmg/bin/udmg-auth-proxy start'
Restart=on-failure
SyslogIdentifier=udmg-auth-proxy
SyslogFacility=local0
[Install]
WantedBy=multi-user.targetThe same applies for the other components:
|
Step 8 | Start the components services. The exact steps depend on the system architecture and the deployed components, for example: On the Proxy host:
On the main UDMG host:
|
Step 9 | Verify or apply the license; see UDMG Licensing. |
Installing and Configuring the Components
Note
Starting with UDMG version 2.0, a license key must be provided to enable file transfers.
Contact your Stonebranch representative or Customer Support to receive the license key before installing version 2.0 or later.
Installing with Linux Software Packages
Step 1 | Contact your Stonebranch representative or Customer Support to receive the software package for the intended operating system. |
|---|---|
Step 2 | Install the UDMG packages (RPM or DEB). For RPM based Linux: On the main UDMG host:
On the Proxy host:
For Debian based Linux: On the main UDMG host:
On the Proxy host:
|
Step 3 | Review the component configuration files. On the main UDMG host:
On the Proxy host:
Note that the UDMG Agent Server requires an SSH key prior to start, the default location is under /data and it can be created with the following commands:
The location and file names can be adjusted with the ssh_key and ssh_key_pub configuration parameters. |
Step 4 | Start the components services. The exact steps depend on the system architecture and the deployed components, for example: On the Proxy host:
On the main UDMG host:
|
Performing a manual installation
Note
Starting with UDMG version 2.0, a license key must be provided to enable file transfers.
Contact your Stonebranch representative or Customer Support to receive the license key before installing version 2.0 or later.
UDMG User Setup
Create a dedicated user for running the UDMG modules and to be the owner of the files that are transferred by UDMG.
# sudo groupadd udmg
# sudo useradd -g udmg udmg
UDMG Server
Create the configuration file /opt/udmg/etc/udmg-server/server.ini with the following parameters:
# sudo mkdir -p /opt/udmg/etc/udmg-server# sudo vi /opt/udmg/etc/udmg-server/server.ini
Note
The lines starting with a semicolon ';' or a hash '#' are comments, either describing the option or showing the default value.
The parameters must be adapted to your environment, in particular:
"paths" section: GatewayHome
"log" section: LogLevel, LogTo, LogPath
"admin" section: Host, Port
"database" section: Type, Address, Name, User, Password
Note
About the log section:
The DEBUG and TRACE log levels are not recommended for production environments.
The detailed log feature (distinct log file for each transfer) is disabled when the log level is set to ERROR or CRITICAL.
Note
About the global section: the requested OS file and directory creation permissions are applied after the umask of the OS user that is running the UDMG Server process.
## (c) Copyright 2024 Stonebranch, Inc., All rights reserved.## Stonebranch, Inc.# Universal Data Mover Gateway Server Configuration File## This configuration file specifies global options for the # udmg-server program. ## The configuration file is organized with the grouping of options under # different section that are marked by brackets: [section_name]# This organization should be maintained when modifying the file.## The file syntax is:## - Lines starting with a # or a ; are comments.# - Blank lines are ignored.# - Option lines are 'keyword = value' format.# - keywords are not case sensitive.# - keywords can start in any column.# - Case sensitivity of the value depends on the value being specified.# For example, a yes or no option is not case sensitive, but a file# or directory name is.# - Values must be enclosed in quotations marks (") or apostrophes (')# if the value contains a space or tab.# - File or folder path on Windows platform must be written with one of the following syntaxes:# LogPath = "C:/UDMG/UDMG Server/logs"# LogPath = "C://UDMG//UDMG Server//logs"# LogPath = "C:\\UDMG\\UDMG Server\\logs"# LogPath = C:\UDMG\UDMG Server\logs# LogPath = C:/UDMG/UDMG Server/logs######################################################################
[global]; The name given to identify this UDMG installation environment. It must be the same for all the nodes in an High Availability cluster.GatewayName = sb-mft-01
; Default OS permission for created files; FilePermissions = 770
; Default OS permission for created directories; DirPermissions = 770
[paths]
; The root directory of the gateway. By default, it is the working directory of the process.GatewayHome = /home/udmg/udmg-server
; The directory for all incoming files.; DefaultInDir = in
; The directory for all outgoing files.; DefaultOutDir = out
; The directory for all running transfer files.; DefaultTmpDir = tmp
[log]; All messages with a severity above this level will be logged. Possible values are TRACE, DEBUG, INFO, WARNING, ERROR and CRITICAL.Level = INFO
; The path to the file where the logs must be written. Special values 'stdout' and 'syslog' log respectively to the standard output and to the syslog daemon.; LogTo = stdout
; If LogTo is set on 'syslog', the logs will be written to this facility.; SyslogFacility = local0
; The directory for the log files of the local servers, partners, and transfers.
; No default, if not provided then the detailed log feature is disabled. If not present, the directory is created with DirPermissions.