OpenVPN
Traditionally, hardware routers use IPsec exclusively because it is easy to implement in hardware, and their CPUs lack sufficient power for software-based encryption. This limitation is less relevant for VyOS, as it is a software router.
OpenVPN has been widely used on UNIX platforms for a long time and is a popular choice for remote-access VPNs. It also supports site-to-site connections.
OpenVPN offers the following advantages:
It uses a single TCP or UDP connection and does not rely on packet source addresses, so it works even through double NAT. This makes it well-suited for public hotspots.
It is easy to set up and offers very flexible split tunneling.
A variety of client GUI frontends are available for any platform.
Disadvantages include:
It is slower than IPsec due to higher protocol overhead and because it runs in user mode, while IPsec on Linux runs in kernel mode.
No operating system includes OpenVPN client software by default.
In the VyOS CLI, OpenVPN is configured as a network interface using set
interfaces openvpn rather than set vpn, which is often overlooked.
Configuration
Configure the password for the auth-user-pass authentication method.
This option applies only to OpenVPN clients.
Configure the username for the auth-user-pass authentication method.
This option applies only to OpenVPN clients.
Configure the description for the OpenVPN interface.
Configure the virtual network device type for the OpenVPN interface:
tun(default): Operates at Layer 3, encapsulating IPv4 or IPv6 packets.tap: Operates at Layer 2, encapsulating Ethernet 802.3 frames.
Configure the static encryption cipher for the OpenVPN tunnel.
The cipher option maps to OpenVPN’s --cipher directive and specifies
the symmetric encryption algorithm for both control and data channels.
This was previously the default encryption method in all OpenVPN modes. In
newer OpenVPN versions, the --cipher directive is considered legacy
and should be used only in compatibility scenarios.
Configure a prioritized list of negotiated ciphers for OpenVPN in
client or server mode.
The data-ciphers option represents a list of supported encryption
algorithms. It corresponds to OpenVPN’s --data-ciphers directive and
enables cipher negotiation, where both peers automatically agree on a mutually
supported cipher during session startup.
Note
This option is not compatible with site-to-site mode.
Configure the fallback cipher for site-to-site mode.
The data-ciphers-fallback option maps to OpenVPN’s --data-ciphers-
fallback directive. It defines the cipher to use if negotiation is not
supported.
Note
This option ensures consistent encryption between two static peers without cipher negotiation capability.
Configure the hashing algorithm for the OpenVPN interface.
Configure the MSS advertised in outgoing TCP SYN packets on the specified interface.
By clamping the MSS value in TCP SYN packets, you explicitly inform the remote side not to send packets larger than that size. This prevents connection issues that occur when Path MTU Discovery (PMTUD) fails.
The following options are available:
mss: Sets the MSS to a specific value, in bytes. Use this option if you need to enforce a specific MSS, for example, to troubleshoot connectivity issues or accommodate specific network requirements.
clamp-mss-to-pmtu: The router automatically calculates the MSS to be the interface’s MTU minus 40 bytes for IPv4 traffic (20 bytes for the IPv4 header and 20 bytes for the TCP header). This option is recommended to automatically set the proper value.
Configure how long an ARP entry remains valid after learning an IP-to-MAC address mapping on this interface.
The default duration is 30 seconds.
An ARP entry remains valid if it receives positive feedback from higher-level protocols.
Example:
set interfaces openvpn vtun0 ip arp-cache-timeout 180
Configure ARP filtering on this interface.
Default behavior: The kernel responds to ARP requests on this interface only if the traffic would be routed back to the ARP sender through that specific interface.
If configured: The kernel responds to ARP requests on this interface for any IP address configured on the local host, regardless of which specific interface that IP address is assigned to, and regardless of the routing table. This reflects the Linux concept that IP addresses belong to the host, not individual interfaces.
Example:
set interfaces openvpn vtun0 ip disable-arp-filter
Configure the interface for host or router behavior.
If configured, the interface switches to host mode, and IPv4 forwarding is disabled on it.
Example:
set interfaces openvpn vtun0 ip disable-forwarding
Configure whether to forward IP-directed broadcast packets received on this interface.
Default behavior: IP-directed broadcast packets are dropped.
If configured: IP-directed broadcast packets are forwarded to all hosts on the destination subnet, as defined in RFC 1812 and RFC 2644.
Example:
set interfaces openvpn vtun0 ip enable-directed-broadcast
Configure how to process gratuitous ARPs on this interface.
If configured, an IP-to-MAC address mapping is added to the ARP table based on gratuitous ARP requests or replies.
Note
If the ARP table already contains the IP address from a gratuitous ARP, its entry is updated regardless of whether this setting is configured.
Example:
set interfaces openvpn vtun0 ip enable-arp-accept
Configure the source IP selection for ARP requests on this interface.
Default behavior: The kernel can use any IP address the host owns as the source IP address in ARP requests on this interface.
If configured: The kernel first attempts to select a source IP address configured on the interface that shares a common subnet with the target IP address. If there is no such subnet, the kernel selects the IP address it would normally use (based on the routing table to reach the target destination).
Example:
set interfaces openvpn vtun0 ip enable-arp-announce
Configure which ARP requests will be ignored on this interface.
Default behavior: The kernel responds to ARP requests for any local IP addresses, regardless of which interface they are assigned to.
If configured: The kernel responds to ARP requests only if the target IP address is assigned to this specific interface.
Example:
set interfaces openvpn vtun0 ip enable-arp-ignore
Configure proxy ARP on this interface.
If configured, the router (kernel) intercepts ARP requests for non-local IP addresses and replies with the MAC address of the interface that received the request. Subsequent packets destined to these IP addresses are forwarded to their actual destinations on remote subnets.
Example:
set interfaces openvpn vtun0 ip enable-proxy-arp
Configure local proxy ARP on the interface.
If configured, the router (kernel) responds to ARP requests on this VLAN interface even if the target IP address resides on the same subnet and interface.
This is used to support network isolation requirements (RFC 3069) for private VLANs (PVLANs). In PVLAN configurations, hosts on isolated ports are NOT allowed to communicate directly with each other at Layer 2, but they can communicate with the upstream router.
By replying to inter-host ARP requests with its own MAC address, the router (kernel) directs inter-host traffic through itself instead of directly between hosts.
Note
This command works independently and does not require enabling the standard proxy ARP on the interface.
Local proxy ARP is also known as:
VLAN aggregation (RFC 3069).
Private VLAN (Cisco, Allied Telesyn).
Source-port filtering or port isolation (Hewlett-Packard).
MAC-Forced Forwarding (Ericsson).
Configure source IP address validation using RPF on this interface, as specified in RFC 3704.
The following options are available:
strict: Each incoming packet’s source IP address is checked against the Forwarding Information Base (FIB). If the interface is not the best route back to that source, validation fails, and the packet is dropped.
loose: Each incoming packet’s source IP address is checked against the FIB. If the source IP address is unreachable through any interface, validation fails.
disable: No source IP address validation is performed. All incoming packets are accepted.
RFC 3704 recommends enabling strict mode to prevent IP spoofing, such as DDoS attacks. For asymmetric or other complex routing scenarios, use loose mode.
Configure the interface to automatically obtain an IPv6 address using SLAAC, as specified in RFC 4862.
IPv6 hosts can configure themselves automatically when connected to an IPv6 network using the Neighbor Discovery Protocol via ICMPv6 router discovery messages. When first connected to a network, a host sends a link-local router solicitation multicast request for its configuration parameters. The router responds with a router advertisement packet containing Internet Layer configuration parameters.
Note
This method automatically disables IPv6 traffic forwarding on the interface.
Example:
set interfaces openvpn vtun0 ipv6 address autoconf
Configure the interface to assign itself an IPv6 address using the EUI-64 method, as specified in RFC 4291.
Example:
set interfaces openvpn vtun0 ipv6 address eui64 2001:db8:beef::/64
Disable the automatic assignment of a link-local IPv6 address to this interface.
Example:
set interfaces openvpn vtun0 ipv6 address no-default-link-local
Configure the interface for host or router behavior.
If configured, the interface switches to host mode, and IPv6 forwarding is disabled on it.
Example:
set interfaces openvpn vtun0 ipv6 disable-forwarding
Configure the MSS advertised in outgoing TCP SYN packets on the specified interface.
By clamping the MSS value in TCP SYN packets, you explicitly inform the remote side not to send packets larger than that size. This prevents connection issues when Path MTU Discovery (PMTUD) fails.
The following options are available:
mss: Set the MSS to a specific value, in bytes. Use this option to enforce a specific MSS, for example, to troubleshoot connectivity issues or accommodate specific network requirements.
clamp-mss-to-pmtu: The router calculates the MSS to be the interface’s MTU minus 60 bytes for IPv6 traffic (40 bytes for the IPv6 header and 20 bytes for the TCP header). This option is recommended to automatically set the proper value.
Configure IPv6 DAD on the interface.
The following options are available:
0: Disables DAD. No duplicate address detection is performed.
1: Enables DAD (default). Duplicate addresses are detected. The interface’s IPv6 operation continues for valid IPv6 addresses.
2: Enables DAD and, if a MAC-based duplicate link-local address is found, disables IPv6 operation on this interface.
Example:
set interfaces openvpn vtun0 ipv6 accept-dad 2
Configure the number of DAD messages that the router (kernel) sends during IPv6 address assignment on this interface.
The default value is 1.
Example:
set interfaces openvpn vtun0 ipv6 dup-addr-detect-transmits 5
Configure the number of tolerated keepalive packet failures.
Default: 60 consecutive failures.
Configure the frequency, in seconds, at which keepalive packets are sent.
Default: 10 seconds.
Configure the local tunnel IP address for site-to-site mode.
Configure the local IP address to accept connections.
If configured, OpenVPN binds to this IP address only.
By default, OpenVPN binds to all interfaces.
Configure the local port to accept connections.
Configure mirroring of outgoing traffic from this OpenVPN interface to the designated monitor interface.
Configure mirroring of incoming traffic from this OpenVPN interface to the designated monitor interface.
Configure OpenVPN operation mode:
site-to-site: Establishes a site-to-site VPN connection.client: Operates as a client in server-client mode.server: Operates as a server in server-client mode.
OpenVPN Data Channel Offload (DCO)
OpenVPN DCO improves the performance of encrypted OpenVPN data processing by keeping most data handling in the kernel and avoiding frequent context switches between the kernel and user space.
As a result, packet processing becomes more efficient and may utilize hardware encryption offload support available in the kernel.
Note
DCO is an experimental, not fully supported OpenVPN feature. Some OpenVPN features and deployment scenarios are not compatible with DCO.
For a complete list of supported features, visit:
https://community.openvpn.net/openvpn/wiki/DataChannelOffload/Features
DCO is configured per tunnel and disabled by default. Existing tunnels operate without DCO unless it is explicitly enabled.
Enabling DCO resets the interface.
Best practice: Create a new tunnel with DCO enabled to avoid compatibility issues with existing clients.
Enable DCO for the specified OpenVPN interface.
Example:
set interfaces openvpn vtun0 offload dco
This command enables DCO and loads the required kernel module.
Add raw OpenVPN configuration options to the openvpn.conf file.
OpenVPN provides many configuration options, but not all are available in the VyOS CLI.
If a required option is missing, you may submit a feature request at Phabricator so all users can benefit from it (see Issues/Feature requests).
Alternatively, use openvpn-option to pass raw OpenVPN configuration options
to the openvpn.conf file.
Warning
Use this option only as a last resort. Invalid options or syntax may prevent OpenVPN from starting. Check system logs for errors after applying changes.
Example:
set interfaces openvpn vtun0 openvpn-option 'persist-key'
This command adds persist-key to the configuration file. This solves the
problem by persisting keys across resets, so they do not need to be re-read.
set interfaces openvpn vtun0 openvpn-option 'route-up "/config/auth/tun_up.sh arg1"'
This command adds route-up "/config/auth/tun_up.sh arg1" to the
configuration file. This option is executed after connection authentication,
either immediately or after a short delay, as defined.
Ensure the path and arguments are enclosed in single or double quotes.
Note
Some raw configuration options require quotes. To include them, use the " statement.
Enable always-active mode for the TUN/TAP device.
When enabled, the TUN/TAP device remains active upon connection resets or daemon reloads.
Configure the protocol for OpenVPN communication with a remote host:
udp(default): Uses the UDP protocol.tcp-passive: Uses the TCP protocol and accepts connections passively.tcp-active: Uses the TCP protocol and initiates connections actively.
Enable redirection of incoming packets to the specified interface.
Configure the remote tunnel IP address for site-to-site mode.
Configure the IPv4/IPv6 address or hostname for a server device if OpenVPN runs in client mode.
This setting is not used in server mode.
Configure the remote port to connect to the server.
Configure the OpenVPN tunnel as the default route.
Configure the gateway IP address.
Configure the first IP address in the pool to allocate to connecting clients.
Configure the last IP address in the pool to allocate to connecting clients.
Configure the subnet mask pushed to dynamic clients.
Configure the Common Name (CN) specified in the client certificate.
Configure the IPv4/IPv6 address for the client.
Configure a route to be pushed to the specific client.
Configure a fixed subnet to be routed from the server to the specified client.
Used as OpenVPN’s iroute directive.
Configure the first IP address in the subnet’s IPv4 pool to be dynamically allocated to connecting clients.
Configure the last IP address in the subnet’s IPv4 pool to be dynamically allocated to connecting clients.
Configure the subnet mask pushed to dynamic clients.
Use this command only for the TAP device type. Do not use it for bridged interfaces.
Configure the IPv6 address pool for dynamic assignment to clients.
Configure the DNS suffix to be pushed to all clients.
Configure the maximum number of client connections.
If enabled, openvpn-otp expects a password as a result of the challenge/ response protocol.
Configure the number of digits to use for the TOTP hash.
Default: 6.
Configure the time drift in seconds.
Default: 0.
Configure the allowed clock slop in seconds.
Default: 180.
Configure the step value for TOTP in seconds.
Default: 30.
Define the client DNS configuration to be used with the connection.
Configure the route to be pushed to all clients.
Reject connections from clients that are not explicitly configured.
Configure the IPv4 or IPv6 network.
This parameter is mandatory when operating in server mode.
Configure the virtual addressing topology for tun mode.
This command does not affect tap mode, which always uses the subnet
topology.
subnet(default): Allocates a single IP address to each connecting client. This is the recommended topology.net30: Allocates a /30 subnet to each connecting client. This is a legacy topology used to support Windows clients. It is now effectively deprecated.point-to-point: Creates a point-to-point topology where the remote endpoint of the client’stuninterface always points to the local endpoint of the server’stuninterface.Like
subnet, this topology allocates a single IP address per client. Use it only if no clients run Windows operating systems.
Configure the TLS secret key for tls-auth.
This adds an HMAC signature to all SSL/TLS handshake packets to verify integrity.
Use run generate pki openvpn shared-secret install <name> to generate
the key.
Configure the Certificate Authority chain in the PKI configuration.
Configure the certificate name in the PKI configuration.
Configure a shared secret key to provide an additional level of security, a variant similar to tls-auth.
Configure Diffie-Hellman parameters for server mode.
Configure the peer certificate SHA256 fingerprint for site-to-site mode.
Configure the TLS negotiation role, preferably used in site-to-site mode:
active: Initiates TLS negotiation actively.passive: Waits for incoming TLS connections.
Configure the minimum TLS version to be accepted from the peer.
Configure fast LZO compression on this TUN/TAP interface.
Operation mode
Examples
This section covers examples of OpenVPN configurations for various deployments.