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 <[email protected]> --- 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/[email protected]/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
