[libvirt PATCHv2 10/10] docs: add virtiofs kbase

[Peter Krempa]

On Thu, Jan 23, 2020 at 18:46:11 +0100, Ján Tomko wrote:
> Add a document describing the usage of virtiofs.
> ---
>  docs/kbase.html.in      |   3 +
>  docs/kbase/virtiofs.rst | 153 ++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 156 insertions(+)
>  create mode 100644 docs/kbase/virtiofs.rst

The XML documentation added to formatdomain.html is really lacking. At
the very least this document should be linked from there.

> 
> 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 @@
>          <dt><a href="kbase/backing_chains.html">Backing chain management</a></dt>
>          <dd>Explanation of how disk backing chain specification impacts libvirt's
>            behaviour and basic troubleshooting steps of disk problems.</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..83351e0a28
> --- /dev/null
> +++ b/docs/kbase/virtiofs.rst
> @@ -0,0 +1,153 @@
> +============================
> +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 delicious delicacy aiming to provide an easy-to-configure
> +way of sharing filesystems between the host and the virtual machine.
> +
> +See https://virtio-fs.gitlab.io/
> +
> +==========
> +Host setup
> +==========
> +
> +The host-side virtiofsd daemon, like other vhost-user backed devices,
> +requres 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:
> +
> +1. 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/"
> +
> +2. Use hugepage-backed memory
> +
> +Make sure there are enough huge pages allocated for the requested guest memory.
> +For exmaple, for one guest with 2 GiB of RAM backed by 2 MiB hugepages:
> +
> +::
> +
> +   # virsh allocpages 2M 1024
> +
> +===========
> +Guest setup
> +===========
> +
> +1. 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.
> +
> +2. Specify the memory backend
> +
> +Either of the following:
> +
> +2.1. File-backed memory
> +
> +::
> +
> +   <domain>
> +     ...
> +     <memoryBacking>
> +       <access mode='shared'/>
> +     </memoryBacking>
> +     ...
> +   </domain>
> +
> +This will create a file in the directory specified in ``qemu.conf``
> +
> +2.2. Hugepage-backed memory
> +
> +::
> +
> +   <domain>
> +     ...
> +     <memoryBacking>
> +       <hugepages>
> +         <page size='2' unit='M'/>
> +       </hugepages>
> +       <access mode='shared'/>
> +     </memoryBacking>
> +     ...
> +   </domain>
> +
> +3. Add the ``vhost-user-fs`` QEMU device via the ``filesystem`` element
> +
> +::
> +
> +   <domain>
> +     ...
> +     <devices>
> +       ...
> +       <filesystem type='mount' accessmode='passthrough'>
> +         <driver type='virtiofs'>
> +           <binary>/usr/libexec/virtiofsd</binary>
> +         </driver>
> +         <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.

In that case it should perhaps also have a different attribute.

> +
> +So far, ``passthrough`` is the only supported access mode and it requires
> +running the ``virtiofsd`` daemon as root.
> +
> +4. 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' xattr='on'>
> +    <binary>/usr/libexec/virtiofsd</binary>
> +    <cache mode='always' size='1024' unit='GiB'/>
> +    <lock posix_lock='on' flock='on'/>
> +  </driver>
> -- 
> 2.21.0
>