[PATCH] passt.1: Clearer and more detailed description of --map-guest-addr

[PATCH] passt.1: Clearer and more detailed description of --map-guest-addr

[David Gibson]

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 <pholzing@redhat.com>
Cc: Jan Rodak <jrodak@redhat.com>
Link: https://bugs.passt.top/show_bug.cgi?id=132
Signed-off-by: David Gibson <david@gibson.dropbear.id.au>
---
 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