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
Select Agents in the file lock job
Lock Server
Monitor and manage locked files in a job
Manage the driver
Best practices and specific use cases
Peculiarities and limitations
Install driver and configure files locks in a job
Install the Agent on each device, administrative privileges are required. The installation automatically includes the Agent Resilio File locking driver. Confirm the driver's installation during setup.
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 launch this script before creating jobs passing the desired account_name as parameter. Example:
to configure access to the driver for userA run:
configAccessToDriver.ps1 userAto configure access to the driver for any user run
configAccessToDriver.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. ThisActivate the "File locking" option on the Settings tab. For existing jobs, this feature can be toggled on/off, necessitating a restart of the Agents for changes to take effect.
File lock timeout forces file unlock, based on lock duration.
It's advised to keep the default lock update interval.
Editbox to ignore some files from being locked supports regular expression syntax.
Select Agents in the file lock job
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.