diff options
Diffstat (limited to 'doc/man-sections/script-options.rst')
| -rw-r--r-- | doc/man-sections/script-options.rst | 842 |
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 |