[libvirt PATCHv5 06/15] docs: add virtiofs kbase
Christophe de Dinechin
dinechin at redhat.com
Wed Feb 26 13:08:31 UTC 2020
> On 26 Feb 2020, at 12:57, Ján Tomko <jtomko at redhat.com> wrote:
>
> Add a document describing the usage of virtiofs.
> ---
> docs/kbase.html.in | 3 +
> docs/kbase/virtiofs.rst | 152 ++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 155 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 @@
> <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
> index 0000000000..fe6885d139
> --- /dev/null
> +++ b/docs/kbase/virtiofs.rst
> @@ -0,0 +1,152 @@
> +============================
> +Sharing files with Virtio-FS
> +============================
> +
> +=== 8< delete before merging 8< ===
> +NOTE: if you're looking at this note, this is just a proposal.
> +See the up-to-date version on: https://libvirt.org/kbase/virtiofs.html
> +=== 8< --------------------- 8< ===
> +
> +.. 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``
Would it be useful to add a rationale as to why this config dir is not in
the XML file itself?
> +
> + ::
> +
> + # 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>
> --
> 2.24.1
>
More information about the libvir-list
mailing list