|
 |
a41c76 |
From ee1081b3b87179b5b9ed6a1d14694962fa04a5fd Mon Sep 17 00:00:00 2001
|
|
|
a41c76 |
Message-Id: <ee1081b3b87179b5b9ed6a1d14694962fa04a5fd@dist-git>
|
|
|
a41c76 |
From: =?UTF-8?q?J=C3=A1n=20Tomko?= <jtomko@redhat.com>
|
|
|
a41c76 |
Date: Wed, 4 Mar 2020 12:42:40 +0100
|
|
|
a41c76 |
Subject: [PATCH] docs: add virtiofs kbase
|
|
|
a41c76 |
MIME-Version: 1.0
|
|
|
a41c76 |
Content-Type: text/plain; charset=UTF-8
|
|
|
a41c76 |
Content-Transfer-Encoding: 8bit
|
|
|
a41c76 |
|
|
|
a41c76 |
Add a document describing the usage of virtiofs.
|
|
|
a41c76 |
|
|
|
a41c76 |
Signed-off-by: Ján Tomko <jtomko@redhat.com>
|
|
|
a41c76 |
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
|
|
|
a41c76 |
Tested-by: Andrea Bolognani <abologna@redhat.com>
|
|
|
a41c76 |
(cherry picked from commit aecf1f5d702ad710aed99a688f38f05cc304b03a)
|
|
|
a41c76 |
Signed-off-by: Ján Tomko <jtomko@redhat.com>
|
|
|
a41c76 |
|
|
|
a41c76 |
Conflicts: * downstream is missing the link to qemu-passthrough-security
|
|
|
a41c76 |
docs/kbase.html.in
|
|
|
a41c76 |
https://bugzilla.redhat.com/show_bug.cgi?id=1694166
|
|
|
a41c76 |
Message-Id: <a037a8c8db2e3be9a54467859b700a9d7ab15429.1583322090.git.jtomko@redhat.com>
|
|
|
a41c76 |
Reviewed-by: Michal Privoznik <mprivozn@redhat.com>
|
|
|
a41c76 |
---
|
|
|
a41c76 |
docs/kbase.html.in | 3 +
|
|
|
a41c76 |
docs/kbase/virtiofs.rst | 147 ++++++++++++++++++++++++++++++++++++++++
|
|
|
a41c76 |
2 files changed, 150 insertions(+)
|
|
|
a41c76 |
create mode 100644 docs/kbase/virtiofs.rst
|
|
|
a41c76 |
|
|
|
a41c76 |
diff --git a/docs/kbase.html.in b/docs/kbase.html.in
|
|
|
a41c76 |
index c156414c41..7d6caf3cb1 100644
|
|
|
a41c76 |
--- a/docs/kbase.html.in
|
|
|
a41c76 |
+++ b/docs/kbase.html.in
|
|
|
a41c76 |
@@ -29,6 +29,9 @@
|
|
|
a41c76 |
Backing chain management
|
|
|
a41c76 |
Explanation of how disk backing chain specification impacts libvirt's
|
|
|
a41c76 |
behaviour and basic troubleshooting steps of disk problems.
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ Virtio-FS
|
|
|
a41c76 |
+ Share a filesystem between the guest and the host
|
|
|
a41c76 |
|
|
|
a41c76 |
|
|
|
a41c76 |
|
|
|
a41c76 |
diff --git a/docs/kbase/virtiofs.rst b/docs/kbase/virtiofs.rst
|
|
|
a41c76 |
new file mode 100644
|
|
|
a41c76 |
index 0000000000..68fbafcf37
|
|
|
a41c76 |
--- /dev/null
|
|
|
a41c76 |
+++ b/docs/kbase/virtiofs.rst
|
|
|
a41c76 |
@@ -0,0 +1,147 @@
|
|
|
a41c76 |
+============================
|
|
|
a41c76 |
+Sharing files with Virtio-FS
|
|
|
a41c76 |
+============================
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+.. contents::
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+=========
|
|
|
a41c76 |
+Virtio-FS
|
|
|
a41c76 |
+=========
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+Virtio-FS is a shared file system that lets virtual machines access
|
|
|
a41c76 |
+a directory tree on the host. Unlike existing approaches, it
|
|
|
a41c76 |
+is designed to offer local file system semantics and performance.
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+See https://virtio-fs.gitlab.io/
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+==========
|
|
|
a41c76 |
+Host setup
|
|
|
a41c76 |
+==========
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+The host-side virtiofsd daemon, like other vhost-user backed devices,
|
|
|
a41c76 |
+requires shared memory between the host and the guest. As of QEMU 4.2, this
|
|
|
a41c76 |
+requires specifying a NUMA topology for the guest and explicitly specifying
|
|
|
a41c76 |
+a memory backend. Multiple options are available:
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+Either of the following:
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+* Use file-backed memory
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ Configure the directory where the files backing the memory will be stored
|
|
|
a41c76 |
+ with the ``memory_backing_dir`` option in ``/etc/libvirt/qemu.conf``
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ ::
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ # This directory is used for memoryBacking source if configured as file.
|
|
|
a41c76 |
+ # NOTE: big files will be stored here
|
|
|
a41c76 |
+ memory_backing_dir = "/dev/shm/"
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+* Use hugepage-backed memory
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ Make sure there are enough huge pages allocated for the requested guest memory.
|
|
|
a41c76 |
+ For example, for one guest with 2 GiB of RAM backed by 2 MiB hugepages:
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ ::
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ # virsh allocpages 2M 1024
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+===========
|
|
|
a41c76 |
+Guest setup
|
|
|
a41c76 |
+===========
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+#. Specify the NUMA topology
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ in the domain XML of the guest.
|
|
|
a41c76 |
+ For the simplest one-node topology for a guest with 2GiB of RAM and 8 vCPUs:
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ ::
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ <domain>
|
|
|
a41c76 |
+ ...
|
|
|
a41c76 |
+ <cpu ...>
|
|
|
a41c76 |
+ <numa>
|
|
|
a41c76 |
+ <cell id='0' cpus='0-7' memory='2' unit='GiB' memAccess='shared'/>
|
|
|
a41c76 |
+ </numa>
|
|
|
a41c76 |
+ </cpu>
|
|
|
a41c76 |
+ ...
|
|
|
a41c76 |
+ </domain>
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ Note that the CPU element might already be specified and only one is allowed.
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+#. Specify the memory backend
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ Either of the following:
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ * File-backed memory
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ ::
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ <domain>
|
|
|
a41c76 |
+ ...
|
|
|
a41c76 |
+ <memoryBacking>
|
|
|
a41c76 |
+ <access mode='shared'/>
|
|
|
a41c76 |
+ </memoryBacking>
|
|
|
a41c76 |
+ ...
|
|
|
a41c76 |
+ </domain>
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ This will create a file in the directory specified in ``qemu.conf``
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ * Hugepage-backed memory
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ ::
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ <domain>
|
|
|
a41c76 |
+ ...
|
|
|
a41c76 |
+ <memoryBacking>
|
|
|
a41c76 |
+ <hugepages>
|
|
|
a41c76 |
+ <page size='2' unit='M'/>
|
|
|
a41c76 |
+ </hugepages>
|
|
|
a41c76 |
+ <access mode='shared'/>
|
|
|
a41c76 |
+ </memoryBacking>
|
|
|
a41c76 |
+ ...
|
|
|
a41c76 |
+ </domain>
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+#. Add the ``vhost-user-fs`` QEMU device via the ``filesystem`` element
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ ::
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ <domain>
|
|
|
a41c76 |
+ ...
|
|
|
a41c76 |
+ <devices>
|
|
|
a41c76 |
+ ...
|
|
|
a41c76 |
+ <filesystem type='mount' accessmode='passthrough'>
|
|
|
a41c76 |
+ <driver type='virtiofs'/>
|
|
|
a41c76 |
+ <source dir='/path'/>
|
|
|
a41c76 |
+ <target dir='mount_tag'/>
|
|
|
a41c76 |
+ </filesystem>
|
|
|
a41c76 |
+ ...
|
|
|
a41c76 |
+ </devices>
|
|
|
a41c76 |
+ </domain>
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ Note that despite its name, the ``target dir`` is actually a mount tag and does
|
|
|
a41c76 |
+ not have to correspond to the desired mount point in the guest.
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ So far, ``passthrough`` is the only supported access mode and it requires
|
|
|
a41c76 |
+ running the ``virtiofsd`` daemon as root.
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+#. Boot the guest and mount the filesystem
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ ::
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ guest# mount -t virtiofs mount_tag /mnt/mount/path
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ Note: this requires virtiofs support in the guest kernel (Linux v5.4 or later)
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+===================
|
|
|
a41c76 |
+Optional parameters
|
|
|
a41c76 |
+===================
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+More optional elements can be specified
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+::
|
|
|
a41c76 |
+
|
|
|
a41c76 |
+ <driver type='virtiofs' queue='1024'/>
|
|
|
a41c76 |
+ <binary path='/usr/libexec/virtiofsd' xattr='on'>
|
|
|
a41c76 |
+ <cache mode='always'/>
|
|
|
a41c76 |
+ <lock posix_lock='on' flock='on'/>
|
|
|
a41c76 |
+ </binary>
|
|
|
a41c76 |
--
|
|
|
a41c76 |
2.25.1
|
|
|
a41c76 |
|