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: > > > 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 | 39 +++++++++++++++++++++++++++------------ > > 1 file changed, 27 insertions(+), 12 deletions(-) > > > > 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. > > > > .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 > > 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/ > > 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. > > > +network has the same address as the guest. > > 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. > > 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: > > Make the host reachable at \fIaddr\fR. > > 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. ...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. > > This one is helpful. Just the definition of "that node" isn't. > > > + > > +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 > > I think we can skip the "While this avoids NAT in most cases" part. > It's true but unrelated. > > > +cannot communicate with the host using that address. > > Fine, I think this is helpful as it is. > > > +\fB--map-guest-addr\fR allows the guest to communicate with the host > > +via \fIaddr\fR instead. > > This is the main point. Maybe we should \fI the whole thing. I haven't > checked how it looks like. > > > +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). > > 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. > > 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: > > https://archives.passt.top/passt-dev/20260725144437.161d8e44@elisabeth/ > > would anyway be helpful here. Good point, I forgot to include them (or something like them). > > > .TP > > .BR \-4 ", " \-\-ipv4-only > > -- > Stefano > -- 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