Developers Documentation

×

Warning

301 error for file:https://clearos.com/dokuwiki2/lib/exe/css.php?t=dokuwiki&tseed=82873f9c9a1f5784b951644363f20ef8

User Tools

Site Tools


Hacking the Downloaded .OVPN File

Sometimes the downloaded configuration file for OpenVPN doesn't quite match the needs of your environment and needs to be modified after the download or before it is distributed. This Howto covers modification of the .ovpn file downloaded by the clients and not the OpenVPN .conf files used in configuring the server.

Topics discussed here should be considered a 'hack' as it is likely that a future app in the marketplace will displace this need for direct modification and will address this issue.

Modifying the .ovpn config file post download

There are some common reasons why a .ovpn file might need modification post download. These can include:

  • Hostname in .ovpn does not match a resolvable DNS name
  • Port does not match port forwarded by firewall to ClearOS gateway (uncommon)
  • Paths to cert, ca, and key files does not reside in an obvious directory to the client (ie. OpenVPN GUI, Tunnelblick)
  • Special parameters are required for your particular installation.

To make modifications to the file that you clients download before they download it will require command line manipulation of your ClearOS server. Moreover, it is a hack/tweak on the system that you should make note of because it will override the behavior of ClearOS and cause some functionality to disappear.

This change should only be enacted on systems where the client attaching to the system is the same OS type (ie. all clients are Macs or all clients are Windows). This modification ruins the pulldown customization for those operating systems and causes the file to be static forever more. This means that subsequent updates and upgrades will NOT change the file unless it is set to 'mutable' status.

Additionally, making these changes makes the certificates for your users to be mismatched in the config. Your users will either need to change the file to match the certificates that they download or rename the certificate and key file to match what is in the .ovpn file.

To start, open the .ovpn file with your text editor and change the parameters. The file is located in /var/clearos/framework/tmp and will be entitled after your system name (ie. server.system.lan.ovpn). What happens here is that when a client requests a config file, ClearOS dynamically overrides any temporary file in this directory and creates a new one. What we will do here is interrupt the process by modifying the file and making it immutable. So when the client request the file, ClearOS will try to overwrite our custom file and fail but will pass the immutable file.

After you save the file, you will make the file immutable to change. To see what parameters you might change and some specific help, please reference the next section. To make this file immutable after you edit it run the following (replacing the name 'server.system.lan' with the name of the file located in that directory):

chattr +i /var/clearos/framework/tmp/server.system.lan.ovpn

To revert the file to mutable, back up the file to a directory of your choice and reverse the process. This is important to do before version upgrades to ClearOS.

To make the file mutable again, run the following (replacing the name 'server.system.lan' with the name of the file located in that directory):

chattr -i /var/clearos/framework/tmp/server.system.lan.ovpn

Modifying the .ovpn config file post download

There are some common reasons why a .ovpn file might need modification pre-download. These can include:

  • Hostname in .ovpn does not match a resolvable DNS name
  • Port does not match port forwarded by firewall to ClearOS gateway (uncommon)
  • Special global parameters are required for your particular installation.

To make modifications to the file, open the .ovpn file with your text editor and change the parameters. After you save the file, you must restart your OpenVPN client. To see what parameters you might change and some specific help, please reference the next section.

Some parameters that may need customization

Here are some common parameters that individuals customize:

remote

The remote parameter is the name or IP address of the OpenVPN server. If your hostname is not resolvable by DNS then you will need to change this parameter to a valid value. For example:

remote server.system.lan 1194

Changed to:

remote myserver.mydomain.example.com 1194

Or…

remote myserver.example.poweredbyclear.com 1194

Or…

remote [external ip address] 1194

port

Rarely, users will have a different config file for clients that uses a different port or perhaps has the port forwarded which uses a different outside port than the default port of 1194 for the clients. In this case you can change the port number by modifying the number at the end of the remote line. For example:

remote myserver.mydomain.example.com 1194

Changed to…

remote myserver.mydomain.example.com 1195

Cert paths

Certificate paths can change, especially if you are using OpenVPN clients to connect to multiple sites. In order to do this you can create subdirectories in your config folder on your client for each of your sites. When you do this, it may not be obvious to the version of OpenVPN that you are using and you may need to create paths to your certs to keep things straight. The default config for the .ovpn files looks like this:

ca ca-cert.pem
cert client-username-cert.pem
key client-username-key.pem

Windows/OpenVPN GUI

In Windows, you can give the absolute path for the OpenVPN files but there is a catch. OpenVPN doesn't like backslashes (must be escaped with another backslash) and it also doesn't like spaces (must have quotes on the parameter if they exist). Let's say that your OpenVPN config file and certs are in the following directory:

C:\Program Files\OpenVPN\config\mynetwork\

Your ca, cert, and key file will then look like this in the .ovpn configuration file:

ca "C:\\Program Files\\OpenVPN\\config\\mynetwork\\ca-cert.pem"
cert "C:\\Program Files\\OpenVPN\\config\\mynetwork\\client-username-cert.pem"
key "C:\\Program Files\\OpenVPN\\config\\mynetwork\\client-username-key.pem"

Mac/Tunnelblick

In Tunnelblick, you can give the absolute path for the OpenVPN files but there is a catch. OpenVPN doesn't like spaces (must have quotes on the parameter if they exist). Let's say that your OpenVPN config file and certs are in the following directory:

/Users/User Name/Library/openvpn/My Network/

Your ca, cert, and key file will then look like this in the .ovpn configuration file:

ca "/Users/User Name/Library/openvpn/My Network/ca-cert.pem"
cert "/Users/User Name/Library/openvpn/My Network/client-username-cert.pem"
key "/Users/User Name/Library/openvpn/My Network/client-username-key.pem"

API changes to config files

Lastly, modifications to the API directly can change the behavior of your ClearOS implementation. The main piece of code which spits out the config files is contained in:

/usr/clearos/apps/openvpn/libraries/OpenVPN.php

… in the function called:

get_client_configuration()

Making the API portions immutable is NOT recommended as it will prevent updates to features and security

content/en_us/kb_o_hacking_the_downloaded_.ovpn_file.txt · Last modified: 2014/12/23 14:07 (external edit)

https://clearos.com/dokuwiki2/lib/exe/indexer.php?id=content%3Aen_us%3Akb_o_hacking_the_downloaded_.ovpn_file&1710820457