Skip to content

File locking in Resilio Active Everywhere jobs

Feature availability

Supported Platforms: Windows_x64 10 and newer.
Not supported: arm-based Windows, other platforms, including mobiles.
Functionalities Covered: Synchronization, File Caching, Hybrid jobs, local file access and access over SMB.

Install driver and configure files locks in a job

To install file locks driver and enable file locking:

  1. Install the Agent on each device, using an account with administrative privileges. Make sure to include the Share locks driver feature.

    Driver availability for different Windows accounts

    By default, further use of the driver is available for Agents running as SYSTEM account or an account from Administrators group. To utilize the functionality with the Agent running with a non-system, non-admin account, download and run this script before creating jobs passing the desired account_name as parameter. For example:

    • to configure access to the driver for userA run:configAccessToDriver.ps1 userA
    • to configure access to the driver for any user runconfigAccessToDriver.ps1 everybody

    Two Resilio Agents installed on same computer

    In the setups with two Resilio Agent services installed and running on the same device, only one of them maintains communication with the file lock driver and can perform file locking in a job - the first one which was added in a job with File locking enabled.

  2. In Management Console , click Jobs and select the Configure Jobs tab.

  3. Locate and click the job definition for which you want to enable file locking.

  4. In the Settings tab:

    1. Select the File Locking option.

    Note

    For Resilio Agents older than 4.1.1, enabling or disabling file locking feature requires restarting the agent service.

    1. (Optional) Change the time after which the lock server will release a locked file.
    2. (Optional) Change the default locked files update interval.

    Warning

    For optimal performance, we recommend leaving the default value unchanged.

    1. Select access level when the lock server is unavailable:
      • No - No access to all files in the job.
      • Read-only - Only ability to read files.
      • Full - Read and write access to files.
    2. In the Ignore locks for these files and folder text input area, provide regular expressions (PCRE2 syntax) to match files and folders that you want to exclude from locking. Add each regular expression in a separate line.

    file-locking-regexp-example.png

Select Agents in the file lock job

To enforce the locks on workstations, even without an Agent installed there, the Agent has to be set up on the source server, pointing to the physical location of the folder that's being shared

File lock feature is supported for Windows Agents, not arm-based CPU, v4.1 and newer. Agents of other OS can participate in such a job, not imposing the locks on files. One Lock Server is required in the job - it manages all metadata of locked files in the job and distributes it to others. . Continuous lock metadata availability is provided by adding Locks servers to a High Availability group.

High availability groups not compatible with locking of the files

Windows Agents, being a part of a HA group in a job with enabled locks do not impose the locks on open files, and files remain accessible for editing for other users.

Lock Server and its role in the job

The following Agents can take the role of a Lock Server:

  • Windows, Linux and macOS Agent. Additionally, Windows Lock server can also act as a lock client and impose lock on locally opened files.
  • An Agent synchronizing a cloud storage can be selected as a lock server. Locks are not imposed on objects though.

Presence and online status of the Lock server is vital for the file locking functionality to work. All communication between Agents and MC regarding the locked files is done through the Lock server. Agents will report the the error and limit access to local files if:

  • They're not connected to the Lock server.
  • Lock server is paused.
  • The Agent itself is paused.
  • The job itself is paused.
  • Lock server is unlicensed.

Monitor and manage locked files in a job

Access the 'File locks' tab in the job run to monitor locked files in the job. This tab provides details on locked files, associated processes, Agents, and lock specifics.
The information is received upon request from the Lock Server. If it’s not connected to the MC, no info can be fetched here.

Lock type depends on the application with which the file is opened. Not all applications implement requested access to the files or only implement full access. To interpret the lock type and app’s requested access, refer below, where RWD stands for Read-Write-Delete:

Unlock files for others by:

  • Closing the file on the device.
  • Manually from the File lock tab. Select a file (multi-selection is not supported) and click "Unlock".
  • Automatically after the configured lock timeout. Default is 5 hours, counting from the last access time of the file. In most app's usage scenarios it matches the Lock duration reported on the MC.

Files remain locked even if the lock owner is removed from the job, until the admin unlocks it from MC or lock times out.

File unlock may fail sometimes for a generic reason. Try again a minute later

File lock conflicts

File lock conflicts may happen if the same file is opened on multiple Agents within the lock propagation timeframe. The first Agent that conforms the file open with Lock server becomes the lock owner. Other Agents in the job report the conflicting access error and the files are not available for them for editing. Depending on the application, they may or may not receive a warning about it.
File access conflicts are not detected for the Agents working under high load.

Manage the driver

Driver is installed in C:\Program Files\Resilio Connect Agent\rsldrv directory and registers itself in the system as driver.
Ensure the Resilio File locking driver is running by querying its state in elevated Command Prompt or PowerShell using the command: sc.exe query rsldrv. Other commands are sc.exe query/start/stop rsldrv.

Each Agent version must match the driver version for compatibility. Be sure to install the driver together with the updated Agent.
If the driver is not running or the driver version is not compatible with the installed Agent, the Agents will report the corresponding error in the jobs.

In the system registry the driver keeps the key records of the job folders with enabled file locking features (HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\rsldrv\Shares).
The corresponding key entry is removed from the registry after removing the job. If the job is removed ungracefully from the Agent and the entry remains, this might affect further usage of the directory and manual deleting the entry from the registry is recommended. Contact support for assistance.

Peculiarities and limitations

Not supported for Windows Agents in a Windows cluster, v 4.1.0

Files that were opened before job creation are not locked and are not reported as locked in MC. Same refers to functionality "Restart the job on the Agent".

MS Word files located on a USB drive do not impose the lock

Agent and driver must be running together for the functionality to work. If the Agent process is stopped, while the driver is working, the user won’t have access to any file in the job folder. If you need to stop the Agent for a reason, be sure to stop the driver as well.

Renaming of the locked files on remote devices works with peculiarities and may lead to edit conflicts. Try avoiding renames of the locked files and their parent directories. Examples include, but are not limited to:

  • If a file is opened on a deviceA, and a different file with the same name is moved (not copied) in its place on deviceB, the file is replaced without any error.
  • Similarly, such a file can be renamed on deviceB, and it will be propagated to remote devices.
  • Similarly, on deviceB renaming of a file that is not locked to a file that is locked works without any errors.

If a file is accessed through SMB and SMB connection is dropped, the file gets unlocked.

For files accessed over SMB (in cache jobs, for example) on Locked files tab:

  • No process is reported, it’s unknown.
  • The user SID reported is the user who was authorized while mounting SMB share, the same user name as returned in net files command executed on SMB server.
  • The Agent reported is the Cache gateway server in the job.

Files accessed over SMB require additional time to set and release locks. It may be up to 10 seconds.

On Windows Server 2016, if a file is deleted while being locked, it remains locked. Unlock it manually or rescan the folder.