docs: improve type='user' docs to higlight differences between SLIRP and passt

This reorganizes the section about <interface type='user'> and
describes the differences in behavior between SLIRP and passt.

Resolves: https://issues.redhat.com/browse/RHEL-46601
Signed-off-by: Laine Stump <laine@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>

docs/formatdomain.rst

@@ -5089,25 +5089,34 @@ to the interface.
    </devices>
    ...
 
-Userspace (SLIRP or passt) connection
+Userspace connection using SLIRP
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The ``user`` type connects the guest interface to the outside via a
+The ``user`` interface type connects the guest interface to the outside via a
 transparent userspace proxy that doesn't require any special system
 privileges, making it usable in cases when libvirt itself is running
 with no privileges (e.g. libvirt's "session mode" daemon, or when
 libvirt is run inside an unprivileged container).
 
-By default, this user proxy is done with QEMU's internal SLIRP driver
+By default, this user proxy is done with QEMU's SLIRP driver, a
-which has DHCP & DNS services that give the guest IP addresses
+userspace proxy built into QEMU that has DHCP & DNS services that give
-starting from ``10.0.2.15``, a default route of ``10.0.2.2`` and DNS
+the guest an IP address of ``10.0.2.15``, a default route of
-server of ``10.0.2.3``. :since:`Since 3.8.0` it is possible to override
+``10.0.2.2`` and DNS server at ``10.0.2.3``.
-the default network address by including an ``ip`` element specifying
+
-an IPv4 address in its one mandatory attribute,
+:since:`Since 3.8.0` it is possible to override the guest's default
-``address``. Optionally, a second ``ip`` element with a ``family``
+network address by including an ``ip`` element specifying an IPv4
-attribute set to "ipv6" can be specified to add an IPv6 address to the
+address in its one mandatory attribute, ``address``. Optionally, a
-interface. ``address``. Optionally, address ``prefix`` can be
+second ``ip`` element with a ``family`` attribute set to "ipv6" can be
-specified.
+specified to add an IPv6 address to the interface. ``address``.
+Optionally, an address ``prefix`` can be specified. These settings are
+surprisingly **not** used by SLIRP to set the exact IP address;
+instead they are used to determine what network/subnet the guest's IP
+address should be on, and the guest will be given an address in that
+subnet, but the host portion of the address will still be "2.15". In
+the example below, for example, the guest will be given the IP address
+172.17.2.15 (**note that the '1.1' in the host portion of the address
+has been ignored**), default route of 172.17.2.2, and DNS server
+172.17.2.3.
 
 ::
 
@@ -5117,34 +5126,65 @@ specified.
      ...
      <interface type='user'>
        <mac address="00:11:22:33:44:55"/>
-       <ip family='ipv4' address='172.17.2.0' prefix='24'/>
+       <ip family='ipv4' address='172.17.1.1' prefix='16'/>
-       <ip family='ipv6' address='2001:db8:ac10:fd01::' prefix='64'/>
+       <ip family='ipv6' address='2001:db8:ac10:fd01::1' prefix='64'/>
      </interface>
    </devices>
    ...
 
-:since:`Since 9.0.0` an alternate backend implementation of the
+Userspace connection using passt
-``user`` interface type can be selected by setting the interface's
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-``<backend>`` subelement ``type`` attribute to ``passt``. In this
-case, the passt transport (https://passt.top) is used. Similar to
-SLIRP, passt has an internal DHCP server that provides a requesting
-guest with one ipv4 and one ipv6 address; it then uses userspace
-proxies and a separate network namespace to provide outgoing
-UDP/TCP/ICMP sessions, and optionally redirect incoming traffic
-destined for the host toward the guest instead.
 
-When the passt backend is used, the ``<backend>`` attribute
+:since:`Since 9.0.0 (QEMU and KVM only)` an alternate backend
-``logFile`` can be used to tell the passt process for this interface
+implementation of the ``user`` interface type can be selected by
-where to write its message log, and the ``<source>`` attribute ``dev``
+setting the interface's ``<backend>`` subelement ``type`` attribute to
-can tell it to use a particular host interface to derive the routes
+``passt``. In this case, the passt transport `(details here)
-given to the guest for forwarding traffic upstream.  Due to the design
+<https://passt.top>`__ is used. passt is run as a separate process
-decisions of passt, if using SELinux, the log file is recommended to
+from QEMU - the passt process handles the details of forwarding
-reside in the runtime directory of a user under which the passt
+network traffic back and forth to the physical network (using
-process will run, most probably ``/run/user/$UID`` where ``$UID`` is
+userspace proxies and a separate network namespace to provide outgoing
-the UID of the user, e.g. ``qemu``.  Beware that libvirt does not
+UDP/TCP/ICMP sessions, and optionally redirecting incoming traffic
-create this directory if it does not already exist to avoid possible,
+destined for the host toward the guest instead), and a socket between
-however unlikely, issues, especially since this logfile attribute is
+passt and QEMU forwards that traffic on to the guest (and back out,
-meant mostly for debugging.
+of course).
+
+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 ``<ip>`` element
+(described above, with behavioral differences as outlined below) to
+configure one IPv4 and one IPv6 address that passt's DHCP server can
+provide to the guest.
+
+Unlike SLIRP, when no `<ip>`` address is specified, passt will by
+default provide the guest with an IP address, DNS server, etc. that
+are identical to those settings on the host itself (through the magic
+of the proxies and a separate network namespace, this doesn't create
+any conflict).
+
+Also different from SLIRP's behavior: if you do specify IP
+address(es), the exact address and netmask/prefix you specify will be
+provided to the guest (i.e. passt doesn't interpret the <ip> settings
+as a network address like SLIRP does, but as a host address). In
+example given above, the guest IP would be set to exactly 172.17.1.1.
+
+Just as with SLIRP, though, once traffic from the guest leaves the
+host towards the rest of the network, it will always appear as if it
+came from the host's IP.
+
+There are a few other options that are configurable only for the passt
+backend.  For example, the ``<backend>`` attribute ``logFile`` can be
+used to tell the passt process for this interface where to write its
+message log, and the ``<source>`` attribute ``dev`` can tell it a
+particular host interface to use when deriving the routes given to the
+guest for forwarding traffic upstream.  Due to the design decisions of
+passt, when using SELinux on the host, it is recommended that the log
+file reside in the runtime directory of the user under which the passt
+process will run, most probably ``/run/user/$UID`` (where ``$UID`` is
+the UID of that user), e.g. ``/run/user/1000``. Be aware that libvirt
+does not create this directory if it does not already exist to avoid
+possible, however unlikely, issues with orphaned directories or
+permissions, etc. The logfile attribute is meant mostly for debugging,
+so it shouldn't be set under normal circumstances.
 
 Additionally, when passt is used, multiple ``<portForward>`` elements
 can be added to forward incoming network traffic for the host to this
@@ -5181,7 +5221,7 @@ ports **with the exception of some subset**.
        <backend type='passt' logFile='/run/user/$UID/passt-domain.log'/>
        <mac address="00:11:22:33:44:55"/>
        <source dev='eth0'/>
-       <ip family='ipv4' address='172.17.2.4' prefix='24'/>
+       <ip family='ipv4' address='172.17.5.4' prefix='24'/>
        <ip family='ipv6' address='2001:db8:ac10:fd01::20'/>
        <portForward proto='tcp'>
          <range start='2022' to='22'/>