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

[David Gibson <david@gibson.dropbear.id.au>]

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 | 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