Skip to main content

Folder Management

Directory path configuration determines where UDMG Server reads and writes files on the host, how transfers are isolated across Domains, and which directories are exposed to remote clients.

A well-defined folder strategy ensures predictable transfer behavior, enables safe reuse of Endpoints and Pipelines, and reduces operational risk. Incorrect path configuration can route files to unintended locations, cause permission errors, or create collisions when multiple transfers or Domains write to the same directory.

The sections below describe the global settings that establish UDMG Server's local filesystem layout. These settings apply across the system and directly influence how file paths are resolved at runtime.

Path Resolution​

Path resolution in UDMG Server is influenced by several factors, including the work directory, domain chroot settings, and the specific configuration of Endpoints and Pipelines. Understanding these factors is crucial for effectively managing file paths and ensuring predictable behavior during file transfers.

Work Directory Path​

The work_directory_path is a root-level argument in the Configuration File that defines UDMG Server's work directory.

This value serves two main purposes:

  • It is the base directory for relative paths set in the Configuration File. Absolute paths are not affected by work_directory_path (recommended for most configurations).
  • It is the base directory for Local Filesystem Endpoints when Domain Chroot is enabled (i.e., set to WORKDIR or WORKDIR+DOMAIN). In particular, it affects how the Root File Path and Temporary Path are resolved at runtime.

Example configuration:

udmg-server.hcl
# Linux
work_directory_path = "/var/opt/udmg/"
# Windows
work_directory_path = "C:\\UDMG\\WorkDir\\"
warning

If you change work_directory_path, ensure the udmg service user has permission to read/write within that directory and any subdirectories created under it. Also ensure the filesystem has sufficient space for temporary data under peak transfer load.

danger

Avoid changing work_directory_path after the system is in use. A work directory change can alter where UDMG expects to find or create directories and may affect existing Endpoint and Pipeline behavior.

Default Value and Runtime Behavior​

By default, work_directory_path is an empty string ("").

If left empty, UDMG uses the process's current working directory (CWD). The effective work directory therefore depends on how UDMG Server is started:

  • When started as a service, the process CWD is set by the service definition.
    • On Linux installations created from RPM/DEB packages, the default udmg-server service definition sets the CWD to:
      • /home/udmg/
    • On Windows installations created from the installer, the udmg-server service CWD is:
      • %WinDir%\System32
  • When started manually from the command line, the process CWD is the directory where you run the command.
tip

To avoid unintentional changes to the effective work directory, explicitly set work_directory_path in production environments.

Domain Chroot​

The security.domain_chroot argument is a global setting configured in the Configuration File. It controls how UDMG computes the base directory for Local Filesystem Endpoint paths.

The supported options are:

OptionDescription
NONE

No Domain Chroot is applied. Local Filesystem Endpoint paths are treated as host-absolute paths.

This is required to access different locations that cannot (either for business or technical reasons) be constrained under a common path, for instance:

  • /data1 (Linux)
  • D:\DATA (Windows)
  • \\host1\folder1 (Windows UNC path)
WORKDIRLocal Filesystem Endpoint paths are scoped under work_directory_path.
WORKDIR+DOMAINSame as WORKDIR, but UDMG also prepends the Domain name, creating a Domain-isolated layout under the work directory.

In other words, security.domain_chroot determines whether Local Filesystem Endpoint paths are treated as:

  1. Paths scoped under UDMG's work directory (WORKDIR); and optionally isolated per Domain (WORKDIR+DOMAIN).
  2. Absolute paths (NONE).

Example configuration:

udmg-server.hcl
security {
    domain_chroot = "WORKDIR+DOMAIN"
}
danger

Avoid changing security.domain_chroot after the system is in use. Changing it alters how UDMG computes local paths and can cause existing configurations to resolve to different locations.

Default Value​

By default, security.domain_chroot is set to WORKDIR+DOMAIN.

This default keeps Domains logically separated on disk under the work directory and reduces the risk of path collisions when multiple Domains use similar local filesystem layouts.

tip

Keep the default value (WORKDIR+DOMAIN) unless you have a specific requirement to share host directories across Domains (NONE or WORKDIR) or to scope paths only to the work directory without Domain isolation (WORKDIR).

Recommendations and Best Practices​

  • Treat work_directory_path and domain_chroot as "foundational" settings. Define them early in your deployment and avoid changing them after Endpoints and Pipelines are in use.
  • Explicitly set work_directory_path in production. Do not rely on defaults that can vary based on how the server is started (see Default Value and Runtime Behavior).
  • Use domain_chroot = "WORKDIR+DOMAIN" unless you have a strong reason not to. This is the safest default for multi-Domain environments and helps prevent cross-Domain path collisions.
  • Confirm ownership and permissions for the udmg service user. Ensure the udmg user can read/write (and traverse) the work directory and any subdirectories that UDMG creates under it.