12d1d25d0SStefan Hajnoczi.. SPDX-License-Identifier: GPL-2.0 22d1d25d0SStefan Hajnoczi 36735c208SWang Wenhu.. _virtiofs_index: 46735c208SWang Wenhu 52d1d25d0SStefan Hajnoczi=================================================== 62d1d25d0SStefan Hajnoczivirtiofs: virtio-fs host<->guest shared file system 72d1d25d0SStefan Hajnoczi=================================================== 82d1d25d0SStefan Hajnoczi 92d1d25d0SStefan Hajnoczi- Copyright (C) 2019 Red Hat, Inc. 102d1d25d0SStefan Hajnoczi 112d1d25d0SStefan HajnocziIntroduction 122d1d25d0SStefan Hajnoczi============ 132d1d25d0SStefan HajnocziThe virtiofs file system for Linux implements a driver for the paravirtualized 142d1d25d0SStefan HajnocziVIRTIO "virtio-fs" device for guest<->host file system sharing. It allows a 152d1d25d0SStefan Hajnocziguest to mount a directory that has been exported on the host. 162d1d25d0SStefan Hajnoczi 172d1d25d0SStefan HajnocziGuests often require access to files residing on the host or remote systems. 182d1d25d0SStefan HajnocziUse cases include making files available to new guests during installation, 192d1d25d0SStefan Hajnoczibooting from a root file system located on the host, persistent storage for 202d1d25d0SStefan Hajnoczistateless or ephemeral guests, and sharing a directory between guests. 212d1d25d0SStefan Hajnoczi 222d1d25d0SStefan HajnocziAlthough it is possible to use existing network file systems for some of these 232d1d25d0SStefan Hajnoczitasks, they require configuration steps that are hard to automate and they 242d1d25d0SStefan Hajnocziexpose the storage network to the guest. The virtio-fs device was designed to 252d1d25d0SStefan Hajnoczisolve these problems by providing file system access without networking. 262d1d25d0SStefan Hajnoczi 272d1d25d0SStefan HajnocziFurthermore the virtio-fs device takes advantage of the co-location of the 282d1d25d0SStefan Hajnocziguest and host to increase performance and provide semantics that are not 292d1d25d0SStefan Hajnoczipossible with network file systems. 302d1d25d0SStefan Hajnoczi 312d1d25d0SStefan HajnocziUsage 322d1d25d0SStefan Hajnoczi===== 332d1d25d0SStefan HajnocziMount file system with tag ``myfs`` on ``/mnt``: 342d1d25d0SStefan Hajnoczi 352d1d25d0SStefan Hajnoczi.. code-block:: sh 362d1d25d0SStefan Hajnoczi 372d1d25d0SStefan Hajnoczi guest# mount -t virtiofs myfs /mnt 382d1d25d0SStefan Hajnoczi 392d1d25d0SStefan HajnocziPlease see https://virtio-fs.gitlab.io/ for details on how to configure QEMU 402d1d25d0SStefan Hajnocziand the virtiofsd daemon. 412d1d25d0SStefan Hajnoczi 42*a5d8422cSMasayoshi MizumaMount options 43*a5d8422cSMasayoshi Mizuma------------- 44*a5d8422cSMasayoshi Mizuma 45*a5d8422cSMasayoshi Mizumavirtiofs supports general VFS mount options, for example, remount, 46*a5d8422cSMasayoshi Mizumaro, rw, context, etc. It also supports FUSE mount options. 47*a5d8422cSMasayoshi Mizuma 48*a5d8422cSMasayoshi Mizumaatime behavior 49*a5d8422cSMasayoshi Mizuma^^^^^^^^^^^^^^ 50*a5d8422cSMasayoshi Mizuma 51*a5d8422cSMasayoshi MizumaThe atime-related mount options, for example, noatime, strictatime, 52*a5d8422cSMasayoshi Mizumaare ignored. The atime behavior for virtiofs is the same as the 53*a5d8422cSMasayoshi Mizumaunderlying filesystem of the directory that has been exported 54*a5d8422cSMasayoshi Mizumaon the host. 55*a5d8422cSMasayoshi Mizuma 562d1d25d0SStefan HajnocziInternals 572d1d25d0SStefan Hajnoczi========= 582d1d25d0SStefan HajnocziSince the virtio-fs device uses the FUSE protocol for file system requests, the 592d1d25d0SStefan Hajnoczivirtiofs file system for Linux is integrated closely with the FUSE file system 602d1d25d0SStefan Hajnocziclient. The guest acts as the FUSE client while the host acts as the FUSE 612d1d25d0SStefan Hajnocziserver. The /dev/fuse interface between the kernel and userspace is replaced 622d1d25d0SStefan Hajnocziwith the virtio-fs device interface. 632d1d25d0SStefan Hajnoczi 642d1d25d0SStefan HajnocziFUSE requests are placed into a virtqueue and processed by the host. The 652d1d25d0SStefan Hajnocziresponse portion of the buffer is filled in by the host and the guest handles 662d1d25d0SStefan Hajnoczithe request completion. 672d1d25d0SStefan Hajnoczi 682d1d25d0SStefan HajnocziMapping /dev/fuse to virtqueues requires solving differences in semantics 692d1d25d0SStefan Hajnoczibetween /dev/fuse and virtqueues. Each time the /dev/fuse device is read, the 702d1d25d0SStefan HajnocziFUSE client may choose which request to transfer, making it possible to 712d1d25d0SStefan Hajnocziprioritize certain requests over others. Virtqueues have queue semantics and 722d1d25d0SStefan Hajnocziit is not possible to change the order of requests that have been enqueued. 732d1d25d0SStefan HajnocziThis is especially important if the virtqueue becomes full since it is then 742d1d25d0SStefan Hajnocziimpossible to add high priority requests. In order to address this difference, 752d1d25d0SStefan Hajnoczithe virtio-fs device uses a "hiprio" virtqueue specifically for requests that 762d1d25d0SStefan Hajnoczihave priority over normal requests. 77