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=Mp64JegO; 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 2F47B5A026E for ; Mon, 27 Jul 2026 16:48:08 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1785163687; 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=63cvWtxYf0dxHHncglknQgAzEpJIfX0b0GXtim5R6TE=; b=Mp64JegOlQRlrUIUe9bx1DcRL0szDwLrPmJ93e1r1WTqL7s4AFvCjgqBmYooZDwBiZwHlX VJvjNEPhTBB0mxtav0KWzaNjRTitcRgYA41AtB9PPP+++qzLnEQl3zZhqaEnhjFgJUxbJA 90CuOjcWriEgtQFGnuqajkzdWJvHwGM= Received: from mail-wr1-f69.google.com (mail-wr1-f69.google.com [209.85.221.69]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-651-TYPRYpZ9O5ia2nuD0Obrnw-1; Mon, 27 Jul 2026 10:48:05 -0400 X-MC-Unique: TYPRYpZ9O5ia2nuD0Obrnw-1 X-Mimecast-MFC-AGG-ID: TYPRYpZ9O5ia2nuD0Obrnw_1785163684 Received: by mail-wr1-f69.google.com with SMTP id ffacd0b85a97d-4729d2a64efso2251234f8f.0 for ; Mon, 27 Jul 2026 07:48:05 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1785163684; x=1785768484; 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=63cvWtxYf0dxHHncglknQgAzEpJIfX0b0GXtim5R6TE=; b=rAVCRnGw1jdPSzlgf/3nIfzuf3gInU18rDMYaMCQJqE86AChyqx667tPavqe/jKfWH CSQ/HTuRdREmRI/dq0J/iayl/hDSkAPTzWds7cskJpoLTiobuZ495KKw+97eGnRa8T/5 ykb7tz5TWhTPjy7e9RzjOYZ9mT/1sBI6q2zhkBnXq0qlNUvfmg6C5sVheDd9fG2YEIrd NP034MOC+vdvbYeX3Crr42DIaonVKwDxGnDjBCLFOQ0AkEfnXhTxGo+JAYNkKEB+uv5w CvZckDZmxDGn5clIK58ApMCIqOLMbfVo0imAo77KaJ/+lugm/wTP1AfngSsKq5mcHeiw MVdA== X-Gm-Message-State: AOJu0YzWXhsFdsLhj0nHAt6XRlanrbS2/xE6peRfwh3tb552FuRE5CVF bLTkXhg54w4q9v8jKQo6Qnx8Ftso+gbPCwLrxvDnxcywZegCK9V0dOS1QnWodpo5jV5pQPbQUOM VHQ7pMuBHZTvip4/kj38b7ZK+RhSEbU6P98PrvPK8OY6ncFG8F6pmjw== X-Gm-Gg: AR+sD110uqPPbgGczzuTtMRbiRFk8jf4tzPYjKBbn3NGDfqUl1mPvk4evmrFKHw3oc2 FmN/V/awX0KXeDt1bibOw5JPwuGFSVVKNDkcjXUCfnh7SqlGIVY7NIMfOUWGRAL7jbMKn7g/TuC wuQBQiO5ESA8mEoWXiRlX0wAjBiey7+NO04KttiEdRY4mkZ5qQU21KUM/SEUq4jwkiceKyh6KsC x/4R0YMpdHgaJIMNEDFYHVtlgu3e8ForQZUdBYqiN4y0DI/xoIIESQ9v4zkvayZKUSpItKQPqM8 pyi2EIljeZShvfgTDDbSjyaYixxDdVJ39UiYE3YHSewsMwP2ODK+Aiy5QxBjJomIjvAK3lPDe5y xMX70mfldHFQGNQLI5cQDDwfJVcf7 X-Received: by 2002:a05:600c:5253:b0:495:7016:b875 with SMTP id 5b1f17b1804b1-496b5c7ca38mr106132535e9.13.1785163684173; Mon, 27 Jul 2026 07:48:04 -0700 (PDT) X-Received: by 2002:a05:600c:5253:b0:495:7016:b875 with SMTP id 5b1f17b1804b1-496b5c7ca38mr106132135e9.13.1785163683549; Mon, 27 Jul 2026 07:48:03 -0700 (PDT) Received: from maya.myfinge.rs (ifcgrfdd.trafficplex.cloud. [176.103.220.4]) by smtp.gmail.com with ESMTPSA id 5b1f17b1804b1-4957f9ae5c3sm329372215e9.3.2026.07.27.07.48.03 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 27 Jul 2026 07:48:03 -0700 (PDT) From: Stefano Brivio To: David Gibson Subject: Re: [PATCH v2] passt.1: Clearer and more detailed description of --map-guest-addr Message-ID: <20260727164801.1fa5fe70@elisabeth> In-Reply-To: <20260727040946.105277-1-david@gibson.dropbear.id.au> References: <20260727040946.105277-1-david@gibson.dropbear.id.au> Organization: Red Hat X-Mailer: Claws Mail 4.2.0 (GTK 3.24.49; x86_64-pc-linux-gnu) MIME-Version: 1.0 Date: Mon, 27 Jul 2026 16:48:02 +0200 (CEST) X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: FxkXGFCB40tIJgei87vW92Lgm_nb9DtW3QQ8KP2qN88_1785163684 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Message-ID-Hash: PGMZMVUN7Z2XBYHZSMFEZP2JQEXZHTJ4 X-Message-ID-Hash: PGMZMVUN7Z2XBYHZSMFEZP2JQEXZHTJ4 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, Ammar Yasser , Paul Holzinger , Jan Rodak 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 Mon, 27 Jul 2026 14:09:46 +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 | 39 +++++++++++++++++++++++++++------------ > 1 file changed, 27 insertions(+), 12 deletions(-) > > diff --git a/passt.1 b/passt.1 > index 995590a6..f326f82c 100644 > --- a/passt.1 > +++ b/passt.1 > @@ -405,18 +405,33 @@ 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. > +Redirect outbound traffic to \fIaddr\fR to whatever node on the host I think to ... to ... is a bit hard to follow, that one reason why my proposal in: https://archives.passt.top/passt-dev/20260725144437.161d8e44@elisabeth/ was a bit longer than that. Saying "originally directed to ..." in a proper complex-compound sentence makes it clear that the original destination address is changed to something else, I think. > +network has the same address as the guest. Not entirely true: nobody guarantees that the guest or namespace will have the same address as the first address of the template interface, or what's given by --addr. That's another reason why the sentence I was proposing had to be a bit longer than that. By the way, for practical purposes, we're generally talking about the host here. I'm taking care of most related questions asked by users in Podman's issues and passt's IRC channel, and what practically all users would need here (because that's how Podman and users use this) is: Make the host reachable at \fIaddr\fR. We can make it more accurate than that, but "whatever node on the host network" doesn't immediately sound as something that includes the host as well. That's why I was trying to work around this by just referring to addresses. > Rewrite inbound traffic > +from that node so it appears to the guest to have come from \fIaddr\fR > +instead. This one is helpful. Just the definition of "that node" isn't. > + > +By default, the guest or namespace is given one of the host's public > +addresses. While this avoids NAT in most cases, it means the guest I think we can skip the "While this avoids NAT in most cases" part. It's true but unrelated. > +cannot communicate with the host using that address. Fine, I think this is helpful as it is. > +\fB--map-guest-addr\fR allows the guest to communicate with the host > +via \fIaddr\fR instead. This is the main point. Maybe we should \fI the whole thing. I haven't checked how it looks like. > +Note, however, that if \fB-a ADDR\fR is used, where \fBADDR\fR is not > +one of the host's addresses, then \fB--map-guest-addr\fR will redirect > +traffic to \fIaddr\fR to the host visible node with address > +\fBADDR\fR, instead of the host itself. > + > +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. \fB--map-guest-addr none\fR means no such > +translation is performed for IPv4 or IPv6; this will usually make it > +impossible for the guest to communicate with the host (at least using > +direct IP). I would skip "at least using direct IP": what else? And "direct IP" isn't entirely clear. > +By default \fB--map-guest-addr GATEWAY\fR is implied, where > +\fBGATEWAY\fR is the guest's default gateway address, unless > +\fB--no-map-gw\fR is also specified, in which case \fB--map-guest-addr > +none\fR is implied. That's not the default, see the description for --map-host-loopback (just double checked against conf()). Again, I would suggest referring to it. I think the examples I was proposing, also in: https://archives.passt.top/passt-dev/20260725144437.161d8e44@elisabeth/ would anyway be helpful here. > .TP > .BR \-4 ", " \-\-ipv4-only -- Stefano