Re: [PATCH v2] passt.1: Clearer and more detailed description of --map-guest-addr

[David Gibson <david@gibson.dropbear.id.au>]

[-- Attachment #1: Type: text/plain, Size: 6680 bytes --]

On Mon, Jul 27, 2026 at 04:48:02PM +0200, Stefano Brivio wrote:
> On Mon, 27 Jul 2026 14:09:46 +1000
> David Gibson <david@gibson.dropbear.id.au> 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 <pholzing@redhat.com>
> > Cc: Jan Rodak <jrodak@redhat.com>
> > Link: https://bugs.passt.top/show_bug.cgi?id=132
> > Signed-off-by: David Gibson <david@gibson.dropbear.id.au>
> > ---
> >  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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]