Developers Documentation



301 error for file:

User Tools

Site Tools


The OpenVPN server is a secure and cost effective way to provide road warrior VPN access to resources on the network. Unlike the PPTP VPN server, OpenVPN is more robust in getting through other firewalls and gateways.

An OpenVPN client is available at no cost for almost any OS (Windows, MacOS, iOS, GNU/Linux, Android) and form-factor (PC, Smartphone).


If your system does not have this app available, you can install it via the Marketplace.


Once installed, you can find this feature in the menu system at the following location:


Configuring the Server

Note for Active Directory Connector users.
The selected AD user must be a member of both the openvpn_plugin and user_certificates_plugin groups. See the Active Directory Connector documentation for details.

Security Certificates Information

Before you can configure OpenVPN, you may be directed to the Certificate Manager configuration page in the web-based administration tool. The information is required to create the necessary security certificates used in OpenVPN.

OpenVPN App menu

Firewall Warning

If the app does not detect the firewall being open for the “OpenVPN” service (UDP port 1194) and the “OpenVPN - TCP” service (TCP port 1194) it will show this warning screen. For normal operation with the client configurations you can download from the Webconfig (see further down the document), you will only need the “OpenVPN” service to be opened and not the “OpenVPN - TCP”.

Will open the firewall to the “OpenVPN” service (UDP port 1194) and the “OpenVPN - TCP” service (TCP port 1194).
Will take you to the Incoming Firewall app where you can selectively open and close the firewall.
will hide the firewall warning panel

If you are very security conscious, manually configure the firewall to open the OpenVPN service only then hide the warning


Automatic Configuration

The OpenVPN app has an automatic configuration feature that selects default settings based on your server's configuration. It will also update them if you make modifications to your server (eg. change LAN subnet).

Unless you are an advanced user, this feature should be left enabled. To disable the feature, click on in the information dialog.

If you have disabled Auto Configuration and want to re-enable it, edit the file /etc/clearos/openvpn.conf and change the “auto_configure” setting from “no” to “yes”. Then restart the app.

Internet Hostname

The Internet Hostname field is auto-populated using the server's Internet Hostname, set in the IP Settings app. This field entry should be a publicly available hostname that VPN users will use in their configuration as the VPN hostname to connect to. It is a key field and used in the client configuration file which you will download later on.

If you do not have your own domain, you can use the ClearOS domain where xxx is your Subdomain in the Dynamic DNS app

Internet Domain

The Internet Domain field is auto-populated using the server's Default Domain, set in the IP Settings app. This field has no function in OpenVPN and is for information only.

DNS Server

A DNS server to use while connected through the VPN. This setting can be useful if accessing locally addressed/internal hostnames (eg. hp-laserjet.lan). Like Internet domain, this field is populated from the DNS server settings on the IP Settings app.

WINS Server

Windows Internet Name Service (WINS) is a NetBIOS name resolution service that allows client computers to register their NetBIOS names and IP addresses in a dynamic, distributed database and to resolve the NetBIOS names of network resources to their IP addresses. If you have a Microsoft[TM] server (or another server running Samba) on the LAN providing WINS, you would want to override the auto-configuration settings and set this to the IP of the server providing this service.

If you are running Samba locally, the automatic configuration settings is fine. If you are not running Samba or a MS WINS server anywhere on the network, this setting is irrelevant and can safely be ignored.

Depending on your network configuration, you may need to specify the WINS settings in VPN client configuration.

App Policies

The allows you to add users to the openVPN User list.

it is better to give users access through the User Manager app because they also need to be enabled as a Security Certificates User

Configuration Tricks

Automatic Login in Windows

Sometimes it may be desirable to have a PC automatically on boot up without user intervention. This is almost like using an automatic PPTP connection when you let Windows remember the password. Something similar can be done with OpenVPN. In order to do this, in the .ovpn file comment out the line “auth-user-pass”. In ClearOS in /etc/openvpn/clients.conf comment out the line “plugin /usr/lib64/openvpn/plugin/lib/ openvpn”, then restart OpenVPN. In Windows go to the Services Manager (e.g. Windows+R > services.msc) and change the Startup Type for the OpenVPNService to Automatic. OpenVPN will now automatically connect to any profile it finds in the config folder, but only succeed where user/pass authentication has been disabled.

