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

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

[David Gibson]

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
+network has the same address as the guest.  Rewrite inbound traffic
+from that node so it appears to the guest to have come from \fIaddr\fR
+instead.
+
+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
+cannot communicate with the host using that address.
+\fB--map-guest-addr\fR allows the guest to communicate with the host
+via \fIaddr\fR instead.
+
+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).
+
+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.
 
 .TP
 .BR \-4 ", " \-\-ipv4-only
-- 
2.55.0

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

[Stefano Brivio]

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:

  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.

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 why I was trying to work around this by just referring
to addresses.

> 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.

> +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.

I think the examples I was proposing, also in:

  https://archives.passt.top/passt-dev/20260725144437.161d8e44@elisabeth/

would anyway be helpful here.

>  .TP
>  .BR \-4 ", " \-\-ipv4-only

-- 
Stefano