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.

Settings¶

The options for the package include:

OpenVPN Server¶

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 remote directive 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 remote directives 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 remote directives 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 remote directive in the client configuration.

Note

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.

Other:

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:: Uses the verify-x509-name directive 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.

Note

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.

Note

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.

Note

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.

Proxy Options¶

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

Advanced¶

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.

Tip

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.

Note

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.

Inline Configurations¶

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.

Tip

This format works well with Tunnelblick on macOS. Download the inline configuration and drag it into the configurations folder for Tunnelblick.
Android:: 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.

Bundled Configurations¶

Archive:: 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.

Windows Installers¶

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.

Viscosity Bundle¶

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.

Note

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.

Warning

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.