With automatic login, the connection is authenticated only by the certificates and at the moment there is no certificate revocation method available.

Routing all traffic through OpenVPN

Add a line:

push "redirect-gateway def1"


push "redirect-gateway def1 bypass-dhcp"

to /etc/openvpn/clients.conf then restart OpenVPN. The second form can get round an issue of the client PC renewing its local LAN DCHP lease.

Windows 10 DNS resolution always resolves to an external IP

Windows 10 introduced a horrible feature in its DNS resolution. It queries all DNS resolvers simultaneously and takes the first answer it gets. Invariably this will be from the external DNS servers rather than through the LAN. If you need the names to resolve to a LAN IP you have three choices:

1 - Use the method above to tunnel all traffic trough the VPN
2 - Edit the Windows hosts file so all LAN IP's resolve through it
3 - add the line

push "block-outside-dns"

to /etc/openvpn/clients.conf then restart OpenVPN. This will force all DNS traffic through the VPN.

Adding additional subnets to go through the tunnel

OpenVPN will normally only give you access to your standard LAN's. If there are other subnets you want access to as well (VLAN's, remote LAN's etc), add the additional subnets to the EXTRALANS parameter in /etc/clearos/network.conf in CIDR form, space separated, then restart OpenVPN. e.g.:

EXTRALANS=" 172.20.0/24"

Managing User Accounts

Users must be configured with both OpenVPN and Security Certificate access. To manage users:

  • Go to the Users page in the web-based administration tool
  • Edit a selected user
  • Make sure both OpenVPN User and Security Certificates User are enabled

If you are using the Active Directory Connector, the selected AD user must be a member of both the openvpn_plugin and user_certificates_plugin groups. See the Active Directory Connector documentation for details.

Configuring the Client

Configuration file and Certificates

This step is common for all operating systems.

Using the web-based administration tool, logout (if applicable) as 'root' once the basic settings and user configuration as outlined above have been achieved.

Login as the road warrior user account that is to have access to the network via OpenVPN.

User Login

Click on the username in the top-right corner and select 'User Certificates'.

User Certificates

Download the configuration file by selecting your operating system as the Configuration File client and click on the 'Download' button.

For Android, choose 'Linux'.
For iOS, choose 'MacOS'.

Download the following files into the same directory as the OpenVPN configuration file above:

  1. Certificate
  2. Certificate Authority
  3. Private Key

Resetting Certificates

If for any reason you want to generate new certificates, you can hit the button. You may want to do this, for example, if the user forgets his password for the PKCS12 file or the Administrator resets the ClearOS CA certificate.

Resetting the certificates does not invalidate the old ones.

Microsoft Windows[tm]

Download and install the OpenVPN client software from the OpenVPN download page. When the download is complete, double click the exe file that you downloaded to start the installation wizard. Windows will request permission to run the installer. Then you'll see the wizard start. Click Next to continue.

Click Next then Agree to the T's and Cs:

Install the recommended components

Allow OpenVPN to install in the default (recommended) path or select a location where you would like the installation files to reside.

You can safely ignore the Device Driver Installation warning…a virtual interface will be created through which, your VPN tunnels will connect. Click on the Install button.

Allow the wizard to continue through to completion. At the end of a successful install, you should see the following dialog. Click Next to continue

…. and Finish

OpenVPN will have created a desktop icon and a System Tray icon. If you choose the desktop icon it will just return a message that you have no valid configuration. You can configure OpenVPN manually by copying the four files you downloaded to the “config” folder under the OpenVPN folder where you chose to install the app (by default “C:\Program Files\OpenVPN\config”), or to “C:\Users\{user}\OpenVPN\config”. To have the config available to all users use the location under Program Files

