How to use openvpn

Access Server Video Tutorials

Launch Access Server in minutes and start using your two free VPN connections today. Our video tutorials will walk you through the installation steps and optional configurations. Hit play and get your server up and running.

Launch OpenVPN Access Server in Just 3 Minutes

Our IT Operations Engineer Justin Leber shows you how in this simple step-by-step tutorial

Installing a valid web certificate

Provide a valid web certificate for your Access Server Admin and Client Portals

Securing OpenVPN Access Server

Learn how to secure the root user account, OpenVPN administrative account and harden web server cipher suite string

Authentication

Learn Local Database authentication and how to use Google Authenticator for Multi-Factor Authentication

Remote User Connection

Connect Your Two Free VPN Connections with Google Authenticator MFA

Introduction to OpenVPN Access Server Logs

Querying and utilizing Access Server Logs: your final step

OpenVPN’s award-winning open source VPN protocol has emerged to establish itself as a de-facto standard in the open source networking space with over 50 million downloads since inception. OpenVPN is the leading provider of next-generation secure and scalable communication services. Our products address the market demands for secure remote access, access control, and cybersecurity for businesses of all sizes around the world.

OpenVPN’s enterprise solution Access Server secures your data communications, provides Internet privacy, remote access for employees, secures IoT, and networking Cloud data centers.

What is OpenVPN & How to Use It?

OpenVPN is a popular SSL-based tunneling protocol used in the implementation of virtual private networks. Offering the perfect combination of security, speed, and compatibility, it is one of the best VPN protocols out there.

What is OpenVPN?

Unlike other IPSec-based tunneling protocols, OpenVPN relies on SSL/TLS for authentication and encryption. It is the standard security technology to create secure, remote site-to-site or point-to-point connections. SSL is widely used for protecting financial transactions, data transfers, email, and more.

OpenVPN is compatible with most major and lesser-known operating systems in use today. It provides powerful encryption standards and is excellent when it comes to circumventing restrictive firewalls and prohibitive geo-blocking. The open-source VPN protocol can be configured to use either TCP or UDP and supports up to 256-bit encryption. Since it is open-source, security vulnerabilities are usually fixed by the open-source community as soon as they are found. OpenVPN is often used due to the various benefits it brings to the table. For starters, unlike other protocols, it is compatible with Android and iOS. It also can bypass any blockade that it encounters. Also, it can access many ports for communication.

OpenVPN – A Brief History about its Programmer

Initially released in 2001, the OpenVPN Project was programmed by James Yonan. He had a background in financial trading as well as software development for the original IBM Personal Computer. Yonan is still involved with the OpenVPN Project and serves as the CTO.

OpenVPN – One of the Few Open-Source Protocols

Unlike most other VPN protocols, one of the best things about OpenVPN is its open-source nature. It can be checked, modified, and updated by anybody. The entire source code for the latest and older versions of OpenVPN is available to all on its site.

Furthermore, users are encourage to submit bug reports so that developers can continually make improvements to the source code and release regular updates. This ensures any issues are identified and fixed quickly.

How Does OpenVPN Work?

To put it simply, OpenVPN establishes a private connection – or tunnel – between your VPN client and the VPN server. The traffic passing through it is fully protected with encryption, keeping your data safe from ISPs, hackers, and other third-parties.

Data packets are encrypted by the OpenVPN client before they leave your device or computer. These are received by the OpenVPN server, which uses a secret cryptographic key for decryption. The decrypted data packets are sent to the intended web server like Disney+, for example. Upon receiving them, the web server sends your requested data to the OpenVPN server, where it is encrypted once again. The data is then sent back to your device or computer running the OpenVPN client, which decrypts it.

What is UDP?

UDP is the acronym for User Datagram Protocol and does not perform error correction. As a result, the packets are received without any retries or acknowledgments. This makes UDP faster but less reliable than TCP.

What is TCP?

TCP is the acronym for Transmission Control Protocol. Unlike UDP, TCP performs error correction. Additionally, its re-transmission mechanism ensures both ends can receive packets. However, the increased reliability results in increased latency.

Key Features of OpenVPN

Full Anonymity

OpenVPN has support for DHCP and dynamic IP addresses, which can result in better anonymity as you browse the Internet.

Fast Speed

The TCP tunnel transport support on the OpenVPN protocol offers you many benefits. It includes seamless online gaming, video conferencing, audio conferencing, & more.

High Security

All your communications are kept secure by various methods, such as shared keys, HMAC authentication, and 256-bit encryption via OpenSSL.

Authentication

OpenVPN has several methods to authenticate peers to one another, including pre-shared keys, username/password-based, and certificate-based authentication.

Extensibility

OpenVPN supports third-party plugins and scripts, allowing you to extend its functionality with enhanced authentication, RADIUS integration, and more.

Beats Firewalls

OpenVPN can run on any port between 1 and 65535. This multi-port functionality makes OpenVPN an ideal tunneling protocol for bypassing firewalls.

Pros of OpenVPN

Here are some advantages of using OpenVPN:

Very Secure

If you want to safeguard your data from interested entities, OpenVPN is a highly recommended protocol. It uses high-end ciphers and 256-bit encryption, making it close to impossible for cybercriminals to intercept or steal your information via man-in-the-middle attacks.

Cross-Platform Compatibility

One of the best things about OpenVPN is that it can be installed and used on all popular desktop and mobile platforms, such as Mac, iOS, Android, and Windows. It also supports less popular platforms like Solaris, FreeBSD, and OpenBSD.

Difficult to Block

It is not easy to detect and block OpenVPN connections as they can use ports on both TCP as well as UDP. Furthermore, configuring OpenVPN on port 443 will enable you to dodge any firewall as it is the same port used by HTTPS traffic.

Full Control over Connections

As opposed to other protocols, OpenVPN gives you the freedom to choose between TCP and UDP for transmitting your data. Having more control over your connections will make it easier to tweak them as per your needs.

Perfect Forward Secrecy Support

This incredibly useful security measure reduces the risk of your private data getting compromised considerably. Your VPN connection is resistant to various types of hacks as unique keys are generated for every session.

Cons of OpenVPN

Here are a few disadvantages of using OpenVPN:

Complex Manual Setup

If you want to configure OpenVPN manually, the chances are that you’ll run into issues. After all, the instructions are too complicated for the non-tech-savvy. You are better off choosing a VPN service as the OpenVPN setup process is handled in the background.

Requires Additional Software

OpenVPN isn’t integrated into any operating system, so you’ll need to install third-party software to use it. This drawback, though, has been mitigated to some extent thanks to the availability of VPN services with easy-to-use user interfaces.

Slower Connection Speeds

OpenVPN is widely considered as the most secure tunneling protocol. However, the robust security it offers may lead to a drop in your connection speeds.

OpenVPN Protocol Comparison

OpenVPN vs L2TP vs IKEv2 vs SSTP vs PPTP. The following is an in-depth comparison of OpenVPN against other common VPN protocols. PureVPN offers support for all major VPN protocols and platforms.

How to Use OpenVPN

If you want to set up a VPN connection using OpenVPN, there are two ways to go about this. The easiest method is to use a VPN service with OpenVPN support, such as PureVPN. In this scenario, all you have to do is:

If you’re a user with technical experience, you might prefer the manual configuration route. You’ll find the required steps to set up OpenVPN manually on different devices below. Before you begin, make sure that you have a:

OpenVPN Setup on Different Devices

Connect with us

Privacy Overview

Necessary cookies are absolutely essential for the website to function properly. These cookies ensure basic functionalities and security features of the website, anonymously.

Functional cookies help to perform certain functionalities like sharing the content of the website on social media platforms, collect feedbacks, and other third-party features.

Performance cookies are used to understand and analyze the key performance indexes of the website which helps in delivering a better user experience for the visitors.

Community Resources

Configuring client-specific rules and access policies

Which version of OpenVPN to use

Configuring OpenVPN to run automatically on system startup

Connecting to a Samba share over OpenVPN

Connecting to an OpenVPN server via an HTTP proxy.

Determining whether to use a routed or bridged VPN

Ethernet Bridging

Expanding the scope of the VPN to include additional machines on either the client or server subnet.

Hardening OpenVPN Security

2x HOW TO

1x HOW TO

Controlling a running OpenVPN process

Implementing a load-balancing/failover configuration

Important Note on possible «Man-in-the-Middle» attack if clients do not verify the certificate of the server they are connecting to.

Installing OpenVPN

Management Interface

Mailing Lists

Numbering private subnets

OpenVPN cryptographic layer

OpenVPN logos and icons

OpenVPN on Windows notes

OpenVPN Protocol

OpenVPN Quickstart

Porting Notes

Protocol Compatibility

Pushing DHCP options to clients

Revoking Certificates

RSA Key Management

Running OpenVPN as a Windows Service

Running OpenVPN from a console window

Setting up routing

Setting up your own Certificate Authority (CA)

Static Key Mini-HOWTO

Subversion Repository

The standard INSTALL file included in the source distribution

Using alternative authentication methods

Reference manual for OpenVPN 2.4

Reference manual for OpenVPN 2.3

Reference manual for OpenVPN 2.2

Reference manual for OpenVPN 2.1

Reference manual for OpenVPN 2.0

This usually occurs because a firewall on the server or client is blocking the TUN/TAP interface. If you already have a firewall on your system, chances are high that it will block incoming connections on new interfaces by default, so you will need to add explicit firewall rules to allow connections via the TUN/TAP interface. In general, it’s reasonable to open up TUN/TAP interfaces to all traffic, since any incoming connections over these interfaces will already have been authenticated by OpenVPN. An exception to this rule would be if you don’t fully trust the OpenVPN clients connecting to the server. Assuming that’s not the case, on Linux, TUN/TAP interfaces can be opened up with the iptables shell command:

Note that if you want OpenVPN clients to be able access other machines on the LAN, it is not enough to merely disable firewalling on the TUN/TAP adapter. You must also enable IP forwarding and set up a return route from the LAN gateway to the OpenVPN server. This is discussed at length in the HOWTO.

