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.
System requirements
TSS for M1 chip macOS 11 is supported starting with version 11.3.1.TSS for macOS 12 is supported starting with version 2.12.10 and 3.1.0.
Is Resilio’s Transparent Selective Sync still working with macOS 12 Monterey?
In the macOS 12.3 beta release notes Apple states: “The kernel extensions used by Dropbox Desktop Application and Microsoft OneDrive are no longer available. Both service providers have replacements for this functionality; Dropbox is currently in beta. (85890896)” Microsoft and Dropbox are not shipping their own kernel extensions. They have been using a private framework (including a kernel extension developed by Apple) that Apple made available to these two companies exclusively some time ago. Apple did not deprecate the virtual file system kernel extensions in macOS 12.3. They are only removing the private kernel extension from macOS that was used by Microsoft and Dropbox. The VFS kernel API that macFUSE relies on, is sill the only way to develop full-featured file systems for macOS. Resilio Inc. continues to participate in all Apple Betas and we are not seeing any issues when using Resilio’s TSS on the latest macOS 12.3 beta. Resilio In’s TSS does NOT use any deprecated APIs.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 (pre 2.11) 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). This parameter is removed from profile and enforced starting with v3.1.0.
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
VIRTUAL FOLDER
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. The file won't be dehydrated until it's uploaded to one of the configured main servers, read more about it here. |
|
|
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 Trash
System'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.
KNOWN LIMITATIONS
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
Changing Selective Sync mode
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.Changing Agent permissions RO <-> RW
Changing Agent permissions RO <-> RW in the job is not supported. Admin needs to remove the Agent from job, save, and add the Agent back to job. Starting with v3.6.0 its possible to change the permissions and simply restart the AgentFileDelayConfig does not work for TSS shares.
File system notifications are forcibly disabled for maOS TSS folders. Agent discovers new and updated files during periodic folder scan.
If a Reference Agent is configured in the job, the macOS Agent in TSS will be reporting Read-Only access in the Agent UI and MC while performing initial synchronization (even though the Agent was configured to have Read-Write access). After completing the initial synchronisation, restart is required for the Agent to switch to Read-Write.
Renames may cause file loss
Don'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).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.
Synced POSIX permissions don't appear on virtual files. The files need to be downloaded to view the permissions.
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:
If the job contains a reference agent, non-reference agents may show an incorrect icon for their virtual folder until the Mac is rebooted. The folder will have a "Read-Only folder" icon while the agent actually has Read-Write permissions in a job.
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).
Some other Finder extensions may prevent TSS context menu options from appearing.
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. (While Finder is not capable to search TSS files, there are other Finder alternatives such as Commander One and EasyFind that can (likely many more). Resilio Inc is not endorsing any of these but we are aware that these applications can be used as a Finder alternative to be able to search TSS files, downloaded or not.)
Finder colour tags don't appear in virtual folder.