Sign Up

OpenVPN 2.3 manual⁠

INTRODUCTION⁠

OpenVPN is an open-source VPN daemon by James Yonan. Because OpenVPN aims to be a universal VPN tool, offering a great deal of flexibility, this manual page presents numerous options. If you're new to OpenVPN, you might want to skip ahead to the examples section, where you will see how to construct simple VPNs on the command line without even needing a configuration file.

The OpenVPN website has more documentation and examples.

If you would like to see a shorter version of this manual, refer to the OpenVPN usage message, which can be obtained by running openvpn without any parameters.

DESCRIPTION⁠

OpenVPN is a robust and highly flexible VPN daemon. OpenVPN supports:

  • SSL/TLS security.

  • Ethernet bridging.

  • TCP or UDP tunnel transport through proxies or Network Address Translation (NAT).

  • Dynamic IP addresses and DHCP.

  • Scalability to hundreds or thousands of users.

  • Portability to most major OS platforms.

OpenVPN is tightly integrated with the OpenSSL library and derives many of its cryptographic capabilities from it.

OpenVPN supports conventional encryption using a pre-shared secret key (Static Key mode) or public key security (SSL/TLS mode) using client and server certificates. OpenVPN also supports non-encrypted TCP and UDP tunnels.

OpenVPN is designed to work with the TUN/TAP virtual networking interface, which is available on most platforms.

Overall, OpenVPN aims to offer many of the key features of IPSec but with a relatively lightweight footprint.

OPTIONS⁠

OpenVPN allows any option to be placed either on the command line or in a configuration file. Though all command line options are preceded by a double-leading-dash ("--"), this prefix can be removed when an option is placed in a configuration file.

--help

Show options.

--config file

Load additional config options from file where each line corresponds to one command line option, but with the leading '--' removed.If --config file is the only option to the openvpn command, the --config can be removed, and the command can be given as openvpn file Note that configuration files can be nested to a reasonable depth. Double quotation or single quotation characters ("", '') can be used to enclose single parameters containing whitespace, and "#" or ";" characters in the first column can be used to denote comments. Note that OpenVPN 2.0 and higher performs backslash-based shell escaping for characters not in single quotations, so the following mappings should be observed: \\ Maps to a single backslash character (\). \" Pass a literal doublequote character ("), don't interpret it as enclosing a parameter. \[SPACE] Pass a literal space or tab character, don't interpret it as a parameter delimiter. For example on Windows, use double backslashes to represent pathnames: secret "c:\\OpenVPN\\secret.key" For examples of configuration files, see https://www-dev.openvpn.in/community-resources/how-to/ Here is an example configuration file: # # Sample OpenVPN configuration file for # using a pre-shared static key. # # '#' or ';' may be used to delimit comments. # Use a dynamic tun device. dev tun # Our remote peer remote mypeer.mydomain # 10.1.0.1 is our local VPN endpoint # 10.1.0.2 is our remote VPN endpoint ifconfig 10.1.0.1 10.1.0.2 # Our pre-shared static key secret static.key

SCRIPTING AND ENVIRONMENTAL VARIABLES⁠

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

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-remappingoption, 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.

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 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 --upscript 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, orlearn-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}

Contains the certificate SHA1 fingerprint/digest hash value, 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 (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

EXAMPLES⁠

Prior to running these examples, you should have OpenVPN installed on two machines with network connectivity between them. If you haven't installed OpenVPN, consult the INSTALL file included in the OpenVPN distribution.

FIREWALLS⁠

OpenVPN's usage of a single UDP port makes it fairly firewall-friendly. You should add an entry to your firewall rules to allow incoming OpenVPN packets. On Linux 2.4+:

iptables -A INPUT -p udp -s 1.2.3.4 --dport 1194 -j ACCEPT

This will allow incoming packets on UDP port 1194 (OpenVPN's default UDP port) from an OpenVPN peer at 1.2.3.4.

If you are using HMAC-based packet authentication (the default in any of OpenVPN's secure modes), having the firewall filter on source address can be considered optional, since HMAC packet authentication is a much more secure method of verifying the authenticity of a packet source. In that case:

iptables -A INPUT -p udp --dport 1194 -j ACCEPT

would be adequate and would not render the host inflexible with respect to its peer having a dynamic IP address.

OpenVPN also works well on stateful firewalls. In some cases, you may not need to add any static rules to the firewall list if you are using a stateful firewall that knows how to track UDP connections. If you specify --ping n, OpenVPN will be guaranteed to send a packet to its peer at least once every n seconds. If n is less than the stateful firewall connection timeout, you can maintain an OpenVPN connection indefinitely without explicit firewall rules.

You should also add firewall rules to allow incoming IP traffic on TUN or TAP devices such as:

iptables -A INPUT -i tun+ -j ACCEPT

to allow input packets from tun devices,

iptables -A FORWARD -i tun+ -j ACCEPT

to allow input packets from tun devices to be forwarded to other hosts on the local network,

iptables -A INPUT -i tap+ -j ACCEPT

to allow input packets from tap devices, and

iptables -A FORWARD -i tap+ -j ACCEPT

to allow input packets from tap devices to be forwarded to other hosts on the local network.

These rules are secure if you use packet authentication, since no incoming packets will arrive on a TUN or TAP virtual device unless they first pass an HMAC authentication test.

FAQ⁠

https://community.openvpn.net/FAQ

HOWTO⁠

For a more comprehensive guide to setting up OpenVPN in a production setting, see the OpenVPN HOWTO.

PROTOCOL⁠

For a description of OpenVPN's underlying protocol, refer to OpenVPN Protocol.

WEB⁠

Refer to OpenVPN's website to download the latest version of OpenVPN, subscribe to the mailing lists, read the mailing list archives, or browse the Git repository.

BUGS⁠

Report all bugs to the OpenVPN team info@openvpn.net.

SEE ALSO⁠

dhcpcd, ifconfig, openssl, route, scp, ssh

NOTES⁠

This product includes software developed by the OpenSSL Project .

For more information on the TLS protocol, see http://www.ietf.org/rfc/rfc2246.txt.

For more information on the LZO real-time compression library see http://www.oberhumer.com/opensource/lzo/.

AUTHORS⁠

James Yonan <jim@yonan.net>

Can't find what you're looking for?

Our support team will be happy to assist you.

Contact Support

© 2026 OpenVPN Inc. | OpenVPN is a registered trademark of OpenVPN, Inc. | CloudConnexa is a registered trademark of OpenVPN, Inc.

Service StatusPrivacy PolicyLegal