Transparent Selective Sync (TSS) on Windows
Starting with Resilio Active Everywhere v2.10 Agents' support system integrated Selective Sync functionality which is based on a special Windows API. It comes to replace the legacy Selective Sync.
It allows access and downloads files directly using a file browser or
transparently through an application. Some limitations in usage flow apply,
see them listed below.
Transparent Selective Sync is enabled by default.
Resilio Active Everywhere v3x and older does not store file versions for TSS folders in Archive
The Archive does not store file versions for Resilio Active Everywhere v3.x and older. Only the files deleted on remote Agents are moved to the Archive in a TSS folder. See below for more details. Starting with Resilio Active Everywhere Platform 4.0, the file version are stored in the Archive.
Don't run two Agents with Selective Sync on the same computer
Running two Agents, with at least one of them is in Transparent Selective Sync mode, on the same computer is not supported and is highly not advisable.
Possible conflict with OneDrive
- Configuring Agent to sync a OneDrive folder with 'on demand' files won't work - these files won't be uploaded and the job won't be completed.
Important for deployments on VMware virtual machines
When using Transparent Selective Sync (TSS) on Windows 10, 11, or Server 2022+ running inside a VMware virtual machine, make sure the virtual disk is configured as Thick Provision Eager Zeroed. This disk type ensures that all disk blocks are fully allocated and initialized at creation time, which is critical for reliable file system behavior expected by the operating system. Other provisioning types, such as Lazy Zeroed or Thin Provision, may cause unexpected I/O errors when working with cloud-stub files created by TSS. These errors are specific to VMware environments and do not affect physical machines or other hypervisors.
TSS and resources with long paths
Options to always keep files or free up space are not available for files stored on Microsoft OneDrive shares when their full path exceeds 260 characters.
System requirements
Advanced selective sync works only on:
- Windows 10 20H2 (OS build 19042) and newer
- Windows Server 2022 (21H2) or newer with desktop experience (from release channel LTSC)
Please check for file C:\Windows\System32\cldapi.dll existence as a quick check if your Windows supports the advanced selective sync.
Works for local NTFS, which can be accessed via SMB. It does not work for FAT32 and exFAT file systems.
Managing files and placeholders
All files and subfolders are seen in a file manager with the availability attributes and context menu items mentioned below.
| Icon | Description |
|---|---|
 Always available on this device |
File is set to be automatically synced. If this is the status of a subdirectory, all files inside it will be automatically downloaded. If a new file is created in such a subdirectory, it gets this status. Updates to the files on remote Agents will be auto-synced, but the file version will NOT be placed to the Archive for Resilio Active Everywhere v3.x and older. Starting with Resilio Active Everywhere Platform 4.0, the file version are stored in the Archive. If the file is renamed on a remote Agents, it will be dehydrated, but the file with the previous name will be placed in the Archive. IF the file is deleted from the disk on remote Agents, the file is placed to the Archive. Such files are not automatically cleaned up per cleanup per Agent Profile setting. Unchecking this state through the context menu reverts the file to  state. If unchecked for a subfolder, all synced files inside it are also reverted to state. |
| Available on this device |
File version is downloaded to the current device and is available here. It also means that if this file changes on remote Agent, it gets cleared off and reverted to a dehydrated file (placeholder), the file version is NOT placed to the Archive Starting with Resilio Active Everywhere Platform 4.0, the file version are stored in the Archive. Local file changes will be synced to remote Agents. Newly created files in a selective sync subdirectory have this status. Such files are dehydrated after cleanup timeout. |
 Available when online |
Dehydrated file - file is an empty placeholder and can be downloaded from remote Agent. It consumes only 1 KB of storage (filesystem header). If the file is updated or deleted on a remote Agent, the dehydrated file is NOT placed to the Archive. Opening a placeholder file through an application makes it puts state .If a dehydrated file is copied (using Explorer or CMD), both - the source file and its copy - are reverted to state If a dehydrated file is moved to a different directory, using Explorer it will appear in state in new location. If moved using CMD, it will remain dehydrated. Vice versa if renamed (change name). |
 Syncing |
