From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: passt.top; dmarc=pass (p=quarantine dis=none) header.from=redhat.com Authentication-Results: passt.top; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=jQP/eHLr; dkim-atps=neutral Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by passt.top (Postfix) with ESMTPS id 43EC25A0262 for ; Thu, 23 Jul 2026 01:28:55 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1784762934; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=8VUw/M9AkVDPoH2jbwRVY/lhCv1g+Cqcj8vXG6Y042o=; b=jQP/eHLr8+/9Eo18xp5UqmEnOQEHHkCVDPAMwXjv1TinMtVRrGWz35LheA9tCAHN7kNpEP Y5KqwIQKIyFbub3DoiXvRltDsxs+jWTsJ5XuB1R930QBhTB7YYwFuvyiGCBXLArXyT4sss kTJmjYpKpFvatY5XqPx7njmFJ7p3+Aw= Received: from mail-wr1-f69.google.com (mail-wr1-f69.google.com [209.85.221.69]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-637-aBVOA_TRPxSqg0p7j8drVA-1; Wed, 22 Jul 2026 19:28:52 -0400 X-MC-Unique: aBVOA_TRPxSqg0p7j8drVA-1 X-Mimecast-MFC-AGG-ID: aBVOA_TRPxSqg0p7j8drVA_1784762932 Received: by mail-wr1-f69.google.com with SMTP id ffacd0b85a97d-47f6d70223dso3452560f8f.1 for ; Wed, 22 Jul 2026 16:28:52 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1784762931; x=1785367731; h=date:content-transfer-encoding:content-type:mime-version :organization:references:in-reply-to:message-id:subject:cc:to:from :x-gm-gg:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to:content-type; bh=8VUw/M9AkVDPoH2jbwRVY/lhCv1g+Cqcj8vXG6Y042o=; b=VC6DHTWDfmqVqs2UuwfihblEZIV2RkTHSJh4kUrZK6HR7Ej3pWzT83wOXytTJ7Ducl e0U3oqJBk2k6l6lI2fVSEW40XSFZC/bqaMaU7inZQ5p6jE6/8idw9AOE31IniEffp1iZ Cmuc124UAFhQIuOr6ABNSkT2qYIsV61vzJ5pi0432JRA+5I/41Cv/1XDtpXkZAfyUP2i yrqHlrZTXjs8xZtAMTIL+PqEww2eIagKOEOcxlWQh+yuEGwvzSksI6TGG5bnyOzLXSAL lTF/aZ0IgRvVlY1I0Odp29OsnryD8dITz1sjFjYPoTd+LNYxu/NGdjDvskEEG6IFeweu v1Mg== X-Gm-Message-State: AOJu0YzYBUOeRx90MJzRZt7QSFo2E4ppOwHcdN3JJDcjXQK4dNoeHAIF hZ6x1mTDKAZjXgA0NvJyJuSoPniWhTVrvi7G38agXqqnMFrFQ2k/G9k2bYw9i9ROQNelK+h3f+x sAjsH0ETLuN8WBdhSlFmI8Aixidi6F5aSlbiqiM6O9tDdSzAC3yTN/g== X-Gm-Gg: AR+sD10uV2GFmpUU2T65qLNZD4suZyksGF7utmR9Jc79i/NqNQCn33d0RoD28KFb96b roSmOiFIs8D1IWqx35q4z0PviMN0DsdULgsgXME7aF3Y6gs989q0WnexBwp+lwhqIKx1XmcLywQ ffRiVCdICjren7qrwfmR7yChCYAVCdWe9vFWZz/eoHvq6mQc5RUg1dLnOk7W+99DJaRtSToPRgA 7lgaJzdmZFiFP0v8ZarCSvsseTvBHbUy6mwFmoIUR/pc7KmPiz2LM30MiGl1z0hypNh9WMxRaCY DW8q8M8ixmFbYXHEZDtCtmPiPqtuXkiFNKkzPRoo/a3J/WFM6/3llKFlujqn3oFyrtYq3HNccfr aBLWl029EF7Hn9TJ6KwWRWXJym3lV X-Received: by 2002:a05:600c:3143:b0:495:6b8f:7e7a with SMTP id 5b1f17b1804b1-49573c6409emr8674405e9.0.1784762931376; Wed, 22 Jul 2026 16:28:51 -0700 (PDT) X-Received: by 2002:a05:600c:3143:b0:495:6b8f:7e7a with SMTP id 5b1f17b1804b1-49573c6409emr8674175e9.0.1784762930887; Wed, 22 Jul 2026 16:28:50 -0700 (PDT) Received: from maya.myfinge.rs (ifcgrfdd.trafficplex.cloud. [176.103.220.4]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4956a4aae16sm101223035e9.0.2026.07.22.16.28.49 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 22 Jul 2026 16:28:49 -0700 (PDT) From: Stefano Brivio To: David Gibson Subject: Re: [PATCH] passt.1: Clearer and more detailed description of --map-guest-addr Message-ID: <20260723012848.7c5479f6@elisabeth> In-Reply-To: <20260721022012.44338-1-david@gibson.dropbear.id.au> References: <20260721022012.44338-1-david@gibson.dropbear.id.au> Organization: Red Hat X-Mailer: Claws Mail 4.2.0 (GTK 3.24.49; x86_64-pc-linux-gnu) MIME-Version: 1.0 Date: Thu, 23 Jul 2026 01:28:49 +0200 (CEST) X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: 7uuv7KwXSwmomBpQnTPuCuYhONU9ts5h1ipBWPCivuw_1784762932 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Message-ID-Hash: FEVCB7V5ZD2IKTKAERG66I6KCTIWTRNU X-Message-ID-Hash: FEVCB7V5ZD2IKTKAERG66I6KCTIWTRNU X-MailFrom: sbrivio@redhat.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header CC: passt-dev@passt.top, Paul Holzinger , Jan =?UTF-8?B?Um9kw6Fr?= X-Mailman-Version: 3.3.8 Precedence: list List-Id: Development discussion and patches for passt Archived-At: Archived-At: List-Archive: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: On Tue, 21 Jul 2026 12:20:12 +1000 David Gibson wrote: > It's been pointed out in bug 132 and elsewhere that the man page's > description of the --map-guest-addr isn't very clear. It's technically > correct, but hard to follow. > > In my defense as its author, this is largely because the problem the option > is addressing is itself quite subtle and hard to explain. In particular > while it's usually about host <-> guest communication, it may not be if > -a is also used, and the semantics need to accomodate that. > > Anyway, here's an attempt to make clearer what it does - and why it more or > less has to work that way. > > Reviews on clarity most welcome - I've had my head in the forwarding and > address translation for the better part of a year, so it's natural that > I've somewhat lost sight of what is and isn't obvious to someone coming > fresh. > > Cc: Paul Holzinger > Cc: Jan Rodak > Link: https://bugs.passt.top/show_bug.cgi?id=132 > Signed-off-by: David Gibson > --- > passt.1 | 40 ++++++++++++++++++++++++++++------------ > 1 file changed, 28 insertions(+), 12 deletions(-) > > diff --git a/passt.1 b/passt.1 > index 995590a6..19901c1e 100644 > --- a/passt.1 > +++ b/passt.1 > @@ -405,18 +405,34 @@ sandboxing process fails. > > .TP > .BR \-\-map-guest-addr " " \fIaddr > -Translate \fIaddr\fR in the guest to be equal to the guest's assigned > -address on the host. That is, packets from the guest to \fIaddr\fR > -will be redirected to the address assigned to the guest with \fB-a\fR, > -or by default the host's global address. This allows the guest to > -access services available on the host's global address, even though its > -own address shadows that of the host. > - > -If \fIaddr\fR is 'none', no address is mapped. Only one IPv4 and one > -IPv6 address can be translated, and if the option is specified > -multiple times, the last one for each address type takes effect. > - > -By default, mapping happens as described for the \-\-map-host-loopback option. > +Because passt cannot allocate addresses in the host's network > +environment, the guest or namespace will typically share an address This is not necessarily the reason: slirp4netns can't allocate addresses either, but it won't (and can't) share host addresses with the container anyway. It's rather a design choice, as well as a default option. > +with some other "shadowed" interface in the host's network or the > +wider internet. By default, the shadowed interface will be the host's This interface is called the template interface everywhere in the documentation, in user-visible output, and in the code. > +own primary interface, because that's the address given to the guest. > +If the guest address is assigned with \fB-a\fR, however, the shadowed > +interface will be whatever host-visible interface has the same > +address, which could belong to any node on the host's network or the > +internet. I'm not sure if -a changes this in any substantial way. I would rather leave this paragraph out, as this is already documented. > +The guest or namespace cannot communicate with the shadowed interface > +using its host-visible address: because that's the same as the guest's > +address, sending packets there would loop back to the guest before > +they're seen by passt to forward. I think this consideration should come after the description of the option. In general we always follow a structure where we describe the option first, and then any consideration or motivation, so that if the user is not interested in the motivation, they can skip it more conveniently. > +\fB--map-guest-addr\fR allows the guest to communicate with the > +shadowed interface via the address \fIaddr\fR instead. Packets from I don't think it's relevant that the communication happens using the template interface. In fact, it doesn't, that is, the traffic forwarded from container or guest won't even hit the 'ingress' hook in nftables for that interface. We'll directly enter the local routing path instead. What matters, I think, are the addresses we use, so I would try to rephrase this to just reflect what we actually do, that is, something on the lines of: --- Forward packets from the guest or container, originally directed to \fIaddr\fR, to the host, translating their destination address to a local, non-loopback address, which is, by default, the same as the first address of the template interface. This address can be overridden with \fB--address\fR. This way, the traffic is forwarded from the guest or container without appearing as loopback traffic on the host. Similarly, forward packets from the host, originally directed to this local address (not loopback), to the guest or container, translating their source address to \fIaddr\fR. In the same way, the traffic is forwarded from the host without appearing as loopback traffic in the guest or namespace. For example, given the option \fI--map-guest-addr 203.0.113.1\fR, and a template interface on the host with address \fI192.0.2.1\fR: .IP \(bu 2 guest or container traffic directed to 203.0.113.1 will be forwarded to the host, with 192.0.2.1 as destination address, and source address selected by the kernel .IP \(bu 2 host traffic, matching the port forwarding configuration, and directed to 192.0.2.1, will be forwarded to the guest or container, with 203.0.113.1 as source address --- > +the guest to \fIaddr\fR are translated into packets from the host to > +the shadowed interface. Similarly, packets from the shadowed > +interface to the host which are forwarded by passt's \fB-t\fR or > +\fB-u\fR options will be translated to appear as if from \fIaddr\fR to > +the guest's address. > + > +\fB--map-guest-addr none\fR or omitting \fB--map-guest-addr\fR > +entirely means no address is mapped, and the guest will be unable to This isn't entirely true: I would refer to the description of --no-map-gw and --map-host-loopback for this case (or say "no additional address is mapped"). > +communicate with the shadowed interface. Only one IPv4 and one IPv6 > +address can be translated, and if the option is specified multiple > +times, the last one for each address family takes effect. This is always the case, and documented at the beginning of the OPTIONS section. > .TP > .BR \-4 ", " \-\-ipv4-only -- Stefano