Skip to content

File locking

Feature availability

Supported platforms: Windows 10 (x64) and newer (v4.1.0 and newer), macOS 26 Tahoe or newer (v6.0.0 and newer).
Not supported platforms: arm-based Windows, other platforms, including mobile devices.
Types of locks: Asynchronious (v4.1.0 and newer), Synchronous file locking in Enterprise Hybrid Work. MacOS Agent supports only Syncronous File locks.
Functionalities covered: Synchronization, File Caching, Hybrid Work and Enterprise Hybrid Work jobs.

File locking enables efficient collaboration on shared files in a job, preventing data loss and conflicts. It allows users to lock files while they're being edited, ensuring that other users cannot modify them until the lock is released.

Active Everywhere features standard, asynchronous file locking, which is available in Hybrid Work, File Caching and Synchronization jobs, and synchronous file locking, which can be enabled in Enterprise Hybrid Work jobs.

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.

    29750242249107

    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 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. For optimal performance, we recommend leaving the default value unchanged.

    3. Select files 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.
    4. 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.

    41866274816147

Agents participating in a Job with file locking

File locking is available in Resilio Active Everywhere 4.1 or newer, by Agents running on Windows x64 (synchronous and asynchronous locks) and macOS (synchronous locks). Agents running on other operating systems and platforms, can participate in a Job with file locking enabled, without imposing locks on files.

High availability groups and file locking

High availability (HA) groups incompatible with Resilio's asynchronous file locking feature. Windows Agents, being a part of a high availability 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

Lock server manages all metadata of locked files in the job and distributes it to others. To ensure continuous lock metadata availability, set up the Agent acting as the lock server in a high availability group.

Note

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.

The following Agents can take the role of a Lock Server in Hybrid Work, File caching and Synchronization Jobs:

  • 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.

In Enterprise Hybrid Work Jobs, the Primary Storage Agent assumes the role of the lock server.

Presence and online status of the Lock server is essential for the file locking functionality to work. All communication between Agents and the Management Console regarding the locked files is done through the Lock server. Agents will report an 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

You can monitor and manage file locks in the Job runs File locks tab. This tab provides details on locked files such as associated processes, Agents, or lock type.

30058875625107

Important

Lock information is stored on the Lock Server and it's sent to the Management Console upon request. If the Lock Server is not currently connected to the Management Console, no lock information will be available.

macOS Agents file lock reporting

macOS Agents don't report username and process name for locked files.

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:

29750435446675

Unlock files by:

  • Closing the file on the device.
  • Manually releasing the lock by selecting the file in the File lock tab and clicking Unlock.
  • Automatically releasing the lock 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 Management Console.

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

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

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 confirms 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

Resilio lock 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.

33332993202067

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.

33332993207059

Synchronous file locking

Info

Synchronous file locking is available in Active Everywhere 6.0 and newer, in Enterprise Hybrid Work Jobs.

Synchronous locking mechanism implements a centralized approach to file locking, solving a number of issues related to concurrent access and ensuring data consistency. Advantages of synchronous file locking include:

  • Lock acquisition conflicts mitigation - In synchronous file locking, file access is blocked until the lock server confirms the lock acquisition, eliminating potential lock acquisition conflicts.
  • Data loss prevention - Synchronous locking ensures that end users collaborating on the same project always access the most up-to-date version of the file, preventing data loss and inconsistencies.
  • Cloud storage objects and network shares support - Synchronous locking also enables imposing locks on cloud storage objects and network shares.

Peculiarities and limitations

Synchronous and asynchronous file locking

  • Windows end user Agents don't lock files if the Job folder is specified as a UNC path.

Asynchronous file locking

  • Not supported for Windows Agents in a Windows cluster.
  • Files that were opened before the Job was created are not locked and are not reported as locked in the Management Console. Same applies to functionality "Restart the job on the Agent".
  • Microsoft Word files located on USB drives do not impose locks.
  • 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, make 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 to avoid renaming the locked files and their parent directories. Examples include, but are not limited to:

    • If a file is opened on a device A, and a different file with the same name is moved (not copied) in its place on device B, the file is replaced without any error.
    • Similarly, such a file can be renamed on device B, and it will be propagated to remote devices.
    • Similarly, on device B 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 (for example, in File Caching jobs) on the 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 Caching 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.

Synchronous file locking

  • macOS Agents don't report username and process name for locked files.
  • There is a small time window (up to a few seconds) when the file is unlocked while it's moved from the temporary location to the final path.
  • In high availability (HA) groups, when a leader is lost, files locked by the HA group will be unlocked until a new leader is elected.
  • Asynchronous locking file ignore list can cause locking/unlocking issues due to different entry versions.
  • If the Primary Storage Agent often restarts, it's advised to lower the shared_locks_lock_timeout value, because lock server reset results in acquiring a new lock, resetting the timeout timer.
  • NAS locks only. If a folder with files was added to the client and removed in a short time, but between creation and deletion someone adds a file inside this folder on the server side, then it won't be added to Active Everywhere file tree.
  • NAS locks only. After the lock server restarts, dehydrated files can't be locked again while they're being downloaded.
  • There can be a race condition with some applications while opening files that have been newly added to the Job folder and they (that first try to open a file with the write (W) permission and if it fails they try accessing it with the read-only (RO) permission). When end user opens a file that hasn't been uploaded to the Primary Storage Agent yet, 'file is opening with W permissions the server doesn't have the actual file version, so the request is denied. The application retries to access the file with RO permissions and between these two requests the file can be uploaded to the server, resulting in a successful RO lock.
  • Active Everywhere is unable to keep track of files that are added directly to the storage (for example, a NAS) without going through the Agent.