Using the Virtual Filesystem

Introduction

The Desktop App provides the use of a virtual file system (VFS) when synchronizing data for Windows clients. This has the great advantage that all files and folders are visible to the Desktop App, but the files are not downloaded until the user requests it. Here are some of the main advantages:

  • Full access to files and folders without the need for downloads.

  • Selectively synchronize folders and files based on user needs.

  • Optimize space with the Desktop App.

The virtual filesystem is only available for Windows clients.

The following quote gives a brief overview of what a virtual file system is:

A virtual file system (VFS) or virtual filesystem switch is an abstract layer on top of a more concrete file system. The purpose of a VFS is to allow client applications to access different types of concrete file systems in a uniform way. A VFS can, for example, be used to access local and network storage devices transparently without the client application noticing the difference. It can be used to bridge the differences in Windows, classic macOS and Unix filesystems, so that applications can access files on local file systems of those types without having to know what type of file system they are accessing.

Wikipedia

Microsoft VFS Implementation

Background

A sync engine is a service that syncs files, typically between a remote host and a local client. Sync engines on Windows often present those files to the user through the Windows file system and File Explorer.

Microsoft
Files can exist in the following states
  • Full pinned file:
    The file has been explicitly hydrated by the user via File Explorer and is guaranteed to be available offline.

  • Full file:
    The file is implicitly hydrated and could be dehydrated by the system if space is needed.

  • Placeholder file:
    An empty representation of the file and is only available if the sync service is available.

  • Syncing file:
    The file is planned for or currently in the process of synchrinozation..

The following picture shows how the file statuses: full pinned, full, placeholder and syncing are displayed in File Explorer:

File States

Limitations and Restrictions

Limitations

A virtual file system needs a root folder where all synchronization items will be stored. The following locations are not allowed as a synchronization root:

  • The root of a disk like D:\

  • A non-NTFS Filesystem

  • Mounted network shares *

  • Symbolic links or junction points

  • Assigned drives

* …​ Only a full scan is performed by the desktop application, which happens at regular but long intervals. See the Configuration File documentation for details. Shared locations should not be used due to other possible negative side effects.

Restrictions

Similar to OneDrive, since it also uses Microsoft’s virtual file system, there are some additional restrictions that should be considered, such as maximum file size, invalid file or folder names, and so on. See the Restrictions and limitations in OneDrive and SharePoint and Filename Considerations documentation for more information.

Desktop App’s VFS Implementation

Note that when using Windows and VFS, the Desktop App must have full control over the sync folder and its subfolders where the data is stored. If this is not the case, you will most likely get access denied errors when syncing VFS data. For more details, see the Troubleshooting guide for more details.

Manage VFS from Windows Explorer

You can manage individual files or entire folders in the Explorer window by right-click on them. This opens a drop-down menu of actions that can be performed on a specific file or folder. The following example shows this for files, but it can be applied to folders as well.

Create a Local Copy

To save space on the local file system, synchronized files are placeholders until you open them or manually select them to have a local copy. To create a local copy of a placeholder file manually, see the following procedure:

  1. Select the folder containing the file that is a Placehholder of which you want to have a local copy.

  2. Select the context menu for the file by doing a right click.

  3. To create a Full Pinned file (have a local copy of it), use the action Always keep on this device.

  4. The state of the file will change to synchronizing, the icon in the Status column changes to Synchronizing.

  5. When the local copy has been created, the icon in the Status column changes to Full Pinned.

    Always keep on this Device Always keep on this Device Syncing Always keep on this Device Synced

Free up Space

This is the opposite of creating a local copy. The file exists as a full copy in the file system, you can free space by making it a placeholder. To do so, see the following procedure:

  1. Select the folder containing the file that is a local copy of which you want to have a placeholder.

  2. Select the context menu for the file by doing a right click.

  3. To create a Placehholder file, use the action Free up space.

  4. When the placeholder has been created, the icon in the Status column changes to Placehholder.

    Free Up Space Free up Space Successful

Using attrib.exe to Manage States

Experienced users can also manage VFS states from the Windows command line using attrib. This is especially useful if you want to change the state of an entire folder/subfolder. Open a PowerShell command line window as from the start menu and change to the directory of the ownCloud sync folder/subfolder that contains the data you want to change in bulk.

From the syncnchronization folder, run the following commands to make bulk changes to synchronization settings:

  • Use the following command for help and to customize the switches.

    attrib /?
  • Keep a set of files or folders, including subfolders, always available:

    attrib -U +P .\* /D /S
  • Make a set of files or folders available online only, including subfolders:

    attrib +U -P .\* /D /S

Manage Drive Space With Storage Sense

Microsoft provides a mechanism called Storage Sense that can automatically free up disk space for applications that use VFS. This is done by converting files that were set to be locally available back to cloud-based content that is placeholder files on the local drive, which takes up no space.

  1. Enable or disable Storage Sense via Windows Settings  System  Storage  Configure Storage Sense or run it now:

  2. Configure the general behavior or each VFS relationship individually via the following section:

    Access storage configuration Setup Storage Sense