A user commented that the documentation was rather vague about when an
<ip> address specified in a domain <interface> can be used and when it
can't. This extra verbiage attempts to clarify that.

Signed-off-by: Laine Stump <laine@redhat.com>
---

I'm undecided if this is too verbose to be in formatdomain.html, but
once I started typing (after reading this message
https://lists.libvirt.org/archives/list/devel@lists.libvirt.org/thread/DZWKJPK3IFBDDBBZC4NRCTT6MMBTCEZM/
) I decided to finish it and send; if it seems inappropriate there
then maybe it can be put somewhere else.

Also, I *think* I have the information correct for non QEMU/LXC
drivers, but it's based solely on a quick examination of the code
(looking for references to "guestIP").

 docs/formatdomain.rst | 59 +++++++++++++++++++++++++++++++++++--------
 1 file changed, 48 insertions(+), 11 deletions(-)

diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index e4eb2d9ba3..2e314b159e 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -6747,17 +6747,54 @@ IP configuration
    </devices>
    ...
 
-:since:`Since 1.2.12` network devices and hostdev devices with network
-capabilities can optionally be provided one or more IP addresses to set on the
-network device in the guest. Note that some hypervisors or network device types
-will simply ignore them or only use the first one. The ``family`` attribute can
-be set to either ``ipv4`` or ``ipv6``, and the ``address`` attribute contains
-the IP address. The optional ``prefix`` is the number of 1 bits in the netmask,
-and will be automatically set if not specified - for IPv4 the default prefix is
-determined according to the network "class" (A, B, or C - see RFC870), and for
-IPv6 the default prefix is 64. The optional ``peer`` attribute holds the IP
-address of the other end of a point-to-point network device
-:since:`(since 2.1.0)`.
+:since:`Since 1.2.12` in some specific instances, network devices and
+hostdev devices with network capabilities can optionally be provided
+one or more IP addresses to set on the network device in the guest
+using the <ip> subelement. Within <ip>, the ``family`` attribute can
+be set to either ``ipv4`` or ``ipv6``, and the ``address`` attribute
+contains the IP address. The optional ``prefix`` is the number of 1
+bits in the netmask, and will be automatically set if not specified -
+for IPv4 the default prefix is determined according to the network
+"class" (A, B, or C - see RFC870), and for IPv6 the default prefix
+is 64. The optional ``peer`` attribute holds the IP address of the
+other end of a point-to-point network device :since:`(since 2.1.0)`.
+
+As mentioned above, only certain types of interfaces on certain
+hypervisors can use the <ip> element. In particular:
+
+* lxc driver - <interface> or <hostdev mode='capabilities' type='net'>
+  can have one or more IP addresses specified for each interface, and
+  this will be directly set on the interface inside the container by
+  libvirt.
+
+* QEMU driver - <interface type='user'> and <interface
+  type='vhostuser'> (the latter only when <backend type='passt'>) can
+  have a single IPv4 address specified (and for passt-backed
+  interfaces also a single IPv6 address). In these cases, libvirt will
+  setup the internal DHCP server of slirp or passt to provide the IP
+  addresses - the guest OS must have the interface config setup to use
+  DHCP or the settings in libvirt will be ignored.
+
+* VirtualBox driver - for <interface type='bridge'> a single IP
+  address can be set.
+
+* Cloud Hypervisor driver - for <interface type='ethernet'> a
+  single IP address can be set.
+
+* openvz driver - <interface type='ethernet'> can have multiple
+  IP addresses specified.
+
+* Xen driver - <interface type='bridge|ethernet'> can have multiple IP
+  addresses set.
+
+In all other cases, IP addresses in the libvirt domain interface
+config will either be ignored, or generate an error. Aside from this,
+for guests connected via libvirt's own bridge-based virtual networks,
+it is also possible to set IP addresses with static <host> entries in
+the `virtual network's config <formatnetwork.html#addressing>`__. If
+none of the above applies to your guest, IP address configuration must
+be done outside of libvirt, either by changing the relevant DHCP
+server config, or changing the guest OS network config directly.
 
 :since:`Since 1.2.12` route elements can also be added to define IP
 routes to add in the guest. The attributes of this element are
