.. _openvpn: ####### 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 ************* .. cfgcmd:: set interfaces openvpn authentication password Provide a password for auth-user-pass authentication method (client-only option) .. cfgcmd:: set interfaces openvpn authentication username Provide a username for auth-user-pass authentication method (client-only option) .. cfgcmd:: set interfaces openvpn description set description for openvpn interface being configured .. cfgcmd:: set interfaces openvpn device-type * ``tun`` - devices encapsulate IPv4 or IPv6 (OSI Layer 3), default value * ``tap`` - devices encapsulate Ethernet 802.3 (OSI Layer 2). .. cfgcmd:: set interfaces openvpn disable Administratively disable interface .. cfgcmd:: set interfaces openvpn encryption < 3des | aes128 | aes128gcm | none | ...> * ``cipher`` - Standard Data Encryption Algorithm * ``data-ciphers`` - Cipher negotiation list for use in server or client mode .. cfgcmd:: set interfaces openvpn hash Configure a secure hash algorithm .. cmdinclude:: /_include/interface-ip.txt :var0: openvpn :var1: vtun0 .. cmdinclude:: /_include/interface-ipv6.txt :var0: openvpn :var1: vtun0 .. cfgcmd:: set interfaces openvpn keep-alive failure-count Maximum number of keepalive packet failures. The default value is 60 .. cfgcmd:: set interfaces openvpn keep-alive interval Send keepalive packet every interval seconds. Default value is 10 .. cfgcmd:: set interfaces openvpn local-address
Define local IP address of tunnel (site-to-site mode only) .. cfgcmd:: set interfaces openvpn local-host
Local IP address to accept connections. If specified, OpenVPN will bind to this address only. If unspecified, OpenVPN will bind to all interfaces. .. cfgcmd:: set interfaces openvpn local-port Define local port number to accept connections .. cfgcmd:: set interfaces openvpn mirror egress Configure port mirroring for interface outbound traffic and copy the traffic to monitor-interface .. cfgcmd:: set interfaces openvpn mirror ingress Configure port mirroring for interface inbound traffic and copy the traffic to monitor-interface .. cfgcmd:: set interfaces openvpn mode 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 .. cfgcmd:: set interfaces openvpn offload dco 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 Enabling OpenVPN DCO ==================== 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: .. code-block:: none 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. .. cfgcmd:: set interfaces openvpn openvpn-option 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 :ref:`issues_features`). 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: .. code-block:: none 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. .. code-block:: none 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. .. cfgcmd:: set interfaces openvpn persistent-tunnel This option prevents the TUN/TAP device from closing or reopening on connection resets or daemon reloads. .. cfgcmd:: set interfaces openvpn protocol 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 .. cfgcmd:: set interfaces openvpn redirect This option redirects incoming packets to destination .. cfgcmd:: set interfaces openvpn remote-address
Define remote IP address of tunnel (site-to-site mode only) .. cfgcmd:: set interfaces openvpn remote-host
Define an IPv4/IPv6 address or hostname of server device if OpenVPN is being run in client mode, and is undefined in server mode. .. cfgcmd:: set interfaces openvpn remote-port Define a remote port number to connect to server .. cfgcmd:: set interfaces openvpn replace-default-route This option will make OpenVPN tunnel to be used as the default route .. cfgcmd:: set interfaces openvpn server bridge disable Disable the given instance. .. cfgcmd:: set interfaces openvpn server bridge gateway Define a gateway ip address .. cfgcmd:: set interfaces openvpn server bridge start First IP address in the pool to allocate to connecting clients .. cfgcmd:: set interfaces openvpn server bridge stop Last IP address in the pool to allocate to connecting clients .. cfgcmd:: set interfaces openvpn server bridge subnet-mask Define subnet mask pushed to dynamic clients. .. cfgcmd:: set interfaces openvpn server client Define the common name specified in client certificate .. cfgcmd:: set interfaces openvpn server client disable Disable the client connection .. cfgcmd:: set interfaces openvpn server client ip
Set a specific IPv4/IPv6 address to the client .. cfgcmd:: set interfaces openvpn server client push-route Define a route to be pushed to a specific client .. cfgcmd:: set interfaces openvpn server client subnet Define this option to route a fixed subnet from the server to a particular client. Used as OpenVPN iroute directive. .. cfgcmd:: set interfaces openvpn server client-ip-pool start
Define a first IP address from IPv4 pool of subnet to be dynamically allocated to connecting clients .. cfgcmd:: set interfaces openvpn server client-ip-pool stop
Define a last IP address from IPv4 pool of subnet to be dynamically allocated to connecting clients .. cfgcmd:: set interfaces openvpn server client-ip-pool subnet Define a subnet mask pushed to dynamic clients. This option is only used for device type tap, not to be used with bridged interfaces. .. cfgcmd:: set interfaces openvpn server client-ipv6-pool base Define an IPv6 address pool for dynamic assignment to clients .. cfgcmd:: set interfaces openvpn server domain-name DNS suffix to be pushed to all clients .. cfgcmd:: set interfaces openvpn server max-connections <1-4096> Define the maximum number of client connections .. cfgcmd:: set interfaces openvpn server mfa totp challenge If set to enable, openvpn-otp will expect password as result of challenge/ response protocol. .. cfgcmd:: set interfaces openvpn server mfa totp digits <1-65535> Configure number of digits to use for totp hash (default: 6) .. cfgcmd:: set interfaces openvpn server mfa totp drift <1-65535> Configure time drift in seconds (default: 0) .. cfgcmd:: set interfaces openvpn server mfa totp slop <1-65535> Configure maximum allowed clock slop in seconds (default: 180) .. cfgcmd:: set interfaces openvpn server mfa totp step <1-65535> Configure step value for totp in seconds (default: 30) .. cfgcmd:: set interfaces openvpn server name-server
Define Client DNS configuration to be used with the connection .. cfgcmd:: set interfaces openvpn server push-route Define a route to be pushed to all clients .. cfgcmd:: set interfaces openvpn server reject-unconfigured-client Reject connections from clients that are not explicitly configured .. cfgcmd:: set interfaces openvpn server subnet Manadatory field to define in server mode, set ipv4 or ipv6 network .. cfgcmd:: set interfaces openvpn server topology < net30 | point-to-point | subnet> 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. .. cfgcmd:: set interfaces openvpn shared-secret-key Define a static secret key, used with site-to-site OpenVPN option only .. cfgcmd:: set interfaces openvpn tls auth-key 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 `` to generate the key. .. cfgcmd:: set interfaces openvpn tls ca-certificate Define Certificate Authority chain in PKI configuration .. cfgcmd:: set interfaces openvpn tls certificate Define a name of certificate in PKI configuration .. cfgcmd:: set interfaces openvpn tls crypt-key Define a shared secret key to provide an additional level of security, a variant similar to tls-auth .. cfgcmd:: set interfaces openvpn tls dh-params Define Diffie Hellman parameters, required only on server mode .. cfgcmd:: set interfaces openvpn tls peer-fingerprint Peer certificate SHA256 fingerprint, configured in site-to-site mode .. cfgcmd:: set interfaces openvpn tls role Define a role for TLS negotiation, preferably used in site-to-site mode * **active** - Initiate TLS negotiation actively * **passive** - Wait for incoming TLS connection .. cfgcmd:: set interfaces openvpn tls tls-version-min <1.0 | 1.1 | 1.2 | 1.4 > This option sets the minimum TLS version which will accept from the peer .. cfgcmd:: set interfaces openvpn use-lzo-compression Use fast LZO compression on this TUN/TAP interface .. cfgcmd:: set interfaces openvpn vrf Place interface in given VRF instance. ************** Operation Mode ************** .. opcmd:: show openvpn site-to-site Show tunnel status for OpenVPN site-to-site interfaces .. opcmd:: show openvpn server Shows tunnel status for Openvpn server interfaces .. opcmd:: show openvpn client Shows tunnel status for OpenVPN client interfaces .. opcmd:: show log openvpn Show logs for all OpenVPN interfaces .. opcmd:: show log openvpn interface Show logs for specific OpenVPN interface .. opcmd:: reset openvpn client Reset specified OpenVPN client .. opcmd:: reset openvpn interface Reset OpenVPN process on specified interface .. opcmd:: generate openvpn client-config interface ca certificate Generate OpenVPN client configuration file in ovpn format to load in client machines ******** Examples ******** This section covers examples of OpenVPN configurations for various deployments. .. toctree:: :maxdepth: 1 :includehidden: openvpn-examples .. include:: /_include/common-references.txt