From aecf1f5d702ad710aed99a688f38f05cc304b03a Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A1n=20Tomko?= Date: Wed, 11 Dec 2019 13:10:07 +0100 Subject: [PATCH] docs: add virtiofs kbase MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 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 --- 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 db84b95b60..7055f4fda4 100644 --- a/docs/kbase.html.in +++ b/docs/kbase.html.in @@ -33,6 +33,9 @@
Security with QEMU passthrough
Examination of the security protections used for QEMU and how they need configuring to allow use of QEMU passthrough with host files/devices.
+ +
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.47.2