From ee1081b3b87179b5b9ed6a1d14694962fa04a5fd Mon Sep 17 00:00:00 2001 Message-Id: From: =?UTF-8?q?J=C3=A1n=20Tomko?= Date: Wed, 4 Mar 2020 12:42:40 +0100 Subject: [PATCH] docs: add virtiofs kbase MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a document describing the usage of virtiofs. Signed-off-by: Ján Tomko Reviewed-by: Peter Krempa Tested-by: Andrea Bolognani (cherry picked from commit aecf1f5d702ad710aed99a688f38f05cc304b03a) Signed-off-by: Ján Tomko Conflicts: * downstream is missing the link to qemu-passthrough-security docs/kbase.html.in https://bugzilla.redhat.com/show_bug.cgi?id=1694166 Message-Id: Reviewed-by: Michal Privoznik --- docs/kbase.html.in | 3 + docs/kbase/virtiofs.rst | 147 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 150 insertions(+) create mode 100644 docs/kbase/virtiofs.rst diff --git a/docs/kbase.html.in b/docs/kbase.html.in index c156414c41..7d6caf3cb1 100644 --- a/docs/kbase.html.in +++ b/docs/kbase.html.in @@ -29,6 +29,9 @@
Backing chain management
Explanation of how disk backing chain specification impacts libvirt's behaviour and basic troubleshooting steps of disk problems.
+ +
Virtio-FS
+
Share a filesystem between the guest and the host
diff --git a/docs/kbase/virtiofs.rst b/docs/kbase/virtiofs.rst new file mode 100644 index 0000000000..68fbafcf37 --- /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: + + :: + + + ... + + + + + + ... + + + 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 + + :: + + + ... + + + + ... + + + This will create a file in the directory specified in ``qemu.conf`` + + * Hugepage-backed memory + + :: + + + ... + + + + + + + ... + + +#. Add the ``vhost-user-fs`` QEMU device via the ``filesystem`` element + + :: + + + ... + + ... + + + + + + ... + + + + 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 + +:: + + + + + + -- 2.25.1