linux/Documentation/filesystems/virtiofs.rst
<<
>>
Prefs
   1.. SPDX-License-Identifier: GPL-2.0
   2
   3.. _virtiofs_index:
   4
   5===================================================
   6virtiofs: virtio-fs host<->guest shared file system
   7===================================================
   8
   9- Copyright (C) 2019 Red Hat, Inc.
  10
  11Introduction
  12============
  13The virtiofs file system for Linux implements a driver for the paravirtualized
  14VIRTIO "virtio-fs" device for guest<->host file system sharing.  It allows a
  15guest to mount a directory that has been exported on the host.
  16
  17Guests often require access to files residing on the host or remote systems.
  18Use cases include making files available to new guests during installation,
  19booting from a root file system located on the host, persistent storage for
  20stateless or ephemeral guests, and sharing a directory between guests.
  21
  22Although it is possible to use existing network file systems for some of these
  23tasks, they require configuration steps that are hard to automate and they
  24expose the storage network to the guest.  The virtio-fs device was designed to
  25solve these problems by providing file system access without networking.
  26
  27Furthermore the virtio-fs device takes advantage of the co-location of the
  28guest and host to increase performance and provide semantics that are not
  29possible with network file systems.
  30
  31Usage
  32=====
  33Mount file system with tag ``myfs`` on ``/mnt``:
  34
  35.. code-block:: sh
  36
  37  guest# mount -t virtiofs myfs /mnt
  38
  39Please see https://virtio-fs.gitlab.io/ for details on how to configure QEMU
  40and the virtiofsd daemon.
  41
  42Mount options
  43-------------
  44
  45virtiofs supports general VFS mount options, for example, remount,
  46ro, rw, context, etc. It also supports FUSE mount options.
  47
  48atime behavior
  49^^^^^^^^^^^^^^
  50
  51The atime-related mount options, for example, noatime, strictatime,
  52are ignored. The atime behavior for virtiofs is the same as the
  53underlying filesystem of the directory that has been exported
  54on the host.
  55
  56Internals
  57=========
  58Since the virtio-fs device uses the FUSE protocol for file system requests, the
  59virtiofs file system for Linux is integrated closely with the FUSE file system
  60client.  The guest acts as the FUSE client while the host acts as the FUSE
  61server.  The /dev/fuse interface between the kernel and userspace is replaced
  62with the virtio-fs device interface.
  63
  64FUSE requests are placed into a virtqueue and processed by the host.  The
  65response portion of the buffer is filled in by the host and the guest handles
  66the request completion.
  67
  68Mapping /dev/fuse to virtqueues requires solving differences in semantics
  69between /dev/fuse and virtqueues.  Each time the /dev/fuse device is read, the
  70FUSE client may choose which request to transfer, making it possible to
  71prioritize certain requests over others.  Virtqueues have queue semantics and
  72it is not possible to change the order of requests that have been enqueued.
  73This is especially important if the virtqueue becomes full since it is then
  74impossible to add high priority requests.  In order to address this difference,
  75the virtio-fs device uses a "hiprio" virtqueue specifically for requests that
  76have priority over normal requests.
  77