From nobody Sat Oct 24 20:21:07 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.libvirt.org designates 38.145.34.151 as permitted sender) client-ip=38.145.34.151; envelope-from=devel-bounces@lists.libvirt.org; helo=lists.libvirt.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of lists.libvirt.org designates 38.145.34.151 as permitted sender) smtp.mailfrom=devel-bounces@lists.libvirt.org; dmarc=pass(p=reject dis=none) header.from=lists.libvirt.org ARC-Seal: i=1; a=rsa-sha256; t=1791820619; cv=none; d=zohomail.com; s=zohoarc; b=DDr5JBk0ceRx7/ECdYVqk686AC5ZjcD+Hcn3AsRgwaiE7JnJVYofYfg8E2Zpeltpbvx/7YXc80hvL1fF+KBb9lpKD4ubtt0UKMBvzyqKClGGbDwqp5OCRvHZGaSzCp04KqwQJBjs3kpfaXbx7fijRon44ZNXm0lxkBamiIu5BtI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1791820619; h=Content-Type:Content-Transfer-Encoding:Date:Date:From:From:List-Subscribe:List-Post:List-Owner:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:Reply-To:Subject:Subject:To:To:Message-Id:Cc; bh=nyLq7j+O6WqH23fFhZIr43kb6KoODEmrID1103s2S2I=; b=Ij130CBzuX5+7BwUlwFaI4nLLcsHc3Jid9e2zZv16ejv41b3hDjWhEvtycZmAOLNCks21+ip40hxeIk3FJ2MzdLIcC0suZndqi+IIurXSOFlAn5paXZvY21H201v0y7jvdDscNl1erYgTk5ISxxXp796j0Z9d6SdNeHhBp5JKXE= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of lists.libvirt.org designates 38.145.34.151 as permitted sender) smtp.mailfrom=devel-bounces@lists.libvirt.org; dmarc=pass header.from= (p=reject dis=none) Return-Path: Received: from lists.libvirt.org (lists.libvirt.org [38.145.34.151]) by mx.zohomail.com with SMTPS id 1791820618983871.2771387116435; Mon, 12 Oct 2026 08:56:58 -0700 (PDT) Received: by lists.libvirt.org (Postfix, from userid 993) id AB6053F97A; Mon, 12 Oct 2026 11:56:57 -0400 (EDT) Received: from [172.19.199.16] (unknown [10.16.107.18]) by lists.libvirt.org (Postfix) with ESMTP id BFA6841AF8; Mon, 12 Oct 2026 11:55:44 -0400 (EDT) Received: by lists.libvirt.org (Postfix, from userid 993) id 872313F383; Mon, 12 Oct 2026 11:55:36 -0400 (EDT) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (3072 bits) server-digest SHA256) (No client certificate requested) by lists.libvirt.org (Postfix) with ESMTPS id 124863F337 for ; Mon, 12 Oct 2026 11:55:34 -0400 (EDT) Received: from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-16-QCpJNoCFPBG0_-esqbdE1w-1; Mon, 12 Oct 2026 15:55:33 +0000 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 3E6621956071 for ; Mon, 12 Oct 2026 15:55:32 +0000 (UTC) Received: from lstump-precisiontower5810.rmtusva.csb (headnet03.pony-001.prod.iad2.dc.redhat.com [10.2.32.114]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id D98D6180034C for ; Mon, 12 Oct 2026 15:55:31 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 4.0.1 (2024-03-26) on lists.libvirt.org X-Spam-Level: X-Spam-Status: No, score=0.6 required=5.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL,RCVD_IN_SBL_CSS,SPF_HELO_PASS autolearn=no autolearn_force=no version=4.0.1 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1791820534; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=nyLq7j+O6WqH23fFhZIr43kb6KoODEmrID1103s2S2I=; b=hmU6JYiRFB/Hk3JYthNH5wTD+QYI19I5kY1vsIwRwq9I/fxXpfoRNkJlH06Z8ss8Hczkzm 2F+Dvk7iKaVW7QI6wCylXadqWo1BbEUol4MX/iXv9oiWISZHuX39BAIqJ81VrPIFCujpQG MivY8OeaIDCODGamk7zJmxuQ8CzA9SM= X-MC-Unique: QCpJNoCFPBG0_-esqbdE1w-1 X-Mimecast-MFC-AGG-ID: QCpJNoCFPBG0_-esqbdE1w_1791820532 To: devel@lists.libvirt.org Subject: [PATCH] docs: be more specific about when can be used in Date: Mon, 12 Oct 2026 11:55:30 -0400 Message-ID: <20261012155530.852958-1-laine@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: uzq2Tc3IHbgT8H87jEZvVP8cVJQh7w1PRKUaR_VyvXw_1791820532 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Message-ID-Hash: Z4TQ2OPLOBQGW2JVKEGNLRBTCAGED2I4 X-Message-ID-Hash: Z4TQ2OPLOBQGW2JVKEGNLRBTCAGED2I4 X-MailFrom: laine@redhat.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; header-match-devel.lists.libvirt.org-0; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Development discussions about the libvirt library & tools Archived-At: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: From: Laine Stump via Devel Reply-To: Laine Stump X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1791820623933158500 Content-Type: text/plain; charset="utf-8"; x-default="true" A user commented that the documentation was rather vague about when an address specified in a domain can be used and when it can't. This extra verbiage attempts to clarify that. Signed-off-by: Laine Stump Reviewed-by: J=C3=A1n Tomko --- 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/DZWK= JPK3IFBDDBBZC4NRCTT6MMBTCEZM/ ) 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 ... =20 -: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`` attribut= e can -be set to either ``ipv4`` or ``ipv6``, and the ``address`` attribute conta= ins -the IP address. The optional ``prefix`` is the number of 1 bits in the net= mask, -and will be automatically set if not specified - for IPv4 the default pref= ix 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 subelement. Within , 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 element. In particular: + +* lxc driver - or + 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 - and (the latter only when ) 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 a single IP + address can be set. + +* Cloud Hypervisor driver - for a + single IP address can be set. + +* openvz driver - can have multiple + IP addresses specified. + +* Xen driver - 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 entries in +the `virtual network's config `__. 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. =20 :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 --=20 2.56.0