[PATCH] Fix a typo in docs/formatdomain.rst
Fix a typo and update the setting in the example. The documentation explains that "when passt is the backend,...the ``<source>`` path/type/mode are all implied to be "matching the passt process" so **must not** be specified." Additionally, this source dev setting is ignored in practice. Therefore, let's remove it from the example to avoid any confusion. Signed-off-by: Yalan Zhang <yalzhang@redhat.com> --- docs/formatdomain.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index cbe378e61d..e84e0a0e8e 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -5154,7 +5154,7 @@ 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 +: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 @@ -6378,7 +6378,6 @@ setting guest-side IP addresses with ``<ip>`` and port forwarding with <interface type='vhostuser'> <backend type='passt'/> <mac address='52:54:00:3b:83:1a'/> - <source dev='enp1s0'/> <ip address='10.30.0.5 prefix='24'/> </interface> </devices> -- 2.48.1
On a Wednesday in 2025, Yalan Zhang wrote:
Fix a typo and update the setting in the example. The documentation explains that "when passt is the backend,...the ``<source>`` path/type/mode are all implied to be "matching the passt process" so **must not** be specified." Additionally, this source dev setting is ignored in practice. Therefore, let's remove it from the example to avoid any confusion.
Signed-off-by: Yalan Zhang <yalzhang@redhat.com> --- docs/formatdomain.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index cbe378e61d..e84e0a0e8e 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -5154,7 +5154,7 @@ 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).
Oops, I have not looked at how this renders when reviewing the original patch - that the extra characters prevent the :since: tag from working.
-*(:since:`Since 11.1.0 (QEMU and KVM only)` you may prefer to use the +: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
Additional context: type='vhostuser'; any other details specific to vhostuser are described* `here <formatdomain.html#vhost-user-connection-with-passt-backend>`__.) So the asterisk ending the italics and the ending parenthesis should be removed too. I can squash that change in before pushing, unless someone objects to removing the italics and parenthesis.
@@ -6378,7 +6378,6 @@ setting guest-side IP addresses with ``<ip>`` and port forwarding with <interface type='vhostuser'> <backend type='passt'/> <mac address='52:54:00:3b:83:1a'/> - <source dev='enp1s0'/> <ip address='10.30.0.5 prefix='24'/> </interface> </devices> --
Reviewed-by: Ján Tomko <jtomko@redhat.com> Jano
Just now took my daily look at the list and saw this patch... On 3/5/25 11:42 AM, Ján Tomko wrote:
On a Wednesday in 2025, Yalan Zhang wrote:
Fix a typo and update the setting in the example. The documentation explains that "when passt is the backend,...the ``<source>`` path/type/mode are all implied to be "matching the passt process" so **must not** be specified." Additionally, this source dev setting is ignored in practice. Therefore, let's remove it from the example to avoid any confusion.
Signed-off-by: Yalan Zhang <yalzhang@redhat.com> --- docs/formatdomain.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index cbe378e61d..e84e0a0e8e 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -5154,7 +5154,7 @@ 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).
Oops, I have not looked at how this renders when reviewing the original patch - that the extra characters prevent the :since: tag from working.
-*(:since:`Since 11.1.0 (QEMU and KVM only)` you may prefer to use the +: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
Additional context: type='vhostuser'; any other details specific to vhostuser are described* `here <formatdomain.html#vhost-user-connection-with-passt-backend>`__.)
So the asterisk ending the italics and the ending parenthesis should be removed too.
Yeah, sorry I didn't notice that the italicization not only didn't work, but also prevented the :since: tag from working. That's unfortunate - I would have preferred for that paragraph to be italicized :-/
I can squash that change in before pushing, unless someone objects to removing the italics and parenthesis.
@@ -6378,7 +6378,6 @@ setting guest-side IP addresses with ``<ip>`` and port forwarding with <interface type='vhostuser'> <backend type='passt'/> <mac address='52:54:00:3b:83:1a'/> - <source dev='enp1s0'/>
It is correct the path/type/mode in <source> are not used or allowed for type='vhostuser', but that's not what is being set in this example - it is setting source dev, which *is* valid to set - for both flavors of passt connection the source dev is the name of the host network device passt uses when figuring out what default route to provide to the guest in its DHCP responses (and also what IP address and netmask to provide by default in the DHCP response when specific IP/netmask aren't set). So this line should remain in the example. Please don't remove it.
<ip address='10.30.0.5 prefix='24'/> </interface> </devices> --
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Jano
Hi Laine, The <source dev/> setting will be ignored after "virsh define" or when you save after "virsh edit". Do you think it is a bug? Details: SC1: define # cat rhel.xml | grep /interface -B6 <interface type='vhostuser'> <mac address='52:54:00:e2:ba:2c'/> <model type='virtio'/> <backend type='passt'/> <source dev='eno8303'/> <address type='pci' domain='0x0000' bus='0x01' slot='0x00' function='0x0'/> </interface> # virsh define rhel.xml Domain 'rhel' defined from rhel.xml # virsh dumpxml rhel --xpath //interface <interface type="vhostuser"> <mac address="52:54:00:e2:ba:2c"/> <model type="virtio"/> <backend type="passt"/> <address type="pci" domain="0x0000" bus="0x01" slot="0x00" function="0x0"/> </interface> SC2: virsh edit # virsh edit rhel <interface type='vhostuser'> <mac address='52:54:00:e2:ba:2c'/> <model type='virtio'/> <backend type='passt'/> <source dev='eno8303'/> <portForward proto='tcp' address='10.73.211.16' dev='eno8303'> <range start='2000'/> <range start='3000' to='3001'/> </portForward> <address type='pci' domain='0x0000' bus='0x01' slot='0x00' function='0x0'/> </interface> after save, check the xml: # virsh dumpxml rhel --xpath //interface <interface type="vhostuser"> <mac address="52:54:00:e2:ba:2c"/> <portForward proto="tcp" address="10.73.211.16" dev="eno8303"> <range start="2000"/> <range start="3000" to="3001"/> </portForward> <model type="virtio"/> <backend type="passt"/> <alias name="net0"/> <address type="pci" domain="0x0000" bus="0x01" slot="0x00" function="0x0"/> </interface> start the vm, check the process: qemu 28692 0.0 0.0 205640 25788 ? Ss 21:07 0:00 passt --vhost-user --one-off --socket /run/libvirt/qemu/passt/1-rhel-net0.socket --pid /run/libvirt/qemu/passt/1-rhel-net0-passt.pid --tcp-ports 10.73.211.16%eno8303/2000,3000:3001 BR, Yalan On Thu, Mar 6, 2025 at 5:50 AM Laine Stump <laine@laine.org> wrote:
Just now took my daily look at the list and saw this patch...
On 3/5/25 11:42 AM, Ján Tomko wrote:
On a Wednesday in 2025, Yalan Zhang wrote:
Fix a typo and update the setting in the example. The documentation explains that "when passt is the backend,...the ``<source>`` path/type/mode are all implied to be "matching the passt process" so **must not** be specified." Additionally, this source dev setting is ignored in practice. Therefore, let's remove it from the example to avoid any confusion.
Signed-off-by: Yalan Zhang <yalzhang@redhat.com> --- docs/formatdomain.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-)
diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index cbe378e61d..e84e0a0e8e 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -5154,7 +5154,7 @@ 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).
Oops, I have not looked at how this renders when reviewing the original patch - that the extra characters prevent the :since: tag from working.
-*(:since:`Since 11.1.0 (QEMU and KVM only)` you may prefer to use the +: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
Additional context: type='vhostuser'; any other details specific to vhostuser are described* `here <formatdomain.html#vhost-user-connection-with-passt-backend>`__.)
So the asterisk ending the italics and the ending parenthesis should be removed too.
Yeah, sorry I didn't notice that the italicization not only didn't work, but also prevented the :since: tag from working. That's unfortunate - I would have preferred for that paragraph to be italicized :-/
I can squash that change in before pushing, unless someone objects to removing the italics and parenthesis.
@@ -6378,7 +6378,6 @@ setting guest-side IP addresses with ``<ip>`` and port forwarding with <interface type='vhostuser'> <backend type='passt'/> <mac address='52:54:00:3b:83:1a'/> - <source dev='enp1s0'/>
It is correct the path/type/mode in <source> are not used or allowed for type='vhostuser', but that's not what is being set in this example - it is setting source dev, which *is* valid to set - for both flavors of passt connection the source dev is the name of the host network device passt uses when figuring out what default route to provide to the guest in its DHCP responses (and also what IP address and netmask to provide by default in the DHCP response when specific IP/netmask aren't set).
So this line should remain in the example. Please don't remove it.
<ip address='10.30.0.5 prefix='24'/> </interface> </devices> --
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Jano
On 3/5/25 9:11 PM, Yalan Zhang wrote:
Hi Laine,
The <source dev/> setting will be ignored after "virsh define" or when you save after "virsh edit". Do you think it is a bug?
Yes, that is a bug. I'll look into it in a bit. Thanks for pointing it out (I could have sworn I included that in the tests, but I guess not)
Details: SC1: define # cat rhel.xml | grep /interface -B6 <interface type='vhostuser'> <mac address='52:54:00:e2:ba:2c'/> <model type='virtio'/> <backend type='passt'/> <source dev='eno8303'/> <address type='pci' domain='0x0000' bus='0x01' slot='0x00' function='0x0'/> </interface>
# virsh define rhel.xml Domain 'rhel' defined from rhel.xml
# virsh dumpxml rhel --xpath //interface <interface type="vhostuser"> <mac address="52:54:00:e2:ba:2c"/> <model type="virtio"/> <backend type="passt"/> <address type="pci" domain="0x0000" bus="0x01" slot="0x00" function="0x0"/> </interface>
SC2: virsh edit # virsh edit rhel
<interface type='vhostuser'>
<mac address='52:54:00:e2:ba:2c'/>
<model type='virtio'/>
<backend type='passt'/>
<source dev='eno8303'/>
<portForward proto='tcp' address='10.73.211.16' dev='eno8303'>
<range start='2000'/>
<range start='3000' to='3001'/>
</portForward>
<address type='pci' domain='0x0000' bus='0x01' slot='0x00' function='0x0'/>
</interface>
after save, check the xml: # virsh dumpxml rhel --xpath //interface <interface type="vhostuser"> <mac address="52:54:00:e2:ba:2c"/> <portForward proto="tcp" address="10.73.211.16" dev="eno8303"> <range start="2000"/> <range start="3000" to="3001"/> </portForward> <model type="virtio"/> <backend type="passt"/> <alias name="net0"/> <address type="pci" domain="0x0000" bus="0x01" slot="0x00" function="0x0"/> </interface>
start the vm, check the process: qemu 28692 0.0 0.0 205640 25788 ? Ss 21:07 0:00 passt --vhost-user --one-off --socket /run/libvirt/qemu/passt/1-rhel- net0.socket --pid /run/libvirt/qemu/passt/1-rhel-net0-passt.pid --tcp- ports 10.73.211.16%eno8303/2000,3000:3001
BR, Yalan
On Thu, Mar 6, 2025 at 5:50 AM Laine Stump <laine@laine.org <mailto:laine@laine.org>> wrote:
Just now took my daily look at the list and saw this patch...
On 3/5/25 11:42 AM, Ján Tomko wrote: > On a Wednesday in 2025, Yalan Zhang wrote: >> Fix a typo and update the setting in the example. The documentation >> explains that "when passt is the backend,...the ``<source>`` >> path/type/mode are all implied to be "matching the passt process" >> so **must not** be specified." Additionally, this source dev setting is >> ignored in practice. Therefore, let's remove it from the example to >> avoid any >> confusion. >> >> Signed-off-by: Yalan Zhang <yalzhang@redhat.com <mailto:yalzhang@redhat.com>> >> --- >> docs/formatdomain.rst | 3 +-- >> 1 file changed, 1 insertion(+), 2 deletions(-) >> >> diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst >> index cbe378e61d..e84e0a0e8e 100644 >> --- a/docs/formatdomain.rst >> +++ b/docs/formatdomain.rst >> @@ -5154,7 +5154,7 @@ 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). >> > > Oops, I have not looked at how this renders when reviewing the original > patch - that the extra characters prevent the :since: tag from working. > >> -*(:since:`Since 11.1.0 (QEMU and KVM only)` you may prefer to use the >> +: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 > > Additional context: > type='vhostuser'; any other details specific to vhostuser are > described* `here > <formatdomain.html#vhost-user-connection-with-passt-backend>`__.) > > So the asterisk ending the italics and the ending parenthesis should be > removed too.
Yeah, sorry I didn't notice that the italicization not only didn't work, but also prevented the :since: tag from working. That's unfortunate - I would have preferred for that paragraph to be italicized :-/
> > I can squash that change in before pushing, unless someone objects > to removing the italics and parenthesis. > >> @@ -6378,7 +6378,6 @@ setting guest-side IP addresses with ``<ip>`` >> and port forwarding with >> <interface type='vhostuser'> >> <backend type='passt'/> >> <mac address='52:54:00:3b:83:1a'/> >> - <source dev='enp1s0'/>
It is correct the path/type/mode in <source> are not used or allowed for type='vhostuser', but that's not what is being set in this example - it is setting source dev, which *is* valid to set - for both flavors of passt connection the source dev is the name of the host network device passt uses when figuring out what default route to provide to the guest in its DHCP responses (and also what IP address and netmask to provide by default in the DHCP response when specific IP/netmask aren't set).
So this line should remain in the example. Please don't remove it.
>> <ip address='10.30.0.5 prefix='24'/> >> </interface> >> </devices> >> -- > > Reviewed-by: Ján Tomko <jtomko@redhat.com <mailto:jtomko@redhat.com>>
> > Jano
participants (3)
-
Ján Tomko -
Laine Stump -
Yalan Zhang