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