virtio-win

Virtio-fs Quick start

Overview

Virtiofs is a shared file system that lets virtual machines access a directory tree on the host, it is designed to offer local file system semantics and performance. More information on the underlying approach is available at virtio-fs.gitlab.io. Virtiofs for Windows is a user mode file system, implemented using WinFsp framework. Virtiofs consists of VirtIO-powered driver and user-space service based on WinFsp.

This guide includes setup instructions for QEMU and libvirt, and for Windows guests specifically.

Status

Virtio-FS is a supported feature. For current known issues, visit the Virtio-FS GitHub issues page.

Setup

Host

This section shows how to setup virtiofs device on the host side. Two options are described: libvirt and QEMU.

libvirt

Add the following domain XML elements to share the host directory /home/user/viofs with the guest:

<domain>
  ...
  <memoryBacking>
    <source type='memfd'/>
    <access mode='shared'/>
  </memoryBacking>
  ...
  <devices>
    <filesystem type="mount" accessmode="passthrough">
      <driver type="virtiofs" queue="1024"/>
      <source dir="/home/user/viofs"/>
      <target dir="mount_tag0"/>
      <address type="pci" domain="0x0000" bus="0x06" slot="0x00" function="0x0"/>
    </filesystem>
    <filesystem type="mount" accessmode="passthrough">
      <driver type="virtiofs" queue="1024"/>
      <source dir="/home/user/vm_share"/>
      <target dir="mount_tag1"/>
      <address type="pci" domain="0x0000" bus="0x07" slot="0x00" function="0x0"/>
    </filesystem>
  </devices>
  ...
</domain>

The <memoryBacking> element is required for Virtio-FS to work, as it enables shared memory between the guest and the host.
Element <source dir="..."/> describes host directory to share.
Despite its name, the <target dir="..."/> does not define a path inside the guest. Instead, it defines a mount tag — an arbitrary identifier that is used inside the guest to identify the shared file system to be mounted (e.g., via Mount).

Virt-Manager (libvirt GUI)

To configure Virtio-FS using Virt-Manager:

Enable Shared Memory
Virtio-FS requires memory sharing between host and guest.
- Go to the Memory tab.
- Check the box Enable shared memory.
If this option is not available in the GUI, you can add it manually in the domain XML:
```
<memoryBacking>
  <source type='memfd'/>
  <access mode='shared'/>
</memoryBacking>
```
Add Virtio-FS Filesystem Device
- Go to Add Hardware → File System
- Choose:
  - Driver: virtiofs
  - Source Path: the host directory you want to share (e.g. /home/user/viofs)
  - Target Path: a mount tag (e.g. mount_tag0) – this is used by the guest to identify the shared file system.
Apply and Start the VM
- Save your configuration.
- Start the VM.
- In the guest use the matching mount_tag0 in the mount command.

More information on libvirt virtiofs options is provided in libvirt docs.

QEMU

1. Start virtiofsd daemon (install or build it if missing):

/usr/libexec/virtiofsd --socket-path=/tmp/virtiofs_socket -o source=/home/user/viofs

The socket path will also need to be passed to QEMU below.

2. Adjust following QEMU command-line parameters to your QEMU command line:

Instantiate the character device for socket communication between QEMU and virtiofsd:
-chardev socket,id=char0,path=/tmp/virtiofs_socket
Instantiate the virtiofs PCI device:
-device vhost-user-fs-pci,queue-size=1024,chardev=char0,tag=my_virtiofs
The tag name is arbitrary and must match the tag given in the guests mount command.
Force use of memory sharing with virtiofsd (replace 4G with your desired VM RAM size):
-m 4G -object memory-backend-file,id=mem,size=4G,mem-path=/dev/shm,share=on -numa node,memdev=mem
The memory-backend size must be equals to VM RAM size.

QEMU Command with Virtio-FS Example

qemu-system-x86_64 \
  -enable-kvm \
  -m 4G \
  -object memory-backend-file,id=mem,size=4G,mem-path=/dev/shm,share=on -numa node,memdev=mem \
  -chardev socket,id=char0,path=/tmp/virtiofs_socket \
  -device vhost-user-fs-pci,queue-size=1024,chardev=char0,tag=my_virtiofs \
  ...

virtiofsd

The virtiofsd daemon is required on the host to enable Virtio-FS for guests.

Installation (Recommended)

On Fedora virtiofsd is available via the package manager.
```
sudo dnf install virtiofsd
```
Building from Source (Alternative)

Modern virtiofsd is written in Rust and supported here: https://gitlab.com/virtio-fs/virtiofsd.
To build virtiofsd:
```
cargo build
```

Guest

Setup with installer

Download and install WinFSP with at least “Core” feature enabled.
Install the virtiofs driver and service using the installation wizard.

Manual setup (for development purposes)

Download and install WinFSP with at least “Core” feature enabled. If you plan to make changes to virtiofs driver or service then enable “Core”, “Developer” and “Kernel Developer” features in the installer.
Install virtiofs driver with Device Manager or pnputil.exe.
To install via Device Manager:
Open Device Manager and locate device called “Mass Storage Controller” under “Other devices”.
Right-click on the device and select “Update driver” from the pop-up menu. From the “Update Drivers” dialog choose “Browse my computer for drivers” and fill in the appropriate directory where the drivers files are located.
If your guest does not include a virtiofs driver you can install from VirtIO-Win package.

