Netgate is offering COVID-19 aid for pfSense software users, learn more.
OpenVPN Configuration Options¶
This section describes all of the available options with OpenVPN and when they are typically used. Subsequent sections cover examples of configuring site-to- site and remote access VPNs with OpenVPN, using the most common options and a minimal configuration.
Server Configuration Options¶
These options are available in one or more modes for OpenVPN server instances, managed from VPN > OpenVPN, on the Servers tab.
Disable this server¶
Check this box and click Save to retain the configuration, but not enable the server. The process for this instance will be stopped, and all peers/clients will be disconnected from this server. Any other active servers are unaffected.
This is the role for the server, which specifies how routers or users will connect to this server instance. Changing this will also affect what options will appear on the rest of the page, so only relevant choices are displayed.
- Peer to Peer (SSL/TLS)
A connection between local and remote networks that is secured by SSL/TLS. This choice offers increased security as well as the ability for the server to push configuration commands to the remote peer router when using a 1:many style setup. Remote peer routers can also have certificates revoked to remove access if they become compromised.
- Peer to Peer (Shared Key)
A connection between local and remote networks that is secured by a single Shared Key configured on both nodes. This choice is easier to setup, but is less secure. If a shared key is compromised, a new key must be generated and then copied to any router or client using the old shared key. In this mode, a separate server instance is needed for each client.
- Remote Access (SSL/TLS)
This choice is a mobile client setup with per-user X.509 certificates. As with the peer-to-peer SSL/TLS connection type, using this method offers increased security as well as the ability for the server to push configuration commands to clients. Mobile clients can also have keys revoked to remove access if a key is compromised, such as a stolen or misplaced laptop.
- Remote Access (User Auth)
A client access server that does not use certificates, but does require the end user to supply a username and password when making a connection. This is not recommended unless authentication is handled externally by LDAP or RADIUS.
- Remote Access (SSL/TLS + User Auth)
The most secure choice offered. Not only does it get the benefits of other SSL/TLS choices, but it also requires a username and password from the client when it connects. Client access can be removed not only by revoking the certificate, but also by changing the password. Also, if a compromised key is not immediately discovered, the danger is lessened because it is unlikely that the attacker has the keys and the password. When using the OpenVPN wizard, this is the mode which is configured during that process.
TCP or UDP may be selected, or their IPv6-enabled counterparts, TCP6 or UDP6. An OpenVPN server instance can currently only bind to either IPv4 or IPv6, but not both at the same time. UDP is the most reliable and fastest choice for running OpenVPN, and it should always be used when possible. In some rare cases TCP can be used to work around limitations, such as bypassing some firewalls by running an OpenVPN server on TCP port 443.
Connectionless protocols such as UDP are always preferable when tunneling traffic. TCP is connection oriented with guaranteed delivery, so any lost packets are retransmitted. This sounds like a good idea on the surface but TCP retransmissions will cause performance to degrade significantly on heavily loaded Internet connections or those with consistent packet loss.
TCP traffic frequently exists within tunnels and it is undesirable to retransmit lost packets of encapsulated VPN traffic. In cases where TCP is wrapped around TCP, such as a VPN tunnel using TCP as a transport protocol, when a packet is lost both the outer and inner lost TCP packets will be re-transmitted. Infrequent occurrences of this will be unnoticeable but recurring loss will cause significantly lower performance than UDP. If the traffic inside the tunnel requires reliable delivery, it will be using a protocol such as TCP which ensures that and will handle its own retransmissions.
OpenVPN can run in one of two device modes: tun or tap:
Works on OSI layer 3 and performs routing on point-to-point interfaces.
Can work at OSI layer 2 and can perform both routing and bridging if necessary.
Not all clients support tap mode, using tun is more stable and more widely supported. Specifically, clients such as those found on Android and iOS only support tun mode in the Apps most people can use. Some Android and iOS OpenVPN apps that require rooting or jailbreaking a device do support tap, but the consequences of doing so can be a bit too high for most users.
Selects the interface, VIP, or failover group that the OpenVPN server instance will listen upon for incoming connections. This also controls which interface the traffic from the server will exit.
Several types of options are listed in the drop-down for Interface, and some have special behavior or use cases:
OpenVPN will bind to the interface address. If the interface is dynamic, such as DHCP, OpenVPN will automatically bind to the new address if it changes.
OpenVPN will bind only to the specified VIP (IP Alias or CARP type)
- Gateway Groups
For use with failover groups, OpenVPN will bind to the address of the interface that is currently active in the group. If that interface gateway becomes unreachable, the next one will be used instead, and so on.
Useful for Multi-WAN deployments, binding to localhost and utilizing port forwards to accept connections from several interfaces and/or ports is a versatile way to provide redundant OpenVPN connectivity for connecting clients.
Binds to every address on every interface. Though tempting, this option is not recommended. When used with UDP, replies to Internet clients will always exit back out the default gateway WAN, which may be undesirable.
The local port is the port number OpenVPN will use to listen. Firewall rules need to allow traffic to this port and it must be specified in the client configuration. The port for each server must be unique for each interface.
Enter a description for this server configuration, for reference.
This section controls how traffic to and from clients is encrypted and validated.
TLS, or Transport Layer Security, provides session authentication to ensure the validity of both the client and the server. Check the box to Enable authentication of TLS packets if desired. If there is no existing TLS key, leave Automatically generate a shared TLS authentication key checked. If key already exists, uncheck that option and then paste it into the provided entry box. When generating the key automatically, return to the edit screen for this tunnel later to obtain the key which may be copied to the remote router or client.
When using an SSL/TLS mode, we strongly recommend using TLS Authentication as well. In addition to the added security benefit from the key requirement, a TLS key also helps protect against some SSL-based attacks such as Heartbleed.
Peer Certificate Revocation List¶
This optional field is for the Certificate Revocation List (CRL) to be used by this tunnel. A CRL is a list of certificates made from a given CA that are no longer considered valid. This could be due to a certificate being compromised or lost, such as from a stolen laptop, spyware infection, etc. A CRL can be created or managed from System > Cert Manager, on the Certificate Revocation tab.
A server certificate must be chosen for each OpenVPN server instance. If none appear in this list, first import or generate a certificate authority under System > Cert Manager, on the Certificates tab.
DH Parameters Length¶
The Diffie-Hellman (DH) key exchange parameters are used for establishing a secure communications channel. They may be regenerated at any time, and are not specific to an OpenVPN instance. That is, when importing an existing OpenVPN configuration these parameters do not need to be copied from the previous server. The length of the desired DH parameters may be chosen from the drop-down box, either 1024, 2048, or 4096.
Due to the heavy computation involved in generating DH keys, a pre- generated set for each key type is used. New DH parameters may be generated manually by using the following shell commands:
# /usr/bin/openssl dhparam 1024 > /etc/dh-parameters.1024 # /usr/bin/openssl dhparam 2048 > /etc/dh-parameters.2048 # /usr/bin/openssl dhparam 4096 > /etc/dh-parameters.4096
The cryptographic cipher to be used for this connection. The default is AES- 128-CBC, which is AES 128 bit Cipher Block Chaining. This is a fine choice for most scenarios.
Hardware Crypto for more information on using cryptographic accelerators and choosing an encryption algorithm.
Auth Digest Algorithm¶
Selects the message digest algorithm to use for HMAC authentication of incoming packets.
OpenVPN defaults to SHA1 when this option is not specified, so unless both sides are set to a known value, use SHA1 here.
If available, this option controls which hardware cryptographic accelerator will be used by OpenVPN. When left unspecified, OpenVPN will choose automatically based on what is available in the Operating System.
If this firewall device has a hardware cryptographic accelerator, choose BSD Cryptodev Engine, or select the specific device if it appears in the list. Most accelerator boards use the BSD cryptodev engine, so when in doubt, select that. This setting will allow OpenVPN to take advantage of the hardware acceleration. An encryption algorithm supported by the accelerator must also be selected. Refer to the hardware documentation for information on ciphers supported by the accelerator.
This option limits the length of a certificate chain before it fails validation. This defaults to One (Client+Server) so that if somehow an unauthorized intermediate CA is generated, certificates signed by the rogue intermediate would fail validation. In cases when chaining with intermediates is required, this limit can be raised.
Strict User-CN Matching¶
For SSL/TLS+User Authentication server, when enabled, this option enforces a match between the username supplied by the user and the Common Name of their user certificate. If the two do not match, the connection is rejected. This prevents users from using their own credentials with another person’s certificate and vice versa.
The tunnel settings section governs how traffic flows between the server and clients, including routing and compression.
IPv4/IPv6 Tunnel Network¶
These are the pools of addresses to be assigned to clients upon connecting. The server’s end of the OpenVPN configuration will use the first address in this pool for its end of the connection, and assign additional addresses to connected clients as needed. These addresses are used for direct communication between tunnel endpoints, even when connecting two existing remote networks. Any subnet may be chosen provided that it is not in use locally or at any remote site. One or both of IPv4 Tunnel Network and IPv6 Tunnel Network may be entered, or in the case of a tap bridge, neither.
Currently, limitations in OpenVPN itself prevent running with only an IPv6 Tunnel Network configured. When an IPv6 Tunnel network is defined, an IPv4 Tunnel Network must also be specified, even if it is not used.
For a site-to-site SSL/TLS server using IPv4, the IPv4 Tunnel Network size
can alter how the server behaves. If
x.x.x.x/30 is entered for the IPv4
Tunnel Network then the server will use a peer-to-peer mode much like Shared
Key operates: It can only have one client, does not require client-specific
overrides or iroutes, but also cannot push routes or settings to clients. If
an IPv4 Tunnel Network larger than that is used, such as
server will accept multiple clients and can push settings, but does require
See Site-to-Site Example Configuration (SSL/TLS) for more information on a site-to-multi-site example using a large tunnel network and iroutes.
When using tap mode, additional options are shown that control bridging behavior in OpenVPN and client address assignment. These are covered in Bridged OpenVPN Connections
When the Redirect Gateway option is selected the server will push a message to clients instructing them to forward all traffic, including Internet traffic, over the VPN tunnel. This only works in SSL/TLS modes with a tunnel network larger than a /30 subnet.
IPv4/IPv6 Local network¶
These fields specify which local networks are reachable by VPN clients, if any.
A route for these networks is pushed to clients connecting to this server. If
multiple routes for subnets of a particular family are needed, enter the subnets
separated by a comma, e.g.
This function relies upon the ability to push routes to the client, so for IPv4
it is only valid in an SSL/TLS context when a tunnel network larger than a
/30 is in use. It will always work for IPv6 provided a similar too-small
mask isn’t set.
IPv4/IPv6 Remote Network¶
This option only appears when a Peer-to-Peer type connection is used, and is not
available for mobile clients. Routes table entries are added to the firewall
for the specified subnets, which hand the traffic over to this OpenVPN instance
for processing. If more than one Remote network subnet is needed, enter the
subnets separated by a comma, e.g.
Specifies the number of clients that may be simultaneously connected to this OpenVPN server instance at any given time. This is a collective limit for all connected clients, not a per-user setting.
When compression is enabled, traffic crossing the OpenVPN connection will be compressed before being encrypted. This saves on bandwidth usage for many types of traffic at the expense of increased CPU utilization on both the server and client. Generally this impact is minimal, and enabling compression is beneficial for nearly any usage of OpenVPN over the Internet.
For high speed connections, such as the usage of OpenVPN across a LAN, high speed low/latency WAN, or local wireless network, this may be undesirable, as the delay added by the compression may be more than the delay saved in transmitting the traffic. If nearly all of the traffic crossing the OpenVPN connection is already encrypted (such as SSH, SCP, HTTPS, among many other protocols), do not enable LZO compression because encrypted data is not compressible and the LZO compression will cause slightly more data to be transferred than would be without compression. The same is true if the VPN traffic is almost entirely data that is already compressed.
This selector controls the handling of LZO compression for this OpenVPN instance. There are four possible settings each with slightly different behavior.
- No Preference
Omits the compression directives from the OpenVPN configuration entirely. No compression will be performed, but this may be overridden by other methods such as Client-Specific overrides or advanced options.
- Disabled - No Compression
Explicitly disables compression in the configuration
- Enabled with Adaptive Compression
Enables compression with a periodic test to ensure the traffic is able to be compressed. If compression is not optimal, it will be disabled until it is tested again. This option strikes the best balance since it will compress data when it will help, but does not compress data when it is hindering performance.
- Enabled without Adaptive Compression
Explicitly enables compression to be on at all times without testing the traffic.
When this option is enabled OpenVPN will set the Type-of-Service (TOS) IP header value of tunnel packets to match the encapsulated packet value. This may cause some important traffic to be handled faster over the tunnel by intermediate hops, at the cost of some minor information disclosure.
The most common example is VoIP or video traffic. If the TOS bit is set to reflect the priority of the traffic it can help QoS along the path, but someone intercepting the traffic could see the TOS bit and gain some knowledge about the contents of the traffic inside the tunnel. For those who rely on TOS bits for QoS, the benefit may outweigh the information leak.
This option controls whether or not connected clients are able to communicate with one another. To allow this behavior, check the option. When unchecked, clients can only send traffic to the server or destinations beyond the server such as routed networks or the Internet.
Typically in remote access style deployments it is unnecessary for clients to reach each other, but there are some corner cases when it can be helpful. One example is remote web developers working together and running test servers on their local systems. With this option activated, they can reach the other test serves for collaborative development.
By default OpenVPN will associate an IP address from its tunnel network with a specific certificate or username for a given session. If the same certificate connects again, it would be assigned the same IP address and either disconnect the first client or cause an IP conflict where neither client will receive proper data. This is primarily for security reasons so the same certificate cannot be used by multiple people simultaneously. We recommend a unique certificate be used for each connecting user. Otherwise if a client is compromised there is no way to revoke that one client alone, certificates would need to be reissued to all clients that share the same certificate.
If a setup that uses the same certificate in multiple locations is an absolute requirement and cannot be avoided, check Duplicate Connections to allow the non-standard behavior of multiple clients using the same certificate or username.
When checked, IPv6 traffic forwarding is disabled for this OpenVPN instance.
These settings pertain to how clients connecting to this sever instance will behave.
Checking this box adds the float configuration option to the OpenVPN configuration. This allows clients to retain their connection if their IP address changes. similar to MOBIKE for IKEv2 in IPsec. For clients on Internet connections where the IP changes frequently, or mobile users who commonly move between different Internet connections, check this option to allow for stable connectivity. Where the client IP is static or rarely changes, not using this option offers a small security improvement.
When this option is enabled the server will assign virtual adapter IP addresses to clients from the subnet specified by the Tunnel Network option. When unchecked IP addresses will not be assigned automatically and clients will have to set their own static IP addresses manually in their client configuration files. Except in rare cases, this is almost always enabled.
By default OpenVPN on pfSense® software version 2.3 and later prefers a topology style of subnet when using a Device Mode of tun. This style allocates only one IP address per client rather than an isolated subnet per client. This is the only available style when using the tap Device Mode.
When the older net30 topology for tun is chosen, OpenVPN allocates a /30 CIDR network (four IP addresses, two usable) to each connecting client. This style has a longer history, but can be confusing for administrators and users alike.
The Topology option is relevant only when supplying a virtual adapter IP address to clients using tun mode on IPv4. Some clients may require this even for IPv6, such as OpenVPN Connect, though in reality IPv6 always runs with a subnet topology even when IPv4 uses net30. OpenVPN version 2.1.3 or newer is required to use a subnet topology, and there were significant fixes to it in OpenVPN 2.3 as well, so using a current OpenVPN client version is important.
The default in pfSense has been changed to subnet because the OpenVPN project has declared the net30 style as deprecated, indicating it will be removed in future versions.
Be aware, however, that some very old clients may break if this option is used, such as older versions of OpenVPN (Before 2.0.9, released nearly 10 years ago), Windows versions with older tun/tap drivers, or clients such as Yealink phones. Always make sure the client and associated drivers are fully up-to-date when using a subnet topology.
DNS Default Domain¶
When checked, a field will appear to specify the DNS domain name to be assigned to clients. To ensure name resolution works properly for hosts on the local network where DNS name resolution is used, specify the internal DNS domain name here. For Microsoft Active Directory environments, this would usually be the Active Directory domain name.
When checked, up to four DNS servers may be entered for use by the client while connected to the VPN. For Microsoft Active Directory environments, this is typically the Active Directory Domain Controllers or DNS servers for proper name resolution and authentication when connected via OpenVPN.
Force DNS Cache Update¶
When checked, this option will push a set of commands to Windows clients that will flush their DNS and restart caching to improve client handling of updated DNS servers from the VPN.
When checked, one or two NTP servers may be set for syncing clocks on clients. It can be an IP address or FQDN.
When Enable NetBIOS over TCP/IP is checked, several other NetBIOS and WINS related options will appear. If the box is unchecked, these settings will be disabled.
The NetBIOS node type controls how Windows systems will function when resolving NetBIOS names. It’s usually fine to leave this to none to accept Windows’ default.
The available options include:
Use broadcasts for NetBIOS name resolution. This would not be used except in the case of a tap bridge.
Point-to-point name queries to a WINS server. WINS has been mostly deprecated, so this option is not useful in modern Windows networks.
Broadcast then query name server. Similar to b-node but will fall back to DNS.
Query name server first, then use broadcast. This option is the most likely to succeed in a current network with proper, functional, DNS.
A NetBIOS Scope ID provides an extended naming service for NetBIOS over TCP/IP. The NetBIOS scope ID isolates NetBIOS traffic on a single network to only those nodes with the same NetBIOS scope ID.
Checking this box allows two WINS servers to be defined which provides name resolution for clients accessing and browsing NetBIOS resources across the VPN. WINS has been largely deprecated and removed from use, so it’s unlikely this will be needed in most modern environments.
Enable Custom Port¶
When checked, a non-default Management Port may be specified for use with the OpenVPNManage feature of the OpenVPN Client Export package. If multiple connections profiles are used on a single client using that interface, each must use a unique management port.
While the pfSense web interface supports the most commonly used options, OpenVPN is very powerful and flexible and occasionally options that are unavailable in the web interface may be necessary. Such custom options may be added in using this entry box. These options are described further in Custom configuration options.
Configures the amount of detail shown in the OpenVPN logs for this instance, useful for troubleshooting problems. Higher numbers will result in higher amounts of detail in the log. During normal operation the default selection is best.
When set to higher levels, the OpenVPN status page and dashboard widget will cause additional logging as they interact with the Management process to poll information from the OpenVPN daemons.
Client Configuration Options¶
These options are available in one or more modes for OpenVPN client instances, managed from VPN > OpenVPN, on the Clients tab.
Many of these options are identical to the server options mentioned above, so only differences will be noted.
For client instances, the server mode choices are limited to Peer to Peer (SSL/TLS) and Peer to Peer (Shared Key), which pair with the server options of the same name and type.
This option selects the interface, VIP, or failover group that the OpenVPN client instance will use for outgoing connections.
When a CARP type VIP is selected for the Interface on OpenVPN Client instances, the OpenVPN instance will be stopped when the CARP VIP is in a backup state. This is done to prevent the secondary HA node from maintaining invalid routes or attempting to make outbound connections which can interfere with the active connection on the primary HA node.
For clients, the local port is left blank in nearly every case so that a randomized local port will be used. This is more secure, but some implementations may require a specific source port. If a specific source port is required, fill it in as needed as needed.
Server host or address¶
The IP address or fully qualified domain name for the server.
The port on which the server is listening, typically
- Proxy Host or Address
The IP address or fully qualified domain name for a proxy server through which this client must connect.
- Proxy Auth Extra Options
Extra authentication options. When set to basic or ntlm, Username and Password fields are presented so that proxy authentication may be configured.
Server Hostname Resolution¶
When Infinitely Resolve Server is checked, the server host name will be resolved on each connection attempt. When unchecked, OpenVPN will only attempt to resolve it once. When using a hostname for the remote server address, this option should be checked.
User Authentication Settings¶
When using Peer to Peer SSL/TLS mode, a Username and Password may be specified in addition to, or instead of, a user certificate, depending on the requirements configured on the server.
The settings in this section are identical to those on their corresponding options on the server side except for the new Client Certificate option, where the certificate is selected for use by this client. This certificate (and the associated key, and CA Certificate) must be imported to this firewall before they can be chosen.
Limit Outgoing Bandwidth¶
The value in this box, specified in bytes per second, is used to limit the speed of outgoing VPN traffic. When left blank, there is no limit. The value must be between 100 and 100000000.
Don’t Pull Routes¶
When checked, the client will ignore routes pushed from the server. This is useful in cases when the server pushes a default gateway redirect when this client does not need one.
Don’t Add/Remove Routes¶
When checked, OpenVPN will not manage route table entries for this VPN. In this
case, they must be managed manually. The routes that would normally be added are
instead passed to
--route-upscript using environmental variables.