docs: add virtiofs kbase

Add a document describing the usage of virtiofs.

Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Tested-by: Andrea Bolognani <abologna@redhat.com>

diff --git a/docs/kbase.html.in b/docs/kbase.html.in
index db84b95b60975a1c8d24a6c0accc8700b5c1508c..7055f4fda4664474dc5d31af7e202cb87beb94c1 100644 (file)
--- a/docs/kbase.html.in
+++ b/docs/kbase.html.in
@@ -33,6 +33,9 @@
         <dt><a href="kbase/qemu-passthrough-security.html">Security with QEMU passthrough</a></dt>
         <dd>Examination of the security protections used for QEMU and how they need
           configuring to allow use of QEMU passthrough with host files/devices.</dd>
+
+        <dt><a href="kbase/virtiofs.html">Virtio-FS</a></dt>
+        <dd>Share a filesystem between the guest and the host</dd>
       </dl>
     </div>
 

diff --git a/docs/kbase/virtiofs.rst b/docs/kbase/virtiofs.rst
new file mode 100644 (file)
index 0000000..68fbafc
--- /dev/null
+++ b/docs/kbase/virtiofs.rst
@@ -0,0 +1,147 @@
+============================
+Sharing files with Virtio-FS
+============================
+
+.. contents::
+
+=========
+Virtio-FS
+=========
+
+Virtio-FS is a shared file system that lets virtual machines access
+a directory tree on the host. Unlike existing approaches, it
+is designed to offer local file system semantics and performance.
+
+See https://virtio-fs.gitlab.io/
+
+==========
+Host setup
+==========
+
+The host-side virtiofsd daemon, like other vhost-user backed devices,
+requires shared memory between the host and the guest. As of QEMU 4.2, this
+requires specifying a NUMA topology for the guest and explicitly specifying
+a memory backend. Multiple options are available:
+
+Either of the following:
+
+* Use file-backed memory
+
+  Configure the directory where the files backing the memory will be stored
+  with the ``memory_backing_dir`` option in ``/etc/libvirt/qemu.conf``
+
+  ::
+
+    # This directory is used for memoryBacking source if configured as file.
+    # NOTE: big files will be stored here
+    memory_backing_dir = "/dev/shm/"
+
+* Use hugepage-backed memory
+
+  Make sure there are enough huge pages allocated for the requested guest memory.
+  For example, for one guest with 2 GiB of RAM backed by 2 MiB hugepages:
+
+  ::
+
+      # virsh allocpages 2M 1024
+
+===========
+Guest setup
+===========
+
+#. Specify the NUMA topology
+
+   in the domain XML of the guest.
+   For the simplest one-node topology for a guest with 2GiB of RAM and 8 vCPUs:
+
+   ::
+
+      <domain>
+        ...
+        <cpu ...>
+          <numa>
+            <cell id='0' cpus='0-7' memory='2' unit='GiB' memAccess='shared'/>
+          </numa>
+        </cpu>
+       ...
+      </domain>
+
+   Note that the CPU element might already be specified and only one is allowed.
+
+#. Specify the memory backend
+
+   Either of the following:
+
+   * File-backed memory
+
+     ::
+
+        <domain>
+          ...
+          <memoryBacking>
+            <access mode='shared'/>
+          </memoryBacking>
+          ...
+        </domain>
+
+     This will create a file in the directory specified in ``qemu.conf``
+
+   * Hugepage-backed memory
+
+     ::
+
+        <domain>
+          ...
+          <memoryBacking>
+            <hugepages>
+              <page size='2' unit='M'/>
+            </hugepages>
+            <access mode='shared'/>
+          </memoryBacking>
+          ...
+        </domain>
+
+#. Add the ``vhost-user-fs`` QEMU device via the ``filesystem`` element
+
+   ::
+
+      <domain>
+        ...
+        <devices>
+          ...
+          <filesystem type='mount' accessmode='passthrough'>
+            <driver type='virtiofs'/>
+            <source dir='/path'/>
+            <target dir='mount_tag'/>
+          </filesystem>
+          ...
+        </devices>
+      </domain>
+
+   Note that despite its name, the ``target dir`` is actually a mount tag and does
+   not have to correspond to the desired mount point in the guest.
+
+   So far, ``passthrough`` is the only supported access mode and it requires
+   running the ``virtiofsd`` daemon as root.
+
+#. Boot the guest and mount the filesystem
+
+   ::
+
+      guest# mount -t virtiofs mount_tag /mnt/mount/path
+
+   Note: this requires virtiofs support in the guest kernel (Linux v5.4 or later)
+
+===================
+Optional parameters
+===================
+
+More optional elements can be specified
+
+::
+
+  <driver type='virtiofs' queue='1024'/>
+  <binary path='/usr/libexec/virtiofsd' xattr='on'>
+    <cache mode='always'/>
+    <lock posix_lock='on' flock='on'/>
+  </binary>