Сети‎ > ‎VPN‎ > ‎Параметры OpenVPN‎ > ‎

SCRIPTING

SCRIPTING AND ENVIRONMENTAL VARIABLES

OpenVPN exports a series of environmental variables for use by user-defined scripts.  

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.

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?

A: 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?

A: 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 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 2.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.

bytes_received
Total number of bytes received from client during VPN session. Set prior to execution of the --client-disconnect script.
bytes_sent
Total number of bytes sent to client during VPN session. Set prior to execution of the --client-disconnect script.
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.
config
Name of first --config file. Set on program initiation and reset on SIGHUP.
daemon
Set to "1" if the --daemon directive is specified, or "0" otherwise. Set on program initiation and reset on SIGHUP.
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.
dev
The actual name of the TUN/TAP device, including a unit number if it exists. Set prior to --up or --down script execution.
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.
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 ifconfig or netsh (windows version of ifconfig) commands which normally occurs prior to --up script execution.
ifconfig_ipv6_local
The local VPN endpoint IPv6 address specified in the --ifconfig-ipv6 option (first parameter). Set prior to OpenVPN calling the ifconfig or netsh (windows version of ifconfig) commands which normally occurs prior to --up script execution.
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 ifconfig or netsh (windows version of ifconfig) commands which normally occurs prior to --up script execution.
ifconfig_ipv6_remote
The remote VPN endpoint IPv6 address specified in the --ifconfig-ipv6 option (second parameter). Set prior to OpenVPN calling the ifconfig or netsh (windows version of ifconfig) commands which normally occurs prior to --up script execution.
ifconfig_local
The local VPN endpoint IP address specified in the --ifconfig option (first parameter). Set prior to OpenVPN calling the ifconfig or netsh (windows version of ifconfig) commands which normally occurs prior to --up script execution.
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 ifconfig or netsh (windows version of ifconfig) commands which normally occurs prior to --up script execution.
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 ifconfig or netsh (windows version of ifconfig) commands which normally occurs prior to --up script execution.
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.
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.
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.
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.
local
The --local parameter. Set on program initiation and reset on SIGHUP.
local_port
The local port number, specified by --port or --lport. Set on program initiation and reset on SIGHUP.
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.
proto
The --proto parameter. Set on program initiation and reset on SIGHUP.
remote_{n}
The --remote parameter. Set on program initiation and reset on SIGHUP.
remote_port_{n}
The remote port number, specified by --port or --rport. Set on program initiation and reset on SIGHUP.
route_net_gateway
The pre-existing default IP gateway in the system routing table. Set prior to --up script execution.
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.
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 "network", "netmask", "gateway", or "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.

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 "network" or "gateway" ("netmask" is contained as "/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.

peer_cert
Temporary file name containing the client certificate upon connection. Useful in conjunction with --tls-verify
script_context
Set to "init" or "restart" prior to up/down script execution. For more information, see documentation for --up.
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: up, down, ipchange, route-up, tls-verify, auth-user-pass-verify, client-connect, client-disconnect, or learn-address. Set prior to execution of any script.
signal
The reason for exit or restart. Can be one of sigusr1, sighup, sigterm, sigint, inactive (controlled by --inactive option), ping-exit (controlled by --ping-exit option), ping-restart (controlled by --ping-restart option), connection-reset (triggered on TCP connection reset), error, or unknown (unknown signal). This variable is set just prior to down script execution.
time_ascii
Client connection timestamp, formatted as a human-readable time string. Set prior to execution of the --client-connect script.
time_duration
The duration (in seconds) of the client session which is now disconnecting. Set prior to execution of the --client-disconnect script.
time_unix
Client connection timestamp, formatted as a unix integer date/time value. Set prior to execution of the --client-connect script.
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.
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 hex string like "37AB46E0", which is suitable for doing serial-based OCSP queries (with OpenSSL, you have to 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 contrib/OCSP_check/OCSP_check.sh script for an example.
tun_mtu
The MTU of the TUN/TAP device. Set prior to --up or --down script execution.
trusted_ip (or 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), trusted_ip6 will be set instead.
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.
untrusted_ip (or 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), untrusted_ip6 will be set instead.
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.
username
The username provided by a connecting client. Set prior to --auth-user-pass-verify script execution only when the via-env modifier is specified.
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 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 "_"). 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

INLINE FILE SUPPORT

OpenVPN allows including files in the main configuration for the --ca, --cert, --dh, --extra-certs, --key, --pkcs12, --secret and --tls-auth options.

Each inline file started by the line <option> and ended by the line </option>

Here is an example of an inline file usage

<cert>
-----BEGIN CERTIFICATE-----
[...]
-----END CERTIFICATE-----
</cert>

When using the inline file feature with --pkcs12 the inline file has to be base64 encoded. Encoding of a .p12 file into base64 can be done for example with OpenSSL by running openssl base64 -in input.p12

Comments