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