.. _openvpn: ####### 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 ************* .. cfgcmd:: set interfaces openvpn authentication password **Configure the password for the** ``auth-user-pass`` **authentication method.** This option applies only to OpenVPN clients. .. cfgcmd:: set interfaces openvpn authentication username **Configure the username for the** ``auth-user-pass`` **authentication method.** This option applies only to OpenVPN clients. .. cfgcmd:: set interfaces openvpn description Configure the description for the OpenVPN interface. .. cfgcmd:: set interfaces openvpn device-type **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. .. cfgcmd:: set interfaces openvpn disable Disable the specific OpenVPN interface. .. cfgcmd:: set interfaces openvpn encryption cipher < 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none > **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. .. cfgcmd:: set interfaces openvpn encryption data-ciphers < 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none > **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. .. cfgcmd:: set interfaces openvpn encryption data-ciphers-fallback < 3des | aes128 | aes128gcm | aes192 | aes192gcm | aes256 | aes256gcm | none > **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. .. cfgcmd:: set interfaces openvpn hash Configure the hashing algorithm for the OpenVPN interface. .. 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 **Configure the number of tolerated keepalive packet failures.** Default: 60 consecutive failures. .. cfgcmd:: set interfaces openvpn keep-alive interval **Configure the frequency, in seconds, at which keepalive packets are sent.** Default: 10 seconds. .. cfgcmd:: set interfaces openvpn local-address
Configure the local tunnel IP address for ``site-to-site`` mode. .. cfgcmd:: set interfaces openvpn local-host
**Configure the local IP address to accept connections.** If configured, OpenVPN binds to this IP address only. By default, OpenVPN binds to all interfaces. .. cfgcmd:: set interfaces openvpn local-port Configure the local port to accept connections. .. cfgcmd:: set interfaces openvpn mirror egress Configure mirroring of outgoing traffic from this OpenVPN interface to the designated monitor interface. .. cfgcmd:: set interfaces openvpn mirror ingress Configure mirroring of incoming traffic from this OpenVPN interface to the designated monitor interface. .. cfgcmd:: set interfaces openvpn mode **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 :abbr:`DCO (Data Channel Offload)` 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:: * :abbr:`DCO (Data Channel Offload)` is an **experimental**, not fully supported OpenVPN feature. Some OpenVPN features and deployment scenarios are **not compatible** with :abbr:`DCO (Data Channel Offload)`. For a complete list of supported features, visit: https://community.openvpn.net/openvpn/wiki/DataChannelOffload/Features * :abbr:`DCO (Data Channel Offload)` is configured per tunnel and disabled by default. Existing tunnels operate without :abbr:`DCO (Data Channel Offload)` unless it is explicitly enabled. * Enabling :abbr:`DCO (Data Channel Offload)` resets the interface. **Best practice:** Create a new tunnel with :abbr:`DCO (Data Channel Offload)` enabled to avoid compatibility issues with existing clients. .. cfgcmd:: set interfaces openvpn offload dco **Enable** :abbr:`DCO (Data Channel Offload)` **for the specified OpenVPN interface.** Example: .. code-block:: none set interfaces openvpn vtun0 offload dco This command enables :abbr:`DCO (Data Channel Offload)` and loads the required kernel module. .. cfgcmd:: set interfaces openvpn openvpn-option **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 :ref:`issues_features`). 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: .. code-block:: none 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. .. code-block:: none 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. .. cfgcmd:: set interfaces openvpn persistent-tunnel **Enable always-active mode for the TUN/TAP device.** When enabled, the TUN/TAP device remains active upon connection resets or daemon reloads. .. cfgcmd:: set interfaces openvpn protocol **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. .. cfgcmd:: set interfaces openvpn redirect Enable redirection of incoming packets to the specified interface. .. cfgcmd:: set interfaces openvpn remote-address
Configure the remote tunnel IP address for site-to-site mode. .. cfgcmd:: set interfaces openvpn remote-host
**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. .. cfgcmd:: set interfaces openvpn remote-port Configure the remote port to connect to the server. .. cfgcmd:: set interfaces openvpn replace-default-route Configure the OpenVPN tunnel as the default route. .. cfgcmd:: set interfaces openvpn server bridge disable Disable the given instance. .. cfgcmd:: set interfaces openvpn server bridge gateway Configure the gateway IP address. .. cfgcmd:: set interfaces openvpn server bridge start Configure the first IP address in the pool to allocate to connecting clients. .. cfgcmd:: set interfaces openvpn server bridge stop Configure the last IP address in the pool to allocate to connecting clients. .. cfgcmd:: set interfaces openvpn server bridge subnet-mask Configure the subnet mask pushed to dynamic clients. .. cfgcmd:: set interfaces openvpn server client Configure the Common Name (CN) specified in the client certificate. .. cfgcmd:: set interfaces openvpn server client disable Disable the client connection. .. cfgcmd:: set interfaces openvpn server client ip
Configure the IPv4/IPv6 address for the client. .. cfgcmd:: set interfaces openvpn server client push-route Configure a route to be pushed to the specific client. .. cfgcmd:: set interfaces openvpn server client subnet **Configure a fixed subnet to be routed from the server to the specified client.** Used as OpenVPN’s ``iroute`` directive. .. cfgcmd:: set interfaces openvpn server client-ip-pool start
Configure the first IP address in the subnet's IPv4 pool to be dynamically allocated to connecting clients. .. cfgcmd:: set interfaces openvpn server client-ip-pool stop
Configure the last IP address in the subnet's IPv4 pool to be dynamically allocated to connecting clients. .. cfgcmd:: set interfaces openvpn server client-ip-pool subnet **Configure the subnet mask pushed to dynamic clients.** Use this command only for the TAP device type. Do not use it for bridged interfaces. .. cfgcmd:: set interfaces openvpn server client-ipv6-pool base Configure the IPv6 address pool for dynamic assignment to clients. .. cfgcmd:: set interfaces openvpn server domain-name Configure the DNS suffix to be pushed to all clients. .. cfgcmd:: set interfaces openvpn server max-connections <1-4096> Configure the maximum number of client connections. .. cfgcmd:: set interfaces openvpn server mfa totp challenge If enabled, openvpn-otp expects a password as a result of the challenge/ response protocol. .. cfgcmd:: set interfaces openvpn server mfa totp digits <1-65535> **Configure the number of digits to use for the** :abbr:`TOTP (Time-based One-Time Password)` **hash.** Default: 6. .. cfgcmd:: set interfaces openvpn server mfa totp drift <1-65535> **Configure the time drift in seconds.** Default: 0. .. cfgcmd:: set interfaces openvpn server mfa totp slop <1-65535> **Configure the allowed clock slop in seconds.** Default: 180. .. cfgcmd:: set interfaces openvpn server mfa totp step <1-65535> **Configure the step value for** :abbr:`TOTP (Time-based One-Time Password)` **in seconds.** Default: 30. .. cfgcmd:: set interfaces openvpn server name-server
Define the client DNS configuration to be used with the connection. .. cfgcmd:: set interfaces openvpn server push-route Configure the 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 **Configure the IPv4 or IPv6 network.** This parameter is mandatory when operating in server mode. .. cfgcmd:: set interfaces openvpn server topology < net30 | point-to-point | subnet> **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’s ``tun`` interface always points to the local endpoint of the server’s ``tun`` interface. Like ``subnet``, this topology allocates a single IP address per client. Use it only if no clients run Windows operating systems. .. cfgcmd:: set interfaces openvpn shared-secret-key Configure the static secret key for a site-to-site OpenVPN connection. .. cfgcmd:: set interfaces openvpn tls auth-key **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 `` to generate the key. .. cfgcmd:: set interfaces openvpn tls ca-certificate Configure the Certificate Authority chain in the PKI configuration. .. cfgcmd:: set interfaces openvpn tls certificate Configure the certificate name in the PKI configuration. .. cfgcmd:: set interfaces openvpn tls crypt-key Configure a shared secret key to provide an additional level of security, a variant similar to tls-auth. .. cfgcmd:: set interfaces openvpn tls dh-params Configure Diffie-Hellman parameters for server mode. .. cfgcmd:: set interfaces openvpn tls peer-fingerprint Configure the peer certificate SHA256 fingerprint for site-to-site mode. .. cfgcmd:: set interfaces openvpn tls role **Configure the TLS negotiation role, preferably used in site-to-site mode:** * ``active``: Initiates TLS negotiation actively. * ``passive``: Waits for incoming TLS connections. .. cfgcmd:: set interfaces openvpn tls tls-version-min <1.0 | 1.1 | 1.2 | 1.3 > Configure the minimum TLS version to be accepted from the peer. .. cfgcmd:: set interfaces openvpn use-lzo-compression Configure fast LZO compression on this TUN/TAP interface. .. cfgcmd:: set interfaces openvpn vrf Assign the interface to a specific VRF instance. ************** Operation mode ************** .. opcmd:: show openvpn site-to-site Show tunnel status for OpenVPN site-to-site interfaces. .. opcmd:: show openvpn server Show tunnel status for OpenVPN server interfaces. .. opcmd:: show openvpn client Show tunnel status for OpenVPN client interfaces. .. opcmd:: show log openvpn Show logs for all OpenVPN interfaces. .. opcmd:: show log openvpn interface Show logs for the specific OpenVPN interface. .. opcmd:: reset openvpn client Reset the specified OpenVPN client. .. opcmd:: reset openvpn interface Reset the OpenVPN process on the specified interface. .. opcmd:: generate openvpn client-config interface ca certificate Generate an OpenVPN client configuration file in the .ovpn format for client machines. ******** Examples ******** This section covers examples of OpenVPN configurations for various deployments. .. toctree:: :maxdepth: 1 :includehidden: openvpn-examples .. include:: /_include/common-references.txt