Skip to content

Mapping job folder to a drive letter on windows

Feature availability

Available from: Resilio Active Everywhere 4.2.0. Extended in 4.2.7.
Available for: Hybrid work job, End-User Agents. In 4.2.7 extended to all Windows Agents outside Scaleout clusters and High Availability groups.

Overview

This guide is intended for system administrators managing file distribution using Hybrid Jobs with Windows End-user Agents. Drive mapping is designed to support specific customer scenarios where files must be organized under a predefined structure.

Configure drive mapping of the job folder in the Hybrid Work job

This functionality is supported only when using Hybrid Jobs and Windows End- user Agents. The root path used in the job must be a non-cloud location, not defined by user.

Hybrid Work Job Map Folder To

Admins can configure a job to map its root path to a specific drive letter (e.g., Z:). The agent will map this path in the context of the current user session.
Selected drive cannot be changed by editing the job. It's required to remove and add the Agent to the job with the new drive letter.

The MC will issue a warning if the chosen drive letter is already used in another job. This does not block saving but serves to prevent unintentional drive conflicts. 41456519665811

The Agent is designed to report specific error messages if drive mapping fails.

Best practices 
Assign unique drive letters per job to avoid conflicts and mapping failures. Carefully organize agent assignments so that no two conflicting jobs target the same device unless absolutely necessary. Always remove Agents from the job via the Management Console to ensure that drives are unmounted cleanly.

Configure drive mapping of the folder outside of the job

With Resilio Active Everywhere 4.2.7, the Agent can map any folder to a drive letter, including folders that are not part of a job. If a parent folder of a job is mapped in this way, the .sync service folder will appear inside the mapped drive as expected.

Agent must run as Local System. Otherwise, the mapped drive won't be accessible by the user.

To configure this, add a custom parameter to the Agent profile "map_folder_to_drive" and define the desired mapping rules. Example syntax: {"F:":"path1", "Z:":"path2", "X:":"%job_macro%"}. It will be applied to all Windows Agents using the Profile. Rule considerations and assumptions:

  • The drive letter must be specified in uppercase. Correct: {"F:":"some_path"}. Incorrect: {"f:": "some_path"}.
  • Job macros are supported. If multiple macros are defined in the custom parameter, only those that are actually used by a job and resolved by the Agent will be populated with data. %USERDEFINED% macro, aka "Ask user" option in job path picker, is not supported.
  • When specifying a local path, escape backslashes properly. Only absolute paths are supported. Example: "map_folder_to_drive":{"F:":"C:\\Documents\\Resilio Agent\\My files"}.
  • UNC paths are supported. Correct sytax would be "map_folder_to_drive":{"N:":"\\\\10.255.0.27\\shared-folder"}. Note the escaped backslashes.
  • If the drive is mapped to a non-existent path, it will appear as "Unavailable" in Windows Explorer.

To unmap a drive, remove the parameter or the corresponding rule from the Agent profile. Removing an Agent from a job does not unmap the drive, as this mapping is profile-based and not tied to any specific job.

Drive Mapping Lifecycle

When the Agent starts or the job begins execution, the drive mapping is automatically applied. By default the drive gets system's name, but it can be changed manually via Registry on the device:

  1. Open Registry Editor and navigate to HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\MountPoints2\Y where Y is the mapped drive letter.
  2. Create a string value _LabelFromReg and add the desired drive name. Save. No additional actions required, it’s applied immediately. Max label length is 32 characters.
    More details can be found here.
    42109053946643

The mapping is persistent:

  • Upon server restart;
  • If Agent process is not running (Agent is stopped). In this case hydrated files are accessible, new files cannot be fetched (downloaded) until the Agent is back online.

The Agent ensures the drive is correctly mapped upon job start, Agent restart, or system reboot.

If the Agent is gracefully removed from the job, the system will unmount the drive by default (job based mapping). However, in cases where the Agent is uninstalled or removed ungracefully, the mapped drive may remain and require manual cleanup.

Mapped drives can be seen in CMD with subst command from the current user's session. 41456719440659