From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: passt.top; dmarc=pass (p=quarantine dis=none) header.from=redhat.com Authentication-Results: passt.top; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=jELNWJt1; dkim-atps=neutral Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by passt.top (Postfix) with ESMTPS id 098245A0265 for ; Sat, 25 Jul 2026 14:44:44 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1784983483; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=m5zSc6vomktrIPSO9e+zJIUZ3p9VUzBLlFHmRpCT14E=; b=jELNWJt1QO/rtPL7QGK62ovA9qVqzxUNxRSeZeeBrmxM/OwKdALzCdelpYAZTSSva4Asni CF9G+JLEjdkfho/scOVrLZmxIZVXnil+jxBShzDe2meDRC6pGJMR+UiTPT/hwJPVNwN4ZY UB71Hg1hFCxXD1XyMbSOQyMc3IZPBes= Received: from mail-wm1-f72.google.com (mail-wm1-f72.google.com [209.85.128.72]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-533-wzBS8GnUPySJk8aj2W0woA-1; Sat, 25 Jul 2026 08:44:42 -0400 X-MC-Unique: wzBS8GnUPySJk8aj2W0woA-1 X-Mimecast-MFC-AGG-ID: wzBS8GnUPySJk8aj2W0woA_1784983481 Received: by mail-wm1-f72.google.com with SMTP id 5b1f17b1804b1-495517d39fbso7560375e9.2 for ; Sat, 25 Jul 2026 05:44:41 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1784983481; x=1785588281; h=date:content-transfer-encoding:content-type:mime-version :organization:references:in-reply-to:message-id:subject:cc:to:from :x-gm-gg:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to:content-type; bh=m5zSc6vomktrIPSO9e+zJIUZ3p9VUzBLlFHmRpCT14E=; b=S6O4fyU9EeDO6dRDiAGF84lbLeOFvJ5gkyWHj+11e0cqsqA+C74tmR662SSb2up2OB YPARjVP3W+vXbe3NqSeIvyPN0HNCRShD4mkH70GvWH5MtKroHjIKuTf6ZBp+DZtWhB00 ce+BPwqL5s8wY1Uhnh16gQ6RJlXH5YgQepYdE0GyLTO6fxye4LE/4o64ivOzxgQ1akO/ LWVxjPjOBaPAo2vl7U4CVnp3dUwJClmnC+m69WWMSYVXLmeoHcM2Ne6KWMgPNikjLFo6 CfT7RTUKt84AFySmlcqkCyOBRu6aCnTucUbxRnmy5efM0TfDFRzfQlj2hdXx9+hdgYbZ FQSA== X-Gm-Message-State: AOJu0YzCyu5RFt3si1BH4QwZfOwX2iZ2E5okwoZgjies9swPl8RYNBsZ 7Ib3B1nOdQ6K08+HHGb6ecWW8xZfltCKmg1sh6Rz4WCjwAk65AhDs9RcXr8lthMXjnOiZlbIQWe WXeLIsjteCHTiS+AkJZulrH8jzbmhYDUsnQrbZpfgiSI893TeptMkJw== X-Gm-Gg: AR+sD12ZrmHFl31xXyg88tNN4e28t+wve1C1a/Gf4OpB4eUc+/oSeprBfuW0jNsT2ej GMUUnq3zIvkKcCtuk6dS3z1c4bhlYv8djS9FfafRq1RFvQ2GSGyzCawauBZsTNi8Td7dBX0+JTl RUnu9diHGuZXq0GKiNFuA2gug+uWBC0oCm34g1f5lWyM6pEa7voZoO7zCr8jrBdBMqVTSVdI5gf LiqEmj4kUfXF7ZGUpEuc2Ppb1VHF7R38f2UJiq3Xq5EOKSzsgbbTkndXbW4zE/drnwpirWp4Ois IgHVd7Eqv63PvLYCP77R2HlDZeYjLqotSqVEmO9b58AnOHqhnarjbCZfbK7NBVYnCOBcA/E5Y/u dOu2HXYxwTG06UiOBexLraQQC4gni X-Received: by 2002:a05:600c:4687:b0:492:68bc:3237 with SMTP id 5b1f17b1804b1-496b6a34c1fmr21506415e9.32.1784983480568; Sat, 25 Jul 2026 05:44:40 -0700 (PDT) X-Received: by 2002:a05:600c:4687:b0:492:68bc:3237 with SMTP id 5b1f17b1804b1-496b6a34c1fmr21505985e9.32.1784983479860; Sat, 25 Jul 2026 05:44:39 -0700 (PDT) Received: from maya.myfinge.rs (ifcgrfdd.trafficplex.cloud. [176.103.220.4]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-496b485f6a2sm78797445e9.4.2026.07.25.05.44.38 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 25 Jul 2026 05:44:38 -0700 (PDT) From: Stefano Brivio To: David Gibson Subject: Re: [PATCH] passt.1: Clearer and more detailed description of --map-guest-addr Message-ID: <20260725144437.161d8e44@elisabeth> In-Reply-To: References: <20260721022012.44338-1-david@gibson.dropbear.id.au> <20260723012848.7c5479f6@elisabeth> Organization: Red Hat X-Mailer: Claws Mail 4.2.0 (GTK 3.24.49; x86_64-pc-linux-gnu) MIME-Version: 1.0 Date: Sat, 25 Jul 2026 14:44:38 +0200 (CEST) X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: eLiHtHHQsUXbz_VtPZ7ueIqRDQTTUCGSFE4vJiKzIa0_1784983481 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Message-ID-Hash: N7MHFCHZ3U5OUKEC2EOELYC3FZJY5EGC X-Message-ID-Hash: N7MHFCHZ3U5OUKEC2EOELYC3FZJY5EGC X-MailFrom: sbrivio@redhat.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header CC: passt-dev@passt.top, Paul Holzinger , Jan =?UTF-8?B?Um9kw6Fr?= X-Mailman-Version: 3.3.8 Precedence: list List-Id: Development discussion and patches for passt Archived-At: Archived-At: List-Archive: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: 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. > 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, 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. > > > +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. > > > +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, 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. > > 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. 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. > > 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. 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. 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. Similarly, forward inbound packets, originally directed to the first address of the template interface, or to the address configured via \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. 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 "". 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 -- Stefano