[libvirt PATCH 0/2] docs: virtiofs: move legacy docs to the bottom
The virtiofs kbase article includes a lot of information that is only relevant to old versions of QEMU and libvirt. Setting up virtiofs can seem intimidating but it's actually easier than the article lets on. Move the legacy information out of the way. Stefan Hajnoczi (2): docs: virtiofs: move legacy docs to the bottom docs: virtiofs: use the preferred virtiofs spelling docs/kbase/virtiofs.rst | 183 +++++++++++++++++++++------------------- 1 file changed, 97 insertions(+), 86 deletions(-) -- 2.31.1
A number of legacy issues make the virtiofs kbase article hard to understand. Most users don't need to configure NUMA or a memory backend other than memfd. Move that information to the bottom of the article so the recommended syntax is most prominent. Suggested-by: Richard W.M. Jones <rjones@redhat.com> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com> --- docs/kbase/virtiofs.rst | 171 +++++++++++++++++++++------------------- 1 file changed, 91 insertions(+), 80 deletions(-) diff --git a/docs/kbase/virtiofs.rst b/docs/kbase/virtiofs.rst index 6ba7299a72..75e740bf96 100644 --- a/docs/kbase/virtiofs.rst +++ b/docs/kbase/virtiofs.rst @@ -13,8 +13,82 @@ is designed to offer local file system semantics and performance. See https://virtio-fs.gitlab.io/ -Host setup -========== +Sharing a host directory with a guest +===================================== + +#. Add the following domain XML elements to share the host directory `/path` + with the guest + + :: + + <domain> + ... + <memoryBacking> + <source type='memfd'/> + <access mode='shared'/> + </memoryBacking> + ... + <devices> + ... + <filesystem type='mount' accessmode='passthrough'> + <driver type='virtiofs'/> + <source dir='/path'/> + <target dir='mount_tag'/> + </filesystem> + ... + </devices> + </domain> + + Don't forget the ``<memoryBacking>`` elements. They are necessary for the + vhost-user connection with the ``virtiofsd`` daemon. + + Note that despite its name, the ``target dir`` is an arbitrary string called + a mount tag that is used inside the guest to identify the shared file system + to be mounted. It does not have to correspond to the desired mount point in the + guest. + +#. 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='on' flock='on'/> + </binary> + +Externally-launched virtiofsd +============================= + +Libvirtd can also connect the ``vhost-user-fs`` device to a ``virtiofsd`` +daemon launched outside of libvirtd. In that case socket permissions, +the mount tag and all the virtiofsd options are out of libvirtd's +control and need to be set by the application running virtiofsd. + +:: + + <filesystem type='mount'/> + <driver type='virtiofs' queue='1024'/> + <source socket='/var/virtiofsd.sock'/> + <target dir='tag'/> + </filesystem> + +Other options for vhost-user memory setup +========================================= + +The following information is necessary if you are using older versions of QEMU +and libvirt or have special memory backend requirements. Almost all virtio devices (all that use virtqueues) require access to at least certain portions of guest RAM (possibly policed by DMA). In @@ -29,34 +103,31 @@ NUMA. As of QEMU 5.0.0 and libvirt 6.9.0, it is possible to specify the memory backend without NUMA (using the so called memobject interface). -One of the following: +#. Set up the memory backend -* Use memfd memory + * Use memfd memory - No host setup is required when using the Linux memfd memory backend. + No host setup is required when using the Linux memfd memory backend. -* Use file-backed memory + * 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`` + 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/" + # 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 + * 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: + 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 -=========== + # virsh allocpages 2M 1024 #. Specify the NUMA topology (this step is only required for the NUMA case) @@ -122,63 +193,3 @@ Guest setup </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='on' flock='on'/> - </binary> - -Externally-launched virtiofsd -============================= - -Libvirtd can also connect the ``vhost-user-fs`` device to a ``virtiofsd`` -daemon launched outside of libvirtd. In that case socket permissions, -the mount tag and all the virtiofsd options are out of libvirtd's -control and need to be set by the application running virtiofsd. - -:: - - <filesystem type='mount'/> - <driver type='virtiofs' queue='1024'/> - <source socket='/var/virtiofsd.sock'/> - <target dir='tag'/> - </filesystem> -- 2.31.1
On a Thursday in 2021, Stefan Hajnoczi wrote:
A number of legacy issues make the virtiofs kbase article hard to understand. Most users don't need to configure NUMA or a memory backend other than memfd. Move that information to the bottom of the article so the recommended syntax is most prominent.
Suggested-by: Richard W.M. Jones <rjones@redhat.com> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com> --- docs/kbase/virtiofs.rst | 171 +++++++++++++++++++++------------------- 1 file changed, 91 insertions(+), 80 deletions(-)
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
On Thu, Sep 09, 2021 at 03:58:28PM +0100, Stefan Hajnoczi wrote:
A number of legacy issues make the virtiofs kbase article hard to understand. Most users don't need to configure NUMA or a memory backend other than memfd. Move that information to the bottom of the article so the recommended syntax is most prominent.
Suggested-by: Richard W.M. Jones <rjones@redhat.com> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
This is much better. There are a couple of minor points below but in general: Reviewed-by: Richard W.M. Jones <rjones@redhat.com>
+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='on' flock='on'/> + </binary>
I always think with XML it's better to be completely clear about the context around the element so that users know where to put these extra elements. For this reason I'd probably write this: + <filesystem type='mount'> + <driver type='virtiofs' queue='1024'/> + ... + <binary path='/usr/libexec/virtiofsd' xattr='on'> + <cache mode='always'/> + <lock posix='on' flock='on'/> + </binary> + </filesystem>
+Externally-launched virtiofsd +============================= + +Libvirtd can also connect the ``vhost-user-fs`` device to a ``virtiofsd`` +daemon launched outside of libvirtd. In that case socket permissions, +the mount tag and all the virtiofsd options are out of libvirtd's +control and need to be set by the application running virtiofsd. + +:: + + <filesystem type='mount'/>
Is there an extra '/' above ^^ ? I see the same mistake is present in the current page. Rich. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones Read my programming and virtualization blog: http://rwmj.wordpress.com virt-p2v converts physical machines to virtual machines. Boot with a live CD or over the network (PXE) and turn machines into KVM guests. http://libguestfs.org/virt-v2v
On a Thursday in 2021, Richard W.M. Jones wrote:
On Thu, Sep 09, 2021 at 03:58:28PM +0100, Stefan Hajnoczi wrote:
A number of legacy issues make the virtiofs kbase article hard to understand. Most users don't need to configure NUMA or a memory backend other than memfd. Move that information to the bottom of the article so the recommended syntax is most prominent.
Suggested-by: Richard W.M. Jones <rjones@redhat.com> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
This is much better. There are a couple of minor points below but in general:
Both of those are in pre-existing text that only shows up as '+' lines due to the move. I pushed the fixes as separate trivial patches. Thank you. Jano
On Thu, Sep 09, 2021 at 03:58:28PM +0100, Stefan Hajnoczi wrote:
A number of legacy issues make the virtiofs kbase article hard to understand. Most users don't need to configure NUMA or a memory backend other than memfd. Move that information to the bottom of the article so the recommended syntax is most prominent.
Suggested-by: Richard W.M. Jones <rjones@redhat.com> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com> --- docs/kbase/virtiofs.rst | 171 +++++++++++++++++++++------------------- 1 file changed, 91 insertions(+), 80 deletions(-)
Sebastian mentioned that explicitly setting <source type='memfd'/> is unnecessary because libvirt will use the shm memory backing path by default: <memoryBacking> <access mode='shared'/> </memoryBacking> Should we simplify the kbase example further and drop memfd?
diff --git a/docs/kbase/virtiofs.rst b/docs/kbase/virtiofs.rst index 6ba7299a72..75e740bf96 100644 --- a/docs/kbase/virtiofs.rst +++ b/docs/kbase/virtiofs.rst @@ -13,8 +13,82 @@ is designed to offer local file system semantics and performance.
See https://virtio-fs.gitlab.io/
-Host setup -========== +Sharing a host directory with a guest +===================================== + +#. Add the following domain XML elements to share the host directory `/path` + with the guest + + :: + + <domain> + ... + <memoryBacking> + <source type='memfd'/> + <access mode='shared'/> + </memoryBacking> + ... + <devices> + ... + <filesystem type='mount' accessmode='passthrough'> + <driver type='virtiofs'/> + <source dir='/path'/> + <target dir='mount_tag'/> + </filesystem> + ... + </devices> + </domain> + + Don't forget the ``<memoryBacking>`` elements. They are necessary for the + vhost-user connection with the ``virtiofsd`` daemon. + + Note that despite its name, the ``target dir`` is an arbitrary string called + a mount tag that is used inside the guest to identify the shared file system + to be mounted. It does not have to correspond to the desired mount point in the + guest. + +#. 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='on' flock='on'/> + </binary> + +Externally-launched virtiofsd +============================= + +Libvirtd can also connect the ``vhost-user-fs`` device to a ``virtiofsd`` +daemon launched outside of libvirtd. In that case socket permissions, +the mount tag and all the virtiofsd options are out of libvirtd's +control and need to be set by the application running virtiofsd. + +:: + + <filesystem type='mount'/> + <driver type='virtiofs' queue='1024'/> + <source socket='/var/virtiofsd.sock'/> + <target dir='tag'/> + </filesystem> + +Other options for vhost-user memory setup +========================================= + +The following information is necessary if you are using older versions of QEMU +and libvirt or have special memory backend requirements.
Almost all virtio devices (all that use virtqueues) require access to at least certain portions of guest RAM (possibly policed by DMA). In @@ -29,34 +103,31 @@ NUMA. As of QEMU 5.0.0 and libvirt 6.9.0, it is possible to specify the memory backend without NUMA (using the so called memobject interface).
-One of the following: +#. Set up the memory backend
-* Use memfd memory + * Use memfd memory
- No host setup is required when using the Linux memfd memory backend. + No host setup is required when using the Linux memfd memory backend.
-* Use file-backed memory + * 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`` + 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/" + # 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 + * 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: + 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 -=========== + # virsh allocpages 2M 1024
#. Specify the NUMA topology (this step is only required for the NUMA case)
@@ -122,63 +193,3 @@ Guest setup </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='on' flock='on'/> - </binary> - -Externally-launched virtiofsd -============================= - -Libvirtd can also connect the ``vhost-user-fs`` device to a ``virtiofsd`` -daemon launched outside of libvirtd. In that case socket permissions, -the mount tag and all the virtiofsd options are out of libvirtd's -control and need to be set by the application running virtiofsd. - -:: - - <filesystem type='mount'/> - <driver type='virtiofs' queue='1024'/> - <source socket='/var/virtiofsd.sock'/> - <target dir='tag'/> - </filesystem> -- 2.31.1
The virtiofs project started off using "virtio-fs" but later switched to the "virtiofs" spelling because it matches the spelling of the mount -t virtiofs command-line. Update the kbase article with the new spelling so it matches the virtiofs website. Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com> --- docs/kbase/virtiofs.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/kbase/virtiofs.rst b/docs/kbase/virtiofs.rst index 75e740bf96..d728a1358c 100644 --- a/docs/kbase/virtiofs.rst +++ b/docs/kbase/virtiofs.rst @@ -1,13 +1,13 @@ -============================ -Sharing files with Virtio-FS -============================ +=========================== +Sharing files with Virtiofs +=========================== .. contents:: -Virtio-FS -========= +Virtiofs +======== -Virtio-FS is a shared file system that lets virtual machines access +Virtiofs 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. -- 2.31.1
On a Thursday in 2021, Stefan Hajnoczi wrote:
The virtiofs project started off using "virtio-fs" but later switched to the "virtiofs" spelling because it matches the spelling of the mount -t virtiofs command-line. Update the kbase article with the new spelling so it matches the virtiofs website.
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com> --- docs/kbase/virtiofs.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-)
There are two more occurrences on pages linking to the kbase article. With the following diff squashed in: Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 479a3acfbb..ad3b4ea92c 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -3305,7 +3305,7 @@ A directory on the host that can be accessed directly from the guest. pages touched during a guest file write operation :since:`(since 0.9.10)` . :since:`Since 6.2.0` , ``type='virtiofs'`` is also supported. Using virtiofs requires setting up shared memory, see the guide: - `Virtio-FS <kbase/virtiofs.html>`__ + `Virtiofs <kbase/virtiofs.html>`__ ``template`` OpenVZ filesystem template. Only used by OpenVZ driver. ``file`` diff --git a/docs/kbase/index.rst b/docs/kbase/index.rst index 372042886d..351ea2c93b 100644 --- a/docs/kbase/index.rst +++ b/docs/kbase/index.rst @@ -12,7 +12,7 @@ Usage Explanation of how disk backing chain specification impacts libvirt's behaviour and basic troubleshooting steps of disk problems. -`Virtio-FS <virtiofs.html>`__ +`Virtiofs <virtiofs.html>`__ Share a filesystem between the guest and the host `Security with QEMU passthrough <qemu-passthrough-security.html>`__
On Thu, Sep 09, 2021 at 05:33:43PM +0200, Ján Tomko wrote:
On a Thursday in 2021, Stefan Hajnoczi wrote:
The virtiofs project started off using "virtio-fs" but later switched to the "virtiofs" spelling because it matches the spelling of the mount -t virtiofs command-line. Update the kbase article with the new spelling so it matches the virtiofs website.
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com> --- docs/kbase/virtiofs.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-)
There are two more occurrences on pages linking to the kbase article.
With the following diff squashed in: Reviewed-by: Ján Tomko <jtomko@redhat.com>
Thanks for spotting this! This looks like it can be squashed when merging so I won't resend unless there are other items that need to be addressed. Stefan
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 479a3acfbb..ad3b4ea92c 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -3305,7 +3305,7 @@ A directory on the host that can be accessed directly from the guest. pages touched during a guest file write operation :since:`(since 0.9.10)` . :since:`Since 6.2.0` , ``type='virtiofs'`` is also supported. Using virtiofs requires setting up shared memory, see the guide: - `Virtio-FS <kbase/virtiofs.html>`__ + `Virtiofs <kbase/virtiofs.html>`__ ``template`` OpenVZ filesystem template. Only used by OpenVZ driver. ``file`` diff --git a/docs/kbase/index.rst b/docs/kbase/index.rst index 372042886d..351ea2c93b 100644 --- a/docs/kbase/index.rst +++ b/docs/kbase/index.rst @@ -12,7 +12,7 @@ Usage Explanation of how disk backing chain specification impacts libvirt's behaviour and basic troubleshooting steps of disk problems.
-`Virtio-FS <virtiofs.html>`__ +`Virtiofs <virtiofs.html>`__ Share a filesystem between the guest and the host
`Security with QEMU passthrough <qemu-passthrough-security.html>`__
participants (3)
-
Ján Tomko -
Richard W.M. Jones -
Stefan Hajnoczi