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.
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.
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)
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
and may be omitted if it is the default. The protocol can be either
tcp, and optionally can end in
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
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.
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
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:
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
(24 hours) to make it once per day.
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¶
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 (
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.
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.
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
The following example adds a route for
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.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 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
def followed by the digit one, not the letter
To do the same for IPv6, use:
push "redirect-gateway ipv6";