@@ -32,6 +32,11 @@ Improved Data channel cipher negotiation

 Asynchronous (deferred) authentication support for auth-pam plugin.

     See src/plugins/auth-pam/README.auth-pam for details.

+Deferred client-connect

+    The ``--client-connect`` option and the connect plugin API allow

+    asynchronous/deferred return of the configuration file in the same way

+    as the auth-plugin.

+

 Faster connection setup

     A client will signal in the ``IV_PROTO`` variable that it is in pull

     mode. This allows the server to push the configuration options to

@@ -394,11 +394,14 @@ which mode OpenVPN is configured as.

   This directory will be used by in the following cases:

-  * ``--client-connect`` scripts to dynamically generate client-specific

-    configuration files.

+  * ``--client-connect`` scripts and :code:`OPENVPN_PLUGIN_CLIENT_CONNECT`

+    plug-in hook to dynamically generate client-specific configuration

+    :code:`client_connect_config_file` and return success/failure via

+    :code:`client_connect_deferred_file` when using deferred client connect

+    method

-  * :code:`OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY` plugin hook to return

-    success/failure via ``auth_control_file`` when using deferred auth

+  * :code:`OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY` plug-in hooks returns

+    success/failure via :code:`auth_control_file` when using deferred auth

     method

   * :code:`OPENVPN_PLUGIN_ENABLE_PF` plugin hook to pass filtering rules

@@ -137,6 +137,13 @@ SCRIPT HOOKS

   returns a non-zero error status, it will cause the client to be

   disconnected.

+  If a ``--client-connect`` wants to defer the generating of the

+  configuration then the script needs to use the

+  :code:`client_connect_deferred_file` and

+  :code:`client_connect_config_file` environment variables, and write

+  status accordingly into these files.  See the `Environmental Variables`_

+  section for more details.

+

 --client-disconnect cmd

   Like ``--client-connect`` but called on client instance shutdown. Will

   not be called unless the ``--client-connect`` script and plugins (if

@@ -512,6 +519,35 @@ instances.

     Total number of bytes sent to client during VPN session. Set prior to

     execution of the ``--client-disconnect`` script.

+:code:`client_connect_config_file`

+    The path to the configuration file that should be written to by the

+    ``--client-connect`` script (optional, if per-session configuration

+    is desired).  This is the same file name as passed via command line

+    argument on the call to the ``--client-connect`` script.

+

+:code:`client_connect_deferred_file`

+    This file can be optionally written to in order to to communicate a

+    status code of the ``--client-connect`` script or plgin.  Only the

+    first character in the file is relevant.  It must be either :code:`1`

+    to indicate normal script execution, :code:`0` indicates an error (in

+    the same way that a non zero exit status does) or :code:`2` to indicate

+    that the script deferred returning the config file.

+

+    For deferred (background) handling, the script or plugin MUST write

+    :code:`2` to the file to indicate the deferral and then return with

+    exit code :code:`0` to signal ``deferred handler started OK``.

+

+    A background process or similar must then take care of writing the

+    configuration to the file indicated by the

+    :code:`client_connect_config_file` environment variable and when

+    finished, write the a :code:`1` to this file (or :code:`0` in case of

+    an error).

+

+    The absence of any character in the file when the script finishes

+    executing is interpreted the same as :code:`1`. This allows scripts

+    that are not written to support the defer mechanism to be used

+    unmodified.

+

 :code:`common_name`

     The X509 common name of an authenticated client. Set prior to execution

     of ``--client-connect``, ``--client-disconnect`` and

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