External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2024-07-11 12:25:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add virtiofs kbase

Browse Source 
Add a document describing the usage of virtiofs.

Signed-off-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Peter Krempa <pkrempa@redhat.com>
Tested-by: Andrea Bolognani <abologna@redhat.com>
This commit is contained in:
Ján Tomko 2019-12-11 13:10:07 +01:00
parent d99128a62b
commit aecf1f5d70
2 changed files with 150 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/kbase.html.in
View File

@ -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>

147
docs/kbase/virtiofs.rst Normal file
View File

@ -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:
::
<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>