After the driver is successfully installed, you can view the device : Go to Device Manager, click on View → Devices by connection
Installing and Starting the virtiofs service
- Run a Command Prompt as administrator and execute the following command in order to register virtiofs as a service which starts automatically when Windows loads.
  sc create VirtioFsSvc binPath="<path to the binary>\virtiofs.exe" start=auto depend=VirtioFsDrv. Don’t forget to appropriately set binPath.
- You can immediately start the service by running sc start VirtioFsSvc. The service will start automatically on boot. Virtiofs uses the first available drive letter starting with Z: unless no mount-point is specified.

Options

The virtiofs service supports several configuration parameters that can be passed via command-line or stored in the Windows registry.
Virtiofs service can parse following settings from command-line:

  -d DebugFlags       [-1: enable all debug logs]
  -D DebugLogFile     [file path; use - for stderr]
  -i                  [case insensitive file system]
  -F FileSystemName   [file system name for OS]
  -m MountPoint       [X:|* (required if no UNC prefix)]
  -t Tag              [mount tag; max 36 symbols]
  -o UID:GID          [host owner UID:GID]

Since command-line arguments can’t be assigned to Windows service permanently, virtiofs can parse them from the registry. When command-line arguments are absent the service looks up for the following parameters under HKLM\Software\virtiofs:

DebugFlags (DWORD)
DebugLogFile (String)
MountPoint (String)
CaseInsensitive (DWORD)
Owner (String)
FileSystemName (String)

For example, registry values depicted below correspond to virtiofs.exe -d -1 -D C:\viofs_debug.log -m X:. Please note that -1 corresponds to 0xffffffff in DWORD value.

Also, parameters named OverflowUid and OverflowGid are always parsed from the registry. Normally, these parameters only affect if the host daemon is running inside a Linux user namespace. They denote UID and GID perceived as nobody on the host, so they should be in sync with corresponding host values. If the service finds out shared folder root owner UID/GID becomes nobody, it will try previous UID/GID as owner for new files and folders. They assumed to be 65534 if no such parameters are found in the registry.

Case insensitivity

Case insensitivity can be turned on by -i command-line parameter of CaseInsensitive registry key. In this situation, when processing a request, virtiofs first tries to access the file or directory by its exact name, as in case-sensitive mode. Second, if there is no such node, virtiofs finds a node with a matching name in the parent directory, ignoring case.

File system name

When running an executable as administrator, the Windows OS seems to require that the name of the file system that is housing the executable is “NTFS”. This can be done by -F command-line parameter or FileSystemName registry key.

Multiple virtiofs instances

Setup

Support for multiple virtiofs instances is made by WinFSP.Launcher service. To use it, the default VirtioFsSvc service must be stopped and disabled

sc stop VirtioFsSvc
sc config VirtioFsSvc start=demand

The virtiofs service is now stopped and will not start even after reboot.
This prevents conflicts — since VirtioFsSvc supports only one instance at a time, while WinFsp.Launcher can manage multiple.

Virtiofs configuration for WinFsp.Launcher:

"C:\Program Files (x86)\WinFsp\bin\fsreg.bat" virtiofs "<path to the binary>\virtiofs.exe" "-t %1 -m %2"

Corresponding data is now available to view and edit under HKLM\SOFTWARE\WOW6432Node\WinFsp\Services\virtiofs registry key.

Also you may need to run virtiofs.exe as an administrator:

either from administrator console
or specifying an administrator user for your service

Mount

Mount virtiofs as a global drive with tag mount_tag0 to Y:\:

"C:\Program Files (x86)\WinFsp\bin\launchctl-x64.exe" start virtiofs viofsY mount_tag0 \\.\Y: 

Mount virtiofs as a global drive with tag mount_tag1 to Z:\:

"C:\Program Files (x86)\WinFsp\bin\launchctl-x64.exe" start virtiofs viofsZ mount_tag1 \\.\Z:

Here viofsY and viofsZ are instance names for WinFsp.Launcher. They are selected arbitrary, but must differ between instances.

Unmount

Unmount is done by the instance name:

"C:\Program Files (x86)\WinFsp\bin\launchctl-x64.exe" stop virtiofs viofsY
"C:\Program Files (x86)\WinFsp\bin\launchctl-x64.exe" stop virtiofs viofsZ

virtio-win

Virtio-fs Quick start

Overview

Status

Setup

Host

libvirt

Virt-Manager (libvirt GUI)

QEMU

1. Start virtiofsd daemon (install or build it if missing):

2. Adjust following QEMU command-line parameters to your QEMU command line:

QEMU Command with Virtio-FS Example

virtiofsd

Installation (Recommended)

Building from Source (Alternative)

Guest

Setup with installer

Manual setup (for development purposes)

Options

Case insensitivity

File system name

Multiple virtiofs instances

Setup

Mount

Unmount