[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

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

[David Gibson]

[-- 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 --]