0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 .. _virtiofs_index:
0004
0005 ===================================================
0006 virtiofs: virtio-fs host<->guest shared file system
0007 ===================================================
0008
0009 - Copyright (C) 2019 Red Hat, Inc.
0010
0011 Introduction
0012 ============
0013 The virtiofs file system for Linux implements a driver for the paravirtualized
0014 VIRTIO "virtio-fs" device for guest<->host file system sharing. It allows a
0015 guest to mount a directory that has been exported on the host.
0016
0017 Guests often require access to files residing on the host or remote systems.
0018 Use cases include making files available to new guests during installation,
0019 booting from a root file system located on the host, persistent storage for
0020 stateless or ephemeral guests, and sharing a directory between guests.
0021
0022 Although it is possible to use existing network file systems for some of these
0023 tasks, they require configuration steps that are hard to automate and they
0024 expose the storage network to the guest. The virtio-fs device was designed to
0025 solve these problems by providing file system access without networking.
0026
0027 Furthermore the virtio-fs device takes advantage of the co-location of the
0028 guest and host to increase performance and provide semantics that are not
0029 possible with network file systems.
0030
0031 Usage
0032 =====
0033 Mount file system with tag ``myfs`` on ``/mnt``:
0034
0035 .. code-block:: sh
0036
0037 guest# mount -t virtiofs myfs /mnt
0038
0039 Please see https://virtio-fs.gitlab.io/ for details on how to configure QEMU
0040 and the virtiofsd daemon.
0041
0042 Mount options
0043 -------------
0044
0045 virtiofs supports general VFS mount options, for example, remount,
0046 ro, rw, context, etc. It also supports FUSE mount options.
0047
0048 atime behavior
0049 ^^^^^^^^^^^^^^
0050
0051 The atime-related mount options, for example, noatime, strictatime,
0052 are ignored. The atime behavior for virtiofs is the same as the
0053 underlying filesystem of the directory that has been exported
0054 on the host.
0055
0056 Internals
0057 =========
0058 Since the virtio-fs device uses the FUSE protocol for file system requests, the
0059 virtiofs file system for Linux is integrated closely with the FUSE file system
0060 client. The guest acts as the FUSE client while the host acts as the FUSE
0061 server. The /dev/fuse interface between the kernel and userspace is replaced
0062 with the virtio-fs device interface.
0063
0064 FUSE requests are placed into a virtqueue and processed by the host. The
0065 response portion of the buffer is filled in by the host and the guest handles
0066 the request completion.
0067
0068 Mapping /dev/fuse to virtqueues requires solving differences in semantics
0069 between /dev/fuse and virtqueues. Each time the /dev/fuse device is read, the
0070 FUSE client may choose which request to transfer, making it possible to
0071 prioritize certain requests over others. Virtqueues have queue semantics and
0072 it is not possible to change the order of requests that have been enqueued.
0073 This is especially important if the virtqueue becomes full since it is then
0074 impossible to add high priority requests. In order to address this difference,
0075 the virtio-fs device uses a "hiprio" virtqueue specifically for requests that
0076 have priority over normal requests.
