neulab/tldr huggingface dataset:
--route-ipv6-gateway gw Specify a default gateway gw for use with --route-ipv6.
--route-metric m Specify a default metric m for use with --route.
--route-noexec Don't add or remove routes automatically. Instead pass routes to --route-up script using environmental variables.
--route-nopull When used with --client or --pull, accept options pushed by server EXCEPT for routes, block-outside-dns and dhcp options like DNS servers.
When used on the client, this option effectively bars the server from adding routes to the client's routing table, however note that this option still allows the server to set the TCP/IP properties of the client's TUN/TAP interface.
--topology mode Configure virtual addressing topology when running in --dev tun mode. This directive has no meaning in --dev tap mode, which always uses a subnet topology.
If you set this directive on the server, the --server and --server-bridge directives will automatically push your chosen topology setting to clients as well. This directive can also be manually pushed to clients. Like the --dev directive, this directive must always be compatible between client and server.
mode can be one of:
net30  Use a point-to-point topology, by allocating one /30 subnet per client. This is designed to allow point-to-point semantics when some or all of the connecting clients might be Windows systems. This is the default on OpenVPN 2.0.
p2p    Use a point-to-point topology where the remote endpoint of the client's tun interface always points to the local endpoint of the server's tun interface. This mode allocates a single IP address per connecting client. Only use when none of the connecting clients are Windows systems.
subnet Use a subnet rather than a point-to-point topology by configuring the tun interface with a local IP address and subnet mask, similar to the topology used in --dev tap and ethernet bridging mode. This mode allocates a single IP address per connecting client and works on Windows as well. Only available when server and clients are OpenVPN 2.1 or higher, or OpenVPN 2.0.x which has been manually patched with the --topology directive code. When used on Windows, requires version 8.2 or higher of the TAP-Win32 driver. When used on *nix, requires that the tun driver supports an ifconfig(8) command which sets a subnet instead of a remote endpoint IP address.
Note: Using --topology subnet changes the interpretation of the arguments of --ifconfig to mean "address netmask", no longer "local remote".
--tun-mtu n Take the TUN device MTU to be n and derive the link MTU from it (default 1500). In most cases, you will probably want to leave this parameter set to its default value.
The MTU (Maximum Transmission Units) is the maximum datagram size in bytes that can be sent unfragmented over a particular network path.  OpenVPN requires that packets on the control and data channels be sent unfragmented.
MTU problems often manifest themselves as connections which hang during periods of active usage.
It's best to use the --fragment and/or --mssfix options to deal with MTU sizing issues.
--tun-mtu-extra n Assume that the TUN/TAP device might return as many as n bytes more than the --tun-mtu size on read. This parameter defaults to 0, which is sufficient for most TUN devices. TAP devices may introduce additional overhead in excess of the MTU size, and a setting of 32 is the default when TAP devices are used. This parameter only controls internal OpenVPN buffer sizing, so there is no transmission overhead associated with using a larger value.
TUN/TAP standalone operations These two standalone operations will require --dev and optionally --user and/or --group.
--mktun (Standalone) Create a persistent tunnel on platforms which support them such as Linux. Normally TUN/TAP tunnels exist only for the period of time that an application has them open. This option takes advantage of the TUN/TAP driver's ability to build persistent tunnels that live through multiple instantiations of OpenVPN and die only when they are deleted or the machine is rebooted.
One of the advantages of persistent tunnels is that they eliminate the need for separate --up and --down scripts to run the appropriate ifconfig(8) and route(8) commands. These commands can be placed in the the same shell script which starts or terminates an OpenVPN session.
Another advantage is that open connections through the TUN/TAP-based tunnel will not be reset if the OpenVPN peer restarts. This can be useful to provide uninterrupted connectivity through the tunnel in the event of a DHCP reset of the peer's public IP address (see the --ipchange option above).
One disadvantage of persistent tunnels is that it is harder to automatically configure their MTU value (see --link-mtu and --tun-mtu above).
On some platforms such as Windows, TAP-Win32 tunnels are persistent by default.
--rmtun (Standalone) Remove a persistent tunnel.
Virtual Routing and Forwarding Options in this section relates to configuration of virtual routing and forwarding in combination with the underlying operating system.
As of today this is only supported on Linux, a kernel >= 4.9 is recommended.
This could come in handy when for example the external network should be only used as a means to connect to some VPN endpoints and all regular traffic should only be routed through any tunnel(s).  This could be achieved by setting up a VRF and configuring the interface connected to the external network to be part of the VRF. The examples below will cover this setup.
Another option would be to put the tun/tap interface into a VRF. This could be done by an up-script which uses the ip link set command shown below.
VRF setup with iproute2 Create VRF vrf_external and map it to routing table 1023
ip link add vrf_external type vrf table 1023
Move eth0 into vrf_external
ip link set master vrf_external dev eth0
Any prefixes configured on eth0 will be moved from the :code`main` routing table into routing table 1023
VRF setup with ifupdown For Debian based Distributions ifupdown2 provides an almost drop-in replacement for ifupdown including VRFs and other features.  A configuration for an interface eth0 being part of VRF code:vrf_external could look like this:
auto eth0 iface eth0 address 192.0.2.42/24 address 2001:db8:08:15::42/64 gateway 192.0.2.1 gateway 2001:db8:08:15::1 vrf vrf_external
auto vrf_external iface vrf_external vrf-table 1023
OpenVPN configuration The OpenVPN configuration needs to contain this line:
bind-dev vrf_external
Further reading Wikipedia has nice page one VRFs: https://en.wikipedia.org/wiki/Virtual_routing_and_forwarding
This talk from the Network Track of FrOSCon 2018 provides an overview about advanced layer 2 and layer 3 features of Linux
• Slides: https://www.slideshare.net/BarbarossaTM/l2l3-fr-fortgeschrittene-helle-und-dunkle-magie-im-linuxnetzwerkstack
• Video (german): https://media.ccc.de/v/froscon2018-2247-l2_l3_fur_fortgeschrittene_-_helle_und_dunkle_magie_im_linux-netzwerkstack
OpenVPN can execute external scripts in various phases of the lifetime of the OpenVPN process.
Script Order of Execution 1.  --up
Executed after TCP/UDP socket bind and TUN/TAP open.
2.  --tls-verify
Executed when we have a still untrusted remote peer.
3.  --ipchange
Executed after connection authentication, or remote IP address change.
4.  --client-connect
Executed in --mode server mode immediately after client authentication.
5.  --route-up
Executed after connection authentication, either immediately after, or some number of seconds after as defined by the --route-delay option.
6.  --route-pre-down
Executed right before the routes are removed.
7.  --client-disconnect
Executed in --mode server mode on client instance shutdown.
8.  --down
Executed after TCP/UDP and TUN/TAP close.
9.  --learn-address
Executed in --mode server mode whenever an IPv4 address/route or MAC address is added to OpenVPN's internal routing table.
10. --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.
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 via-env, OpenVPN will call script with the environmental variables username and 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 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 /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 (0) if the client's authentication request is to be accepted, or a failure 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 ('_'), dash ('-'), dot ('.'), or at ('@'). 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 ('_').
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 sample-scripts/auth-pam.pl in the OpenVPN source distribution.
--client-connect cmd Run command cmd on client connection.
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 client_connect_deferred_file and 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 not passed any extra arguments (only those arguments specified in cmd, if any).
--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.
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 /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.
Three arguments will be appended to any arguments in cmd as follows:
$1 - [operation] "add", "update", or "delete" based on whether or not the address is being added to, modified, or deleted from OpenVPN's internal routing table.
$2 - [address] The address being learned or unlearned. This can be an IPv4 address such as "198.162.10.14", an IPv4 subnet such as "198.162.10.0/24", or an ethernet MAC address (when --dev tap is being used) such as "00:FF:01:02:03:04".
$3 - [common name] The common name on the certificate associated with the client linked to this address. Only present for "add" or "update" operations, not "delete".
On "add" or "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.
--route-pre-down cmd Run command cmd before routes are removed upon disconnection.
--setenv args Set a custom environmental variable name=value to pass to script.
setenv name value setenv FORWARD_COMPATIBLE 1 setenv opt config_option
By setting FORWARD_COMPATIBLE to 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.
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 OPENVPN_name to value to pass to scripts.
setenv-safe name value
This directive is designed to be pushed by the server to clients, and the prepending of OPENVPN_ to the environmental variable is a safety precaution to prevent a 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 0 to allow the TLS handshake to proceed, or 1 to fail.
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.
--up cmd Run command cmd after successful TUN/TAP device open (pre --user UID change).
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]
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 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.
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.
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.
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 1 to indicate normal script execution, 0 indicates an error (in the same way that a non zero exit status does) or 2 to indicate that the script deferred returning the config file.
For deferred (background) handling, the script or plugin MUST write 2 to the file to indicate the deferral and then return with exit 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 client_connect_config_file environment variable and when finished, write the a 1 to this file (or 0 in case of an error).
The absence of any character in the file when the script finishes executing is interpreted the same as 1. This allows scripts that are not written to support the defer mechanism to be used unmodified.
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.
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.
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 code: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 or name, 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, gateway or metric. route_ipv6_network_{n} contains netmask as /nnn, unlike IPv4 where it is passed in a separate environment variable.
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_digest_{n} / 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.
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 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 contrib/OCSP_check/OCSP_check.sh script for an example.
tls_serial_hex_{n} Like tls_serial_{n}, but in hex form (e.g.  12:34:56:78:9A).
tun_mtu The MTU of the TUN/TAP device. Set prior to --up or --down script execution.
trusted_ip / 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 / 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
Management Interface Options OpenVPN provides a feature rich socket based management interface for both server and client mode operations.
--management args Enable a management server on a socket-name Unix socket on those platforms supporting it, or on a designated TCP port.
management socket-name unix          # management socket-name unix pw-file  # (recommended) management IP port                   # (INSECURE) management IP port pw-file           #
pw-file, if specified, is a password file where the password must be on first line. Instead of a filename it can use the keyword stdin which will prompt the user for a password to use when OpenVPN is starting.
For unix sockets, the default behaviour is to create a unix domain socket that may be connected to by any process. Use the --management-client-user and --management-client-group directives to restrict access.
The management interface provides a special mode where the TCP management link can operate over the tunnel itself. To enable this mode, set IP to tunnel. Tunnel mode will cause the management interface to listen for a TCP connection on the local VPN address of the TUN/TAP interface.
*BEWARE* of enabling the management interface over TCP. In these cases you should ALWAYS make use of pw-file to password protect the management interface. Any user who can connect to this TCP IP:port will be able to manage and control (and interfere with) the OpenVPN process. It is also strongly recommended to set IP to 127.0.0.1 (localhost) to restrict accessibility of the management server to local clients.
While the management port is designed for programmatic control of OpenVPN by other applications, it is possible to telnet to the port, using a telnet client in "raw" mode. Once connected, type help for a list of commands.
For detailed documentation on the management interface, see the management-notes.txt file in the management folder of the OpenVPN source distribution.
--management-client Management interface will connect as a TCP/unix domain client to IP:port specified by --management rather than listen as a TCP server or on a unix domain socket.
If the client connection fails to connect or is disconnected, a SIGTERM signal will be generated causing OpenVPN to quit.
--management-client-auth Gives management interface client the responsibility to authenticate clients after their client certificate has been verified. See management-notes.txt in OpenVPN distribution for detailed notes.
--management-client-group g When the management interface is listening on a unix domain socket, only allow connections from group g.
--management-client-pf Management interface clients must specify a packet filter file for each connecting client. See management-notes.txt in OpenVPN distribution for detailed notes.
--management-client-user u When the management interface is listening on a unix domain socket, only allow connections from user u.
--management-external-cert certificate-hint Allows usage for external certificate instead of --cert option (client-only). certificate-hint is an arbitrary string which is passed to a management interface client as an argument of NEED-CERTIFICATE notification. Requires --management-external-key.
--management-external-key args Allows usage for external private key file instead of --key option (client-only).
management-external-key management-external-key nopadding management-external-key pkcs1 management-external-key nopadding pkcs1
The optional parameters nopadding and pkcs1 signal support for different padding algorithms. See doc/mangement-notes.txt for a complete description of this feature.
--management-forget-disconnect Make OpenVPN forget passwords when management session disconnects.
--management-hold Start OpenVPN in a hibernating state, until a client of the management interface explicitly starts it with the hold release command.
--management-log-cache n Cache the most recent n lines of log file history for usage by the management channel.
--management-query-passwords Query management channel for private key password and --auth-user-pass username/password. Only query the management channel for inputs which ordinarily would have been queried from the console.
--management-query-proxy Query management channel for proxy server information for a specific --remote (client-only).
--management-query-remote Allow management interface to override --remote directives (client-only).
--management-signal Send SIGUSR1 signal to OpenVPN if management session disconnects. This is useful when you wish to disconnect an OpenVPN session on user logoff.  For --management-client this option is not needed since a disconnect will always generate a SIGTERM.
--management-up-down Report tunnel up/down events to management interface.
Plug-in Interface Options OpenVPN can be extended by loading external plug-in modules at runtime. These plug-ins must be prebuilt and adhere to the OpenVPN Plug-In API.
--plugin args Loads an OpenVPN plug-in module.
plugin module-name plugin module-name "arguments"
The module-name needs to be the first argument, indicating the plug-in to load.  The second argument is an optional init string which will be passed directly to the plug-in.  If the init consists of multiple arguments it must be enclosed in double-quotes (").  Multiple plugin modules may be loaded into one OpenVPN process.
The module-name argument can be just a filename or a filename with a relative or absolute path. The format of the filename and path defines if the plug-in will be loaded from a default plug-in directory or outside this directory.
--plugin path         Effective directory used ===================== ============================= myplug.so            DEFAULT_DIR/myplug.so subdir/myplug.so     DEFAULT_DIR/subdir/myplug.so ./subdir/myplug.so   CWD/subdir/myplug.so /usr/lib/my/plug.so  /usr/lib/my/plug.so
DEFAULT_DIR is replaced by the default plug-in directory, which is configured at the build time of OpenVPN. CWD is the current directory where OpenVPN was started or the directory OpenVPN have switched into via the --cd option before the --plugin option.
For more information and examples on how to build OpenVPN plug-in modules, see the README file in the plugin folder of the OpenVPN source distribution.
If you are using an RPM install of OpenVPN, see /usr/share/openvpn/plugin. The documentation is in doc and the actual plugin modules are in lib.
Multiple plugin modules can be cascaded, and modules can be used in tandem with scripts. The modules will be called by OpenVPN in the order that they are declared in the config file. If both a plugin and script are configured for the same callback, the script will be called last. If the return code of the module/script controls an authentication function (such as tls-verify, auth-user-pass-verify, or client-connect), then every module and script must return success (0) in order for the connection to be authenticated.
Windows-Specific Options --allow-nonadmin TAP-adapter (Standalone) Set TAP-adapter to allow access from non-administrative accounts. If TAP-adapter is omitted, all TAP adapters on the system will be configured to allow non-admin access. The non-admin access setting will only persist for the length of time that the TAP-Win32 device object and driver remain loaded, and will need to be re-enabled after a reboot, or if the driver is unloaded and reloaded. This directive can only be used by an administrator.
--block-outside-dns Block DNS servers on other network adapters to prevent DNS leaks. This option prevents any application from accessing TCP or UDP port 53 except one inside the tunnel. It uses Windows Filtering Platform (WFP) and works on Windows Vista or later.
This option is considered unknown on non-Windows platforms and unsupported on Windows XP, resulting in fatal error. You may want to use --setenv opt or --ignore-unknown-option (not suitable for Windows XP) to ignore said error. Note that pushing unknown options from server does not trigger fatal errors.
--cryptoapicert select-string (Windows/OpenSSL Only) Load the certificate and private key from the Windows Certificate System Store.
Use this option instead of --cert and --key.
This makes it possible to use any smart card, supported by Windows, but also any kind of certificate, residing in the Cert Store, where you have access to the private key. This option has been tested with a couple of different smart cards (GemSAFE, Cryptoflex, and Swedish Post Office eID) on the client side, and also an imported PKCS12 software certificate on the server side.
To select a certificate, based on a substring search in the certificate's subject:
cryptoapicert "SUBJ:Peter Runestig"
To select a certificate, based on certificate's thumbprint:
cryptoapicert "THUMB:f6 49 24 41 01 b4 ..."
The thumbprint hex string can easily be copy-and-pasted from the Windows Certificate Store GUI.
--dhcp-release Ask Windows to release the TAP adapter lease on shutdown. This option has no effect now, as it is enabled by default starting with OpenVPN 2.4.1.
--dhcp-renew Ask Windows to renew the TAP adapter lease on startup. This option is normally unnecessary, as Windows automatically triggers a DHCP renegotiation on the TAP adapter when it comes up, however if you set the TAP-Win32 adapter Media Status property to "Always Connected", you may need this flag.
--ip-win32 method When using --ifconfig on Windows, set the TAP-Win32 adapter IP address and netmask using method. Don't use this option unless you are also using --ifconfig.
manual Don't set the IP address or netmask automatically. Instead output a message to the console telling the user to configure the adapter manually and indicating the IP/netmask which OpenVPN expects the adapter to be set to.
dynamic [offset] [lease-time] Automatically set the IP address and netmask by replying to DHCP query messages generated by the kernel.  This mode is probably the "cleanest" solution for setting the TCP/IP properties since it uses the well-known DHCP protocol. There are, however, two prerequisites for using this mode:
1. The TCP/IP properties for the TAP-Win32 adapter must be set to "Obtain an IP address automatically", and
2. OpenVPN needs to claim an IP address in the subnet for use as the virtual DHCP server address.
By default in --dev tap mode, OpenVPN will take the normally unused first address in the subnet. For example, if your subnet is 192.168.4.0 netmask 255.255.255.0, then OpenVPN will take the IP address 192.168.4.0 to use as the virtual DHCP server address.  In --dev tun mode, OpenVPN will cause the DHCP server to masquerade as if it were coming from the remote endpoint.
The optional offset parameter is an integer which is > -256 and < 256 and which defaults to -1. If offset is positive, the DHCP server will masquerade as the IP address at network address + offset. If offset is negative, the DHCP server will masquerade as the IP address at broadcast address + offset.
The Windows ipconfig /all command can be used to show what Windows thinks the DHCP server address is. OpenVPN will "claim" this address, so make sure to use a free address. Having said that, different OpenVPN instantiations, including different ends of the same connection, can share the same virtual DHCP server address.
The lease-time parameter controls the lease time of the DHCP assignment given to the TAP-Win32 adapter, and is denoted in seconds. Normally a very long lease time is preferred because it prevents routes involving the TAP-Win32 adapter from being lost when the system goes to sleep. The default lease time is one year.
netsh  Automatically set the IP address and netmask using the Windows command-line "netsh" command. This method appears to work correctly on Windows XP but not Windows 2000.
ipapi  Automatically set the IP address and netmask using the Windows IP Helper API. This approach does not have ideal semantics, though testing has indicated that it works okay in practice. If you use this option, it is best to leave the TCP/IP properties for the TAP-Win32 adapter in their default state, i.e. "Obtain an IP address automatically."
adaptive (Default) Try dynamic method initially and fail over to netsh if the DHCP negotiation with the TAP-Win32 adapter does not succeed in 20 seconds. Such failures have been known to occur when certain third-party firewall packages installed on the client machine block the DHCP negotiation used by the TAP-Win32 adapter. Note that if the netsh failover occurs, the TAP-Win32 adapter TCP/IP properties will be reset from DHCP to static, and this will cause future OpenVPN startups using the adaptive mode to use netsh immediately, rather than trying dynamic first.
To "unstick" the adaptive mode from using netsh, run OpenVPN at least once using the dynamic mode to restore the TAP-Win32 adapter TCP/IP properties to a DHCP configuration.
--pause-exit Put up a "press any key to continue" message on the console prior to OpenVPN program exit. This option is automatically used by the Windows explorer when OpenVPN is run on a configuration file using the right-click explorer menu.
--register-dns Run ipconfig /flushdns and ipconfig /registerdns on connection initiation. This is known to kick Windows into recognizing pushed DNS servers.
--route-method m Which method m to use for adding routes on Windows?
adaptive (default) Try IP helper API first. If that fails, fall back to the route.exe shell command.
ipapi  Use IP helper API.
exe    Call the route.exe shell command.
--service args Should be used when OpenVPN is being automatically executed by another program in such a context that no interaction with the user via display or keyboard is possible.
service exit-event [0|1]