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

["Ammar Yasser" <aerosound161@gmail.com>]

On Mon Jul 27, 2026 at 6:30 AM EEST, David Gibson wrote:
>> 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.
>
> It's difficult to explain clearly in terms of addresses only, because
> the whole trouble is the same address refers to two different things:
> on the inside it refers to the guest on the outside it refers to
> .. something, usually the host but not always.  The whole "shadowed
> whatever" term is trying to get at "the thing on the outside that has
> the same address as the guest does on the inside".

I do agree that the notion of "shadowing" did confuse me a bit while
reading through the rewrite. If i had to use my own words to describe
whats going on with my current level of knowledge, i'd say:

passt can't allocate addresses in the host namespace. to overcome this,
an address will be picked and the guest will be made to believe that 
this is its own. by default, this is the host primary address. Unless 
another was specified through the -a option. 

Keeping it at that, without mentioning that -a can refer to remote
addresses is enough context for me as someone finding out about this
option for the first time to understand how to use --map-guest-addr 
in this paragraph

>> > > > +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.
>
> Well, maybe, it's demonstrably difficult though...

I don't think it was entirely harmful for me to get the additional
context around interfaces. but nevertheless, as Stefano says, we can do
without it

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

Yes, actually giving the background, then saying that as a result to
<background> the guest cannot communicate with this address was pretty
valuable in me understanding the problem statement

>> > > 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.
>
> The option is controlling L3 NAT, so we need to describe its behaviour
> in terms of L3 - specifically what the final L3 destination of the
> packet will be.  What's happening at L2 and exactly how it's routed
> there is secondary.

Thats why i am in favor of leaving this detail entirely out of the
description of --map-guest-addr. The relevant piece of information i
need as i am specifying this option is to know why it exists (the
background + the inability to communicate with the guest assigned from 
the guest) and the layer 3 description of what will be the source and
destination from both sides, who will the guest and passt (by whoever is
on the other side whether its a local or remote interface) see the packets
coming from