-- 
2.56.0

On a Monday in 2026, Laine Stump via Devel wrote:
>A user commented that the documentation was rather vague about when an
><ip> address specified in a domain <interface> can be used and when it
>can't. This extra verbiage attempts to clarify that.
>
>Signed-off-by: Laine Stump <laine@redhat.com>
>---
>
>I'm undecided if this is too verbose to be in formatdomain.html, but
>once I started typing (after reading this message
>https://lists.libvirt.org/archives/list/devel@lists.libvirt.org/thread/DZWKJPK3IFBDDBBZC4NRCTT6MMBTCEZM/
>) I decided to finish it and send; if it seems inappropriate there
>then maybe it can be put somewhere else.
>
>Also, I *think* I have the information correct for non QEMU/LXC
>drivers, but it's based solely on a quick examination of the code
>(looking for references to "guestIP").
>
> docs/formatdomain.rst | 59 +++++++++++++++++++++++++++++++++++--------
> 1 file changed, 48 insertions(+), 11 deletions(-)
>
>diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
>index e4eb2d9ba3..2e314b159e 100644
>--- a/docs/formatdomain.rst
>+++ b/docs/formatdomain.rst
>@@ -6747,17 +6747,54 @@ IP configuration
>    </devices>
>    ...
>
>-:since:`Since 1.2.12` network devices and hostdev devices with network
>-capabilities can optionally be provided one or more IP addresses to set on the
>-network device in the guest. Note that some hypervisors or network device types
>-will simply ignore them or only use the first one. The ``family`` attribute can
>-be set to either ``ipv4`` or ``ipv6``, and the ``address`` attribute contains
>-the IP address. The optional ``prefix`` is the number of 1 bits in the netmask,
>-and will be automatically set if not specified - for IPv4 the default prefix is
>-determined according to the network "class" (A, B, or C - see RFC870), and for
>-IPv6 the default prefix is 64. The optional ``peer`` attribute holds the IP
>-address of the other end of a point-to-point network device
>-:since:`(since 2.1.0)`.
>+:since:`Since 1.2.12` in some specific instances, network devices and
>+hostdev devices with network capabilities can optionally be provided
>+one or more IP addresses to set on the network device in the guest
>+using the <ip> subelement. Within <ip>, the ``family`` attribute can
>+be set to either ``ipv4`` or ``ipv6``, and the ``address`` attribute
>+contains the IP address. The optional ``prefix`` is the number of 1
>+bits in the netmask, and will be automatically set if not specified -
>+for IPv4 the default prefix is determined according to the network
>+"class" (A, B, or C - see RFC870), and for IPv6 the default prefix
>+is 64. The optional ``peer`` attribute holds the IP address of the
>+other end of a point-to-point network device :since:`(since 2.1.0)`.
>+
>+As mentioned above, only certain types of interfaces on certain

If I read this correctly, you removed the mention of some hypervisors
ignoring the element, so you can drop the "As mentioned above"

>+hypervisors can use the <ip> element. In particular:
>+
>+* lxc driver - <interface> or <hostdev mode='capabilities' type='net'>
>+  can have one or more IP addresses specified for each interface, and
>+  this will be directly set on the interface inside the container by
>+  libvirt.
>+
>+* QEMU driver - <interface type='user'> and <interface
>+  type='vhostuser'> (the latter only when <backend type='passt'>) can
>+  have a single IPv4 address specified (and for passt-backed
>+  interfaces also a single IPv6 address). In these cases, libvirt will
>+  setup the internal DHCP server of slirp or passt to provide the IP
>+  addresses - the guest OS must have the interface config setup to use
>+  DHCP or the settings in libvirt will be ignored.
>+

Reviewed-by: Ján Tomko <jtomko@redhat.com>

Jano