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

[PATCH] 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 | 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
+with some other "shadowed" interface in the host's network or the
+wider internet.  By default, the shadowed interface will be the host's
+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.
+
+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.
+
+\fB--map-guest-addr\fR allows the guest to communicate with the
+shadowed interface via the address \fIaddr\fR instead.  Packets from
+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
+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.
 
 .TP
 .BR \-4 ", " \-\-ipv4-only
-- 
2.55.0

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

[Stefano Brivio]

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

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

[David Gibson]

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

On Thu, Jul 23, 2026 at 01:28:49AM +0200, Stefano Brivio wrote:
> 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.

Hm, true.  The basic issue exists because we can't allocate addresses,
but where the shadowed interface lands is a design choice, yes.  For
slirp4netns there's an entire shadowed subnet, 10.0.2.0/24 - if the
host has routes to that subnet, they'll all be inaccessible to the
guest.

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

The template interface is not the same thing.  Or rather, it's only
the same thing in the default case where the guest's address is taken
from the template interface.  When -a is used, the shadowed interface
will move somewhere else.

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

I would say the interaction with -a is exactly what makes this
confusing.  That's why it has to be "map guest addr" not "map host
addr" or "map template addr".

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

I agree in principle, but I'm really struggling to find a
non-confusing way of describing what it does without giving this
background first.  Then again, from the below I'm evidently failing to
find a non-confusing way of describing even with the background first.

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

Right.  This is not the same thing as the template interface, and the
communication isn't going through it, it's going *to* it.  The
shadowed interface not an interface on the host, it's an interface on
the peer.

I'd love a better term than "shadowed interface" but I haven't thought
of one yet.  I tried "shadowed node", but that's kind of confusing
because a node can have multiple addresses, but only one is shadowed.
"Shadowed address" doesn't really work, because as a value that's the
same thing as the guest (assigned) address, but I'm trying to refer to
the thing that has the same address in the host's world.

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

It's *not* to the host if -a gives an address that doesn't belong to
the host.

> translating their destination address to a
> local, non-loopback address,

Again, not if -a is not a local, non-loopback address of the host.

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

Often true, but not always.  That's the heart of the problem here.

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

Again, it need not be traffic from the host.

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

The second part is also true of --map-host-loopback without
--host-lo-to-ns-lo, but in this case the traffic might not be from the
host.

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

Uh.. yes, I need to recheck this.  I often forget which of
--map-guest-addr and --map-host-loopback defaults to "none" and which
defaults to "<gw addr>".

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

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