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

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