Also note that firewalling the TUN/TAP interface is a completely separate operation from firewalling the internet-facing interface. For example, suppose an OpenVPN client is sending email via SMTP over the OpenVPN tunnel. The OpenVPN server firewall will need to allow both incoming encrypted data on TCP/UDP port 1194 via the internet-facing interface as well as incoming SMTP connections via the TUN/TAP interface.

OpenVPN allocates one /30 subnet per client in order to provide compatibility with Windows clients due to the limitation of the TAP-Win32 driver’s TUN emulation mode.

If you know that only non-Windows clients will be connecting to your OpenVPN server, you can avoid this behavior by using the ifconfig-pool-linear directive.

In OpenVPN 1.6, when you had to run one OpenVPN instance per client, then it would be more like you expected: a PtP link between the server and each client.

In 2.0 however, OpenVPN can handle multiple clients with only one tun interface on the server. To handle this, you can think of the PtP link you see on server as a link between the operating system and OpenVPN. Then when you’re inside OpenVPN, another PtP link needs to created to each client. If all O/S would have supported true PtP links over the tun interface, this could have been done with the OpenVPN server using only one IP address and each client using another IP address.

But, as the TUN/TAP driver implementation on Windows does not support true PtP links, this is emulated through a /30 subnet.

So, you first have a PtP link 192.168.1.1 192.168.1.2 between your server O/S and OpenVPN on the server.

Then OpenVPN assigns a /30 subnet for each client that connets. The first available /30 subnet (after the one the server is using) is:

As 192.168.1.5 is only a virtual IP address inside the OpenVPN server, used as an endpoint for routes, OpenVPN doesn’t bother to answer pings on this address, while the 192.168.1.1 is a real IP address in the servers O/S, so it will reply to pings.

It does cause a little waste of IP addresses, but it’s the best way to allow a consistent configuration that works on all O/S supported by OpenVPN.

The TAP-Win32 driver includes a DHCP server which assigns the 192.168.1.6 address to you, that’s why you see 192.168.1.5 as DHCP server address.

Hope I made things a little clearer.

These errors occur because OpenVPN doesn’t have an internal route for 192.168.100.249. Consequently, it doesn’t know how to route the packet to this machine, so it drops the packet.

Use client-config-dir and create a ccd file for your client containing the iroute option to tell OpenVPN that the 192.168.100.0/24 network is available behind this client.

«MULTI: bad source address from client [192.168.100.249], packet dropped» or «GET INST BY VIRT: 192.168.100.249 [failed]»?

This error can occur if you don’t include a ca directive in your profile, since the iOS Keychain does not provide the CA list from the PKCS#12 file to OpenVPN. The solution is to extract the CA list from the PKCS#12 file and add it to your profile via the ca directive. This is discussed in detail in the FAQ item above: How do I use a client certificate and private key from the iOS Keychain?

Yes, CRLs are supported starting with version 1.1.14 for Android.

Multiple CRLs may be concatenated together within the crl-verify block above.

Absolutely, as long as you make sure that:

The NAT gateway on the server’s network has a port forward rule for TCP/UDP 1194 to the internal address of the OpenVPN server machine.
If you are using routing rather than ethernet bridging mode and would like connecting clients to see the whole LAN rather than only the server machine itself, you need to add an internal LAN route to the LAN gateway so that the private OpenVPN subnet (declared in theserver, ifconfig, or ifconfig-pool directives) is routed to the OpenVPN server machine (i.e. its internal address).

Yes. An OpenVPN server can push HTTP and HTTPS proxy settings to an iOS client such that these settings will be used by Safari (or other iOS browsers) during the duration of the VPN session. For example, suppose that you are managing an OpenVPN Server and want iOS clients, after they connect, to use an HTTP/HTTPS proxy at 10.144.5.14 port 3128. You could add the following directives to the OpenVPN server-side configuration to push these settings to clients:

Suppose also that you want several web domains to connect directly (example1.tld, example2.tld, and example3.tld), without going through the proxy:

If your site uses a Proxy Autoconfiguration URL, you can specify the URL as follows:

In some cases, if you push proxy options, it may also be necessary to push a DNS server address as well:

Note that this feature controls application proxy use over the VPN tunnel and is not related to the connection proxy capability of OpenVPN to connect to a server through an HTTP proxy. The connection proxy capability is a separate feature that is accessed through the Settings App under OpenVPN or by using the http-proxy and http-proxy-optiondirectives.

Yes, you can add any number of proxies from the main menu. Once a proxy is added, a proxy selection field will appear on the main page. Tap the field to select a proxy or None at the end of the list to connect directly.

Next, edit the newly created Configuration Profile. Click on General in the left pane and fill out the fields such as Name, Identifier, Organization, etc. Click on VPN in the left pane and a «Configure VPN» dialog box should appear in the main window. Click the «Configure» button. Fill out the VPN settings as described below:

Parameters normally given in the OpenVPN client configuration file must be defined using key/value pairs in the Custom Data section:

Once the profile has been defined, you have two options for exporting it to an iOS device:

Yes, you can push an IPv6 DNS by using the same format used for IPv4 ones. For Example:

If you are running 2 or more OpenVPN instances on the same machine, you will need a separate virtual TUN/TAP adapter and a separate port (using the port directive) for each instance.

Make sure each TUN/TAP adapter has a unique, non-overlapping subnet using server, server-bridge, or ifconfig.

Yes. VPN-On-Demand (VoD) is a new technology introduced by Apple in iOS 6 that allows a VPN profile to specify the conditions under which it will automatically connect. In addition, using a VoD profile on iOS 7 allows OpenVPN to be connected and disconnected using the iOS Settings App under the VPN tab (although note that on iOS 8 and higher, ordinary OpenVPN profiles can be connected using the Settings App, as long as they don’t require credential entry). OpenVPN on iOS fully supports VoD, with the following features:

OpenVPN VoD profiles can be created using the iPhone Configuration utility. Unfortunately, the process is a bit cumbersome at the moment because the directives of the OpenVPN profile must be manually entered as key/value pairs into the iPhone Configuration utility UI.

For now, to create a VoD profile, open the iPhone Configuration utility (these directions were tested with version 3.5 on a Mac tethered to an iPad running iOS 6.0.1), go to the File menu, and select «New Configuration Profile».

Next, edit the newly created Configuration Profile. Click on General in the left pane and fill out the fields such as Name, Identifier, Organization, etc. Click on VPN in the left pane and a «Configure VPN» dialog box should appear in the main window. Click the «Configure» button. Fill out the VPN settings as described below:

In addition, parameters normally given in the OpenVPN client configuration file may instead be defined using key/value pairs in the Custom Data section:

Once the VoD profile has been defined, you have two options for exporting it to an iOS device:

When an iOS device receives a VoD profile (via Mail attachment, Safari download, or pushed by the iPhone Configuration utility), it will raise a dialog box to facilitate import of the profile. After import, the profile will be visible in the Settings App under General / Profiles. It will also be visible as a profile in the OpenVPN app. Note that the profile must be the currently-enabled VPN profile in order for the VoD functionality to work.

A prerequiste of this method is that you subscribe to a service such as dyndns.org that lets you conveniently point an internet domain name to a dynamic address (or you can do it yourself if you have control over a DNS server that exists on a machine having a static IP address).

The crux of this method is in the ‘timeouts’ section of the config file below, or more specifically the ‘ping’ and ‘ping-restart’ options. Basically, if for whatever reason, OpenVPN doesn’t receive a ping from its peer during a 300 second period (as would happen if its peer changed addresses), it will restart. When it restarts, it will re-resolve myremote.mydomain.com to get the new IP address. This method assumes that you are using a dynamic DNS service that lets you immediately update your domain name with your current dynamic address.

Using this technique, OpenVPN will essentially «follow» a dynamic DNS address as it changes.

Here is the config file example:

# crypto config
replay-persist replay-persist-file # optional (1.4.0 or above)

# TLS config (or omit TLS security by using a pre-shared key
# such as ‘secret static.key’).
tls-client
ca key/my-ca.crt
cert key/my-cert.crt
key key/my-key.key
tls-auth key/my-tls-password # optional

# timeouts
ping 15
ping-restart 300 # 5 minutes
resolv-retry 300 # 5 minutes
persist-tun
persist-key

# compression (optional)
comp-lzo

# UID (optional)
user nobody
group nobody

# verbosity (optional)
verb 4
On the other end of the connection, you would duplicate the above config file but change ‘remote’ appropriately, and swap the ifconfig addresses.

If you are using TLS security, then also change ‘tls-client’ to ‘tls-server’, add a ‘dh’ file for the diffie-hellman file, and change ‘cert’ and ‘key’ to match your appropriate local cert and key.

This setup requires that each machine have a dynamic DNS name which is updated automatically when DHCP causes an address change. Such an automatic update can be accomplished by using a tool such as ddclient.

ddclient should be called by your /etc/dhcpc/dhcpcd-eth0.exe file (replace «eth0» in the filename with the appropriate network device name):

login=mylogin # default login
password=mypassword # default password
#mx=mx.for.your.host # default MX
#backupmx=yes|no # host is primary MX?
#wildcard=yes|no # add wildcard CNAME?

##
##
## dyndns.org custom addresses
##
## (supports variables: wildcard,mx,backupmx)
##
custom=yes \
server=members.dyndns.org, \
protocol=dyndns2 \
myremote.mydomain.com

Yes, starting with iOS 8. Note that, if you are using 1.2.5 or older, only autologin profiles (i.e. profiles that don’t require credential entry) can be launched using this mechanism. Starting with version 1.2.6, also profiles using a PKCS#12 bundle stored in the iOS keychain can be connected from the Settings.

Q: I edited my OpenVPN static key, changing some of the hex bytes, but the key still connects to a remote peer which is using the original key. Is this a bug?

