From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: passt.top; dmarc=none (p=none dis=none) header.from=gibson.dropbear.id.au Authentication-Results: passt.top; dkim=pass (2048-bit key; secure) header.d=gibson.dropbear.id.au header.i=@gibson.dropbear.id.au header.a=rsa-sha256 header.s=202606 header.b=cKDwj8jF; dkim-atps=neutral Received: from mail.ozlabs.org (gandalf.ozlabs.org [150.107.74.76]) by passt.top (Postfix) with ESMTPS id 8E1C05A0262 for ; Tue, 28 Jul 2026 07:05:06 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gibson.dropbear.id.au; s=202606; t=1785215103; bh=HPVT+AuazC+kMV/WwpboxiLg9qo64p++fCtyRrO5Y1s=; h=Date:From:To:Cc:Subject:References:In-Reply-To:From; b=cKDwj8jFUYOGmzNZBvol1XSyy8Z2HV4WntHt4AcihIBCK6bk1LOk4Ol3+Y0pzH+tI r9vh/YoxTDE2jS8+T1uKx+OV1gJ7IiSuZJ9dDv8n5JD+433ZsUrQnGforsoVVwSjRu 0g+9BstcuflcgbWC0g0TPbnOBgKqKSSqkoCKdCrqaZdv2fXqQ6P9RE95RVhazN8ptd hmbte/odnyGCv1wGgOLKgdCEZzsPKw7wJ0wjxxOuGcaQsjKIhroBwlZG2sE4PKidNm 2VytI9houC6ir9ee0axU5joCJglGwU5vIEfemVS3ajur6EvfMiDLnRZIDfnUJIICBy G1ScFU3vf8WRg== Received: by gandalf.ozlabs.org (Postfix, from userid 1007) id 4h8Ngg28R4z4w1V; Tue, 28 Jul 2026 15:05:03 +1000 (AEST) Date: Tue, 28 Jul 2026 13:59:01 +1000 From: David Gibson To: Stefano Brivio Subject: Re: [PATCH v2] passt.1: Clearer and more detailed description of --map-guest-addr Message-ID: References: <20260727040946.105277-1-david@gibson.dropbear.id.au> <20260727164801.1fa5fe70@elisabeth> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="w/5p6ggAxk6iRmZi" Content-Disposition: inline In-Reply-To: <20260727164801.1fa5fe70@elisabeth> Message-ID-Hash: EPBNUOIKYNJVD37BTF7JNINND3HHN4FC X-Message-ID-Hash: EPBNUOIKYNJVD37BTF7JNINND3HHN4FC X-MailFrom: dgibson@gandalf.ozlabs.org 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, Ammar Yasser , Paul Holzinger , Jan Rodak 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: --w/5p6ggAxk6iRmZi Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Mon, Jul 27, 2026 at 04:48:02PM +0200, Stefano Brivio wrote: > On Mon, 27 Jul 2026 14:09:46 +1000 > David Gibson wrote: >=20 > > 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. > >=20 > > In my defense as its author, this is largely because the problem the op= tion > > 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. > >=20 > > Anyway, here's an attempt to make clearer what it does - and why it mor= e or > > less has to work that way. > >=20 > > 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. > >=20 > > Cc: Paul Holzinger > > Cc: Jan Rodak > > Link: https://bugs.passt.top/show_bug.cgi?id=3D132 > > Signed-off-by: David Gibson > > --- > > passt.1 | 39 +++++++++++++++++++++++++++------------ > > 1 file changed, 27 insertions(+), 12 deletions(-) > >=20 > > diff --git a/passt.1 b/passt.1 > > index 995590a6..f326f82c 100644 > > --- a/passt.1 > > +++ b/passt.1 > > @@ -405,18 +405,33 @@ sandboxing process fails. > > =20 > > .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. > > +Redirect outbound traffic to \fIaddr\fR to whatever node on the host >=20 > I think to ... to ... is a bit hard to follow, that one reason why my > proposal in: Good point. > https://archives.passt.top/passt-dev/20260725144437.161d8e44@elisabeth/ >=20 > was a bit longer than that. Saying "originally directed to ..." in a > proper complex-compound sentence makes it clear that the original > destination address is changed to something else, I think. >=20 > > +network has the same address as the guest. >=20 > Not entirely true: nobody guarantees that the guest or namespace will > have the same address as the first address of the template interface, > or what's given by --addr. That's another reason why the sentence I was > proposing had to be a bit longer than that. Ah, true. It's whatever on the host network has the address the guest is _supposed_ to have, whether or not the guest is actually using the address it's supposed to. > By the way, for practical purposes, we're generally talking about the > host here. >=20 > I'm taking care of most related questions asked by users in Podman's > issues and passt's IRC channel, and what practically all users would > need here (because that's how Podman and users use this) is: >=20 > Make the host reachable at \fIaddr\fR. >=20 > We can make it more accurate than that, but "whatever node on the host > network" doesn't immediately sound as something that includes the host > as well. That's a reasonable concern... > That's why I was trying to work around this by just referring > to addresses. =2E..but so far I'm not seeing that helping. > > Rewrite inbound traffic > > +from that node so it appears to the guest to have come from \fIaddr\fR > > +instead. >=20 > This one is helpful. Just the definition of "that node" isn't. >=20 > > + > > +By default, the guest or namespace is given one of the host's public > > +addresses. While this avoids NAT in most cases, it means the guest >=20 > I think we can skip the "While this avoids NAT in most cases" part. > It's true but unrelated. >=20 > > +cannot communicate with the host using that address. >=20 > Fine, I think this is helpful as it is. >=20 > > +\fB--map-guest-addr\fR allows the guest to communicate with the host > > +via \fIaddr\fR instead. >=20 > This is the main point. Maybe we should \fI the whole thing. I haven't > checked how it looks like. >=20 > > +Note, however, that if \fB-a ADDR\fR is used, where \fBADDR\fR is not > > +one of the host's addresses, then \fB--map-guest-addr\fR will redirect > > +traffic to \fIaddr\fR to the host visible node with address > > +\fBADDR\fR, instead of the host itself. > > + > > +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. \fB--map-guest-addr none\fR means no such > > +translation is performed for IPv4 or IPv6; this will usually make it > > +impossible for the guest to communicate with the host (at least using > > +direct IP). >=20 > I would skip "at least using direct IP": what else? And "direct IP" > isn't entirely clear. Fair point. I was trying to distinguish from, say relaying via some third host, or using non-IP L2 protocols or something. But yeah, I think that just muddies the water for no real gain. > > +By default \fB--map-guest-addr GATEWAY\fR is implied, where > > +\fBGATEWAY\fR is the guest's default gateway address, unless > > +\fB--no-map-gw\fR is also specified, in which case \fB--map-guest-addr > > +none\fR is implied. >=20 > That's not the default, see the description for --map-host-loopback > (just double checked against conf()). Again, I would suggest referring > to it. Ah, dangit, I mixed the defaults up with those of --map-host-loopback again. > I think the examples I was proposing, also in: >=20 > https://archives.passt.top/passt-dev/20260725144437.161d8e44@elisabeth/ >=20 > would anyway be helpful here. Good point, I forgot to include them (or something like them). >=20 > > .TP > > .BR \-4 ", " \-\-ipv4-only >=20 > --=20 > Stefano >=20 --=20 David Gibson (he or they) | I'll have my music baroque, and my code david AT gibson.dropbear.id.au | minimalist, thank you, not the other way | around. http://www.ozlabs.org/~dgibson --w/5p6ggAxk6iRmZi Content-Type: application/pgp-signature; name=signature.asc -----BEGIN PGP SIGNATURE----- iQIzBAEBCgAdFiEEO+dNsU4E3yXUXRK2zQJF27ox2GcFAmpoKPoACgkQzQJF27ox 2GdmqQ/9EZWFn1dBULPY8r+NMbIQ8Hqb9JFRkr9SfiU6can5xrVKIrQuDiA6GCCJ AIBRe7+yyEJ25++0sJUd6C86FOzGkYqadeNmAkamHzxHsKlvRQK39LoCdkvlVxRH aAMAi9+gr3K9wvV31sJ99FpAAAZSAk2SUArTcQ+DM13xIyybJ4sO4Rxq8AWZSk/3 fpu3zL6VDk95ypIRPgnK/e1W9Q4bqvuQQvjOVl52DnwUddSBiPhrKcN3ukM5ZwwA /0ZzbeTN9enxIhoq3AINNZ0PtXjSpEiGx+SWoHbpnvKriY85b6hvVI8x8oOgN4l7 FBsaUS/adX2mLSSCGp+X1Pv4ne+ucrve1drsAzrhQ000eXHtMBJGdpuyUuUXSUyQ 2cFn6iZ4UWVe11UsQF25QePuwViIkJvywgyX2S9fkD2o/Gfj4Lyl7ttoJOd8wDiL fCV3TCl7HhSSGP+ZIm+Lhr/XuA6c+WTQpK6ArwFjtex7HP90KxCSYdlw3miqr3WL EzxpX8r/PMNDT7cntIfRF0WDuGA9HQsAZ719V1li95rmf4lDmjNIPrP/xLOECbOk kFPbu7H7QxhR3us0rg7NxR+ps1YKXLkFEWCV0er2yMlAqy9uEqoIRWOdug69vvcc lE2XVbp+nVTc8+/X0HP9yv2ZdqRo2uIEkF7lT6TQfBQx3b8OdNI= =sEj4 -----END PGP SIGNATURE----- --w/5p6ggAxk6iRmZi--