If you imported the profile from the system tray icon, it will go into “%USERPROFILE%\OpenVPN\config” but you will need to copy your certificates there as well or you will need to use the “Alternative Method” in the Apple iOS section to assemble your certificates and keys into the .ovpn file before you import it.

Now you can start the tunnel either from the desktop icon if the system tray program is not running or from the system tray icon.

A progress dialog will be displayed, providing information on the status of the connection and a popup will appear asking for your ClearOS user name and password:

If all went according to plan, the connection dialogue will disappear and the system tray icon will change colour.

Ubuntu Linux

Download the Configuration file and Certificates as usual.

You may need the PKCS12 file containing the associated certificates instead of the individual Certificate and key files. The PKCS12 file will ask you to password protect the package the first time you use it. Don't forget this password…Your Ubuntu client will need it to extract the certificates later.

You're now done with the server/ClearOS. In Ubuntu's Network Manager, right click on the Network Manager, select Edit Connections, select the VPN tab, and click Import.

Network Manager Select the configuration file you saved earlier.

Ensure that the server hostname is accessible from outside your LAN (eg. it is not a local domain like network.lan).

Under Authentication, select type “Password with Certificates”. Populate the username and password fields with the user authentication credentials.

Under User Certificates, click on the file/folder icon and select the PKCS12 file you also downloaded from the ClearOS server. Enter the password used to authenticate the file.


Click on the Advanced button and ensure you check (enable) Use LZO Compression.

Click Apply. Your VPN settings should now be configured. It is good practice to test your connection (if possible) with the client still on the LAN. That way, if there are any problems, you have a narrow set of possibilities to troubleshoot against.

Click on the Network Manager link and select VPN Connections and the name of the VPN connection named from your ClearOS configuration.


If all goes well, you will see a lock appear on your Network Manager icon signifying the tunnel was successfully deployed.

Apple MacOS

Download the Configuration file and Certificates as usual.

Download and install the OpenVPN client software for Mac OS X from the Google Code.

Click on the Download Tunnelblick link.

Click on the latest Tunnelblick .dmg image to begin the download.

After double clicking on the dmg file you download, a dialog will open asking if you wish to proceed.

Once the application is successfully installed, you will get an pop-up notifying you. Either launch the application or find the application in your Applications folder using Finder and click on the Tunnelblick app.

When prompted with a question for config files, select I have configuration files.

Unless you are an advanced user, at the next dialog prompt, select Tunnelblick VPN Configuration.

After the step above, Tunnelblick will have created a folder for you, usually on our desktop named “Empty Tunnelblick Configuration” or something similar. Rename this folder so it is easily identifiable. Add your configuration file and certificates to this folder that you downloaded from ClearOS web-based administration tool's certificate manager.

Once done with the inline instructions, rename the folder and add the extension .tblk.

Double click on your new archive to install the configuration.

Select whether you want all users on the system access to this tunnel or just your current user.

You'll be notified that the configuration has been installed. Time to test the VPN connection.

In the upper right hand corner of your desktop, you'll see the Tunnelblick icon. Click on it once and select Connect XYZ where XYZ is the name of your OpenVPN configuration as set when you renamed the folder containing the configuration and certificates.

You'll see a status message displayed as OpenVPN attempts to connect to the ClearOS VPN server.

If all sent according to plan, you'll be notified that a connection has been made. An icon change will indicate when you are connected through the tunnel and when you are not.


There are many Android clients in the Play Store. The official one is the OpenVPN Connect app and this works fine. The OpenVPN for Android by Arne Schwabe is written by one of the OpenVPN Connect developers and has more advanced tweakable parameters.

You will need to transfer all four files (configuration and three certificates) to your Android device then import the ovpn file through OpenVPN Connect the menu.

Apple iOS

The official app is 'OpenVPN Connect' and this works fine.

Using iTunes

This method for loading profiles is not so neat and needs to be done through iTunes. Connect your iOS device to your PC/Mac and select the device in iTunes.

Then select the File Sharing menu on the left and the OpenVPN app in the Apps box. Then drag and drop all four files (configuration and three certificates) into the Documents box together.