When I modify the Preshared 2048 bit Static Key on the Initiator Side of the Tunnel(don’t tested the other way) I’m anyhow able to establish the Tunnel an send Packets through the Tunnel. I don’t understand the Key splitting and handling as described below, but I think the Keys on both Sides of the Tunnel should be identical for the Tunnel to be established.

I can modify every Char in Line 2,3,4,7,8,9,10,11,12,13,14,15,16 without any effect and think this is possible a Bug.

A: No, this is not a bug. The 2048 bit static key is designed to be large enough to allow 512 bit encrypt, decrypt, HMAC send, and HMAC receive keys to be extracted from it.

However, this key size is far too large for current conventional OpenVPN usage. OpenVPN uses the 128 bit blowfish cipher by default. It also uses the 160 bit HMAC-SHA1 as a cryptographic signature on packets to protect against tampering. Since you probably didn’t specify a key direction parameter, the encrypt/decrypt keys for both directions are the same and the HMAC keys for both directions are also the same.

Below, I will show a sample 2048 bit OpenVPN key, bracketed to show which bits are actually used for key material, assuming default crypto settings:

#
# 2048 bit OpenVPN static key
#
——BEGIN OpenVPN Static key V1——
[eac9ae92cd73c5c2d6a2338b5a22263a] 128 bits for cipher
4ef4a22326d2a996e0161d25d41150c8
38bebc451ccf8ad19c7d1c7ce09742c3
2047ba60f1d97d47c88f7ab0afafb2ce
[f702cb04c7d15ff2606736c1825e830a 160 bits for HMAC SHA1
7e30a796] 4b82825d6767a04b3c8f4583
d4928127262c3a8603776bd6da339f69
dece3bbfee35f1dceb7cbceaef4c6933
2c2cef8ac550ed15213b216b825ab31e
49840f99ff9df3c5f31156439ed6b99c
4fc1bff417d33d77134365e38c9d71cd
e294ba6e65d51703d6d4a629d5fc618e
adddb889b8173ac79b4261328770bbbe
74294bc79e357c82af9ef53f2968be6a
007e6022da0a1a39f2ed5660f94a5926
35d72e5838dd78dd680d91f6edcf6988
——END OpenVPN Static key V1——

As you can see, the only lines actually used are 1, 5, and 6. And of course, that matches up perfectly with what you observed.

To verify this, run OpenVPN as follows:

where ‘key’ is a file containing the key shown above.

Static Encrypt: Cipher ‘BF-CBC’ initialized with 128 bit key
Static Encrypt: CIPHER KEY: eac9ae92 cd73c5c2 d6a2338b 5a22263a
Static Encrypt: Using 160 bit message hash ‘SHA1’ for HMAC authentication
Static Encrypt: HMAC KEY: f702cb04 c7d15ff2 606736c1 825e830a 7e30a796
Static Decrypt: Cipher ‘BF-CBC’ initialized with 128 bit key
Static Decrypt: CIPHER KEY: eac9ae92 cd73c5c2 d6a2338b 5a22263a
Static Decrypt: Using 160 bit message hash ‘SHA1’ for HMAC authentication
Static Decrypt: HMAC KEY: f702cb04 c7d15ff2 606736c1 825e830a 7e30a796

Note that the keys which are shown in the OpenVPN output exactly match the bracketed section of the key source.

Now if you want to use more of the key material, it is possible to use two sets of encrypt/HMAC keys, one for each direction:

Static Encrypt: Cipher ‘BF-CBC’ initialized with 128 bit key
Static Encrypt: CIPHER KEY: eac9ae92 cd73c5c2 d6a2338b 5a22263a
Static Encrypt: Using 160 bit message hash ‘SHA1’ for HMAC authentication
Static Encrypt: HMAC KEY: f702cb04 c7d15ff2 606736c1 825e830a 7e30a796
Static Decrypt: Cipher ‘BF-CBC’ initialized with 128 bit key
Static Decrypt: CIPHER KEY: 2c2cef8a c550ed15 213b216b 825ab31e
Static Decrypt: Using 160 bit message hash ‘SHA1’ for HMAC authentication
Static Decrypt: HMAC KEY: adddb889 b8173ac7 9b426132 8770bbbe 74294bc7

Now notice that the Encrypt and Decrypt keys are no longer identical. The encrypt keys are drawing key material from lines 1, 5, and 6 in the key file, while the decrypt keys are drawing from lines 9, 13, and 14.

Now the opposite peer will use a key-direction of 1:

Static Encrypt: Cipher ‘BF-CBC’ initialized with 128 bit key
Static Encrypt: CIPHER KEY: 2c2cef8a c550ed15 213b216b 825ab31e
Static Encrypt: Using 160 bit message hash ‘SHA1’ for HMAC authentication
Static Encrypt: HMAC KEY: adddb889 b8173ac7 9b426132 8770bbbe 74294bc7
Static Decrypt: Cipher ‘BF-CBC’ initialized with 128 bit key
Static Decrypt: CIPHER KEY: eac9ae92 cd73c5c2 d6a2338b 5a22263a
Static Decrypt: Using 160 bit message hash ‘SHA1’ for HMAC authentication
Static Decrypt: HMAC KEY: f702cb04 c7d15ff2 606736c1 825e830a 7e30a796

Notice how the Encrypt and Decrypt keys are swapped, in relation to the key-direction 1 example.

So you might ask why is the OpenVPN static key file so large, if such a small percentage of the bits are currently used? The answer is to accomodate future ciphers and HMAC hashes which use large keys. Changing a file format is obviously problematic from a compatibility perspective, so 2048 bits were chosen so that two sets of 512-bit encrypt and HMAC keys could be derived for two separate key directions.

openvpn

Secure IP tunnel daemon

SYNOPSIS

INTRODUCTION

OpenVPN is an open source VPN daemon by James Yonan. Because OpenVPN tries to be a universal VPN tool offering a great deal of flexibility, there are a lot of options on this manual page. 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.

Also note that there’s more documentation and examples on the OpenVPN web site: https://openvpn.net/

And if you would like to see a shorter version of this manual, see 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 NAT, support for dynamic IP addresses and DHCP, scalability to hundreds or thousands of users, and portability to most major OS platforms.

OpenVPN is tightly bound to the OpenSSL library, and derives much of its crypto 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 & server certificates. OpenVPN also supports non-encrypted TCP/UDP tunnels.

OpenVPN is designed to work with the TUN/TAP virtual networking interface that exists 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.

Generic Options

This section covers generic options which are accessible regardless of which mode OpenVPN is configured as.

If specified, this directive will cause OpenVPN to immediately forget username/password inputs after they are used. As a result, when OpenVPN needs a username/password, it will prompt for input from stdin, which may be multiple times during the duration of an OpenVPN session.

Since the chroot operation is delayed until after initialization, most OpenVPN options that reference files will operate in a pre-chroot context.

In many cases, the dir parameter can point to an empty directory, however complications can result when scripts or restarts are executed after the chroot operation.

Note: The SSL library will probably need /dev/urandom to be available inside the chroot directory dir. This is because SSL libraries occasionally need to collect fresh random. Newer linux kernels and some BSDs implement a getrandom() or getentropy() syscall that removes the need for /dev/urandom to be available.

Load additional config options from file where each line corresponds to one command line option, but with the leading ‘—‘ removed.

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:

For example on Windows, use double backslashes to represent pathnames:

Here is an example configuration file:

The optional progname parameter will cause OpenVPN to report its program name to the system logger as progname. This can be useful in linking OpenVPN messages in the syslog file with specific tunnels. When unspecified, progname defaults to «openvpn».

In OpenVPN, the vast majority of errors which occur after initialization are non-fatal.

Use of this option is discouraged, but is provided as a temporary fix in situations where a recent version of OpenVPN must connect to an old version.

Enable OpenSSL hardware-based crypto engine functionality.

