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=j9I72mp2; dkim-atps=neutral Received: from mail.ozlabs.org (mail.ozlabs.org [IPv6:2404:9400:2221:ea00::3]) by passt.top (Postfix) with ESMTPS id EFA815A0265 for ; Tue, 21 Jul 2026 04:20:20 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gibson.dropbear.id.au; s=202606; t=1784600417; bh=tTZ4xfoemsn06Oxl4/nTwyFtpxZsmu0pDJznRRYxPcE=; h=From:To:Cc:Subject:Date:From; b=j9I72mp25W6pNcMlyM7KpFJKgrApz3X9ba2/rxJ0fFjO39C7ETnFyMXKOlFRDxVZd L3sUUqdIdu2+U+s13LlfZWxxTNX5oO1wOC1M9tSOz9dOawPUR8W62VcjFu085Vdtkk UUX8jwGDuTe1TfX0gDMcA6eS6IKTie9LqTWCesHXMq4ngc4coaaAT9v4I/bnWLd8N9 JV3I3626JCnG1xC7aEY+W009+bIwDGh2aQTn5Ig203pdKeB4h9LtXhLReaPHE1EBDo lINkTDsISxKwzcRA247ra5KAKIKyaaqKV+wlqpJgdY3aSby82bfyaA5qMNgko8awHK TQcH4FOwH8dsw== Received: by gandalf.ozlabs.org (Postfix, from userid 1007) id 4h41Ln2BFlz4w2F; Tue, 21 Jul 2026 12:20:17 +1000 (AEST) From: David Gibson To: Stefano Brivio , passt-dev@passt.top Subject: [PATCH] passt.1: Clearer and more detailed description of --map-guest-addr Date: Tue, 21 Jul 2026 12:20:12 +1000 Message-ID: <20260721022012.44338-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: VOZI2SPCVKKOZLAVKKTCR4ZX3GL2L4XS X-Message-ID-Hash: VOZI2SPCVKKOZLAVKKTCR4ZX3GL2L4XS 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: 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 | 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 +with some other "shadowed" interface in the host's network or the +wider internet. By default, the shadowed interface will be the host's +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. + +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. + +\fB--map-guest-addr\fR allows the guest to communicate with the +shadowed interface via the address \fIaddr\fR instead. Packets from +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 +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. .TP .BR \-4 ", " \-\-ipv4-only -- 2.55.0