Starting with Resilio Connect v2.11, Resilio Connect Agents on macOS support a new advanced Selective Sync. It's based on the FUSE interface and makes Selective Sync transparent to end-users and applications on macOS devices.
Regardless of whether Transparent selective sync is used, upon installation, the Connect Agent will be trying to register the new kernel extension and a security warning may appear. Extensions must be allowed through System Preferences -> Security & Privacy.
More detailed guidelines can be found here.
HOW TO SWITCH TO TRANSPARENT SELECTIVE SYNC
Transparent selective sync feature is enabled by default for clean installation and updates of Resilio Connect.
In order to correctly upgrade from older version of Resilio Connect and switch to the Transparent Selective Sync follow the steps below:
1. Before updating the Management Console to 2.11, check if there are sync jobs with macOS agents in Selective Sync mode. Remove these agents from the job and save.
2. Follow the procedure to update the Management Console first and Agents after that.
3. Verify that in Agent profile assigned to macOS agents option "Advanced selective sync" is set to True (default)
4. Add the MacOS Agents back to the job. Note, a new empty directory needs to be used.
See here for more information on how to update to Resilio Connect v2.11
The basic idea behind Transparent Selective Sync is, that a virtual folder will be mounted on the chosen location, and files in such a share can be handled with a native routine file management workflow.
If an Agent has Read-only permissions in a job, the folder is mounted as "read-only" meaning the user cannot change anything in it.
Mounting and unmounting of a folder depends on and is performed by the Agent process. It means that the folder is mounted and present only as the Agent is running. This may imply some limitations, as mentioned below, for example, the virtual folder cannot be mounted on an already existing non-empty path or on a network location. Also, if the Agent is removed from a job, the folder is unmounted, and all downloaded files remain on the internal drive. Agents won’t be able to unmount the path if it’s opened in another application, for example, in Terminal.
If the user manually unmounts (ejects) the mounted folder through Finder, the Agent will attempt to mount it back immediately.
See more details about mountpoint errors here - Troubleshooting mounting errors.
MANAGING VIRTUAL FILES
Files can be downloaded to a folder indirectly by opening it with a designated application or using the context menu. Files can be present in three states and managed through the context menu
Fully synced file
File version is present
File is being downloaded
These Finder icons are only present on files, not subdirectories.
A fully synced file will be always present on the device. If a file is updated on a remote Agent, it will be automatically synced here and the previous version will be placed in the Archive folder. Such files are not cleared by the "Cleanup timeout" Profile setting.
The flag is preserved if file is edited in the virtual folder in most cases, or if synchronization of NTFS or Posix permissions is enabled in Agent profile. File's state is changed to 'file version'. Click on "Always keep synced" context menu again to keep it synced automatically.
If a file is fetched by an application, only the current version is stored on the device. It also means that if file changes on a remote Agent, it will become dehydrated but that file version will be placed to Archive.
Files that are added to a TSS folder locally store only the current version.
Dehydrated files don't take space.
Context menu items:
If "Always keep synced" selected, a checkmark appears on the context menu and the file will be auto-downloaded locally. If file changes on remote agents, the changes will be synced. Clicking this menu again for a file removes the checkmark and reverts the files from the "fully synced" state to the "file version" state.
Clicking this menu again on a file that is being synced cancels the download.
The menu is available for subdirectories (a green checkmark appears next to a directory name) and for the FUSE volume itself.
While "Always keep synced" is checked, menu “Free up space” is not available for files and subfolders.
Other subdirectories inherit this flag, files inside are all automatically synced. While flag "Always keep synced" is set on a subdirectory or the fuse volume, it’s still possible to clear some files and subdirectories inside.
When "Always keep synced" is unchecked for a file, it will be in state "File version".
When "Always keep synced" is unchecked for a subdirectory or the fuse volume, files inside it are still kept so and continue syncing automatically. New files will appear as placeholders. New files created locally, appear as placeholders. The flag is removed from the first level of subdirectories and others lying deeper, unless the flag had been manually set so (as opposed to being inherited from the parent folder).
(image is clickable)
"Free up space" reverts the file to the dehydrated state.
|Clears all downloaded files - those that are fully synced and file versions. The context menu appears when clicking on the mounted folder itself or inside its root.|
Files are not placed in TrashSystem's "Move to Trash" does not put files (virtual, or downloaded) to Trash, because Trash is located on an internal disk partition and moving files across different mount points is not supported by OS. Files are deleted skipping the Trash, and this deletion propagates to other agents. On remote agents, files are placed to Archive.
A virtual folder cannot be mounted on an already existing path:
- transparent Selective Sync is not supported for pre-seeded folders
- folder cannot be mounted on a network path
Synced POSIX permissions don't appear on virtual files. The files need to be downloaded to view the permissions.
If a virtual file is renamed, it will be downloaded so that the rename is processed locally. However, it's possible to avoid this behavior by setting
lazy_indexing (a custom parameter) to
false in the Agent Profile.
Renames may cause file lossDon't rename virtual files if Archive is disabled from this and other agents in the job! This will lead to file loss (How agents process file renames).
Changing Selective Sync mode from ON to OFF and back is not supported. In order to change the mode for an agent, the admin must remove it from the job, save the job, and add the agent back.
If a zero-sized file is created on a remote agent, it’s marked as ‘virtual’ on Selective Sync macOS Agent (i.e. not auto-downloaded) and is not counted in the file count.
Sharing the virtual folder as a network drive is not allowed.
Related to other apps:
Some applications may automatically download files when listing them (e.g., iTunes Library, CleanMyMac, etc).
macOS bundles can be downloaded through the right-click context menu only. Some files inside bundles (e.g. Info.plist, Pkginfo, icons) may be automatically downloaded.
Application bundles don't start from virtual folder.
Choosing location with which other synchronization solutions work, for example, DropBox, GoogleCloud, is not supported and may lead to unpredictable behavior both for Resilio Connect and those products.
If a virtual file is attempted to be opened with an application while there's no network or no other agent connected, the application will either show a "Cannot read/open file" error, or could behave unexpectedly (e.g., open an empty text file, for example).
Related to Finder:
TSS icons in Finder may be shown with delay or be missing when browsing through files on large data set.
Finder hangs if a file that is being downloaded or a subfolder inside which a file is being downloaded, is selected for any manipulation (open file, rename, move, etc).
Context menu "Get info" does not show correct information about virtual folder. It shows information about the whole volume.
Search does not work in virtual folder.
Finder colour tags don't appear in virtual folder.