Custom Configuration Options

OpenVPN offers a vast array of configuration options, many more than the most commonly used fields in the GUI. The Custom Options box enables using directives in OpenVPN which are not available directly in the GUI.

Warning

Each directive must be separated by a semicolon (;).

This section covers a few custom options users have found useful, but which are not common enough to add to the GUI. There are many more, and the OpenVPN man page details them all.

Warning

Exercise caution when adding custom options. The GUI cannot perform input validation on directives in this field. If an option is incorrect or invalid, the OpenVPN instance may not start.

View the OpenVPN logs under Status > System logs on the OpenVPN tab to ensure the options used are valid. Any invalid options will result in a log message, followed by the option that caused the error:

Options error: Unrecognized option or missing parameter(s)

Additional Servers

The remote <address> <port> <protocol> directive specifies servers to which a client can connect. This is primarily used on client instances to define multiple servers for redundancy. Clients will try the server defined in the GUI settings first and then any additional servers in the order given.

The address can be an IP address or FQDN. The port number defaults to 1194 and may be omitted if it is the default. The protocol can be either udp or tcp, and optionally can end in 4 or 6 to limit an FQDN server to either IPv4 or IPv6 respectively, if DNS contains records for both.

There are two primary strategies for which administrators use this type of configuration. One is for redundancy between multiple servers, and the other is for redundancy between multiple ports. The latter can be important for working around limitations on client networks, such as networks which only allow specific outbound ports. The two strategies can also be mixed as needed.

To specify multiple additional servers, consider a set of entries such as this:

remote vpn2.example.com 1194 udp4;
remote vpn3.example.com 1194 udp4;
remote vpn4.example.com 1194 udp4;

Contrast this with a set of servers which are crafted to work around network limitations:

remote vpn1.example.com 53 udp;
remote vpn1.example.com 123 udp;
remote vpn1.example.com 443 tcp;
remote vpn1.example.com 80 tcp;
remote vpn1.example.com 8080 tcp;

Another way the remote directive can be used is in the custom options of a peer-to-peer server instance (shared key or SSL/TLS with a tunnel network of /30). If both peers are defined as a server and each has a remote directive pointing to the other, then they will attempt connections in both directions and whichever connects first is used. This operates closer to IPsec where both peers can initiate. In practice this is not very useful as it’s typically better to have one designated initiator, but there may be a rare use case which calls for this behavior.

The remote-random directive tells clients to connect to a random server from the list instead of the next available choice. This is particularly useful when trying to load balance clients between multiple servers, such as with public VPN providers.

Renegotiation Time

The reneg-sec <seconds> directive controls how often OpenVPN renegotiates authentication with clients. The default time is 3600 seconds (one hour). In most cases the clients renegotiate and continue on without interruption, however with multi-factor authentication (MFA) this can disrupt clients. With MFA, clients would need to utilize a fresh token each time OpenVPN renegotiates the VPN, which can range from inconvenient to impossible. With MFA mechanisms such as OTP or Google Authenticator there is no mechanism to supply a new code, so the VPN disconnects after an hour and the client must manually reconnect.

In these cases, it is common for administrators to disable the renegotiation:

reneg-sec 0;

This is less secure, but more convenient than forcing users to reauthenticate once per hour.

Alternately, the time limit can be raised to a higher value which is less inconvenient, such as 28800 (8 hours) for a typical workday, or 86400 (24 hours) to make it once per day.

Recursive Routing

The allow-recursive-routing directive allows OpenVPN to send non-OpenVPN traffic to the VPN server itself over the VPN. Certain rare use cases call for this behavior where the VPN server and a public service are both hosted on the same server, but portions of the public service are only available to clients connecting over the VPN. OpenVPN used to allow this by default, but now it must be explicitly enabled by this directive.

Control Pushed Options

The push-remove <name> directive selectively filters options pushed by OpenVPN servers. This allows clients to ignore certain directives that would normally be sent by servers, such as routes (route or route-ipv6), keepalive/ping values, compression options, default gateway (redirect-gateway def1), DNS options, and more.

In a client-specific override context this can be used to skip pushing certain items to a specific client and then supply a new value in its place.

Routing options

Note

Using the custom option box is not necessary to add most routes. To add additional routes for a particular OpenVPN client or server, use the Local Network and Remote Network boxes, which support multiple networks as comma-separated lists.

The route custom configuration option adds routes locally for networks that are reachable through the VPN, but is not necessary in most cases as the GUI Remote Network fields for IPv4 and IPv6 accomplish the same goal. Some users prefer to enter the routes in this box instead, however. It can also be useful for cases where the routing is ambiguous, such as in bridged VPNs, to manually define specific routes with gateways that cannot be automatically determined by OpenVPN.

The following example adds a route for 10.50.0.0/24:

route 10.50.0.0 255.255.255.0;

To add a route with a specific gateway, add it after the netmask:

route 10.50.0.0 255.255.255.0 10.0.1.1;

To add multiple routes, separate them with a semicolon:

route 10.50.0.0 255.255.255.0;
route 10.254.0.0 255.255.255.0;

An OpenVPN server configuration using SSL/TLS in client/server mode can push additional routes to clients. The GUI can configure these using the Local Network field. To push the routes manually for 10.50.0.0/24 and 10.254.0.0/24 to all clients, use the following custom configuration option:

push "route 10.50.0.0 255.255.255.0";
push "route 10.254.0.0 255.255.255.0";

Note

Note the placement of the double quotes in these directives.

Redirecting the default gateway

OpenVPN can also redirect the default gateway to the VPN, so all non-local traffic from a client is sent through the VPN. This is great for untrusted local networks such as wireless hotspots, as it provides protection against numerous attacks that are a risk on untrusted networks. This is configurable in the GUI using the Redirect Gateway checkbox in the OpenVPN instance configuration.

To do this manually for IPv4, add the following custom option:

push "redirect-gateway def1";

The same value may be used as a custom option on the client side by entering redirect-gateway def1 without specifying push . (Note the option is the letters def followed by the digit one, not the letter L.)

To do the same for IPv6, use:

push "redirect-gateway ipv6";