> On 26 Feb 2020, at 12:57, Ján Tomko <jtomko@xxxxxxxxxx> 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 >
