[src/trunk]: src/share/man/man4 Improve wording, and put a new drawing, from ...

[maxv <maxv%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/f7084627eb8a
branches:  trunk
changeset: 829301:f7084627eb8a
user:      maxv <maxv%NetBSD.org@localhost>
date:      Thu Jan 25 09:29:18 2018 +0000

description:
Improve wording, and put a new drawing, from me and Kengo Nakahara.

diffstat:

 share/man/man4/ipsecif.4 |  64 +++++++++++++++++++++++++++---------------------
 1 files changed, 36 insertions(+), 28 deletions(-)

diffs (139 lines):

diff -r 9e7901e4b6a5 -r f7084627eb8a share/man/man4/ipsecif.4
--- a/share/man/man4/ipsecif.4  Thu Jan 25 08:57:59 2018 +0000
+++ b/share/man/man4/ipsecif.4  Thu Jan 25 09:29:18 2018 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: ipsecif.4,v 1.4 2018/01/11 08:59:27 wiz Exp $
+.\"    $NetBSD: ipsecif.4,v 1.5 2018/01/25 09:29:18 maxv Exp $
 .\"
 .\" Copyright (C) 2017 Internet Initiative Japan Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd January 11, 2018
+.Dd January 25, 2018
 .Dt IPSECIF 4
 .Os
 .Sh NAME
@@ -54,7 +54,7 @@
 tunnel endpoint addresses.
 These addresses will be used for the outer IP header of ESP packets.
 The administrator also configures the protocol
-and addresses for the inner IP header with
+and addresses for the inner IP header with the
 .Xr ifconfig 8
 .Cm inet
 or
@@ -68,22 +68,20 @@
 .Xr gif 4
 over
 .Xr ipsec 4
-transport mode, however their security policy managements are different.
+transport mode, however the security policy management is different.
 .Xr gif 4
 over
 .Xr ipsec 4
-transport mode expects for userland programs to managed its
+transport mode expects userland programs to manage their
 security policies.
 In contrast,
 .Nm
-manages its security policies by itself, that is, when the administrator
-sets up a
+manages its security policies by itself: when the administrator
+sets up an
 .Nm
 tunnel source and destination address pair, the related security policies
 are created automatically in the kernel.
-Therefore, the security policies of
-.Nm
-are added/deleted atomically.
+They are automatically deleted when the tunnel is destroyed.
 .Pp
 It also means that
 .Nm
@@ -93,9 +91,9 @@
 policy pair exists.
 .Pp
 There are four security policies generated by
-.Nm ,
-that is, one in and out pair for IPv4 and IPv6 each.
-These security policies equal to the following
+.Nm :
+one in and out pair for IPv4 and IPv6 each.
+These security policies are equivalent to the following
 .Xr ipsec.conf 5
 configuration where src and dst are IP addresses specified to the tunnel:
 .Bd -literal -offset indent
@@ -105,9 +103,9 @@
 spdadd "dst" "src" ipv6 -P in ipsec esp/transport//unique;
 .Ed
 .Pp
-Therefore,
+The
 .Nm
-configuration will fail if you already added such security policies, and
+configuration will fail if such security policies already exist, and
 vice versa.
 .Pp
 The related security associates can be established by an IKE daemon such as
@@ -120,9 +118,8 @@
 .Pp
 Some
 .Xr ifconfig 8
-parameters change
-.Nm Ap s
-behaviour.
+parameters change the behaviour of
+.Nm .
 link0 can enable NAT-Traversal,
 link1 can enable ECN friendly mode like
 .Xr gif 4 ,
@@ -138,15 +135,28 @@
 .Sh EXAMPLES
 Configuration example:
 .Bd -literal
-Host X--NetBSD A  ----------------tunnel---------- NetBSD B------Host E
-           \\                                          |
-            \\                                        /
-             +-----Router B--------Router C---------+
+Out IP addr = 172.16.100.1            Out IP addr = 172.16.200.1
+wm0 = 192.168.0.1/24                        wm0 = 192.168.0.2/24
+wm1 = 10.100.0.1/24                          wm1 = 10.200.0.1/24
+
++------------+                                    +------------+
+|  NetBSD_A  |                                    |  NetBSD_B  |
+|------------|                                    |------------|
+|  [ipsec0] - - - - - - - - (tunnel) - - - - - - - - [ipsec0]  |
+|          [wm0]------------- ... --------------[wm0]          |
+|            |                                    |            |
++---[wm1]----+                                    +----[wm1]---+
+      |                                                  |
+      |                                                  |
++------------+                                    +------------+
+|   Host_X   |                                    |   Host_Y   |
++------------+                                    +------------+
 .Ed
 .Pp
-On
-.Nx
-system A
+Host_X and Host_Y will be able to communicate via an IPv4 IPsec
+tunnel.
+.Pp
+On NetBSD_A:
 .Bd -literal
 # ifconfig wm0 inet 192.168.0.1/24
 # ifconfig ipsec0 create
@@ -157,9 +167,7 @@
 # route add 10.200.0.1 172.16.100.1
 .Ed
 .Pp
-On
-.Nx
-system B
+On NetBSD_B:
 .Bd -literal
 # ifconfig wm0 inet 192.168.0.2/24
 # ifconfig ipsec0 create