In the OpenVPN app in iOS you will then see you have a message “1 new OpenVPN profile is available for import”. You can then import it and rename it as you wish. Refer to the 'Importing the VPN Profile in OpenVPN' found below the 'Alternative Method' instructions below.

Alternative Method

There is an alternative way of importing the profile information in iOS which is also compatible with Android and Windows, but it means manipulating the .ovpn file. It has the advantage of putting the certificates in a single file with the profile information and is therefore suitable for importing from an e-mail or browser.

If you are using Windows™ to edit the .ovpn file, the recommended application is 'Notepad++'.

From the ovpn file, remove the three lines:

ca ca-cert.pem
cert client-XXXX-cert.pem
key client-XXXX-key.pem

Your file should look something like this. Be sure that your 'hostname' is defined correctly. It should match the hostname used to access ClearOS.

remote [hostname] 1194
dev tun
proto udp
resolv-retry infinite
user nobody
group nobody
ns-cert-type server
verb 3

copy in the CA cert here from the downloaded ca file
copy in the user Cert here from the downloaded cert file but only the
certificate info between the BEGIN CERTIFICATE and END CERTIFICATE lines
copy in the Key here from the downloaded key file

Now you no longer need the separate certificate and key files. This alternative profile can be imported directly from an e-mail in iOS or, if you can put it in a location where you can browse to it, you can download it with the Safari browser.

Importing Configuration File into iOS

The instructions below are current as of iOS 10.3.3.

Open the OpenVPN configuration file from your email client or from Safari, then click on the Open button in the bottom-left corner of your screen.

Then scroll over to the 'Copy to OpenVPN' button and click on it.

Importing the VPN Profile in OpenVPN

In the OpenVPN app click on the '+' button to add the profile.

Then click 'Allow' on the popup dialog box. You'll then be asked to authenticate on iOS using your passcode, Touch ID, or Face ID.

Authenticate using the same roadwarrior username and password used on ClearOS. Then click on the slider switch to connect.

If it shows as 'Connected' but authentication fails, you've used an incorrect password. Just reenter the correct password and it should connect correctly.
If it shows as 'Connected' at this point, you'll know your configuration file was assembled correctly.
If it doesn't connect, you'll receive an error. You should then recheck your configuration file for errors.

Once connected, you should see the screen below. To disconnect, click the slider switch once more.

ChromeOS (ChromeBook)

The best instructions for configuring a ChromeBook for OpenVPN can be found here:OpenVPN on ChromeOS

Site to Site VPN Tunnels

This section has been moved to a separate document, Connecting Networks with OpenVPN


Log Files

OpenVPN is very verbose in its logging and logs of authentications and errors will be registered to the /var/log/messages log file on the ClearOS side. On the client side it will log what is happening in the details log of the client application. These logs, while very technical, are EXTREMELY helpful in determining issues with the connection. The OpenVPN team has done a fantastic job at creating precise logs which are often the last place you need to go to find out why you cannot connect.

Cannot connect to server

Go to the OpenVPN configuration page in the web-based administration tool Service Status and ensure the service is started. If the status says Stopped, click on the Start. If the services fails to start, you can get more information from the logs. The following log files may contain clues:

  • /var/log/messages
  • /var/log/system
  • /var/log/secure

