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

[David Gibson <david@gibson.dropbear.id.au>]

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

On Mon, Jul 27, 2026 at 10:46:50PM +0300, Ammar Yasser wrote:
> 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".

Ah.. sorry, I should have been clearer.  I'd prefer if you can take a
look at v2 of the patch, which is significantly changed.

> 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

Ok, noted.

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

Ok, useful to know.

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

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