From 3bcec68251696b1255be7dc2504378b927ef5123 Mon Sep 17 00:00:00 2001 Message-ID: <3bcec68251696b1255be7dc2504378b927ef5123.1739824250.git.jdenemar@redhat.com> From: Laine Stump Date: Fri, 14 Feb 2025 23:35:56 -0500 Subject: [PATCH] docs: document using passt backend with MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Almost everything is already there (in the section for using passt with type='user'), so we just need to point to that from the type='vhostuser' section (and vice versa), and add a bit of glue. Also updated a few related details that have changed (e.g. default model type for vhostuser is now 'virtio', and source type/mode are now optional), and changed "vhost-user interface" to "vhost-user connection" because the interface is a virtio interface, and vhost-user is being used to connect that interface to the outside. Signed-off-by: Laine Stump Reviewed-by: Ján Tomko (cherry picked from commit 96fd17a99b514e585a94d43d40ab9a74907c7a5b) https://issues.redhat.com/browse/RHEL-69455 Signed-off-by: Laine Stump --- docs/formatdomain.rst | 73 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 62 insertions(+), 11 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 577366b934..c077c09a39 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -5131,6 +5131,15 @@ destined for the host toward the guest instead), and a socket between passt and QEMU forwards that traffic on to the guest (and back out, of course). +*(:since:`Since 11.1.0 (QEMU and KVM only)` you may prefer to use the +passt backend with the more efficient and performant type='vhostuser' +rather than type='user'. All the options related to passt in the +paragraphs below here also apply when using the passt backend with +type='vhostuser'; any other details specific to vhostuser are +described* `here +`__.) + + Similar to SLIRP, passt has an internal DHCP server that provides a requesting guest with one ipv4 and one ipv6 address. There are default values for both of these, or you can use the ```` element @@ -5823,7 +5832,7 @@ following attributes are available for the ``virtio`` NIC driver: The optional ``queues`` attribute controls the number of queues to be used for either `Multiqueue virtio-net `__ or vhost-user (See - `vhost-user interface`_) network interfaces. Use of multiple packet + `vhost-user connection`_) network interfaces. Use of multiple packet processing queues requires the interface having the ```` element. Each queue will potentially be handled by a different processor, resulting in much higher throughput. @@ -6267,8 +6276,8 @@ similarly named elements used to configure the guest side of the interface (described above). -vhost-user interface -^^^^^^^^^^^^^^^^^^^^ +vhost-user connection +^^^^^^^^^^^^^^^^^^^^^ :since:`Since 1.2.7` the vhost-user enables the communication between a QEMU virtual machine and other userspace process using the Virtio transport protocol. @@ -6295,16 +6304,58 @@ plane is based on shared memory. ... -The ```` element has to be specified along with the type of char device. -Currently, only type='unix' is supported, where the path (the directory path of -the socket) and mode attributes are required. Both ``mode='server'`` and -``mode='client'`` are supported. vhost-user requires the virtio model type, thus -the ```` element is mandatory. :since:`Since 4.1.0` the element has an -optional child element ``reconnect`` which configures reconnect timeout if the -connection is lost. It has two attributes ``enabled`` (which accepts ``yes`` and -``no``) and ``timeout`` which specifies the amount of seconds after which +The ```` element has to be specified along with the type of +char device. Currently, only type='unix' is supported, where the path +(the directory path of the socket) and mode attributes are +required. Both ``mode='server'`` and ``mode='client'`` are +supported. (:since:`Since 11.1.0` the default source type for +vhostuser interfaces is 'unix' and default mode is 'client', so those +two attributes are now optional). + +The vhost-user protocol only works with the virtio guest driver, so +the ```` element ``type`` attribute is mandatory (:since:`Since +11.1.0` the default model type for vhostuser interfaces is now +'virtio' so ```` is no longer mandatory). :since:`Since 4.1.0` +the ```` element has an optional child element ``reconnect`` +which configures reconnect timeout if the connection is lost. It has +two attributes ``enabled`` (which accepts ``yes`` and ``no``) and +``timeout`` which specifies the amount of seconds after which hypervisor tries to reconnect. + +vhost-user connection with passt backend +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:since:`Since 11.1.0 (QEMU and KVM only)` passt can be used as the +other end of the vhost-user connection. This is a compelling +alternative, because passt provides all of its network connectivity +without requiring any elevated privileges or capabilities, and +vhost-user uses shared memory to make this unprivileged connection +very high performance as well. You can set a type='vhostuser' +interface to use passt as the backend by adding ````. When passt is the backend, only a single driver +queue is supported, and the ```` path/type/mode are all +implied to be "matching the passt process" so **must not** be +specified. All of the passt options `described here +`__, are also +supported for ``type='vhostuser'`` with the passt backend, e.g. +setting guest-side IP addresses with ```` and port forwarding with +`` + + + + + + + + ... + + Traffic filtering with NWFilter ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- 2.48.1