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