diff --git a/Changes.rst b/Changes.rst index 0da01e84..37792342 100644 --- a/Changes.rst +++ b/Changes.rst @@ -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 diff --git a/doc/man-sections/generic-options.rst b/doc/man-sections/generic-options.rst index d44dc05f..a07fe7e7 100644 --- a/doc/man-sections/generic-options.rst +++ b/doc/man-sections/generic-options.rst @@ -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 diff --git a/doc/man-sections/script-options.rst b/doc/man-sections/script-options.rst index ddc1363c..b4bbf52f 100644 --- a/doc/man-sections/script-options.rst +++ b/doc/man-sections/script-options.rst @@ -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 diff --git a/include/openvpn-plugin.h.in b/include/openvpn-plugin.h.in index 38fbe097..64b20886 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