From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: passt.top; dmarc=none (p=none dis=none) header.from=gibson.dropbear.id.au Authentication-Results: passt.top; dkim=pass (2048-bit key; secure) header.d=gibson.dropbear.id.au header.i=@gibson.dropbear.id.au header.a=rsa-sha256 header.s=202606 header.b=IjtlNIuF; dkim-atps=neutral Received: from mail.ozlabs.org (gandalf.ozlabs.org [150.107.74.76]) by passt.top (Postfix) with ESMTPS id 23B2F5A0262 for ; Mon, 27 Jul 2026 06:09:52 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gibson.dropbear.id.au; s=202606; t=1785125388; bh=p9dqWQo4TxXY5V5kftPEhrwcx+0ehpLrGM9KUrfhFsM=; h=From:To:Cc:Subject:Date:From; b=IjtlNIuFX8LnjAA3363pW5p45msgm3/sAudBJ6xyfbih9Or8q94k3yFUBwAZFMcKw je3YBHtnfTkocH4GimWxaAZ1DleGylbWiv46DbGKH6wDV0TJyylfK8XJDjltJfMtu9 b7GvAJyWfy3DbsILvtGR7jddVDEOXGv6YncPDPODbA6TTKKGJdTdMPGoOI2tn6IYWp ggm0kj6BUgmqM3P1bPm+xogaNTKl4wjRfJskGKgVbPb21j4OrPGBOvaZ3DQUKdVyTc CkB24uj5C2biHGyTdCTi4yaL3U1EY7Rf3f8ydUwNOewKAhardqV90WXZEMc7Cbc0FK IsbM4PFm0qhKw== Received: by gandalf.ozlabs.org (Postfix, from userid 1007) id 4h7lVN46L6z4w1p; Mon, 27 Jul 2026 14:09:48 +1000 (AEST) From: David Gibson To: Stefano Brivio , passt-dev@passt.top Subject: [PATCH v2] passt.1: Clearer and more detailed description of --map-guest-addr Date: Mon, 27 Jul 2026 14:09:46 +1000 Message-ID: <20260727040946.105277-1-david@gibson.dropbear.id.au> X-Mailer: git-send-email 2.55.0 MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Message-ID-Hash: EQ4FBQ2OY2TOWI3WS7WWWJNHFU52SVR6 X-Message-ID-Hash: EQ4FBQ2OY2TOWI3WS7WWWJNHFU52SVR6 X-MailFrom: dgibson@gandalf.ozlabs.org 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: Ammar Yasser , David Gibson , 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: 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 +network has the same address as the guest. Rewrite inbound traffic +from that node so it appears to the guest to have come from \fIaddr\fR +instead. + +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 +cannot communicate with the host using that address. +\fB--map-guest-addr\fR allows the guest to communicate with the host +via \fIaddr\fR instead. + +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). + +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. .TP .BR \-4 ", " \-\-ipv4-only -- 2.55.0