File is being downloaded and opened in an application. Cancelling download depends how file was selected for download:
Note: download cannot be canceled for certain types of files (mountable). |
 Sync pending |
File is being processed in any way: is going to be downloaded or cleared off, local changes to the files are being processed, newly created file is being processed, for example, is being copied into sync folder. Files which are ignored by ignore rules are also marked with this status. |
Files can be managed through an application, or a file manager using context menu.
Note
These options are not available for files stored on Microsoft OneDrive shares when their full path exceeds 260 characters.
- Always keep on the device - Makes file always available on the device and automatically download any file updates from remote Agents. This menu item may fail to work if there's a non-Windows Agent in the mesh and synchronization of NTFS permissions is enabled through the Profile. Also, a false positive error "Cannot finish file download - problem moving it to its location" may appear if a small file is attempted to be downloaded right after appearing in TSS folder; the file shall be downloaded automatically a few seconds later.
- Free up space - Converts the file to a placeholder. The file is not moved to recycle bin! Until it's processed, file's status is and then changes to
Available when online. If “Free up space” is performed on a subdirectory, all items inside it are cleared but browsing inside it is still possible. The file won't free up space if it's still opened in an application and will keep showing
. The file also won't be dehydrated until it's uploaded to one of the configured main servers. For more information, see File will be reverted to placeholder automatically once it is synced to at least one of the configured main servers. Files free up space if the cleanup timeout is configured in the Agent profile, but do that only when the folder is rescanned periodically or manually. Files with the status "Always available on this device" are not cleaned up.
Double-clicking on a file. If the file is a placeholder, it will be downloaded and opened in an application. The file becomes "Available on this device". Downloading may be delayed by up to 60 seconds (a peculiarity of CloudAPI).
System’s “Delete” deletes files to Recycle Bin and propagates this deletion to remote Agents and puts files in the Archive there.
It does not revert files to placeholders! Additionally, placeholders (with the status "Available when online") will not be even moved to Recycle bin locally.
When the job is removed, all placeholders are removed from the disk from "selective sync" Agents. Hydrated files remain.
Transparent Selective Sync and 'Legacy' Selective Sync
Legacy Selective Sync is compatible with Transparent Selective Sync enabled on other agents.
Network shares
A folder with enabled Transparent selective sync is available over SMB and files are accessible, but with some limitations:
- Placeholders will be created in the TSS share and the user can download files by double-clicking on them, but there will be no context menu for placeholders.
- If the File is not available for download and gives an error shortly after job creation until the Agent fully scans the folder for the first time.
The Agent cannot create a Transparent selective sync folder on a network share. TSS folder must be local.
Peculiarities and limitations
- Changed file attributes (timestamps, permissions) are not synced from a placeholder to remote Agents until the file is downloaded locally. For changes to be propagated to remote Agents, attributes must be changed after you download the file. Otherwise, changes will be rewritten as you download the file.
- The Archive does not store file versions. Only the files deleted on remote Agents are moved to the Archive in a TSS folder for Resilio Active Everywhere v3.x and older. Starting with Resilio Active Everywhere Platform 4.0, the file version are stored in the Archive.
- Due to Archive limitations, file edit collision detection does not work on TSS shares on a Windows Agent for Resilio Active Everywhere v3.x and older. Starting with Resilio Active Everywhere Platform 4.0, the file edit collision works.
- It's not possible to use new Selective Sync for root of a mounted network share (Z:\foo), Agent will give an error
Other Errors related to Transparent Selective Sync are mentioned here.
- TSS folder inherits attributes from a previous job or an application that uses this technology (Cloud API). In other words, if an attribute was set on a folder (Always available on this device, Available on this device, or Available when online) when a job is being created, the agent won't overwrite them and will follow those attributes. This may result in unexpected behavior, for example, the files might be synced automatically. Check the existing flags using an elevated Command Prompt with the command
attrib. Read more about it here. - False positive error "Cannot finish file download - problem moving it to its location" may appear if a small file is attempted to be downloaded right after appearing in TSS folder; the file shall be downloaded automatically a few seconds later.
