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

[Stefano Brivio <sbrivio@redhat.com>]

On Tue, 21 Jul 2026 12:20:12 +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 | 40 ++++++++++++++++++++++++++++------------
>  1 file changed, 28 insertions(+), 12 deletions(-)
> 
> diff --git a/passt.1 b/passt.1
> index 995590a6..19901c1e 100644
> --- a/passt.1
> +++ b/passt.1
> @@ -405,18 +405,34 @@ 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.
> +Because passt cannot allocate addresses in the host's network
> +environment, the guest or namespace will typically share an address

This is not necessarily the reason: slirp4netns can't allocate
addresses either, but it won't (and can't) share host addresses with the
container anyway. It's rather a design choice, as well as a default
option.

> +with some other "shadowed" interface in the host's network or the
> +wider internet.  By default, the shadowed interface will be the host's

This interface is called the template interface everywhere in the
documentation, in user-visible output, and in the code.

> +own primary interface, because that's the address given to the guest.
> +If the guest address is assigned with \fB-a\fR, however, the shadowed
> +interface will be whatever host-visible interface has the same
> +address, which could belong to any node on the host's network or the
> +internet.

I'm not sure if -a changes this in any substantial way. I would rather
leave this paragraph out, as this is already documented.

> +The guest or namespace cannot communicate with the shadowed interface
> +using its host-visible address: because that's the same as the guest's
> +address, sending packets there would loop back to the guest before
> +they're seen by passt to forward.

I think this consideration should come after the description of the
option. In general we always follow a structure where we describe the
option first, and then any consideration or motivation, so that if the
user is not interested in the motivation, they can skip it more
conveniently.

> +\fB--map-guest-addr\fR allows the guest to communicate with the
> +shadowed interface via the address \fIaddr\fR instead.  Packets from

I don't think it's relevant that the communication happens using the
template interface. In fact, it doesn't, that is, the traffic forwarded
from container or guest won't even hit the 'ingress' hook in nftables
for that interface. We'll directly enter the local routing path instead.

What matters, I think, are the addresses we use, so I would try to
rephrase this to just reflect what we actually do, that is, something
on the lines of:

---

Forward packets from the guest or container, originally directed to
\fIaddr\fR, to the host, translating their destination address to a
local, non-loopback address, which is, by default, the same as the first
address of the template interface. This address can be overridden with
\fB--address\fR.

This way, the traffic is forwarded from the guest or container without
appearing as loopback traffic on the host.

Similarly, forward packets from the host, originally directed to this
local address (not loopback), to the guest or container, translating
their source address to \fIaddr\fR.

In the same way, the traffic is forwarded from the host without
appearing as loopback traffic in the guest or namespace.

For example, given the option \fI--map-guest-addr 203.0.113.1\fR, and a
template interface on the host with address \fI192.0.2.1\fR:

.IP \(bu 2
guest or container traffic directed to 203.0.113.1 will be forwarded to
the host, with 192.0.2.1 as destination address, and source address
selected by the kernel

.IP \(bu 2
host traffic, matching the port forwarding configuration, and directed to
192.0.2.1, will be forwarded to the guest or container, with 203.0.113.1
as source address

---

> +the guest to \fIaddr\fR are translated into packets from the host to
> +the shadowed interface.  Similarly, packets from the shadowed
> +interface to the host which are forwarded by passt's \fB-t\fR or
> +\fB-u\fR options will be translated to appear as if from \fIaddr\fR to
> +the guest's address.
> +
> +\fB--map-guest-addr none\fR or omitting \fB--map-guest-addr\fR
> +entirely means no address is mapped, and the guest will be unable to

This isn't entirely true: I would refer to the description of
--no-map-gw and --map-host-loopback for this case (or say "no
additional address is mapped").

> +communicate with the shadowed interface.  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.

This is always the case, and documented at the beginning of the OPTIONS
section.

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

-- 
Stefano