Merge branch 'debian/experimental-2.5'

1 files changed, 842 insertions, 0 deletions

diff --git a/doc/man-sections/script-options.rst b/doc/man-sections/script-options.rst
new file mode 100644
index 0000000..b4bbf52
--- /dev/null
+++ b/doc/man-sections/script-options.rst
@@ -0,0 +1,842 @@
+SCRIPTING INTEGRATION
+=====================
+
+OpenVPN can execute external scripts in various phases of the lifetime of
+the OpenVPN process.
+
+
+Script Order of Execution
+-------------------------
+
+#. ``--up``
+
+   Executed after TCP/UDP socket bind and TUN/TAP open.
+
+#. ``--tls-verify``
+
+   Executed when we have a still untrusted remote peer.
+
+#. ``--ipchange``
+
+   Executed after connection authentication, or remote IP address change.
+
+#. ``--client-connect``
+
+   Executed in **--mode server** mode immediately after client
+   authentication.
+
+#. ``--route-up``
+
+   Executed after connection authentication, either immediately after, or
+   some number of seconds after as defined by the **--route-delay** option.
+
+#. ``--route-pre-down``
+
+   Executed right before the routes are removed.
+
+#. ``--client-disconnect``
+
+   Executed in ``--mode server`` mode on client instance shutdown.
+
+#. ``--down``
+
+   Executed after TCP/UDP and TUN/TAP close.
+
+#. ``--learn-address``
+
+   Executed in ``--mode server`` mode whenever an IPv4 address/route or MAC
+   address is added to OpenVPN's internal routing table.
+
+#. ``--auth-user-pass-verify``
+
+   Executed in ``--mode server`` mode on new client connections, when the
+   client is still untrusted.
+
+SCRIPT HOOKS
+------------
+
+--auth-user-pass-verify args
+  Require the client to provide a username/password (possibly in addition
+  to a client certificate) for authentication.
+
+  Valid syntax:
+  ::
+
+     auth-user-pass-verify cmd method
+
+  OpenVPN will run command ``cmd`` to validate the username/password
+  provided by the client.
+
+  ``cmd`` consists of a path to a script (or executable program), optionally
+  followed by arguments. The path and arguments may be single- or
+  double-quoted and/or escaped using a backslash, and should be separated
+  by one or more spaces.
+
+  If ``method`` is set to :code:`via-env`, OpenVPN will call ``script``
+  with the environmental variables :code:`username` and :code:`password`
+  set to the username/password strings provided by the client. *Beware*
+  that this method is insecure on some platforms which make the environment
+  of a process publicly visible to other unprivileged processes.
+
+  If ``method`` is set to :code:`via-file`, OpenVPN will write the username
+  and password to the first two lines of a temporary file. The filename
+  will be passed as an argument to ``script``, and the file will be
+  automatically deleted by OpenVPN after the script returns. The location
+  of the temporary file is controlled by the ``--tmp-dir`` option, and
+  will default to the current directory if unspecified. For security,
+  consider setting ``--tmp-dir`` to a volatile storage medium such as
+  :code:`/dev/shm` (if available) to prevent the username/password file
+  from touching the hard drive.
+
+  The script should examine the username and password, returning a success
+  exit code (:code:`0`) if the client's authentication request is to be
+  accepted, or a failure code (:code:`1`) to reject the client.
+
+  This directive is designed to enable a plugin-style interface for
+  extending OpenVPN's authentication capabilities.
+
+  To protect against a client passing a maliciously formed username or
+  password string, the username string must consist only of these
+  characters: alphanumeric, underbar (':code:`_`'), dash (':code:`-`'),
+  dot (':code:`.`'), or at (':code:`@`'). The password string can consist
+  of any printable characters except for CR or LF. Any illegal characters
+  in either the username or password string will be converted to
+  underbar (':code:`_`').
+
+  Care must be taken by any user-defined scripts to avoid creating a
+  security vulnerability in the way that these strings are handled. Never
+  use these strings in such a way that they might be escaped or evaluated
+  by a shell interpreter.
+
+  For a sample script that performs PAM authentication, see
+  :code:`sample-scripts/auth-pam.pl` in the OpenVPN source distribution.
+
+--client-connect cmd
+  Run command ``cmd`` on client connection.
+
+  ``cmd`` consists of a path to a script (or executable program), optionally
+  followed by arguments. The path and arguments may be single- or
+  double-quoted and/or escaped using a backslash, and should be separated
+  by one or more spaces.
+
+  The command is passed the common name and IP address of the
+  just-authenticated client as environmental variables (see environmental
+  variable section below). The command is also passed the pathname of a
+  freshly created temporary file as the last argument (after any arguments
+  specified in ``cmd`` ), to be used by the command to pass dynamically
+  generated config file directives back to OpenVPN.
+
+  If the script wants to generate a dynamic config file to be applied on
+  the server when the client connects, it should write it to the file
+  named by the last argument.
+
+  See the ``--client-config-dir`` option below for options which can be
+  legally used in a dynamically generated config file.
+
+  Note that the return value of ``script`` is significant. If ``script``
+  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
+  defined) were previously called on this instance with successful (0)
+  status returns.
+
+  The exception to this rule is if the ``--client-disconnect`` command or
+  plugins are cascaded, and at least one client-connect function
+  succeeded, then ALL of the client-disconnect functions for scripts and
+  plugins will be called on client instance object deletion, even in cases
+  where some of the related client-connect functions returned an error
+  status.
+
+  The ``--client-disconnect`` command is passed the same pathname as the
+  corresponding ``--client-connect`` command as its last argument (after
+  any arguments specified in ``cmd``).
+
+--down cmd
+  Run command ``cmd`` after TUN/TAP device close (post ``--user`` UID
+  change and/or ``--chroot`` ). ``cmd`` consists of a path to script (or
+  executable program), optionally followed by arguments. The path and
+  arguments may be single- or double-quoted and/or escaped using a
+  backslash, and should be separated by one or more spaces.
+
+  Called with the same parameters and environmental variables as the
+  ``--up`` option above.
+
+  Note that if you reduce privileges by using ``--user`` and/or
+  ``--group``, your ``--down`` script will also run at reduced privilege.
+
+--down-pre
+  Call ``--down`` cmd/script before, rather than after, TUN/TAP close.
+
+--ipchange cmd
+  Run command ``cmd`` when our remote ip-address is initially
+  authenticated or changes.
+
+  ``cmd`` consists of a path to a script (or executable program), optionally
+  followed by arguments. The path and arguments may be single- or
+  double-quoted and/or escaped using a backslash, and should be separated
+  by one or more spaces.
+
+  When ``cmd`` is executed two arguments are appended after any arguments
+  specified in ``cmd`` , as follows:
+  ::
+
+     cmd ip address port number
+
+  Don't use ``--ipchange`` in ``--mode server`` mode. Use a
+  ``--client-connect`` script instead.
+
+  See the `Environmental Variables`_ section below for additional
+  parameters passed as environmental variables.
+
+  If you are running in a dynamic IP address environment where the IP
+  addresses of either peer could change without notice, you can use this
+  script, for example, to edit the :code:`/etc/hosts` file with the current
+  address of the peer. The script will be run every time the remote peer
+  changes its IP address.
+
+  Similarly if *our* IP address changes due to DHCP, we should configure
+  our IP address change script (see man page for ``dhcpcd``\(8)) to
+  deliver a ``SIGHUP`` or ``SIGUSR1`` signal to OpenVPN. OpenVPN will
+  then re-establish a connection with its most recently authenticated
+  peer on its new IP address.
+
+--learn-address cmd
+  Run command ``cmd`` to validate client virtual addresses or routes.
+
+  ``cmd`` consists of a path to a script (or executable program), optionally
+  followed by arguments. The path and arguments may be single- or
+  double-quoted and/or escaped using a backslash, and should be separated
+  by one or more spaces.
+
+  Three arguments will be appended to any arguments in ``cmd`` as follows:
+
+  :code:`$1` - [operation]
+      :code:`"add"`, :code:`"update"`, or :code:`"delete"` based on whether
+      or not the address is being added to, modified, or deleted from
+      OpenVPN's internal routing table.
+
+  :code:`$2` - [address]
+      The address being learned or unlearned. This can be an IPv4 address
+      such as :code:`"198.162.10.14"`, an IPv4 subnet such as
+      :code:`"198.162.10.0/24"`, or an ethernet MAC address (when
+      ``--dev tap`` is being used) such as :code:`"00:FF:01:02:03:04"`.
+
+  :code:`$3` - [common name]
+      The common name on the certificate associated with the client linked
+      to this address. Only present for :code:`"add"` or :code:`"update"`
+      operations, not :code:`"delete"`.
+
+  On :code:`"add"` or :code:`"update"` methods, if the script returns
+  a failure code (non-zero), OpenVPN will reject the address and will not
+  modify its internal routing table.
+
+  Normally, the ``cmd`` script will use the information provided above to
+  set appropriate firewall entries on the VPN TUN/TAP interface. Since
+  OpenVPN provides the association between virtual IP or MAC address and
+  the client's authenticated common name, it allows a user-defined script
+  to configure firewall access policies with regard to the client's
+  high-level common name, rather than the low level client virtual
+  addresses.
+
+--route-up cmd
+  Run command ``cmd`` after routes are added, subject to ``--route-delay``.
+
+  ``cmd`` consists of a path to a script (or executable program), optionally
+  followed by arguments. The path and arguments may be single- or
+  double-quoted and/or escaped using a backslash, and should be separated
+  by one or more spaces.
+
+  See the `Environmental Variables`_ section below for additional
+  parameters passed as environmental variables.
+
+--route-pre-down cmd
+  Run command ``cmd`` before routes are removed upon disconnection.
+
+  ``cmd`` consists of a path to a script (or executable program), optionally
+  followed by arguments. The path and arguments may be single- or
+  double-quoted and/or escaped using a backslash, and should be separated
+  by one or more spaces.
+
+  See the `Environmental Variables`_ section below for additional
+  parameters passed as environmental variables.
+
+--setenv args
+  Set a custom environmental variable :code:`name=value` to pass to script.
+
+  Valid syntaxes:
+  ::
+
+     setenv name value
+     setenv FORWARD_COMPATIBLE 1
+     setenv opt config_option
+
+  By setting :code:`FORWARD_COMPATIBLE` to :code:`1`, the config file
+  syntax checking is relaxed so that unknown directives will trigger a
+  warning but not a fatal error, on the assumption that a given unknown
+  directive might be valid in future OpenVPN versions.
+
+  This option should be used with caution, as there are good security
+  reasons for having OpenVPN fail if it detects problems in a config file.
+  Having said that, there are valid reasons for wanting new software
+  features to gracefully degrade when encountered by older software
+  versions.
+
+  It is also possible to tag a single directive so as not to trigger a
+  fatal error if the directive isn't recognized. To do this, prepend the
+  following before the directive: ``setenv opt``
+
+  Versions prior to OpenVPN 2.3.3 will always ignore options set with the
+  ``setenv opt`` directive.
+
+  See also ``--ignore-unknown-option``
+
+--setenv-safe args
+  Set a custom environmental variable :code:`OPENVPN_name` to :code:`value`
+  to pass to scripts.
+
+  Valid syntaxes:
+  ::
+
+     setenv-safe name value
+
+  This directive is designed to be pushed by the server to clients, and
+  the prepending of :code:`OPENVPN_` to the environmental variable is a
+  safety precaution to prevent a :code:`LD_PRELOAD` style attack from a
+  malicious or compromised server.
+
+--tls-verify cmd
+  Run command ``cmd`` to verify the X509 name of a pending TLS connection
+  that has otherwise passed all other tests of certification (except for
+  revocation via ``--crl-verify`` directive; the revocation test occurs
+  after the ``--tls-verify`` test).
+
+  ``cmd`` should return :code:`0` to allow the TLS handshake to proceed,
+  or :code:`1` to fail.
+
+  ``cmd`` consists of a path to a script (or executable program), optionally
+  followed by arguments. The path and arguments may be single- or
+  double-quoted and/or escaped using a backslash, and should be separated
+  by one or more spaces.
+
+  When ``cmd`` is executed two arguments are appended after any arguments
+  specified in ``cmd``, as follows:
+  ::
+
+     cmd certificate_depth subject
+
+  These arguments are, respectively, the current certificate depth and the
+  X509 subject distinguished name (dn) of the peer.
+
+  This feature is useful if the peer you want to trust has a certificate
+  which was signed by a certificate authority who also signed many other
+  certificates, where you don't necessarily want to trust all of them, but
+  rather be selective about which peer certificate you will accept. This
+  feature allows you to write a script which will test the X509 name on a
+  certificate and decide whether or not it should be accepted. For a
+  simple perl script which will test the common name field on the
+  certificate, see the file ``verify-cn`` in the OpenVPN distribution.
+
+  See the `Environmental Variables`_ section below for additional
+  parameters passed as environmental variables.
+
+--up cmd
+  Run command ``cmd`` after successful TUN/TAP device open (pre ``--user``
+  UID change).
+
+  ``cmd`` consists of a path to a script (or executable program), optionally
+  followed by arguments. The path and arguments may be single- or
+  double-quoted and/or escaped using a backslash, and should be separated
+  by one or more spaces.
+
+  The up command is useful for specifying route commands which route IP
+  traffic destined for private subnets which exist at the other end of the
+  VPN connection into the tunnel.
+
+  For ``--dev tun`` execute as:
+  ::
+
+      cmd tun_dev tun_mtu link_mtu ifconfig_local_ip ifconfig_remote_ip [init | restart]
+
+  For ``--dev tap`` execute as:
+  ::
+
+       cmd tap_dev tap_mtu link_mtu ifconfig_local_ip ifconfig_netmask [init | restart]
+
+  See the `Environmental Variables`_ section below for additional
+  parameters passed as environmental variables.
+
+  Note that if ``cmd`` includes arguments, all OpenVPN-generated arguments
+  will be appended to them to build an argument list with which the
+  executable will be called.
+
+  Typically, ``cmd`` will run a script to add routes to the tunnel.
+
+  Normally the up script is called after the TUN/TAP device is opened. In
+  this context, the last command line parameter passed to the script will
+  be *init.* If the ``--up-restart`` option is also used, the up script
+  will be called for restarts as well. A restart is considered to be a
+  partial reinitialization of OpenVPN where the TUN/TAP instance is
+  preserved (the ``--persist-tun`` option will enable such preservation).
+  A restart can be generated by a SIGUSR1 signal, a ``--ping-restart``
+  timeout, or a connection reset when the TCP protocol is enabled with the
+  ``--proto`` option. If a restart occurs, and ``--up-restart`` has been
+  specified, the up script will be called with *restart* as the last
+  parameter.
+
+  *NOTE:*
+     On restart, OpenVPN will not pass the full set of environment
+     variables to the script. Namely, everything related to routing and
+     gateways will not be passed, as nothing needs to be done anyway - all
+     the routing setup is already in place. Additionally, the up-restart
+     script will run with the downgraded UID/GID settings (if configured).
+
+  The following standalone example shows how the ``--up`` script can be
+  called in both an initialization and restart context. (*NOTE:* for
+  security reasons, don't run the following example unless UDP port 9999
+  is blocked by your firewall. Also, the example will run indefinitely, so
+  you should abort with control-c).
+
+  ::
+
+      openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 \
+              --up 'echo up' --down 'echo down' --persist-tun  \
+              --up-restart
+
+  Note that OpenVPN also provides the ``--ifconfig`` option to
+  automatically ifconfig the TUN device, eliminating the need to define an
+  ``--up`` script, unless you also want to configure routes in the
+  ``--up`` script.
+
+  If ``--ifconfig`` is also specified, OpenVPN will pass the ifconfig
+  local and remote endpoints on the command line to the ``--up`` script so
+  that they can be used to configure routes such as:
+
+  ::
+
+      route add -net 10.0.0.0 netmask 255.255.255.0 gw $5
+
+--up-delay
+  Delay TUN/TAP open and possible ``--up`` script execution until after
+  TCP/UDP connection establishment with peer.
+
+  In ``--proto udp`` mode, this option normally requires the use of
+  ``--ping`` to allow connection initiation to be sensed in the absence of
+  tunnel data, since UDP is a "connectionless" protocol.
+
+  On Windows, this option will delay the TAP-Win32 media state
+  transitioning to "connected" until connection establishment, i.e. the
+  receipt of the first authenticated packet from the peer.
+
+--up-restart
+  Enable the ``--up`` and ``--down`` scripts to be called for restarts as
+  well as initial program start. This option is described more fully above
+  in the ``--up`` option documentation.
+
+String Types and Remapping
+--------------------------
+
+In certain cases, OpenVPN will perform remapping of characters in
+strings. Essentially, any characters outside the set of permitted
+characters for each string type will be converted to underbar ('\_').
+
+*Q: Why is string remapping necessary?*
+    It's an important security feature to prevent the malicious
+    coding of strings from untrusted sources to be passed as parameters to
+    scripts, saved in the environment, used as a common name, translated to
+    a filename, etc.
+
+*Q: Can string remapping be disabled?*
+    Yes, by using the ``--no-name-remapping`` option, however this
+    should be considered an advanced option.
+
+Here is a brief rundown of OpenVPN's current string types and the
+permitted character class for each string:
+
+*X509 Names*
+   Alphanumeric, underbar ('\_'), dash ('-'), dot ('.'), at
+   ('@'), colon (':'), slash ('/'), and equal ('='). Alphanumeric is
+   defined as a character which will cause the C library isalnum() function
+   to return true.
+
+*Common Names*
+   Alphanumeric, underbar ('\_'), dash ('-'), dot ('.'), and at ('@').
+
+*--auth-user-pass username*
+   Same as Common Name, with one exception:
+   starting with OpenVPN 2.0.1, the username is passed to the
+   :code:`OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY` plugin in its raw form,
+   without string remapping.
+
+*--auth-user-pass password*
+   Any "printable" character except CR or LF. Printable is defined to be
+   a character which will cause the C library isprint() function to
+   return true.
+
+*--client-config-dir filename as derived from common name or`username*
+   Alphanumeric, underbar ('\_'), dash ('-'), and dot ('.') except for "."
+   or ".." as standalone strings. As of v2.0.1-rc6, the at ('@') character
+   has been added as well for compatibility with the common name character
+   class.
+
+*Environmental variable names*
+   Alphanumeric or underbar ('\_').
+
+*Environmental variable values*
+   Any printable character.
+
+For all cases, characters in a string which are not members of the legal
+character class for that string type will be remapped to underbar
+('\_').  
+
+
+Environmental Variables
+-----------------------
+
+Once set, a variable is persisted indefinitely until it is reset by a
+new value or a restart,
+
+As of OpenVPN 2.0-beta12, in server mode, environmental variables set by
+OpenVPN are scoped according to the client objects they are associated
+with, so there should not be any issues with scripts having access to
+stale, previously set variables which refer to different client
+instances.
+
+:code:`bytes_received`
+    Total number of bytes received from client during VPN session. Set prior
+    to execution of the ``--client-disconnect`` script.
+
+:code:`bytes_sent`
+    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
+    ``--auth-user-pass-verify`` scripts.
+
+:code:`config`
+    Name of first ``--config`` file. Set on program initiation and reset on
+    SIGHUP.
+
+:code:`daemon`
+    Set to "1" if the ``--daemon`` directive is specified, or "0" otherwise.
+    Set on program initiation and reset on SIGHUP.
+
+:code:`daemon_log_redirect`
+    Set to "1" if the ``--log`` or ``--log-append`` directives are
+    specified, or "0" otherwise. Set on program initiation and reset on
+    SIGHUP.
+
+:code:`dev`
+    The actual name of the TUN/TAP device, including a unit number if it
+    exists. Set prior to ``--up`` or ``--down`` script execution.
+
+:code:`dev_idx`
+    On Windows, the device index of the TUN/TAP adapter (to be used in
+    netsh.exe calls which sometimes just do not work right with interface
+    names). Set prior to ``--up`` or ``--down`` script execution.
+
+:code:`foreign_option_{n}`
+    An option pushed via ``--push`` to a client which does not natively
+    support it, such as ``--dhcp-option`` on a non-Windows system, will be
+    recorded to this environmental variable sequence prior to ``--up``
+    script execution.
+
+:code:`ifconfig_broadcast`
+    The broadcast address for the virtual ethernet segment which is derived
+    from the ``--ifconfig`` option when ``--dev tap`` is used. Set prior to
+    OpenVPN calling the :code:`ifconfig` or :code:`netsh` (windows version
+    of ifconfig) commands which normally occurs prior to ``--up`` script
+    execution.
+
+:code:`ifconfig_ipv6_local`
+    The local VPN endpoint IPv6 address specified in the
+    ``--ifconfig-ipv6`` option (first parameter). Set prior to OpenVPN
+    calling the :code:`ifconfig` or code:`netsh` (windows version of
+    ifconfig) commands which normally occurs prior to ``--up`` script
+    execution.
+
+:code:`ifconfig_ipv6_netbits`
+    The prefix length of the IPv6 network on the VPN interface. Derived
+    from the /nnn parameter of the IPv6 address in the ``--ifconfig-ipv6``
+    option (first parameter). Set prior to OpenVPN calling the
+    :code:`ifconfig` or :code:`netsh` (windows version of ifconfig)
+    commands which normally occurs prior to ``--up`` script execution.
+
+:code:`ifconfig_ipv6_remote`
+    The remote VPN endpoint IPv6 address specified in the
+    ``--ifconfig-ipv6`` option (second parameter). Set prior to OpenVPN
+    calling the :code:`ifconfig` or :code:`netsh` (windows version of
+    ifconfig) commands which normally occurs prior to ``--up`` script
+    execution.
+
+:code:`ifconfig_local`
+    The local VPN endpoint IP address specified in the ``--ifconfig``
+    option (first parameter). Set prior to OpenVPN calling the
+    :code:`ifconfig` or :code:`netsh` (windows version of ifconfig)
+    commands which normally occurs prior to ``--up`` script execution.
+
+:code:`ifconfig_remote`
+    The remote VPN endpoint IP address specified in the ``--ifconfig``
+    option (second parameter) when ``--dev tun`` is used. Set prior to
+    OpenVPN calling the :code:`ifconfig` or :code:`netsh` (windows version
+    of ifconfig) commands which normally occurs prior to ``--up`` script
+    execution.
+
+:code:`ifconfig_netmask`
+    The subnet mask of the virtual ethernet segment that is specified as
+    the second parameter to ``--ifconfig`` when ``--dev tap`` is being
+    used. Set prior to OpenVPN calling the :code:`ifconfig` or
+    :code:`netsh` (windows version of ifconfig) commands which normally
+    occurs prior to ``--up`` script execution.
+
+:code:`ifconfig_pool_local_ip`
+    The local virtual IP address for the TUN/TAP tunnel taken from an
+    ``--ifconfig-push`` directive if specified, or otherwise from the
+    ifconfig pool (controlled by the ``--ifconfig-pool`` config file
+    directive). Only set for ``--dev tun`` tunnels. This option is set on
+    the server prior to execution of the ``--client-connect`` and
+    ``--client-disconnect`` scripts.
+
+:code:`ifconfig_pool_netmask`
+    The virtual IP netmask for the TUN/TAP tunnel taken from an
+    ``--ifconfig-push`` directive if specified, or otherwise from the
+    ifconfig pool (controlled by the ``--ifconfig-pool`` config file
+    directive). Only set for ``--dev tap`` tunnels. This option is set on
+    the server prior to execution of the ``--client-connect`` and
+    ``--client-disconnect`` scripts.
+
+:code:`ifconfig_pool_remote_ip`
+    The remote virtual IP address for the TUN/TAP tunnel taken from an
+    ``--ifconfig-push`` directive if specified, or otherwise from the
+    ifconfig pool (controlled by the ``--ifconfig-pool`` config file
+    directive). This option is set on the server prior to execution of the
+    ``--client-connect`` and ``--client-disconnect`` scripts.
+
+:code:`link_mtu`
+    The maximum packet size (not including the IP header) of tunnel data in
+    UDP tunnel transport mode. Set prior to ``--up`` or ``--down`` script
+    execution.
+
+:code:`local`
+    The ``--local`` parameter. Set on program initiation and reset on
+    SIGHUP.
+
+:code:`local_port`
+    The local port number or name, specified by ``--port`` or ``--lport``.
+    Set on program initiation and reset on SIGHUP.
+
+:code:`password`
+    The password provided by a connecting client. Set prior to
+    ``--auth-user-pass-verify`` script execution only when the ``via-env``
+    modifier is specified, and deleted from the environment after the script
+    returns.
+
+:code:`proto`
+    The ``--proto`` parameter. Set on program initiation and reset on
+    SIGHUP.
+
+:code:`remote_{n}`
+    The ``--remote`` parameter. Set on program initiation and reset on
+    SIGHUP.
+
+:code:`remote_port_{n}`
+    The remote port number, specified by ``--port`` or ``--rport``. Set on
+    program initiation and reset on SIGHUP.
+
+:code:`route_net_gateway`
+    The pre-existing default IP gateway in the system routing table. Set
+    prior to ``--up`` script execution.
+
+:code:`route_vpn_gateway`
+    The default gateway used by ``--route`` options, as specified in either
+    the ``--route-gateway`` option or the second parameter to
+    ``--ifconfig`` when ``--dev tun`` is specified. Set prior to ``--up``
+    script execution.
+
+:code:`route_{parm}_{n}`
+    A set of variables which define each route to be added, and are set
+    prior to ``--up`` script execution.
+
+    ``parm`` will be one of :code:`network`, :code:`netmask"`,
+    :code:`gateway`, or :code:`metric`.
+
+    ``n`` is the OpenVPN route number, starting from 1.
+
+    If the network or gateway are resolvable DNS names, their IP address
+    translations will be recorded rather than their names as denoted on the
+    command line or configuration file.
+
+:code:`route_ipv6_{parm}_{n}`
+    A set of variables which define each IPv6 route to be added, and are
+    set prior to **--up** script execution.
+
+    ``parm`` will be one of :code:`network` or :code:`gateway`
+    (:code:`netmask` is contained as :code:`/nnn` in the
+    ``route_ipv6_network_{n}``, unlike IPv4 where it is passed in a
+    separate environment variable).
+
+    ``n`` is the OpenVPN route number, starting from 1.
+
+    If the network or gateway are resolvable DNS names, their IP address
+    translations will be recorded rather than their names as denoted on the
+    command line or configuration file.
+
+:code:`peer_cert`
+    Temporary file name containing the client certificate upon connection.
+    Useful in conjunction with ``--tls-verify``.
+
+:code:`script_context`
+    Set to "init" or "restart" prior to up/down script execution. For more
+    information, see documentation for ``--up``.
+
+:code:`script_type`
+    Prior to execution of any script, this variable is set to the type of
+    script being run. It can be one of the following: :code:`up`,
+    :code:`down`, :code:`ipchange`, :code:`route-up`, :code:`tls-verify`,
+    :code:`auth-user-pass-verify`, :code:`client-connect`,
+    :code:`client-disconnect` or :code:`learn-address`. Set prior to
+    execution of any script.
+
+:code:`signal`
+    The reason for exit or restart. Can be one of :code:`sigusr1`,
+    :code:`sighup`, :code:`sigterm`, :code:`sigint`, :code:`inactive`
+    (controlled by ``--inactive`` option), :code:`ping-exit` (controlled
+    by ``--ping-exit`` option), :code:`ping-restart` (controlled by
+    ``--ping-restart`` option), :code:`connection-reset` (triggered on TCP
+    connection reset), :code:`error` or :code:`unknown` (unknown signal).
+    This variable is set just prior to down script execution.
+
+:code:`time_ascii`
+    Client connection timestamp, formatted as a human-readable time string.
+    Set prior to execution of the ``--client-connect`` script.
+
+:code:`time_duration`
+    The duration (in seconds) of the client session which is now
+    disconnecting. Set prior to execution of the ``--client-disconnect``
+    script.
+
+:code:`time_unix`
+    Client connection timestamp, formatted as a unix integer date/time
+    value. Set prior to execution of the ``--client-connect`` script.
+
+:code:`tls_digest_{n}` / :code:`tls_digest_sha256_{n}`
+    Contains the certificate SHA1 / SHA256 fingerprint, where ``n`` is the
+    verification level. Only set for TLS connections. Set prior to execution
+    of ``--tls-verify`` script.
+
+:code:`tls_id_{n}`
+    A series of certificate fields from the remote peer, where ``n`` is the
+    verification level. Only set for TLS connections. Set prior to execution
+    of ``--tls-verify`` script.
+
+:code:`tls_serial_{n}`
+    The serial number of the certificate from the remote peer, where ``n``
+    is the verification level. Only set for TLS connections. Set prior to
+    execution of ``--tls-verify`` script. This is in the form of a decimal
+    string like "933971680", which is suitable for doing serial-based OCSP
+    queries (with OpenSSL, do not prepend "0x" to the string) If something
+    goes wrong while reading the value from the certificate it will be an
+    empty string, so your code should check that. See the
+    :code:`contrib/OCSP_check/OCSP_check.sh` script for an example.
+
+:code:`tls_serial_hex_{n}`
+    Like :code:`tls_serial_{n}`, but in hex form (e.g.
+    :code:`12:34:56:78:9A`).
+
+:code:`tun_mtu`
+    The MTU of the TUN/TAP device. Set prior to ``--up`` or ``--down``
+    script execution.
+
+:code:`trusted_ip` / :code:`trusted_ip6`)
+    Actual IP address of connecting client or peer which has been
+    authenticated. Set prior to execution of ``--ipchange``,
+    ``--client-connect`` and ``--client-disconnect`` scripts. If using ipv6
+    endpoints (udp6, tcp6), :code:`trusted_ip6` will be set instead.
+
+:code:`trusted_port`
+    Actual port number of connecting client or peer which has been
+    authenticated. Set prior to execution of ``--ipchange``,
+    ``--client-connect`` and ``--client-disconnect`` scripts.
+
+:code:`untrusted_ip` / :code:`untrusted_ip6`
+    Actual IP address of connecting client or peer which has not been
+    authenticated yet. Sometimes used to *nmap* the connecting host in a
+    ``--tls-verify`` script to ensure it is firewalled properly. Set prior
+    to execution of ``--tls-verify`` and ``--auth-user-pass-verify``
+    scripts. If using ipv6 endpoints (udp6, tcp6), :code:`untrusted_ip6`
+    will be set instead.
+
+:code:`untrusted_port`
+    Actual port number of connecting client or peer which has not been
+    authenticated yet. Set prior to execution of ``--tls-verify`` and
+    ``--auth-user-pass-verify`` scripts.
+
+:code:`username`
+    The username provided by a connecting client. Set prior to
+    ``--auth-user-pass-verify`` script execution only when the
+    :code:`via-env` modifier is specified.
+
+:code:`X509_{n}_{subject_field}`
+    An X509 subject field from the remote peer certificate, where ``n`` is
+    the verification level. Only set for TLS connections. Set prior to
+    execution of ``--tls-verify`` script. This variable is similar to
+    :code:`tls_id_{n}` except the component X509 subject fields are broken
+    out, and no string remapping occurs on these field values (except for
+    remapping of control characters to ":code:`_`"). For example, the
+    following variables would be set on the OpenVPN server using the sample
+    client certificate in sample-keys (client.crt). Note that the
+    verification level is 0 for the client certificate and 1 for the CA
+    certificate.
+
+    ::
+
+       X509_0_emailAddress=me@myhost.mydomain
+       X509_0_CN=Test-Client
+       X509_0_O=OpenVPN-TEST
+       X509_0_ST=NA
+       X509_0_C=KG
+       X509_1_emailAddress=me@myhost.mydomain
+       X509_1_O=OpenVPN-TEST
+       X509_1_L=BISHKEK
+       X509_1_ST=NA
+       X509_1_C=KG