OpenVPN Client Export Package¶
The easiest way to configure an OpenVPN client on most platforms is to use the OpenVPN Client Export Package on pfSense® software.
Installing the Export Package¶
Install the OpenVPN Client Export Utility package as follows:
Navigate to System > Packages, Available Packages tab
Locate the OpenVPN Client Export package in the list
Click Install next to that package listing to install
Click Confirm to confirm the installation
Using the Export Package¶
Once installed, the package is located at VPN > OpenVPN, on the Client Export tab. That page presents several options which control the behavior of exported clients. The firewall can optionally save selections on this page as new defaults for future use.
The options for the package include:
- Remote Access Server
The OpenVPN server instance for which the package will export a client.
The list includes only Remote Access mode OpenVPN servers. If there is only one OpenVPN remote access server there will only be one choice in the list. The list will be empty if the firewall has no OpenVPN servers set to a Remote Access mode.
Client Connection Behavior¶
- Host Name Resolution
Controls the format of
remotedirective entries the package uses in client configuration files.
- Interface IP Address
Uses the OpenVPN server interface IP address directly.
This is typically the best choice for installations with a static IP address on WAN.
- Automagic Multi-WAN IPs
Searches all port forwards and automatically creates
remotedirectives for all port forwards that target the OpenVPN server interface address and port. It uses the destination IP address on the port forward in the
remotedirectives for the client configuration so the clients will use the correct external address(es).
This option is useful when redirecting connections using port forwards for deployments that utilize, multi-WAN, multiple ports on the same WAN, or servers which bind to Localhost.
- Automagic Multi-WAN DDNS Hostnames
Similar to the previous option, but instead of using IP addresses it uses the first Dynamic DNS entry it finds which matches the chosen destination.
This is useful if one or more of the WANs involved in OpenVPN has a dynamic IP address.
- Installation Hostname
Uses hostname assigned to the firewall at System > General Setup for the
remotedirective in the client configuration.
The hostname must exist in public DNS so clients can resolve it by name.
- Dynamic DNS Hostname Entries
The GUI includes entries in the selection list for each Dynamic DNS hostname in the firewall configuration.
These are typically the best choice for a server on a single WAN with a dynamic IP address.
Displays a Host Name field for a custom hostname or IP address.
This is useful when the firewall is behind one or more layers of NAT, which may make the external address difficult or impossible for the package to discover. It is also useful for situations where the firewall does not manage the DNS entry (static or dynamic) for a hostname.
- Verify Server CN
Controls how the client verifies the identity of the server certificate.
The package places the CN of the server certificate in the client configuration, so that if another valid certificate pretends to be the server with a different CN, it will not match and the client will refuse to connect.
- Automatic - Use verify-x509-name where possible
verify-x509-namedirective in OpenVPN to set a specific string the client will expect to match the common name on the server certificate.
- Do not verify the server CN
Disables client verification of the server certificate common name. This is not a secure, as the client will accept any server certificate signed by the CA.
- Block Outside DNS
Makes Windows 10 clients block access to DNS server except across OpenVPN while connected, forcing clients to use only VPN DNS servers.
This is only relevant on Windows 10 clients using OpenVPN version 2.3.9 and later as they are the only clients prone to leak DNS requests in this way. The option has no effect on other platforms and they will ignore the directive.
- Legacy Client
Controls whether the package uses OpenVPN 2.5.x and later directives in the configuration, or directives for older legacy clients.
When set, the package forms configurations using older options accepted by outdated clients such as OpenVPN 2.4.x and avoids newer directives only understood by current versions of OpenVPN.
- Silent Installer
When set, the package adds flags to the Windows installer which allows for silent and unattended client deployment.
The installer generated by the package is not signed. As such, deploying the installer executable may require special software.
- Use Random Local Port
Controls whether or not the client binds to a specific local port.
When checked, which is the best practice, the client will use a random source port. When unchecked, two OpenVPN connections cannot be run simultaneously on the client device as they would attempt to use the same port.
Some older clients do not support this option.
Certificate Export Options¶
- PKCS#11 Certificate Storage
Configures the client to use PKCS#11 storage device (e.g. cryptographic token, HSM, smart card) instead of local files.
- PKCS#11 Providers
The client-side path to PKCS#11 provider(s) files (e.g. DLL, module). Separate multiple entries with a space.
- PKCS#11 ID
The object ID on the PKCS#11 device.
- Use Microsoft Certificate Storage
Creates the installer in such a way that it places the CA and user certificate in Microsoft certificate storage rather than using inline entries or files directly.
- Use a password to protect the PKCS#12 file contents or key in Viscosity bundle
Controls whether or not the package protects the certificates and keys supplied to the client with a password.
When checked, the GUI displays fields to enter and confirm a password.
If the OpenVPN server requires user authentication this will cause users to see two different password prompts when loading the client: One to decrypt the keys and certificates and another for OpenVPN user authentication upon connecting.
- Use Proxy
If the client is located behind a proxy, check this options. The GUI displays several fields to configure the proxy. Supply a Proxy Type, IP Address, Port, and Proxy Authentication with credentials (if the proxy server requires authentication).
- Additional configuration options
Any extra custom OpenVPN directives for the package to include in the client configuration.
This is roughly equivalent to the Advanced options box on the OpenVPN configuration screens, but from the perspective of the client.
Save as default¶
The package does not save the settings on this page by default, so they must be set each time the package is used. The Save as default button stores the current package settings as new default values for future use.
OpenVPN Clients List¶
OpenVPN Clients contains a list of potential clients that the package can export. The contents of the list depend on the server configuration and which users and/or certificates are present on the firewall.
The following list describes how the server configuration style affects the list in the package:
- Remote Access (SSL/TLS)
The list contains entries for user certificates signed by the same CA as the OpenVPN server
- Remote Access (SSL/TLS + User Auth – Local Users)
The list contains entries for local users which also have an associated certificate signed by the same CA as the OpenVPN server.
This is the type of server configured by the OpenVPN wizard.
- Remote Access (SSL/TLS + User Auth – Remote Authentication)
The list contains user certificates signed by the same CA as the OpenVPN server. Because the users are remote, the package cannot determine the usernames, so the package assumes that the username is identical to the common name of the certificate.
- Remote Access (User Auth – Local Users or Remote Authentication)
The list contains a single configuration entry for all users since there are no per-user certificates or settings. Each client uses the same configuration.
The Search box above the client list filters the list to only entries which match a given string. This feature is particularly useful on firewalls with many clients, allowing administrators to quickly locate a specific entry.
If the list contains no entries, or if a specific entry is missing from the list, then either the user does not exist or the user does not have an appropriate certificate.
See Local Database for the correct procedure to create a user and certificate.
Client Install Package Types¶
Each client entry contains numerous options which export the configuration and associated files in different ways. Each choice accommodates a different potential type of client.
These choices export a single configuration file with the certificates and keys inline. This format is ideal for use on all platforms, especially Android and iOS clients, or for manually copying a configuration to a device which already has a client installed.
This option will work for any client type based on OpenVPN version 2.1 or newer.
- Most Clients
Exports a configuration which is usable by any standard OpenVPN client on platforms such as Windows, macOS, or BSD/Linux.
This format works well with Tunnelblick on macOS. Download the inline configuration and drag it into the configurations folder for Tunnelblick.
Exports a configuration for the Android OpenVPN client mentioned in Installing the OpenVPN Client on Android, which may support a different set of directives or omit certain features.
- OpenVPN Connect (iOS/Android)
Exports a configuration for the OpenVPN Connect client on iOS or Android described in Installing the OpenVPN Client on iOS.
Exports a ZIP archive containing the configuration file, the server TLS key (if it has one), and a PKCS#12 file which contains the CA certificate, client key, and client certificate. This option is usable with Linux clients, Tunnelblick, Windows, and many others when configuring the files manually.
- File Only
Exports only the basic configuration file, no certificates or keys. This would mainly be used to update the configuration file for systems which used the ZIP archive or executable installer before, without downloading the other associated files. For example, this is useful if the user authentication did not change but some aspect of the server configuration or package preferences is different.
The Windows installer options export a simple-to-use executable installer file which contains the OpenVPN client software plus the configuration data. The installer runs like the normal Windows OpenVPN client installer, but it also copies all of the settings and certificates the clients needs when it connects to the VPN.
See Installing the OpenVPN Client on Windows for notes on how to install and run the Windows client.
Currently, there are four options available:
- Current Windows Installer - 64-bit/32-bit
Export an installation bundle for the latest available version of the Windows OpenVPN client, currently version 2.5.x. The installer is available in 64-bit and 32-bit varieties. This is the best version to use where possible, and it works on Windows 11, Windows 10, and more.
- Legacy Windows Installer - 10/2016/2019
Export an installation bundle for the legacy version of the Windows OpenVPN client, currently version 2.4.x. This version is specific to Windows 10 and similar vintage versions of Windows.
- Legacy Windows Installer - 7/8/8.1/2012r2
Export an installation bundle for the legacy version of the Windows OpenVPN client, currently version 2.4.x. This version is specific to Windows 7/8.x and similar vintage versions of Windows.
Users must click next/finish all the way through the installation process. Do not click cancel or X out the installer at any step, as this can leave the client system with the client installed but without an imported configuration.
This exports the configuration similar to the archive method, but in a format used by the Viscosity OpenVPN client for macOS and Windows. Install the Viscosity client separately, then export this bundle and click it to import the configuration.
SIP Phone archives¶
The package can export configurations formatted for several popular VoIP phones which natively support OpenVPN. Notable examples are the Yealink T28 and T38G, and SNOM phones.
The process to install and configure OpenVPN on the phone varies by model, check the manufacturer documentation for more information.
The package only displays these options for OpenVPN servers set to SSL/TLS only without authentication.
The phone must have a proper clock setup and/or NTP server otherwise the certificates will fail to validate and the VPN will not connect.
Typically these handsets only support the use of SHA1 as a certificate hash. Ensure the CA, server certificate, and client certificates all use SHA1 or they may fail. They may also only support a limited set of encryption algorithms such as AES-128-CBC. Consult the phone documentation for details, and use the strongest possible combination of options.