summaryrefslogtreecommitdiff
path: root/doc/man-sections/script-options.rst
diff options
context:
space:
mode:
authorBernhard Schmidt <berni@debian.org>2020-09-01 16:52:17 +0200
committerBernhard Schmidt <berni@debian.org>2020-09-01 16:52:17 +0200
commit9fc3b98112217f2d92a67977dbde0987cc7a1803 (patch)
tree29fcc8654ee65d9dd89ade797bea2f3d9dfd9cfd /doc/man-sections/script-options.rst
parenta8758c0e03eed188dcb9da0e4fd781a67c25bf1e (diff)
parent69b02b1f7fd609d84ace13ab04697158de2418a9 (diff)
Merge branch 'debian/experimental-2.5'
Diffstat (limited to 'doc/man-sections/script-options.rst')
-rw-r--r--doc/man-sections/script-options.rst842
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