[src/trunk]: src/share/man/man4 Improve ipsecif.4. Default port ipsec(4) NAT-...

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

details:   https://anonhg.NetBSD.org/src/rev/78a836e639b7
branches:  trunk
changeset: 828945:78a836e639b7
user:      knakahara <knakahara%NetBSD.org@localhost>
date:      Thu Jan 11 06:38:05 2018 +0000

description:
Improve ipsecif.4. Default port ipsec(4) NAT-T is tested now.

pointed out by wiz@n.o and suggested by ozaki-r@n.o, thanks.

diffstat:

 share/man/man4/ipsecif.4 |  69 ++++++++++++++++++++++++++++++++++++-----------
 1 files changed, 52 insertions(+), 17 deletions(-)

diffs (133 lines):

diff -r e311ae70a53a -r 78a836e639b7 share/man/man4/ipsecif.4
--- a/share/man/man4/ipsecif.4  Wed Jan 10 20:51:11 2018 +0000
+++ b/share/man/man4/ipsecif.4  Thu Jan 11 06:38:05 2018 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: ipsecif.4,v 1.2 2018/01/10 12:18:22 wiz Exp $
+.\"    $NetBSD: ipsecif.4,v 1.3 2018/01/11 06:38:05 knakahara 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 December 22, 2017
+.Dd January 11, 2018
 .Dt IPSECIF 4
 .Os
 .Sh NAME
@@ -38,24 +38,51 @@
 .Sh DESCRIPTION
 The
 .Nm
-interface is similar to
+interface is targeted for route-based VPNs. It can tunnel IPv4 and
+IPv6 traffic over either IPv4 or IPv6 and secure it with ESP.
+.Pp
+.Nm
+interfaces are dynamically created and destroyed with the
+.Xr ifconfig 8
+.Cm create
+and
+.Cm destroy
+subcommands. The administrator must configure
+.Nm
+.Cm
+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
+.Xr ifconfig 8
+.Cm inet
+or
+.Cm inet6
+subcommands, and modify the routing table to route the packets through
+the
+.Nm
+interface.
+.Pp
+The packet processing is similar to
 .Xr gif 4
 over
 .Xr ipsec 4
-transport mode.
+transport mode, however their security policy managements are different.
 .Xr gif 4
 over
 .Xr ipsec 4
-transport mode is managed by userland programs.
-In contrast,
+transport mode expects for userland programs to managed its
+security policies. In contrast,
 .Nm
-manages its security policies by itself, that is, when user sets up a
+manages its security policies by itself, that is, when the administrator
+sets up a
 .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.
+.Pp
 It also means that
 .Nm
 ensures that both the in and out security policy pairs exist, that is,
@@ -66,10 +93,10 @@
 There are four security policies generated by
 .Nm ,
 that is, one in and out pair for IPv4 and IPv6 each.
-This
+These security policies equal to the following
 .Xr ipsec.conf 5
-has the same meaning as these security policies:
-.Bd -literal
+configuration where src and dst are IP addresses specified to the tunnel:
+.Bd -literal -offset indent
 spdadd "src" "dst" ipv4 -P out ipsec esp/transport//unique;
 spdadd "dst" "src" ipv4 -P in ipsec esp/transport//unique;
 spdadd "src" "dst" ipv6 -P out ipsec esp/transport//unique;
@@ -89,16 +116,23 @@
 .Fl u
 option which sets a security policy's unique id.
 .Pp
-Some if_flags change
+Some
+.Xr ifconfig 8
+parameters change
 .Nm Ap s
 behaviour.
-IFF_LINK0 can enable Network Address Translator traversal,
-IFF_LINK1 can enable ECN friendly mode like
+link0 can enable NAT-Traversal,
+link1 can enable ECN friendly mode like
 .Xr gif 4 ,
-and IFF_LINK2 can enable forwarding inner IPv6 packets.
-Only IFF_LINK2 is set by default.
+and link2 can enable forwarding inner IPv6 packets.
+Only link2 is set by default.
 If you use only IPv4 packets as inner packets, you would want to
-unset IFF_LINK2 to reduce security associates for IPv6 packets.
+do
+.Bd -literal -offset indent
+ifconfig ipsec0 -link2
+.Ed
+.Pp
+to reduce security associates for IPv6 packets.
 .Sh EXAMPLES
 Configuration example:
 .Bd -literal
@@ -139,6 +173,7 @@
 .Xr inet6 4 ,
 .Xr ipsec 4 ,
 .Xr ifconfig 8 ,
+.Xr racoon 8 ,
 .Xr setkey 8
 .Sh HISTORY
 The
@@ -150,4 +185,4 @@
 .Nm
 interface supports the ESP protocol only.
 .Nm
-does not support Network Address Translator traversal (NAT-T).
+supports default port number (4500) only for NAT-Traversal.