(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to poll/epoll/select prior to the write operation. The purpose of such a call would normally be to block until the device or socket is ready to accept the write. Such blocking is unnecessary on some platforms which don’t support write blocking on UDP sockets or TUN/TAP devices. In such cases, one can optimize the event loop by avoiding the poll/epoll/select call, improving CPU efficiency by 5% to 10%.

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.

—ignore-unknown-option is available since OpenVPN 2.3.3.

Save Exported Keying Material [RFC5705] of len bytes (must be between 16 and 4095 bytes) using label in environment ( exported_keying_material ) for use by plugins in OPENVPN_PLUGIN_TLS_FINAL callback.

The limit on how much memory can be locked and how that limit is enforced are OS-dependent. On Linux the default limit that an unprivileged process may lock (RLIMIT_MEMLOCK) is low, and if privileges are dropped later, future memory allocations will very likely fail. The limit can be increased using ulimit or systemd directives depending on how OpenVPN is started.

This option solves the problem by persisting keys across SIGUSR1 resets, so they don’t need to be re-read.

Load the list of (OpenSSL) providers. This is mainly useful for using an external provider for key management like tpm2-openssl or to load the legacy provider with

Behaviour of changing this option between SIGHUP might not be well behaving. If you need to change/add/remove this option, fully restart OpenVPN.

Control whether internally or externally generated SIGUSR1 signals are remapped to SIGHUP (restart without persisting state) or SIGTERM (exit).

This directive offers policy-level control over OpenVPN’s usage of external programs and scripts. Lower level values are more restrictive, higher values are more permissive. Settings for level:

0 Strictly no calling of external programs. 1 (Default) Only call built-in executables such as ifconfig, ip, route, or netsh. 2 Allow calling of built-in executables and user-defined scripts. 3 Allow passwords to be passed to scripts via environmental variables (potentially unsafe).

Please note the single quote marks and the escaping of the backslashes (\) and the space character.

The reason the support for the system flag was removed is due to the security implications with shell expansions when executing scripts via the system() call.

Since the setcon operation is delayed until after initialization, OpenVPN can be restricted to just network-related system calls, whereas by applying the context before startup (such as the OpenVPN one provided in the SELinux Reference Policies) you will have to allow many things required only during initialization.

Write operational status to file every n seconds.

Status can also be written to the syslog by sending a SIGUSR2 signal.

For clients or instances running in point-to-point mode, it will contain the traffic statistics.

Set the status file format version number to n.

This only affects the status file on servers with multi-client capability enabled. Valid status version values:

This option is very useful to test OpenVPN after it has been ported to a new platform, or to isolate problems in the compiler, OpenSSL crypto library, or OpenVPN’s crypto code. Since it is a self-test mode, problems with encryption and authentication can be debugged independently of network and tunnel issues.

Specify a directory dir for temporary files. This directory will be used by openvpn processes and script to communicate temporary data with openvpn main process. Note that the directory must be writable by the OpenVPN process after it has dropped it’s root privileges.

This directory will be used by in the following cases:

Enable prediction resistance on mbed TLS’s RNG.

Enabling prediction resistance causes the RNG to reseed in each call for random. Reseeding this often can quickly deplete the kernel entropy pool.

If you need this option, please consider running a daemon that adds entropy to the kernel pool.

Change the user ID of the OpenVPN process to user after initialization, dropping privileges in the process. This option is useful to protect the system in the event that some hostile party was able to gain control of an OpenVPN session. Though OpenVPN’s security features make this unlikely, it is provided as a second line of defense.

Log options

Echo parms to log output.

Designed to be used to send messages to a controlling application which is receiving the OpenVPN log output.

Note that on Windows, when OpenVPN is started as a service, logging occurs by default without the need to specify this option.

Set output verbosity to n (default 1 ). Each level shows all info from the previous levels. Level 3 is recommended if you want a good summary of what’s happening without being swamped by output.

0 No output except fatal errors. 1 to 4 Normal usage range. 5 Outputs R and W characters to the console for each packet read and write, uppercase is used for TCP/UDP packets and lowercase is used for TUN/TAP packets. 6 to 11 Debug info range (see errlevel.h in the source code for additional information on debug levels).

Protocol options

Options in this section affect features available in the OpenVPN wire protocol. Many of these options also define the encryption options of the data channel in the OpenVPN wire protocol. These options must be configured in a compatible way between both the local and remote side.

The mode argument can be one of the following values:

asym (default) OpenVPN will only decompress downlink packets but not compress uplink packets. This also allows migrating to disable compression when changing both server and client configurations to remove compression at the same time is not a feasible option. no OpenVPN will refuse any non-stub compression. yes OpenVPN will send and receive compressed packets.

Authenticate data channel packets and (if enabled) tls-auth control channel packets with HMAC using message digest algorithm alg. (The default is SHA1 ). HMAC is a commonly used message authentication algorithm (MAC) that uses a data string, a secure hash algorithm and a key to produce a digital signature.

The OpenVPN data channel protocol uses encrypt-then-mac (i.e. first encrypt a packet then HMAC the resulting ciphertext), which prevents padding oracle attacks.

Encrypt data channel packets with cipher algorithm alg.

Set alg to none to disable encryption.

DEPRECATED Enable a compression algorithm. Compression is generally not recommended. VPN tunnels which use compression are susceptible to the VORALCE attack vector.

The lz4-v2 and stub-v2 variants implement a better framing that does not add overhead when packets cannot be compressed. All other variants always add one extra framing byte compared to no compression framing.

*Security Considerations*

Compression and encryption is a tricky combination. If an attacker knows or is able to control (parts of) the plain-text of packets that contain secrets, the attacker might be able to extract the secret if compression is enabled. See e.g. the CRIME and BREACH attacks on TLS and VORACLE on VPNs which also leverage to break encryption. If you are not entirely sure that the above does not apply to your traffic, you are advised to not enable compression.

DEPRECATED Enable LZO compression algorithm. Compression is generally not recommended. VPN tunnels which uses compression are suspectible to the VORALCE attack vector.

In a server mode setup, it is possible to selectively turn compression on or off for individual clients.

The first line sets the comp-lzo setting for the server side of the link, the second sets the client side.

Adaptive compression tries to optimize the case where you have compression enabled, but you are sending predominantly incompressible (or pre-compressed) packets over the tunnel, such as an FTP or rsync transfer of a large, compressed file. With adaptive compression, OpenVPN will periodically sample the compression process to measure its efficiency. If the data being sent over the tunnel is already compressed, the compression efficiency will be very low, triggering openvpn to disable compression for a period of time until the next re-sample test.

DEPRECATED This option will be removed in OpenVPN 2.6.

For servers, the first cipher from cipher-list that is also supported by the client will be pushed to clients that support cipher negotiation.

Note for using NCP with an OpenVPN 2.4 peer: This list must include the AES-256-GCM and AES-128-GCM ciphers.

This list is restricted to be 127 chars long after conversion to OpenVPN ciphers.

Configure a cipher that is used to fall back to if we could not determine which cipher the peer is willing to use.

The optional direction parameter enables the use of 4 distinct keys (HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt), so that each data flow direction has a different set of HMAC and cipher keys. This has a number of desirable security properties including eliminating certain kinds of DoS and message replay attacks.

When the direction parameter is omitted, 2 keys are used bidirectionally, one for HMAC and the other for encryption/decryption.

Static key encryption mode has certain advantages, the primary being ease of configuration.

There are no certificates or certificate authorities or complicated negotiation handshakes and protocols. The only requirement is that you have a pre-existing secure channel with your peer (such as ssh) to initially copy the key. This requirement, along with the fact that your key never changes unless you manually generate a new one, makes it somewhat less secure than TLS mode (see below). If an attacker manages to steal your key, everything that was ever encrypted with it is compromised. Contrast that to the perfect forward secrecy features of TLS mode (using Diffie Hellman key exchange), where even if an attacker was able to steal your private key, he would gain no information to help him decrypt past sessions.

Another advantageous aspect of Static Key encryption mode is that it is a handshake-free protocol without any distinguishing signature or feature (such as a header or protocol handshake sequence) that would mark the ciphertext packets as being generated by OpenVPN. Anyone eavesdropping on the wire would see nothing but random-looking data.

Client Options

The purpose of this is to enable two factor authentication methods, such as HOTP or TOTP, to be used without needing to retrieve a new OTP code each time the connection is renegotiated. Another use case is to cache authentication data on the client without needing to have the users password cached in memory during the life time of the session.

into the file/buffer for dynamic configuration data. This will then make the OpenVPN server to push this value to the client, which replaces the local password with the UNIQUE_TOKEN_VALUE.

The username has to be base64 encoded.

Authenticate with server using username/password.

If up is present, it must be a file containing username/password on 2 lines. If the password line is missing, OpenVPN will prompt for one.

If up is omitted, username/password will be prompted from the console.

Controls how OpenVPN responds to username/password verification errors such as the client-side response to an AUTH_FAILED message from the server or verification failure of the private key password.

Normally used to prevent auth errors from being fatal on the client side, and to permit username/password requeries in case of error.

type can be one of:

Note that while this option cannot be pushed, it can be controlled from the management interface.

A helper directive designed to simplify the configuration of OpenVPN’s client mode. This directive is equivalent to:

This pushable client option sets up a stateless one-to-one NAT rule on packet addresses (not ports), and is useful in cases where routes or ifconfig settings pushed to the client would create an IP numbering conflict.

network/netmask (for example 192.168.0.0/255.255.0.0 ) defines the local view of a resource from the client perspective, while alias/netmask (for example 10.64.0.0/255.255.0.0 ) defines the remote view from the server perspective.

Use snat (source NAT) for resources owned by the client and dnat (destination NAT) for remote resources.

In UDP client mode or point-to-point mode, send server/peer an exit notification if tunnel is restarted or OpenVPN process is exited. In client mode, on exit/restart, this option will tell the server to immediately close its client instance object rather than waiting for a timeout.

The n parameter (default 1 if not present) controls the maximum number of attempts that the client will try to resend the exit notification message.

In UDP server mode, send RESTART control channel command to connected clients. The n parameter (default 1 if not present) controls client behavior. With n = 1 client will attempt to reconnect to the same server, with n = 2 client will advance to the next server.

OpenVPN will not send any exit notifications unless this option is enabled.

Causes OpenVPN to exit after n seconds of inactivity on the TUN/TAP device. The time length of inactivity is measured since the last incoming or outgoing tunnel packet. The default value is 0 seconds, which disables this feature.

If the optional bytes parameter is included, exit if less than bytes of combined in/out traffic are produced on the tun/tap device in n seconds.

In any case, OpenVPN’s internal ping packets (which are just keepalives) and TLS control packets are not considered «activity», nor are they counted as traffic, as they are used internally by OpenVPN and are not an indication of actual user activity.

When iterating through connection profiles, only consider profiles using protocol p ( tcp | udp ).

Note that this specifically only filters by the transport layer protocol, i.e. UDP or TCP. This does not affect whether IPv4 or IPv6 is used as IP protocol.

For implementation reasons the option accepts the 4 and 6 suffixes when specifying the protocol (i.e. udp4 / udp6 / tcp4 / tcp6 ). However, these behave the same as without the suffix and should be avoided to prevent confusion.

Filter options on the client pushed by the server to the client.

Prefix comparison is used to match text against the received option so that

would remove all routes that do not start with 192.168.1.

Push additional information about the client to server. The following data is always pushed to the server:

IV_VER= The client OpenVPN version IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win] The client OS platform IV_LZO_STUB=1 If client was built with LZO stub capability IV_LZ4=1 If the client supports LZ4 compressions. IV_PROTO

