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

[Stefano Brivio <sbrivio@redhat.com>]

On Thu, 23 Jul 2026 10:48:05 +1000
David Gibson <david@gibson.dropbear.id.au> wrote:

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

I would argue that, to some extent, we can, by using non-local binds,
but we don't do that by default anyway because 1. it would clash with
the original goal of making things as seamless / transparent as
possible (also in terms of addressing) and 2. because we would confuse
users, specifically with non-local binds.

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

I see what you meant now, but at this point I think it would be clearer
to avoid mentioning interfaces (because they don't exist, and a
conceptual equivalent *might* be used to explain things but I think
it's more complicated than the alternative), and just refer to
addresses like the implementation does, after all. Adjusted attempt
below.

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

I see now. I considered it a corner case which didn't deserve much
attention, but, even with -a, I still think it's possible to include
that in the description, talking about addresses, and avoid referring to
interfaces.

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

I see the fact that something is shadowed as a mere limitation, usually
insignificant to the user, rather than a fundamental part of the
description. We could simply explain later what won't be reachable
instead of building a single-use term to implicitly refer to that.

I rather wouldn't, because even the description I'm proposing is rather
long, but if this really needs to be described in the man page for some
reason, I would rather add one line in this sense, rather than
introducing the concept of shadowing of interfaces or hosts.

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

I'd say it still is, at Layer-2, because fwd_nat_from_tap() always
returns PIF_HOST (and the packets will reach the host somehow). I'm not
talking about routing or local delivery.

But anyway, I think there's a way to avoid mentioning "the host" while
still maintaining sufficient clarity.

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

In which case wouldn't that be true? conf_nat() rejects loopback
addresses, so it should never appear 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.  
> 
> Again, it need not be traffic from the host.

So, adjusted attempt taking -a into account:

Forward packets from the guest or namespace, originally directed to
\fIaddr\fR, in the outbound direction, translating their destination
address to the first address of the host template interface if
\fB--address\fR is not given, and to the address passed as
\fB--address\fR if given.

For outbound traffic, this is usually used to \fIforward packets to the
host, using a local, non-loopback address, so that it doesn't appear
as loopback traffic\fR.

Note, however, that the resulting destination address is not
necessarily a local address: \fB--address\fR can configure remote
addresses as well. As a result, the traffic is not necessarily
directed to the host.

Similarly, forward inbound packets, originally directed to the first
address of the template interface, or to the address configured via
\fB--address\fR if given, to the guest or namespace, translating
their source address to \fIaddr\fR.

For inbound traffic, this is usually used to \fIforward packets from
the host, without making them appear as loopback traffic in the guest
or namespace\fR.

Also note that this traffic does not necessarily need to come from
the host: if \fB--address\fR is given, the address translation might
be applied to packets arriving from other sources.

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

True, but I don't see it as a reason to complicate this description any
further. I don't think users would really miss something useful if we
omit this.

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

These examples could be adjusted to:

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, and no
\fB--address\fR option:

.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
inbound traffic, matching the port forwarding configuration, and directed
to 192.0.2.1, will be forwarded to the guest or namespace, 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>".

Well but it's written in the man page, that's why I was suggesting we
could refer to it.

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