Log file contents are available for display and/or download via the web-based administration tool. You will need to install (if you haven't done so already) the Log Viewer app from the Marketplace.

If the server is also your gateway to the Internet, navigate to Incoming Firewall and ensure the OpenVPN service is an allowed incoming firewall rule (port 1194).

Incoming Firewall

Windows LAN PC does not respond through tunnel

Sometime you will find you cannot ping a Windows device or connect to it through the tunnel. If this is the case, please check the Windows firewall. In many cases it is set by default to only allow in traffic from the local subnet and the OpenVPN subnet (default does not count as local. As an example, in the Windows firewall, look at the “File and Printer Sharing (Echo Request - ICMPv4-In)” rule and its “Scope” tab. You will see it only allows the “Remote IP address” to be “Local subnet” by default. You may need to modify those rules or create a blanket rule to also allow all traffic from the OpenVPN subnet.

It may also be able to change the settings via Group Policies - see under Local Computer Policy > Computer Configuration > Administrative Templates > Network > Network Connections > Windows Defender Firewall > Standard Profile or Domain Profile depending on your environment.

Alternatively you can use the following Custom Firewall rule:

$IPTABLES -t nat -I POSTROUTING -s your_openvpn_subnet -j MASQUERADE

Again, you get the OpenVPN subnet from /etc/openvpn/clients.conf.
The disadvantage of using this rule is that all connections to the Windows machine will appear to come from the ClearOS server and so you will not be able to log which machine is connecting.

Multi-WAN Environments

In some multi-WAN environments (eg. two external interfaces configured), OpenVPN can fail to connect from clients when the client configuration is using the default UDP. Check you have the line “multihome” in your /etc/openvpn/clients.conf. It is not needed in /etc/openvpn/clients-tcp.conf. If this does not work, try forcing the use of TCP protocol in the client, remembering to open the “OpenVPN - TCP” service (TCP:1194) in your firewall. You can do this by changing the “proto udp” line to “proto tcp” in the .ovpn file or sometimes through the GUI.


Connecting to a server with a Dynamic IP

If a server has a dynamic IP, for an IP change at the server to work seamlessly with the client, add a line “float” to the .ovpn file.


If you are having issues with DNS on your OpenVPN connection, it can be that you are using an external DNS server to resolve internal hosts or an internal which doesn't resolve external hosts. If you use the ClearOS gateway to resolve the DNS from its cache, you can split the resolution of external and internal domains using this guide.

VPN connects but no traffic passes

If your local and remote LAN subnets are the same or one is a subset of the other, then the VPN will establish bit no traffic will pass. For that reason it is best to avoid the and subnets on the ClearOS LAN as they are very common defaults on domestic routers.

Also avoid and as they clash with the default OpenVPN subnets (although these can easily be changed retrospectively).

If you can't change either of these then you can try forcing all traffic through OpenVPN by either adding the following to the client's .ovpn file:

redirect-gateway def1 bypass-dhcp

or add the following to /etc/openvpn/clients.conf then restart OpenVPN:

push "redirect-gateway def1 bypass-dhcp"

OpenVPN with Gateway Management/DNSThingy

There is a problem for OpenVPN users trying to access devices on the ClearOS LAN if the ClearOS LAN is protected by Gateway Management or DNSThingy with Don't Talk to Strangers (DTTS) enabled. The official DNSThingy solution is to go into the control panel then go Rules > Enablers (at the top) and add an enabler with the following in it:


Repeat the line for multiple LAN subnets. This will allow all TCP and UDP traffic through to the LAN, but it will not allow pings (ICMP) .

There is an alternative solution which will allow all traffic including ICMP. Create a file /etc/clearos/firewall.d/11-dnsthingy-DTTS-bypass (the name is irrelevant as long as it begins with a two digit number greater than 10) and put the following in it:

if [ "$FW_PROTO" == "ipv4" ]; then true
    CHECK=$($IPTABLES -nvL FORWARD --line-numbers| grep DNSthingyIPE | awk '{print $1}' 2>/dev/null)
    if [ -n "$CHECK" ]; then
        CHECK2=$($IPTABLES -nvL FORWARD --line-numbers| grep tun+ | awk '{print $1}' 2>/dev/null)
        if [ "$CHECK2" -gt "$CHECK" ]; then
            $IPTABLES -D FORWARD $CHECK                  # Delete default DNSthingyIPE rule
            $IPTABLES -I FORWARD $CHECK2 -j DNSthingyIPE # Add the DNSthingyIPE further down

Then restart the firewall with a:

service firewall restart

It is OK to use both solutions at the same time.

content/en_us/7_ug_openvpn.txt · Last modified: 2019/09/12 02:23 by nickh