From nobody Sun Feb 8 21:03:00 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) client-ip=8.43.85.245; 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 8.43.85.245 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=1742859689; cv=none; d=zohomail.com; s=zohoarc; b=nrMVaNaiKKaHrY11+JeY4uRyH5yjqW/vp/Lwgl2aDnnVpYUDCRQb21Xi6QmS4gg8C2PX+U8fjuBo3FiC3gJfBKJLpK6+8RZFnqm0D9QIrFhfO67qMDX2aFpJTyWpSMry3qrNyVTxz6+MWT1hPGRV0XIE2ffzWZZYcF1CZgNyp7o= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1742859689; h=Content-Type:Content-Transfer-Encoding:Date:Date:From:From:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:Reply-To:Subject:Subject:To:To:Message-Id:Cc; bh=hw/w4ujIIDVo9GyVoYgcALvrkxwOvdmMkjLMGar2G+Y=; b=k2c1I15Mh9AsbsEsrGCJpLgguFmge0QfpqH8TtUeW4oTnAHd9O5qM591zcv5v5YgctbpiSCrcrSyE267Q0ob8pFlGIUXifoF8YSAr/njfZFhL1ZenVS1M9aNt+HXnupuEjJP9X8BIx2JAva60ABAzjulkHu2MGJlnwUybXzfNXM= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 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 [8.43.85.245]) by mx.zohomail.com with SMTPS id 1742859689170778.0220812049594; Mon, 24 Mar 2025 16:41:29 -0700 (PDT) Received: by lists.libvirt.org (Postfix, from userid 996) id 29A86140B; Mon, 24 Mar 2025 19:41:28 -0400 (EDT) Received: from lists.libvirt.org (localhost [IPv6:::1]) by lists.libvirt.org (Postfix) with ESMTP id 5D6ED14FC; Mon, 24 Mar 2025 19:41:04 -0400 (EDT) Received: by lists.libvirt.org (Postfix, from userid 996) id 2F35F14EE; Mon, 24 Mar 2025 19:41:00 -0400 (EDT) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by lists.libvirt.org (Postfix) with ESMTPS id 7521F13C3 for ; Mon, 24 Mar 2025 19:40:59 -0400 (EDT) Received: from mx-prod-mc-02.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-386-ByKv7SFgPGSWoJDppEjyqw-1; Mon, 24 Mar 2025 19:40:57 -0400 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (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-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 4FDAE196B356 for ; Mon, 24 Mar 2025 23:40:56 +0000 (UTC) Received: from vhost3.router.laine.org (unknown [10.22.64.97]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id D3F88195609D for ; Mon, 24 Mar 2025 23:40:55 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on lists.libvirt.org X-Spam-Level: X-Spam-Status: No, score=-0.8 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, MAILING_LIST_MULTI,RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2, RCVD_IN_VALIDITY_RPBL_BLOCKED,RCVD_IN_VALIDITY_SAFE_BLOCKED, SPF_HELO_NONE autolearn=unavailable autolearn_force=no version=3.4.4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1742859659; 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=Bgf1rGbJgJi60SpxVJTnoEG2jSE4OH5LaLVz8Y/HCOI=; b=h94tOSnqNKilk1Cu/ASmjjidryMoHXaiykEZg9eRKKYfUgqOlPm619uyU79ymCsKT4QvfE ks032RolCsvhBZsaQOj19VdTVz17Af4Oi99aJUtTtQ6Itw3ZPEKF0j2pZajHb9Qh0tJ/ub aPvZiTnl/MTdhgoxh1YsWtDJ5V3wQmE= X-MC-Unique: ByKv7SFgPGSWoJDppEjyqw-1 X-Mimecast-MFC-AGG-ID: ByKv7SFgPGSWoJDppEjyqw_1742859656 To: devel@lists.libvirt.org Subject: [PATCH] docs: add table showing guest IP/DNS/gateway settings when using SLIRP Date: Mon, 24 Mar 2025 19:40:54 -0400 Message-ID: <20250324234054.38249-1-laine@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: yccvwmVuM1wCvoAZl5V5X1IH9Q92OdiKnuQZ5ulwLWA_1742859656 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Message-ID-Hash: CCJ4ULLWS3LJMPO5N7DBPQIG32LFOZX3 X-Message-ID-Hash: CCJ4ULLWS3LJMPO5N7DBPQIG32LFOZX3 X-MailFrom: laine@redhat.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-config-1; header-match-config-2; header-match-config-3; header-match-devel.lists.libvirt.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; suspicious-header X-Mailman-Version: 3.2.2 Precedence: list List-Id: Development discussions about the libvirt library & tools Archived-At: List-Archive: List-Help: 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: 1742859691165019100 Content-Type: text/plain; charset="utf-8"; x-default="true" When using the default SLIRP backend for , the setting doesn't behave as might be expected (i.e. it doesn't set the guest interface IP/prefix to exactly the provided values). This *should* have created questions when users originally encountered it, but instead it has become more apparent as people are contemplating switching from using the SLIRP backend to using passt instead (with passt, the settings do behave "as expected"). In order to make this difference in behavior less mysterious, Yalan Zhang kindly took the time to test and document the effect of various representative settings on guest interface config when SLIRP is used (see https://issues.redhat.com/browse/RHEL-46601); this patch adds that same table to libvirt's documentation. Signed-off-by: Laine Stump Reviewed-by: Michal Privoznik --- docs/formatdomain.rst | 69 ++++++++++++++++++++++++++++++++++++------- 1 file changed, 58 insertions(+), 11 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index aae58fab60..a6d0660135 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -5239,15 +5239,7 @@ network address by including an ``ip`` element speci= fying an IPv4 address in its one mandatory attribute, ``address``. Optionally, a second ``ip`` element with a ``family`` attribute set to "ipv6" can be 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. +Optionally, an address ``prefix`` can be specified. =20 :: =20 @@ -5263,6 +5255,59 @@ has been ignored**), default route of 172.17.2.2, an= d DNS server ... =20 +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 the host portion of "10.0.2.15" (based on the configured prefix (or +a prefix of 24 if no prefix is specified). The DNS and default gateway +addresses given to the guest will be similarly based on the network +portion of the configuration-provided combined with the host +portion of SLIRPs default settings for DNS/gateway +(10.0.2.3/10.0.2.2). To help resolve the confusion of the previous +sentences, the table below shows examples of the settings that will be +provided to the guest (via a DHCP response) to use for its interface +config (ip/prefix, DNS, default gateway) for various settings of +element address and prefix in libvirt's +config: + +.. list-table:: + :header-rows: 1 + + * - libvirt element + - guest ip/prefix + - guest DNS + - guest default gateway + + * - (unspecified) + - 10.0.2.15/24 + - 10.0.2.3 + - 10.0.2.2 + + * - address=3D'172.17.1.1' + prefix=3D'16' + - 172.17.2.15/16 + - 172.17.2.3 + - 172.17.2.2 + + * - address=3D'172.17.1.1' + prefix=3D'24' + - 172.17.1.15/24 + - 172.17.1.3 + - 172.17.1.2 + + * - address=3D'172.17.1.1' + prefix=3D'8' + - 172.0.2.15/16 + - 172.0.2.3 + - 172.0.2.2 + + * - address=3D'172.17.1.1' + prefix=3D'23' + - 172.17.0.15/23 + - 172.17.0.3 + - 172.17.0.2 + Userspace connection using passt ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ =20 @@ -5304,8 +5349,10 @@ 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 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. +as a network address like SLIRP does, but as a host address). In the +table of examples given above, the guest IP would be set to exactly +172.17.1.1 in all cases (the DNS and default gateway will be set +the same as they are on the host). =20 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 --=20 2.48.1