[Openvpn-devel,v6,13/13] client-connect: Add documentation for the deferred client connect feature

Message ID 20181126081224.30779-1-arne@rfc2549.org
State New
Headers show
Series
  • Untitled series #415
Related show

Commit Message

Arne Schwabe Nov. 26, 2018, 8:12 a.m.
Patch V5: Fix typos, clarify man page section about deferred client-connect
          script. Add section to Changes.rst

Signed-off-by: Arne Schwabe <arne@rfc2549.org>
---
 Changes.rst                 |  4 +++
 doc/openvpn.8               | 55 +++++++++++++++++++++++++++++++++++--
 include/openvpn-plugin.h.in | 21 ++++++++++----
 3 files changed, 71 insertions(+), 9 deletions(-)

Patch

diff --git a/Changes.rst b/Changes.rst
index a7429b11..357b0901 100644
--- a/Changes.rst
+++ b/Changes.rst
@@ -3,6 +3,10 @@  Overview of changes in 2.5
 
 New features
 ------------
+Deferred client-connect
+    client-connect and the connect plugin API allow now asynchronous/deferred
+    return of configuration file in the same way as the auth-plugin.
+
 Client-specific tls-crypt keys (``--tls-crypt-v2``)
     ``tls-crypt-v2`` adds the ability to supply each client with a unique
     tls-crypt key.  This allows large organisations and VPN providers to profit
diff --git a/doc/openvpn.8 b/doc/openvpn.8
index 94b5cc4f..a5ec3b07 100644
--- a/doc/openvpn.8
+++ b/doc/openvpn.8
@@ -3346,6 +3346,13 @@  is significant.  If
 .B script
 returns a non\-zero error status, it will cause the client
 to be disconnected.
+
+If a
+.B \-\-client\-connect cmd
+wants to defer the generating the configuration the script, should
+use the client_connect_deferred_file and client_connect_config_file
+environment variables and write status accordingly into these files
+(See the environment section below for more details).
 .\"*********************************************************
 .TP
 .B \-\-client\-disconnect cmd
@@ -3428,12 +3435,18 @@  This directory will be used by in the following cases:
 
 *
 .B \-\-client\-connect
-scripts to dynamically generate client\-specific
-configuration files.
+scripts and
+.B OPENVPN_PLUGIN_CLIENT_CONNECT
+plugin hook 
+to dynamically generate client\-specific configuration files
+and return success/failure via client_connect_deferred_file
+when using deferred client connect method
 
 *
 .B OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY
-plugin hook to return success/failure via auth_control_file
+and 
+
+plugin hook to return success/failure via auth_control_file/
 when using deferred auth method
 
 *
@@ -6431,6 +6444,42 @@  Set prior to execution of the
 script.
 .\"*********************************************************
 .TP
+.B client_connect_config_file
+The path to the configuration file that should be written by
+the
+.B \-\-client\-connect
+The content of this environment variable is identical to the
+file as a argument of the called
+.B \-\-client\-connect
+script.
+.\"*********************************************************
+.TP
+.B client_connect_deferred_file
+This file can be optionally written to communicate a status
+code of the
+.TP
+.B \-\-client\-connect
+script. If used for deferring, this file must be written
+before the
+.B \-\-client\-connect
+script exits. The first character in the file is interpreted
+and '1 is equal to normal script execution, '0' indicates an
+error (in the same way that a non zero exit status does) and
+'2 indicates that the script deferred returning the config
+file. When the script defers returning the configuration, it must
+must '2' to to the file to indicate the deferral.
+A background process or similar must then take of writing the
+configuration to the file indicated by the
+.B
+client_connect_config_file
+environment variable and when finished, write the a '1' to this
+file (or '0' in case of an error).
+
+The absence of any character in the file when the script finishes
+executing is interpreted the same as '1'. This allows script that
+are not written to support the defer mechanism to be used unmodified.
+.\"*********************************************************
+.TP
 .B common_name
 The X509 common name of an authenticated client.
 Set prior to execution of
diff --git a/include/openvpn-plugin.h.in b/include/openvpn-plugin.h.in
index 38fbe097..c776178f 100644
--- a/include/openvpn-plugin.h.in
+++ b/include/openvpn-plugin.h.in
@@ -557,12 +557,21 @@  OPENVPN_PLUGIN_DEF openvpn_plugin_handle_t OPENVPN_PLUGIN_FUNC(openvpn_plugin_op
  * OPENVPN_PLUGIN_FUNC_SUCCESS on success, OPENVPN_PLUGIN_FUNC_ERROR on failure
  *
  * In addition, OPENVPN_PLUGIN_FUNC_DEFERRED may be returned by
- * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY.  This enables asynchronous
- * authentication where the plugin (or one of its agents) may indicate
- * authentication success/failure some number of seconds after the return
- * of the OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY handler by writing a single
- * char to the file named by auth_control_file in the environmental variable
- * list (envp).
+ * OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY, OPENVPN_PLUGIN_CLIENT_CONNECT and
+ * OPENVPN_PLUGIN_CLIENT_CONNECT_V2. This enables asynchronous
+ * authentication or client connect  where the plugin (or one of its agents) 
+ * may indicate authentication success/failure or client configuration some
+ * number of seconds after the return of the function handler.
+ * For OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY and OPENVPN_PLUGIN_CLIENT_CONNECT
+ * this is done by writing a single char to the file named by
+ * auth_control_file/client_connect_deferred_file
+ * in the environmental variable list (envp).
+ *
+ * In addition the OPENVPN_PLUGIN_CLIENT_CONNECT_DEFER and 
+ * OPENVPN_PLUGIN_CLIENT_CONNECT_DEFER_V2 are called when OpenVPN tries to
+ * get the deferred result. For a V2 call implementing this function is 
+ * required as information is not passed by files. For the normal version
+ * the call is optional.
  *
  * first char of auth_control_file:
  * '0' -- indicates auth failure