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