Details about protocol extensions that the peer supports. The variable is a bitfield and the bits are defined as follows (starting a bit 0 for the first (unused) bit:

Remote host name or IP address, port and protocol.

The client will move on to the next host in the list, in the event of connection failure. Note that at any given time, the OpenVPN client will at most be connected to one server.

If host is a DNS name which resolves to multiple IP addresses, OpenVPN will try them in the order that the system getaddrinfo() presents them, so priorization and DNS randomization is done by the system library. Unless an IP version is forced by the protocol specification (4/6 suffix), OpenVPN will try both IPv4 and IPv6 addresses, in the order getaddrinfo() returns them.

Set n to «infinite» to retry indefinitely.

After initially connecting to a remote peer, disallow any new connections. Using this option means that a remote peer cannot connect, disconnect, and then reconnect.

Enable static challenge/response protocol

See management-notes.txt in the OpenVPN distribution for a description of the OpenVPN challenge/response protocol.

HTTP Digest authentication is supported as well, but only via the auto or auto-nct flags (below). This must replace the authfile argument.

The auto flag causes OpenVPN to automatically determine the auth-method and query stdin or the management interface for username/password credentials, if required. This flag exists on OpenVPN 2.1 or higher.

The auto-nct flag (no clear-text auth) instructs OpenVPN to automatically determine the authentication method, but to reject weak authentication protocols such as HTTP Basic Authentication.

Set extended HTTP proxy options. Requires an option type as argument and an optional parameter to the type. Repeat to set multiple options.

Server Options

Returns an authentication token to successfully authenticated clients.

After successful user/password authentication, the OpenVPN server will with this option generate a temporary authentication token and push that to the client. On the following renegotiations, the OpenVPN client will pass this token instead of the users password. On the server side the server will do the token authentication internally and it will NOT do any additional authentications against configured external user/password authentication mechanisms.

The tokens implemented by this mechanism include an initial timestamp and a renew timestamp and are secured by HMAC.

The token will expire either after the configured lifetime of the token is reached or after not being renewed for more than 2 * reneg-sec seconds. Clients will be sent renewed tokens on every TLS renogiation to keep the client’s token updated. This is done to invalidate a token if a client is disconnected for a sufficently long time, while at the same time permitting much longer token lifetimes for active clients.

This feature is useful for environments which are configured to use One Time Passwords (OTP) as part of the user/password authentications and that authentication mechanism does not implement any auth-token support.

When the external-auth keyword is present the normal authentication method will always be called even if auth-token succeeds. Normally other authentications method are skipped if auth-token verification suceeds or fails.

This option postpones this decision to the external authentication methods and checks the validity of the account and do other checks.

In this mode the environment will have a session_id variable that holds the session id from auth-gen-token. Also an environment variable session_state is present. This variable indicates whether the auth-token has succeeded or not. It can have the following values:

Warning: Use this feature only if you want your authentication method called on every verification. Since the external authentication is called it needs to also indicate a success or failure of the authentication. It is strongly recommended to return an authentication failure in the case of the Invalid/Expired auth-token with the external-auth option unless the client could authenticate in another acceptable way (e.g. client certificate), otherwise returning success will lead to authentication bypass (as does returning success on a wrong password from a script).

Specify a directory dir for custom client config files. After a connecting client has been authenticated, OpenVPN will look in this directory for a file having the same name as the client’s X509 common name. If a matching file exists, it will be opened and parsed for client-specific configuration options. If no matching file is found, OpenVPN will instead try to open and parse a default file called «DEFAULT», which may be provided but is not required. Note that the configuration files must be readable by the OpenVPN process after it has dropped it’s root privileges.

One of the useful properties of this option is that it allows client configuration files to be conveniently created, edited, or removed while the server is live, without needing to restart the server.

When this option is used, each client will «see» the other clients which are currently connected. Otherwise, each client will only see the server. Don’t use this option if you want to firewall tunnel traffic using custom, per-client rules.

Allow a maximum of n new connections per sec seconds from clients.

This is designed to contain DoS attacks which flood the server with connection requests using certificates which will ultimately fail to authenticate.

This is an imperfect solution however, because in a real DoS scenario, legitimate connections might also be refused.

Set aside a pool of subnets to be dynamically allocated to connecting clients, similar to a DHCP server.

For tun-style tunnels, each client will be given a /30 subnet (for interoperability with Windows clients). For tap-style tunnels, individual addresses will be allocated, and the optional netmask parameter will also be pushed to clients.

Specify an IPv6 address pool for dynamic assignment to clients.

The pool starts at ipv6addr and matches the offset determined from the start of the IPv4 pool. If the host part of the given IPv6 address is 0, the pool starts at ipv6addr +1.

Persist/unpersist ifconfig-pool data to file, at seconds intervals (default 600 ), as well as on program startup and shutdown.

The optional alias parameter may be used in cases where NAT causes the client view of its local endpoint to differ from the server view. In this case local/remote-netmask will refer to the server view while alias/remote-netmask will refer to the client view.

OpenVPN’s internal client IP address selection algorithm works as follows:

Use this option when OpenVPN is being run from the inetd or xinetd(8) server.

Also note that in wait mode, each OpenVPN tunnel requires a separate TCP/UDP port and a separate inetd or xinetd entry. See the OpenVPN 1.x HOWTO for an example on using OpenVPN with xinetd: https://openvpn.net/community-resources/1xhowto/

Note that this directive affects OpenVPN’s internal routing table, not the kernel routing table.

Clients that connect with options that are incompatible with those of the server will be disconnected.

Share OpenVPN TCP with another service

When run in TCP server mode, share the OpenVPN port with another application, such as an HTTPS server. If OpenVPN senses a connection to its port which is using a non-OpenVPN protocol, it will proxy the connection to the server at host: port. Currently only designed to work with HTTP/HTTPS, though it would be theoretically possible to extend to other protocols such as ssh.

dir specifies an optional directory where a temporary file with name N containing content C will be dynamically generated for each proxy connection, where N is the source IP:port of the client connection and C is the source IP:port of the connection to the proxy receiver. This directory can be used as a dictionary by the proxy receiver to determine the origin of the connection. Each generated file will be automatically deleted when the proxied connection is torn down.

Not implemented on Windows.

NOTE 2: due to implementation details, ‘ifconfig’ and ‘ifconfig-ipv6’ can only be removed with an exact match on the option ( push-remove ifconfig ), no substring matching and no matching on the IPv4/IPv6 address argument is possible.

To configure ethernet bridging, you must first use your OS’s bridging capability to bridge the TAP interface with the ethernet NIC interface. For example, on Linux this is done with the brctl tool, and with Windows XP it is done in the Network Connections Panel by selecting the ethernet and TAP adapters and right-clicking on «Bridge Connections».

For example, server-bridge 10.8.0.4 255.255.255.0 10.8.0.128 10.8.0.254 expands as follows:

Remove routes which haven’t had activity for n seconds (i.e. the ageing time). This check is run every t seconds (i.e. check interval).

If t is not present it defaults to n.

The common_name environment variable passed to scripts and plugins invoked after authentication (e.g, client-connect script) and file names parsed in client-config directory will match the username.

Specify whether the client is required to supply a valid certificate.

Possible mode options are:

A client certificate is not required. the client needs to authenticate using username/password only. Be aware that using this directive is less secure than requiring certificates from all clients.

require This is the default option. A client is required to present a certificate, otherwise VPN access is refused.

Server-only option. Turns the OpenVPN server instance into a switch that understands VLAN-tagging, based on IEEE 802.1Q.

Ethernet frames with a prepended 802.1Q tag are called «tagged». If the VLAN Identifier (VID) field in such a tag is non-zero, the frame is called «VLAN-tagged». If the VID is zero, but the Priority Control Point (PCP) field is non-zero, the frame is called «prio-tagged». If there is no 802.1Q tag, the frame is «untagged».

The packet filtering takes place in the OpenVPN server. Clients should not have any VLAN tagging configuration applied.

Configure the VLAN tagging policy for the server TAP device.

The following modes are available:

In some switch implementations, the PVID is also referred to as «Native VLAN».

Encryption Options

SSL Library information

(Standalone) Show all TLS ciphers supported by the crypto library. OpenVPN uses TLS to secure the control channel, over which the keys that are used to protect the actual VPN traffic are exchanged. The TLS ciphers will be sorted from highest preference (most secure) to lowest.

Be aware that whether a cipher suite in this list can actually work depends on the specific setup of both peers (e.g. both peers must support the cipher, and an ECDSA cipher suite will not work if you are using an RSA certificate, etc.).

Generating key material

(Standalone) Generate a key to be used of the type keytype. if keyfile is left out or empty the key will be output on stdout. See the following sections for the different keytypes.

Valid keytype arguments are:

secret Standard OpenVPN shared secret keys

tls-crypt Alias for secret

tls-auth Alias for secret

tls-crypt-v2-server TLS Crypt v2 server key

tls-crypt-v2-client TLS Crypt v2 client key

If supplied, include the supplied metadata in the wrapped client key. This metadata must be supplied in base64-encoded form. The metadata must be at most 735 bytes long (980 bytes in base64).

If no metadata is supplied, OpenVPN will use a 64-bit unix timestamp representing the current time in UTC, encoded in network order, as metadata for the generated key.

Generate Authentication Token key Generate a new secret that can be used with —auth-gen-token-secret

This file should be kept secret to the server as anyone that has access to this file will be able to generate auth tokens that the OpenVPN server will accept as valid.

Data Channel Renegotiation

When running OpenVPN in client/server mode, the data channel will use a separate ephemeral encryption key which is rotated at regular intervals.

Renegotiate data channel key after n bytes sent or received (disabled by default with an exception, see below). OpenVPN allows the lifetime of a key to be expressed as a number of bytes encrypted/decrypted, a number of packets, or a number of seconds. A key renegotiation will be forced if any of these three criteria are met by either peer.

Renegotiate data channel key after at most max seconds (default 3600 ) and at least min seconds (default is 90% of max for servers, and equal to max for clients).

When using dual-factor authentication, note that this default value may cause the end user to be challenged to reauthorize once per hour.

TLS Mode Options

TLS mode is the most powerful crypto mode of OpenVPN in both security and flexibility. TLS mode works by establishing control and data channels which are multiplexed over a single TCP/UDP port. OpenVPN initiates a TLS session over the control channel and uses it to exchange cipher and HMAC keys to protect the data channel. TLS mode uses a robust reliability layer over the UDP connection for all control channel communication, while the data channel, over which encrypted tunnel data passes, is forwarded without any mediation. The result is the best of both worlds: a fast data channel that forwards over UDP with only the overhead of encrypt, decrypt, and HMAC functions, and a control channel that provides all of the security features of TLS, including certificate-based authentication and Diffie Hellman forward secrecy.

If that check on both peers succeeds, then the TLS negotiation will succeed, both OpenVPN peers will exchange temporary session keys, and the tunnel will begin passing data.

The OpenVPN project provides a set of scripts for managing RSA certificates and keys: https://github.com/OpenVPN/easy-rsa

Get certificate password from console or file before we daemonize.

If file is specified, read the password from the first line of file. Keep in mind that storing your password in a file to a certain extent invalidates the extra security provided by using an encrypted key.

Then edit your openssl.cnf file and edit the certificate variable to point to your new root certificate ca.crt.

For testing purposes only, the OpenVPN distribution includes a sample CA certificate (ca.crt). Of course you should never use the test certificates and test keys distributed with OpenVPN in a production environment, since by virtue of the fact that they are distributed with OpenVPN, they are totally insecure.

Directory containing trusted certificates (CAs and CRLs). Not available with mbed TLS.

If your certificate authority private key lives on another machine, copy the certificate signing request (mycert.csr) to this other machine (this can be done over an insecure channel such as email). Now sign the certificate with a command such as:

Check peer certificate against a Certificate Revocation List.

A CRL (certificate revocation list) is used when a particular key is compromised but when the overall PKI is still intact.

Suppose you had a PKI consisting of a CA, root certificate, and a number of client certificates. Suppose a laptop computer containing a client key and certificate was stolen. By adding the stolen certificate to the CRL file, you could reject any connection which attempts to use it, while preserving the overall integrity of the PKI.

The only time when it would be necessary to rebuild the entire PKI from scratch would be if the root certificate key itself was compromised.

but the connection will be allowed. If the optional dir flag is specified, enable a different mode where the crl-verify is pointed at a directory containing files named as revoked serial numbers (the files may be empty, the contents are never read). If a client requests a connection, where the client certificate serial number (decimal string) is the name of a file present in the directory, it will be rejected.

Set file to none to disable Diffie Hellman key exchange (and use ECDH only). Note that this requires peers to be using an SSL library that supports ECDH TLS cipher suites (e.g. OpenSSL 1.0.1+, or mbed TLS 2.0+).

This option is not supported in mbed TLS builds of OpenVPN.

Specify a file containing one or more PEM certs (concatenated together) that complete the local certificate chain.

This option is useful for «split» CAs, where the CA for server certs is different than the CA for client certs. Putting certs in this file allows them to be used to complete the local certificate chain without trusting them to verify the peer-submitted certificate, as would be the case if the certs were placed in the ca file.

Require that peer certificate was signed with an explicit extended key usage.

This is a useful security option for clients, to ensure that the host they connect to is a designated server.

The extended key usage should be encoded in oid notation, or OpenSSL symbolic representation.

If present in the certificate, the keyUsage value is validated by the TLS library during the TLS handshake. Specifying this option without arguments requires this extension to be present (so the TLS library will verify it).

If key-usage is a list of usage bits, the keyUsage field must have at least the same bits set as the bits in one of the values supplied in the key-usage list.

The key-usage values in the list must be encoded in hex, e.g.

Require that peer certificate was signed with an explicit key usage and extended key usage based on RFC3280 TLS rules.

This is a useful security option for clients, to ensure that the host they connect to is a designated server. Or the other way around; for a server to verify that only hosts with a client certificate can connect.

Add an additional layer of HMAC authentication on top of the TLS control channel to mitigate DoS attacks and attacks on the TLS stack.

Older versions (up to OpenVPN 2.3) supported a freeform passphrase file. This is no longer supported in newer versions (v2.4+).

The rationale for this feature is as follows. TLS requires a multi-packet exchange before it is able to authenticate a peer. During this time before authentication, OpenVPN is allocating resources (memory and CPU) to this potential peer. The potential peer is also exposing many parts of OpenVPN and the OpenSSL library to the packets it is sending. Most successful network attacks today seek to either exploit bugs in programs (such as buffer overflow attacks) or force a program to consume so many resources that it becomes unusable. Of course the first line of defense is always to produce clean, well-audited code. OpenVPN has been written with buffer overflow attack prevention as a top priority. But as history has shown, many of the most widely used network applications have, from time to time, fallen to buffer overflow attacks.

So as a second line of defense, OpenVPN offers this special layer of authentication on top of the TLS control channel so that every packet on the control channel is authenticated by an HMAC signature and a unique ID for replay protection. This signature will also help protect against DoS (Denial of Service) attacks. An important rule of thumb in reducing vulnerability to DoS attacks is to minimize the amount of resources a potential, but as yet unauthenticated, client is able to consume.

A list of allowable groups/curves in order of preference.

Set the allowed elliptic curves/groups for the TLS session. These groups are allowed to be used in signatures and key exchange.

mbedTLS currently allows all known curves per default.

OpenSSL 1.1+ restricts the list per default to

OpenVPN maps the curve name secp256r1 to prime256v1 to allow specifying the same tls-groups option for mbedTLS and OpenSSL.

Warning: this option not only affects elliptic curve certificates but also the key exchange in TLS 1.3 and using this option improperly will disable TLS 1.3.

Set the allowed cryptographic algorithms for certificates according to profile.

The following profiles are supported:

insecure Identical for mbed TLS to legacy legacy (default) SHA1 and newer, RSA 2048-bit+, any elliptic curve. preferred SHA2 and newer, RSA 2048-bit+, any elliptic curve. suiteb SHA256/SHA384, ECDSA with P-256 or P-384.

This option is only fully supported for mbed TLS builds. OpenSSL builds use the following approximation:

OpenVPN will migrate to ‘preferred’ as default in the future. Please ensure that your keys already comply.

A list l of allowable TLS ciphers delimited by a colon (» : «).

These setting can be used to ensure that certain cipher suites are used (or not used) for the TLS connection. OpenVPN uses TLS to secure the control channel, over which the keys that are used to protect the actual VPN traffic are exchanged.

The supplied list of ciphers is (after potential OpenSSL/IANA name translation) simply supplied to the crypto library. Please see the OpenSSL and/or mbed TLS documentation for details on the cipher list interpretation.

Encrypting (and authenticating) control channel packets:

Security Considerations

Use client-specific tls-crypt keys.

Run command cmd to verify the metadata of the client-specific tls-crypt-v2 key of a connecting client. This allows server administrators to reject client connections, before exposing the TLS stack (including the notoriously dangerous X.509 and ASN.1 stacks) to the connecting client.

OpenVPN supplies the following environment variables to the command:

The command can reject the connection by exiting with a non-zero exit code.

Sets the minimum TLS version we will accept from the peer (default is «1.0»).

Specify SHA1 or SHA256 fingerprint for level-1 cert.

The level-1 cert is the CA (or intermediate cert) that signs the leaf certificate, and is one removed from the leaf certificate in the direction of the root. When accepting a connection from a peer, the level-1 cert fingerprint must match hash or certificate verification will fail. Hash is specified as XX:XX. For example:

Accept connections only if a host’s X.509 name is equal to name. The remote host must also pass all other tests of verification.

would be matched by:

Using a name prefix is a useful alternative to managing a CRL (Certificate Revocation List) on the client, since it allows the client to refuse all certificates except for those associated with designated servers.

Field in the X.509 certificate subject to be used as the username (default CN ).

Typically, this option is specified with fieldname as either of the following:

Only the subjectAltName and issuerAltName X.509 extensions are supported.

PKCS#11 / SmartCard options

Set if access to certificate object should be performed after login. Every provider has its own setting.

Specify which method to use in order to perform private key operations. A different mode can be specified for each provider. Mode is encoded as hex number, and can be a mask one of the following:

0 (default) Try to determine automatically.

2 Use sign recover.

Use PKCS#11 protected authentication path, useful for biometric and external keypad devices. Every provider has its own setting.

(Standalone) Show PKCS#11 token object list.

Specify cert_private as 1 if certificates are stored as private objects.

If p11-kit is present on the system, the provider argument is optional; if omitted the default p11-kit-proxy.so module will be queried.

—verb option can be used BEFORE this option to produce debugging information.

Data channel cipher negotiation

OpenVPN 2.4 and higher have the capability to negotiate the data cipher that is used to encrypt data packets. This section describes the mechanism in more detail and the different backwards compatibility mechanism with older server and clients.

OpenVPN 2.5 and higher behaviour

AUTH: Received control message: AUTH_FAILED,Data channel cipher negotiation failed (no shared cipher)

OpenVPN 2.4 clients

OpenVPN 3 clients

OpenVPN 2.4 server

Blowfish in CBC mode (BF-CBC) deprecation

We strongly recommend to switching away from BF-CBC to a more secure cipher as soon as possible instead.

NETWORK CONFIGURATION

OpenVPN consists of two sides of network configuration. One side is the link between the local and remote side, the other side is the virtual network adapter (tun/tap device).

Link Options

This link options section covers options related to the connection between the local and the remote host.

If the optional ipv6only keyword is present OpenVPN will bind only to IPv6 (as opposed to IPv6 and IPv4) when a IPv6 socket is opened.

Enable internal datagram fragmentation so that no UDP datagrams are sent which are larger than max bytes.

—fragment adds 4 bytes of overhead per datagram.

It should also be noted that this option is not meant to replace UDP fragmentation at the IP stack level. It is only meant as a last resort when path MTU discovery is broken. Using this option is less efficient than fixing path MTU discovery for your IP link and using native IP fragmentation instead.

Having said that, there are circumstances where using OpenVPN’s internal fragmentation capability may be your only option, such as tunneling a UDP multicast stream which requires fragmentation.

The timeout argument will be twice as long on the server side. This ensures that a timeout is detected on client side before the server side drops the connection.

The usual symptom of such a breakdown is an OpenVPN connection which successfully starts, but then stalls during active usage.

Therefore, one could lower the maximum UDP packet size to 1300 (a good first try for solving MTU-related connection problems) with the following options:

Should we do Path MTU discovery on TCP/UDP channel? Only supported on OSes such as Linux that supports the necessary system call to set.

no Never send DF (Don’t Fragment) frames

maybe Use per-route hints

yes Always DF (Don’t Fragment)

This option has two intended uses:

when used on both peers will cause OpenVPN to exit within 60 seconds if its peer disconnects, but will exit after one hour if no actual tunnel data is exchanged.

This option is useful in cases where the remote peer has a dynamic IP address and a low-TTL DNS name is used to track the IP address using a service such as https://www.nsupdate.info/ + a dynamic DNS client such as ddclient.

OpenVPN is designed to operate optimally over UDP, but TCP capability is provided for situations where UDP cannot be used. In comparison with UDP, TCP will usually be somewhat less efficient and less robust when used over unreliable or congested networks.

This article outlines some of problems with tunneling IP over TCP: http://sites.inka.de/sites/bigred/devel/tcp-tcp.html

There are certain cases, however, where using TCP may be advantageous from a security and robustness perspective, such as tunneling non-IP or application-level UDP protocols, or tunneling protocols which don’t possess a built-in reliability layer.

Modify the replay protection sliding-window size and time window.

Use a replay protection sliding-window of size n and a time window of t seconds.

By default n is 64 (the IPSec default) and t is 15 seconds.

This option is only relevant in UDP mode, i.e. when either —proto udp is specified, or no —proto option is specified.

When OpenVPN tunnels IP packets over UDP, there is the possibility that packets might be dropped or delivered out of order. Because OpenVPN, like IPSec, is emulating the physical network layer, it will accept an out-of-order packet sequence, and will deliver such packets in the same order they were received to the TCP/IP protocol stack, provided they satisfy several constraints.

If you are using a network link with a large pipeline (meaning that the product of bandwidth and latency is high), you may want to use a larger value for n. Satellite links in particular often require this.

There is some controversy on the appropriate method of handling packet reordering at the security layer.

Namely, to what extent should the security layer protect the encapsulated protocol from attacks which masquerade as the kinds of normal packet loss and reordering that occur over IP networks?

The IPSec and OpenVPN approach is to allow packet reordering within a certain fixed sequence number window.

OpenVPN adds to the IPSec model by limiting the window size in time as well as sequence space.

OpenVPN also adds TCP transport as an option (not offered by IPSec) in which case OpenVPN can adopt a very strict attitude towards message deletion and reordering: Don’t allow it. Since TCP guarantees reliability, any packet loss or reordering event can be assumed to be an attack.

In this sense, it could be argued that TCP tunnel transport is preferred when tunneling non-IP or UDP application protocols which might be vulnerable to a message deletion or reordering attack which falls within the normal operational parameters of IP networks.

So I would make the statement that one should never tunnel a non-IP protocol or UDP application protocol over UDP, if the protocol might be vulnerable to a message deletion or reordering attack that falls within the normal operating parameters of what is to be expected from the physical IP layer. The problem is easily fixed by simply using TCP as the VPN transport layer.

Persist replay-protection state across sessions using file to save and reload the state.

This option will keep a disk copy of the current replay protection state (i.e. the most recent packet timestamp and sequence number received from the remote peer), so that if an OpenVPN session is stopped and restarted, it will reject any replays of packets which were already received by the prior session.

Apply the given flags to the OpenVPN transport socket. Currently, only TCP_NODELAY is supported.

The TCP_NODELAY socket flag is useful in TCP mode, and causes the kernel to send tunnel packets immediately over the TCP connection without trying to group several smaller packets into a larger packet. This can result in a considerably improvement in latency.

This option is pushable from server to client, and should be used on both client and server for maximum effect.

This macro sets the TCP_NODELAY socket flag on the server as well as pushes it to connecting clients. The TCP_NODELAY flag disables the Nagle algorithm on TCP sockets causing packets to be transmitted immediately with low latency, rather than waiting a short period of time in order to aggregate several packets into a larger containing packet. In VPN applications over TCP, TCP_NODELAY is generally a good latency optimization.

The macro expands as follows:

Virtual Network Adapter (VPN interface)

Options in this section relates to configuration of the virtual tun/tap network interface, including setting the VPN IP address and network routing.

For this option to make sense you actually have to route traffic to the tun interface. The following example config block would send all IPv6 traffic to OpenVPN and answer all requests with no route to host, effectively blocking IPv6 (to avoid IPv6 connections from dual-stacked clients leaking around IPv4-only VPN services).

Client config Server config

Push a «valid» ipv6 config to the client and block on the server

Note: this option does not influence traffic sent from the server towards the client (neither on the server nor on the client side). This is not seen as necessary, as such traffic can be most easily avoided by not configuring IPv6 on the server tun, or setting up a server-side firewall rule.

See examples section below for an example on setting up a TUN device.

You must use either tun devices on both ends of the connection or tap devices on both ends. You cannot mix them, as they represent different underlying network layers:

tun devices encapsulate IPv4 or IPv6 (OSI Layer 3) tap devices encapsulate Ethernet 802.3 (OSI Layer 2).

Set additional network parameters on supported platforms. May be specified on the client or pushed from the server. On Windows these options are handled by the tap-windows6 driver by default or directly by OpenVPN if dhcp is disabled or the wintun driver is in use. The OpenVPN for Android client also handles them internally.

Set primary domain name server IPv4 or IPv6 address. Repeat this option to set secondary DNS server addresses.

WINS address Set primary WINS server address (NetBIOS over TCP/IP Name Server). Repeat this option to set secondary WINS server addresses. NBDD address Set primary NBDD server address (NetBIOS over TCP/IP Datagram Distribution Server). Repeat this option to set secondary NBDD server addresses. NTP address Set primary NTP server address (Network Time Protocol). Repeat this option to set secondary NTP server addresses. NBT type

Set NetBIOS over TCP/IP Node type. Possible options:

1 b-node (broadcasts) 2 p-node (point-to-point name queries to a WINS server) 4 m-node (broadcast then query name server) 8 h-node (query name server, then broadcast). NBS scope-id Set NetBIOS over TCP/IP Scope. A NetBIOS Scope ID provides an extended naming service for the NetBIOS over TCP/IP (Known as NBT) module. The primary purpose of a NetBIOS scope ID is to isolate NetBIOS traffic on a single network to only those nodes with the same NetBIOS scope ID. The NetBIOS scope ID is a character string that is appended to the NetBIOS name. The NetBIOS scope ID on two hosts must match, or the two hosts will not be able to communicate. The NetBIOS Scope ID also allows computers to use the same computer name, as they have different scope IDs. The Scope ID becomes a part of the NetBIOS name, making the name unique. (This description of NetBIOS scopes courtesy of NeonSurge@abyss.com) DISABLE-NBT Disable Netbios-over-TCP/IP.

This option, while primarily a proxy for the ifconfig(8) command, is designed to simplify TUN/TAP tunnel configuration by providing a standard interface to the different ifconfig implementations on different platforms.

—ifconfig parameters which are IP addresses can also be specified as a DNS or /etc/hosts file resolvable name.

Configure an IPv6 address on the tun device.

This option will also silence warnings about potential address conflicts which occasionally annoy more experienced users by triggering «false positive» warnings.

Automatically execute routing commands to cause all outgoing IP traffic to be redirected over the VPN. This is a client-side option.

This option performs three steps:

When the tunnel is torn down, all of the above steps are reversed so that the original default route is restored.

Add route to routing table after connection is established. Multiple routes can be specified. Routes will be automatically torn down in reverse order prior to TUN/TAP device close.

This option is intended as a convenience proxy for the route(8) shell command, while at the same time providing portable semantics across OpenVPN’s platform space.

The network and gateway parameters can also be specified as a DNS or /etc/hosts file resolvable name, or as one of three special keywords:

This option is designed to be useful in scenarios where DHCP is used to set tap adapter addresses. The delay will give the DHCP handshake time to complete before routes are added.

Setup IPv6 routing in the system to send the specified IPv6 network into OpenVPN’s tun.

If dhcp is specified as the parameter, the gateway address will be extracted from a DHCP negotiation with the OpenVPN server-side LAN.

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.

mode can be one of:

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.

TUN/TAP standalone operations

(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.

On some platforms such as Windows, TAP-Win32 tunnels are persistent by default.

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

Move eth0 into vrf_external

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:

OpenVPN configuration

The OpenVPN configuration needs to contain this line:

Further reading

This talk from the Network Track of FrOSCon 2018 provides an overview about advanced layer 2 and layer 3 features of Linux

SCRIPTING INTEGRATION

OpenVPN can execute external scripts in various phases of the lifetime of the OpenVPN process.

Script Order of Execution

Executed after TCP/UDP socket bind and TUN/TAP open.

Executed when we have a still untrusted remote peer.

Executed after connection authentication, or remote IP address change.

Executed in —mode server mode immediately after client authentication.

Executed after connection authentication, either immediately after, or some number of seconds after as defined by the —route-delay option.

Executed right before the routes are removed.

Executed after TCP/UDP and TUN/TAP close.

SCRIPT HOOKS

Require the client to provide a username/password (possibly in addition to a client certificate) for authentication.

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.

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.

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.

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.

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.

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.

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.

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:

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.

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.

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.

Set a custom environmental variable name=value to pass to script.

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.

Set a custom environmental variable OPENVPN_name to value to pass to scripts.

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.

cmd should return 0 to allow the TLS handshake to proceed, or 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:

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.

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.

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.

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.

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 (‘_’).

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.

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).

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.

A set of variables which define each IPv6 route to be added, and are set prior to —up script execution.

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.

Management Interface Options

OpenVPN provides a feature rich socket based management interface for both server and client mode operations.

Enable a management server on a socket-name Unix socket on those platforms supporting it, or on a designated TCP port.

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.

If the client connection fails to connect or is disconnected, a SIGTERM signal will be generated causing OpenVPN to quit.

The optional parameters nopadding and pkcs1 signal support for different padding algorithms. See doc/mangement-notes.txt for a complete description of this feature.

Make OpenVPN forget passwords when management session disconnects.

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.

Loads an OpenVPN plug-in module.

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.

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.

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.

WARNING: Plug-ins may do deferred execution, meaning the plug-in will return the control back to the main OpenVPN process and provide the plug-in result later on via a different thread or process. OpenVPN does NOT support multiple authentication plug-ins where more than one plugin tries to do deferred authentication. If this behaviour is detected, OpenVPN will shut down upon first authentication.

Windows-Specific Options

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.

(Windows/OpenSSL Only) Load the certificate and private key from the Windows Certificate System Store.

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:

To select a certificate, based on certificate’s thumbprint:

The thumbprint hex string can easily be copy-and-pasted from the Windows Certificate Store GUI.

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:

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.

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.

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.

In general, end-users should never need to explicitly use this option, as it is automatically added by the OpenVPN service wrapper when a given OpenVPN configuration is being run as a service.

exit-event is the name of a Windows global event object, and OpenVPN will continuously monitor the state of this event object and exit when it becomes signaled.

The second parameter indicates the initial state of exit-event and normally defaults to 0.

Namely, the point-to-point endpoints used in TUN device emulation must be the middle two addresses of a /30 subnet (netmask 255.255.255.252).

Cause OpenVPN to sleep for n seconds immediately after the TAP-Win32 adapter state is set to «connected».

Set the Windows system directory pathname to use when looking for system executables such as route.exe and netsh.exe. By default, if this directive is not specified, OpenVPN will use the SystemRoot environment variable.

Standalone Debug Options

(Standalone) Show current IPv4 and IPv6 default gateway and interface towards the gateway (if the protocol in question is enabled).

For IPv6 this queries the route towards ::/128, or the specified IPv6 target address if passed as argument. For IPv4 on Linux, Windows, MacOS and BSD it looks for a 0.0.0.0/0 route. If there are more specific routes, the result will not always be matching the route of the IPv4 packets to the VPN gateway.

Advanced Expert Options

These are options only required when special tweaking is needed, often used when debugging or testing out special usage scenarios.

Set the size of the real address hash table to r and the virtual address table to v.

By default, both tables are sized at 256 buckets.

(Advanced) Change the PRNG (Pseudo-random number generator) parameters

Changes the PRNG to use digest algorithm alg (default sha1 ), and set nsl (default 16 ) to the size in bytes of the nonce secret length (between 16 and 64).

Set alg to none to disable the PRNG and use the OpenSSL RAND_bytes function instead for all of OpenVPN’s pseudo-random number needs.

OpenVPN uses the following algorithm to implement traffic shaping: Given a shaper rate of n bytes per second, after a datagram write of b bytes is queued on the TCP/UDP port, wait a minimum of (b / n) seconds before queuing the next write.

It should be noted that OpenVPN supports multiple tunnels between the same two peers, allowing you to construct full-speed and reduced bandwidth tunnels at the same time, routing low-priority data such as off-site backups over the reduced bandwidth tunnel, and other data over the full-speed tunnel.

Also note that for low bandwidth tunnels (under 1000 bytes per second), you should probably use lower MTU values as well (see above), otherwise the packet latency will grow so large as to trigger timeouts in the TLS layer and TCP connections running over the tunnel.

OpenVPN allows n to be between 100 bytes/sec and 100 Mbytes/sec.

Maximum number of output packets queued before TCP (default 64 ).

When OpenVPN is tunneling data from a TUN/TAP device to a remote client over a TCP connection, it is possible that the TUN/TAP device might produce data at a faster rate than the TCP connection can support. When the number of output packets queued before sending to the TCP socket reaches this limit for a given client connection, OpenVPN will start to drop outgoing packets directed at this client.

UNSUPPORTED OPTIONS

Options listed in this section have been removed from OpenVPN and are no longer supported

CONNECTION PROFILES

An OpenVPN client will try each connection profile sequentially until it achieves a successful connection.

—remote-random can be used to initially «scramble» the connection list.

Here is an example of connection profile usage:

First we try to connect to a server at 198.19.34.56:1194 using UDP. If that fails, we then try to connect to 198.19.34.56:443 using TCP. If that also fails, then try connecting through an HTTP proxy at 192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to connect through the same proxy to a server at 198.19.36.99:443 using TCP.

The following OpenVPN options may be used inside of a block:

A defaulting mechanism exists for specifying options to apply to all profiles. If any of the above options (with the exception of remote ) appear outside of a block, but in a configuration file which has one or more blocks, the option setting will be used as a default for blocks which follow it in the configuration file.

For example, suppose the nobind option were placed in the sample configuration file above, near the top of the file, before the first block. The effect would be as if nobind were declared in all blocks below it.

INLINE FILE SUPPORT

Each inline file started by the line

Here is an example of an inline file usage

SIGNALS

HOWTO

For a more comprehensive guide to setting up OpenVPN in a production setting, see the OpenVPN HOWTO at https://openvpn.net/community-resources/how-to/

PROTOCOL

Go here to download the latest version of OpenVPN, subscribe to the mailing lists, read the mailing list archives, or browse the SVN repository.

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

SEE ALSO

openvpn-examples (5), dhcpcd(8), ifconfig(8), openssl(1), route(8), scp(1) ssh(1)

NOTES

This product includes software developed by the OpenSSL Project (https://www.openssl.org/)

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 https://www.oberhumer.com/opensource/lzo/

COPYRIGHT

Copyright (C) 2002-2020 OpenVPN Inc This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.

VPN Setup Examples

We have updated some of the terminology associated with OpenVPN Cloud. Review the recent changes.

Overview In this document, we examine OpenVPN Cloud being used to meet the needs of a fictitious scenario. Owen is in charge of IT and Networking for a technical college. Owen is looking for a solution that does not require him to manage, install, and maintain servers to achieve the following: Provide staff and students […]

Secure Internet Access Admin Guide

This guide takes you through the process of securing internet traffic for your workforce. You can set up secure access to the public internet on the whole or to specific public resources. This illustration shows a high-level view of the concept of secure internet access. On the left, each user connects with the OpenVPN Connect […]

Remote Access Admin Guide

This guide takes you through the process of providing secure, remote access to your private networks and resources through OpenVPN Cloud. Your private resources can be located on cloud platforms (IaaS) or on-premises or both. You can quickly build a remote access solution for your employees who are connecting from various regions around the world. […]

This guide shows you how to set up OpenVPN Cloud DNS security and the DNS-based content filtering provided by Cyber Shield.

There are two options for properly configuring the OpenVPN Cloud service to work with your AWS private hosted zone. For both options, you must first reconfigure your OpenVPN Cloud DNS servers to use the IP address of the Amazon-provided DNS servers for your VPC.

This guides provides steps to set up a host with a domain name and multiple connectors, which you can use to load-balance user traffic to that domain name.

You can configure secure remote access to your private networks even when those LANs use overlapping private IP address ranges.

Establish an authenticated VPN connection to OpenVPN Cloud in order to gain HTTPS access to apps hosted on the private network, and a select set of internet sites.

You can route traffic to specific public internet domains through a VPN, which enables you to restrict sign ins to only those that originate from the public IP address of the VPN.

User Guide: Zero Trust Application Access

Follow the steps in this guide to set up zero trust application access, which means that in order to access your SaaS applications, users must connect to the VPN even when they are physically in the office.

Starting from the OpenVPN Connect app version 3.2, the application includes the OpenVPN Service binary that allows running a VPN connection as a system service. This guide provides steps to help you configure OpenVPN Connect as a Windows system service.

This document provides steps for you to secure your IoT communications across multiple networks, using the example of a network of video monitoring services.

Follow the steps in this guide to configure your VPN to allow role-based access control to your SaaS applications.

Follow the steps in this guide to set up networks with VPN egress to route traffic that has entered the VPN to destinations on the Internet.

This guide provides steps for configuring multiple connectors to improve the reliability of remote access across VPN regions.

Watch this video to learn about the inherent DNS security that OpenVPN Cloud provides.

Watch this video to learn about how OpenVPN Cloud can enable you to secure your RDP connections.

Using OpenVPN Cloud profile to configure DD-WRT

This guide provides information to enable you to make a decision on whether you want to use a router with DD-WRT firmware to connect to OpenVPN Cloud.

Using OpenVPN Cloud profile to configure pfSense

This guide provides information to enable you to make a decision on whether you want to use a pfSense router to connect to OpenVPN Cloud.

Using OpenVPN Cloud profile to configure OpenWrt

This guide provides information to enable you to make a decision on whether you want to use a router with OpenWrt firmware to connect to OpenVPN Cloud.

Connecting to a Windows Server 2016 network

This is a how-to guide to show the steps involved in networking a Windows-based office network to OpenVPN Cloud.

Follow the steps in this guide to learn how to set up your VPN to ensure secure, whitelisted access to your SaaS applications.

This guide provides information on how to use OpenVPN Cloud to set up remote access to private websites and other private services hosted on an AWS virtual private cloud.

Follow the steps in this guide to learn how to set up secure access to your organization’s private services.

This guide provides information on how OpenVPN Cloud secures DNS queries to guard against DNS-based attacks and exploits.

Follow the steps in this guide to learn how to create a full-mesh private network between two private networks and enable remote access to those networks, ensuring full site-to-site private connectivity.

Follow the steps in this guide to learn how to set up secure internet access for your users with a VPN egress network that acts as an internet gateway.

This guide provides a comprehensive set of steps to configure a VPN that meets a variety of needs including site-to-site networking, secure remote access, and more.