[NetworkManager-libreswan/fg/IKEv2_rh1557035] man: add man page for nm-settings-libreswan

[Francesco Giudici <fgiudici src gnome org>]

commit b8e5b578b44f42b4e02587f722c6fb5e9b26c418
Author: Francesco Giudici <fgiudici redhat com>
Date:   Mon Jul 9 17:56:27 2018 +0200

    man: add man page for nm-settings-libreswan
    
    document the available options for vpn.data and vpn.secrets for the
    NetworkManager-libreswan plugin.

 .gitignore                     |   1 +
 Makefile.am                    |   3 +-
 configure.ac                   |   2 +
 man/Makefile.am                |   1 +
 man/nm-settings-libreswan.5.in | 119 +++++++++++++++++++++++++++++++++++++++++
 5 files changed, 124 insertions(+), 2 deletions(-)
---
diff --git a/.gitignore b/.gitignore
index 1d1954e..2b1b157 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,5 +39,6 @@ src/nm-libreswan-service-helper
 src/show-xfrm
 src/nm-libreswan-helper-service-dbus.c
 src/nm-libreswan-helper-service-dbus.h
+man/nm-settings-libreswan.5
 
 /NetworkManager-libreswan*.tar*
diff --git a/Makefile.am b/Makefile.am
index d7955e4..ed86802 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -19,8 +19,7 @@ libexec_PROGRAMS =
 
 noinst_PROGRAMS =
 
-SUBDIRS = \
-       po
+SUBDIRS = po man
 
 ###############################################################################
 
diff --git a/configure.ac b/configure.ac
index 3e8e87e..1baee6e 100644
--- a/configure.ac
+++ b/configure.ac
@@ -179,6 +179,8 @@ fi
 AC_CONFIG_FILES([
 Makefile
 po/Makefile.in
+man/Makefile
+man/nm-settings-libreswan.5
 ])
 AC_OUTPUT
 
diff --git a/man/Makefile.am b/man/Makefile.am
new file mode 100644
index 0000000..bc8978d
--- /dev/null
+++ b/man/Makefile.am
@@ -0,0 +1 @@
+man_MANS = nm-settings-libreswan.5
diff --git a/man/nm-settings-libreswan.5.in b/man/nm-settings-libreswan.5.in
new file mode 100644
index 0000000..95a81f4
--- /dev/null
+++ b/man/nm-settings-libreswan.5.in
@@ -0,0 +1,119 @@
+.\" nm-settings-libreswan(5) manual page
+.\"
+.\" This is free documentation; you can redistribute it and/or
+.\" modify it under the terms of the GNU General Public License as
+.\" published by the Free Software Foundation; either version 2 of
+.\" the License, or (at your option) any later version.
+.\"
+.\" The GNU General Public License's references to "object code"
+.\" and "executables" are to be interpreted as the output of any
+.\" document formatting or typesetting system, including
+.\" intermediate and printed output.
+.\"
+.\" This manual is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public Licence along
+.\" with this manual; if not, write to the Free Software Foundation, Inc.,
+.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+.\"
+.\" Copyright (C) 2018 Red Hat, Inc.
+.\"
+.TH NM-SETTINGS-LIBRESWAN "5" "9 July 2018"
+
+.SH NAME
+nm\-setting\-libreswan \- NetworkManager Libreswan plugin supported options
+
+.SH DESCRIPTION
+.PP
+NetworkManager is based on the concept of connection profiles made up of settings
+containing the network configuration (see
+\fBnm-settings\fR(5)
+for details).
+The data and secret keys belonging to the vpn setting take dictionaries of key/value
+pairs which depends on the specific VPN plugin. Here the list of the allowed key/value pairs
+for the NetworkManager Libreswan plugin.
+
+.SH VPN.DATA
+.PP
+Many key/value pairs in the \fBvpn.data\fR property are passed unchanged to the Libreswan service.
+The configuration is first validated by the NetworkManager plugin, which will also add some extra Libreswan
+parameters and defaults as needed. There are some key/value pairs used for the plugin configuration only,
+e.g., the flags used to manage the secrets needed by the connection.
+Here the full list of the allowed parameters:
+.TP
+.I "right"
+contains the address of the remote VPN endpoint. Corresponds to the Libreswan parameter of the same name.
+Always Required.
+.TP
+.I "leftid"
+specifies the local identifier to be used during IKE negotiation. When this property is specified and the
+IKEv1 protocol is used the key exchange will be performed in aggressive mode. Corresponds to the Libreswan
+parameter of the same name.
+.TP
+.I "leftxauthusername"
+the username to be used during XAUTH authentication. If not specified, the
+current user will be implicitly assumed. Corresponds to the Libreswan parameter
+of the same name.
+.TP
+.I "dhgroup"
+ignored.
+.TP
+.I "pfsgroup"
+ignored.
+.TP
+.I "dpdtimeout"
+ignored.
+.TP
+.I "ike"
+allowed ciphers to be negotiatied to establish the IKE SAs. Corresponds to the
+Libreswan parameter of the same name.
+.TP
+.I "esp"
+allowed ciphers for establishing phase2 SAs. Matches the Libreswan
+parameter of the same name.
+.TP
+.I "ikelifetime"
+how long the phase1 SA of a connection should last. Matches the Libreswan
+parameter of the same name. Default is 24h.
+.TP
+.I "salifetime"
+how long the pashe2 SA of a connection should last. Matches the Libreswan
+parameter of the same name. Default is 24h.
+.TP
+.I "vendor"
+when equals 'Cisco', the 'cisco-unity=yes' will be passed to Libreswan, to allow
+ending the CISCO_UNITY payload to the peer. The option is ignored otherwise.
+.TP
+.I "rightsubnet"
+the destination subnet that should be reached throught the VPN. If omitted, will
+be filled with '0.0.0.0/0'. Matches the Libreswan parameter of the same name.
+.TP
+.I "pskinputmodes"
+legacy, use 'pskvalue-flags' instead. Allowed values are: 'unused', 'save', 'ask'.
+.TP
+.I "xauthpasswordinputmodes"
+legacy, use 'xauthpassword-flags instead. Allowed values are: 'unused', 'save', 'ask'.
+.TP
+.I "pskvalue-flags"
+how to handle the 'pskvalue' secret. See the "Secret flag type" section at
+\fBnm-settings\fR(5)
+for details.
+
+.SH VPN.SECRETS
+.PP
+The \fBvpn.secrets\R property holds the secrets stored in the connection (if any).
+The allowed keys are:
+.TP
+.I "pskvalue"
+if specified, its value is configured in the Libreswan secret file for the authentication
+of the connection.
+.TP
+.I "xauthpassword"
+if specified, its value is provided to Libreswan during XAUTH authentication.
+
+.SH SEE ALSO
+.BR NetworkManager(8),
+.BR nm\-settings(5).