On Thu, Jul 23, 2026 at 01:28:49AM +0200, Stefano Brivio wrote:

On Tue, 21 Jul 2026 12:20:12 +1000 David Gibson 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 Cc: Jan Rodak Link: https://bugs.passt.top/show_bug.cgi?id=132 Signed-off-by: David Gibson --- 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, 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.

...

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

...

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

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.

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.

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.

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.

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

---

...

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

...

+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

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

On Sat, Jul 25, 2026 at 02:44:38PM +0200, Stefano Brivio wrote:

On Thu, 23 Jul 2026 10:48:05 +1000 David Gibson 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 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 Cc: Jan Rodak Link: https://bugs.passt.top/show_bug.cgi?id=132 Signed-off-by: David Gibson --- 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.

Ah, hm, so there's one ambiguity: that's not the sense in which I meant "allocate". I was meaning in the sense "can authoritatively say that this address belongs to X and no-one else". Non-local binds don't help with that.

...

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,

I'm not really sure what you mean by "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.

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

...

...

...

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

...

...

...

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

If it was usuaully insignificant to the user, we wouldn't need --map-guest-addr at all. We need it because in the default case the shadowed thing is the host, which the guest frequently does want to talk to.

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.

Well, again, I'm struggling to see how to explain this clearly except in terms of something shadowed. What we have already was an attempt at that and it's demonstrably failed to be clear.

...

...

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.

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.

Sorry, I was unclear about which bit I was referrring to. It's the "local, non-loopback address" part: it will always be non-loopback, but it won't be local if -a is not a host address.

...

...

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.

That very long sentence seems approximately as confusing as to me as what we have already. I also don't love avoiding mentioning the guest's assigned address by restating how the guest's assigned address is calculated.

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.

That helps, though.

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.

As does tht.

Similarly, forward inbound packets, originally directed to the first address of the template interface, or to the address configured via

For inbound it's where the packets are *from*, not where they're *to* that matters.

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

Appearing as loopback traffic in the guest is only possible with splicing, so this is more about forwarding the traffic _at all_ than it is about not appearing as loopback.

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

Ok, we'll I'll take into account the comments above and have another crack at this. -- 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