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