OpenVPN
Traditionally hardware routers implement IPsec exclusively due to relative ease of implementing it in hardware and insufficient CPU power for doing encryption in software. Since VyOS is a software router, this is less of a concern. OpenVPN has been widely used on the UNIX platform for a long time and is a popular option for remote access VPN, though it’s also capable of site-to-site connections.
Advantages of OpenVPN are:
It uses a single TCP or UDP connection and does not rely on packet source addresses, so it will work even through a double NAT: perfect for public hotspots and such
It’s easy to setup and offers very flexible split tunneling
There’s a variety of client GUI frontends for any platform
Disadvantages are:
It’s slower than IPsec due to higher protocol overhead and the fact it runs in user mode while IPsec, on Linux, is in kernel mode
None of the operating systems have client software installed by default
In the VyOS CLI, a key point often overlooked is that rather than being configured using the set vpn stanza, OpenVPN is configured as a network interface using `set interfaces openvpn.
Configuration
Provide a password for auth-user-pass authentication method (client-only option)
Provide a username for auth-user-pass authentication method (client-only option)
set description <text> for openvpn interface being configured
tun- devices encapsulate IPv4 or IPv6 (OSI Layer 3), default valuetap- devices encapsulate Ethernet 802.3 (OSI Layer 2).
cipher- Standard Data Encryption Algorithmdata-ciphers- Cipher negotiation list for use in server or client mode
As Internet wide PMTU discovery rarely works, we sometimes need to clamp our TCP MSS value to a specific value. This is a field in the TCP options part of a SYN packet. By setting the MSS value, you are telling the remote side unequivocally ‘do not try to send me packets bigger than this value’.
Note
This command was introduced in VyOS 1.4 - it was previously called:
set firewall options interface <name> adjust-mss <value>
Hint
MSS value = MTU - 20 (IP header) - 20 (TCP header), resulting in 1452 bytes on a 1492 byte MTU.
Instead of a numerical MSS value clamp-mss-to-pmtu can be used to automatically set the proper value.
Once a neighbor has been found, the entry is considered to be valid for at least for this specific time. An entry’s validity will be extended if it receives positive feedback from higher level protocols.
This defaults to 30 seconds.
Example:
set interfaces openvpn vtun0 ip arp-cache-timeout 180
If set the kernel can respond to arp requests with addresses from other interfaces. This may seem wrong but it usually makes sense, because it increases the chance of successful communication. IP addresses are owned by the complete host on Linux, not by particular interfaces. Only for more complex setups like load-balancing, does this behaviour cause problems.
If not set (default) allows you to have multiple network interfaces on the same subnet, and have the ARPs for each interface be answered based on whether or not the kernel would route a packet from the ARP’d IP out that interface (therefore you must use source based routing for this to work).
In other words it allows control of which cards (usually 1) will respond to an arp request.
Example:
set interfaces openvpn vtun0 ip disable-arp-filter
Configure interface-specific Host/Router behaviour. If set, the interface will switch to host mode and IPv6 forwarding will be disabled on this interface.
set interfaces openvpn vtun0 ip disable-forwarding
Define different modes for IP directed broadcast forwarding as described in RFC 1812 and RFC 2644.
If configured, incoming IP directed broadcast packets on this interface will be forwarded.
If this option is unset (default), incoming IP directed broadcast packets will not be forwarded.
set interfaces openvpn vtun0 ip enable-directed-broadcast
Define behavior for gratuitous ARP frames whose IP is not already present in the ARP table. If configured create new entries in the ARP table.
Both replies and requests type gratuitous arp will trigger the ARP table to be updated, if this setting is on.
If the ARP table already contains the IP address of the gratuitous arp frame, the arp table will be updated regardless if this setting is on or off.
set interfaces openvpn vtun0 ip enable-arp-accept
Define different restriction levels for announcing the local source IP address from IP packets in ARP requests sent on interface.
Use any local address, configured on any interface if this is not set.
If configured, try to avoid local addresses that are not in the target’s subnet for this interface. This mode is useful when target hosts reachable via this interface require the source IP address in ARP requests to be part of their logical network configured on the receiving interface. When we generate the request we will check all our subnets that include the target IP and will preserve the source address if it is from such subnet. If there is no such subnet we select source address according to the rules for level 2.
set interfaces openvpn vtun0 ip enable-arp-announce
Define different modes for sending replies in response to received ARP requests that resolve local target IP addresses:
If configured, reply only if the target IP address is local address configured on the incoming interface.
If this option is unset (default), reply for any local target IP address, configured on any interface.
set interfaces openvpn vtun0 ip enable-arp-ignore
Use this command to enable proxy Address Resolution Protocol (ARP) on this interface. Proxy ARP allows an Ethernet interface to respond with its own MAC address to ARP requests for destination IP addresses on subnets attached to other interfaces on the system. Subsequent packets sent to those destination IP addresses are forwarded appropriately by the system.
Example:
set interfaces openvpn vtun0 ip enable-proxy-arp
Private VLAN proxy arp. Basically allow proxy arp replies back to the same interface (from which the ARP request/solicitation was received).
This is done to support (ethernet) switch features, like RFC 3069, where the individual ports are NOT allowed to communicate with each other, but they are allowed to talk to the upstream router. As described in RFC 3069, it is possible to allow these hosts to communicate through the upstream router by proxy_arp’ing.
Note
Does not need to be used together with proxy_arp.
This technology is known by different names:
In RFC 3069 it is called VLAN Aggregation
Cisco and Allied Telesyn call it Private VLAN
Hewlett-Packard call it Source-Port filtering or port-isolation
Ericsson call it MAC-Forced Forwarding (RFC Draft)
Enable policy for source validation by reversed path, as specified in RFC 3704. Current recommended practice in RFC 3704 is to enable strict mode to prevent IP spoofing from DDos attacks. If using asymmetric routing or other complicated routing, then loose mode is recommended.
strict: Each incoming packet is tested against the FIB and if the interface is not the best reverse path the packet check will fail. By default failed packets are discarded.
loose: Each incoming packet’s source address is also tested against the FIB and if the source address is not reachable via any interface the packet check will fail.
disable: No source validation
SLAAC 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; routers respond to such a request with a router advertisement packet that contains Internet Layer configuration parameters.
Note
This method automatically disables IPv6 traffic forwarding on the interface in question.
Example:
set interfaces openvpn vtun0 ipv6 address autoconf
EUI-64 as specified in RFC 4291 allows a host to assign iteslf a unique 64-Bit IPv6 address.
Example:
set interfaces openvpn vtun0 ipv6 address eui64 2001:db8:beef::/64
Do not assign a link-local IPv6 address to this interface.
Example:
set interfaces openvpn vtun0 ipv6 address no-default-link-local
Configure interface-specific Host/Router behaviour. If set, the interface will switch to host mode and IPv6 forwarding will be disabled on this interface.
Example:
set interfaces openvpn vtun0 ipv6 disable-forwarding
As Internet wide PMTU discovery rarely works, we sometimes need to clamp our TCP MSS value to a specific value. This is a field in the TCP options part of a SYN packet. By setting the MSS value, you are telling the remote side unequivocally ‘do not try to send me packets bigger than this value’.
Note
This command was introduced in VyOS 1.4 - it was previously called:
set firewall options interface <name> adjust-mss6 <value>
Hint
MSS value = MTU - 40 (IPv6 header) - 20 (TCP header), resulting in 1432 bytes on a 1492 byte MTU.
Instead of a numerical MSS value clamp-mss-to-pmtu can be used to automatically set the proper value.
Whether to accept DAD (Duplicate Address Detection).
0: Disable DAD
1: Enable DAD (default)
2: Enable DAD, and disable IPv6 operation if MAC-based duplicate link-local address has been found.
Example:
set interfaces openvpn vtun0 ipv6 accept-dad 2
The amount of Duplicate Address Detection probes to send.
Default: 1
Example:
set interfaces openvpn vtun0 ipv6 dup-addr-detect-transmits 5
Maximum number of keepalive packet failures. The default value is 60
Send keepalive packet every interval seconds. Default value is 10
Define local IP address of tunnel (site-to-site mode only)
Local IP address to accept connections. If specified, OpenVPN will bind to this address only. If unspecified, OpenVPN will bind to all interfaces.
Configure port mirroring for interface outbound traffic and copy the traffic to monitor-interface
Configure port mirroring for interface inbound traffic and copy the traffic to monitor-interface
Define a mode for OpenVPN operation
site-to-site - enables site-to-site VPN connection
client - acts as client in server-client mode
server - acts as server in server-client mode
OpenVPN Data Channel Offload (DCO) enables significant performance enhancement in encrypted OpenVPN data processing. By minimizing context switching for each packet, DCO effectively reduces overhead. This optimization is achieved by keeping most data handling tasks within the kernel, avoiding frequent switches between kernel and user space for encryption and packet handling.
As a result, the processing of each packet becomes more efficient, potentially leveraging hardware encryption offloading support available in the kernel.
Note
OpenVPN DCO is not a fully supported OpenVPN feature, and is currently considered experimental. Furthermore, there are certain OpenVPN features and use cases that remain incompatible with DCO. To get a comprehensive understanding of the limitations associated with DCO, refer to the list of known limitations in the documentation.
https://community.openvpn.net/openvpn/wiki/DataChannelOffload/Features
DCO support is a per-tunnel option and it is not automatically enabled by default for new or upgraded tunnels. Existing tunnels will continue to function as they have in the past.
DCO can be enabled for both new and existing tunnels. VyOS adds an option in each tunnel configuration where we can enable this function. The current best practice is to create a new tunnel with DCO to minimize the chance of problems with existing clients.
Example:
set interfaces openvpn vtun0 offload dco
Enable OpenVPN Data Channel Offload feature by loading the appropriate kernel module.
Disabled by default - no kernel module loaded.
Note
Enable this feature causes an interface reset.
OpenVPN has a lot of options, all of them are not included in VyOS CLI.
If an option is missing, a feature request may be opened at Phabricator so
all users can benefit from it (see Issues/Feature requests). Alternatively,
use openvpn-option for passing raw OpenVPN options to openvpn.conf file.
Note
Please use this only as last resort - things might break and OpenVPN won’t start if you pass invalid options/syntax. Check system logs for errors.
Example:
set interfaces openvpn vtun0 openvpn-option 'persist-key'
This will add persist-key to the generated OpenVPN configuration. This
option solves the problem by persisting keys across resets, so they
don’t need to be re-read.
set interfaces openvpn vtun0 openvpn-option 'route-up "/config/auth/tun_up.sh arg1"'
This will add route-up "/config/auth/tun_up.sh arg1" to the generated OpenVPN
config file. This option is executed after connection authentication, either
immediately after, or some number of seconds after as defined. The path and
arguments need to be single- or double-quoted.
Note
Sometimes option lines in the generated OpenVPN configuration require
quotes. This is done through a hack on our config generator. You can pass
quotes using the " statement.
This option prevents the TUN/TAP device from closing or reopening on connection resets or daemon reloads.
Define a protocol for OpenVPN communication with remote host
udp - default protocol is udp when not defined
tcp-passive - TCP protocol and accepts connections passively
tcp-active - TCP protocol and initiates connections actively
This option redirects incoming packets to destination
Define remote IP address of tunnel (site-to-site mode only)
Define an IPv4/IPv6 address or hostname of server device if OpenVPN is being run in client mode, and is undefined in server mode.
Define a remote port number to connect to server
This option will make OpenVPN tunnel to be used as the default route
First IP address in the pool to allocate to connecting clients
Last IP address in the pool to allocate to connecting clients
Define subnet mask pushed to dynamic clients.
Define the common name specified in client certificate
Set a specific IPv4/IPv6 address to the client
Define a route to be pushed to a specific client
Define this option to route a fixed subnet from the server to a particular client. Used as OpenVPN iroute directive.
Define a first IP address from IPv4 pool of subnet to be dynamically allocated to connecting clients
Define a last IP address from IPv4 pool of subnet to be dynamically allocated to connecting clients
Define a subnet mask pushed to dynamic clients. This option is only used for device type tap, not to be used with bridged interfaces.
Define an IPv6 address pool for dynamic assignment to clients
Define the maximum number of client connections
If set to enable, openvpn-otp will expect password as result of challenge/ response protocol.
Configure number of digits to use for totp hash (default: 6)
Configure time drift in seconds (default: 0)
Configure maximum allowed clock slop in seconds (default: 180)
Configure step value for totp in seconds (default: 30)
Define Client DNS configuration to be used with the connection
Define a route to be pushed to all clients
Reject connections from clients that are not explicitly configured
Manadatory field to define in server mode, set ipv4 or ipv6 network
Define virtual addressing topology when running in tun mode. This directive
has no meaning in tap mode, which always uses a subnet topology.
subnet - This topology is the current recommended and default topology. This mode allocates a single IP address per connecting client.
net30 - This is the old topology for support with Windows clients, by allocating one /30 subnet per client. It is effictively depcrecated.
point-to-point - Use a point-to-point topology where the remote endpoint of the client’s tun interface always points to the local endpoint of the server’s tun interface. This mode allocates a single IP address per connecting client. Only use when none of the connecting clients are Windows systems.
Define a tls secret key for tls-auth which adds an additional HMAC signature
to all SSL/TLS handshake packets for integrity verification. Use run generate pki openvpn shared-secret install <name> to generate the key.
Define Certificate Authority chain in PKI configuration
Define a name of certificate in PKI configuration
Define a shared secret key to provide an additional level of security, a variant similar to tls-auth
Define Diffie Hellman parameters, required only on server mode
Peer certificate SHA256 fingerprint, configured in site-to-site mode
Define a role for TLS negotiation, preferably used in site-to-site mode
active - Initiate TLS negotiation actively
passive - Wait for incoming TLS connection
This option sets the minimum TLS version which will accept from the peer
Use fast LZO compression on this TUN/TAP interface
Operation Mode
Examples
This section covers examples of OpenVPN configurations for various deployments.