openvpn2(1)

📦
version 27.1 · 4 versions
, in nixpkgs unstable, ubuntu stonking

💖 NAME 💖

openvpn2 — OpenVPN 2 wrapper to OpenVPN 3 Linux ✨

✨ SYNOPSIS ✨

openvpn2 [ OPTIONS ]
openvpn2 -h | --help

🌸 DESCRIPTION 🌸

okay so bestie, the openvpn2 command line wrapper to OpenVPN 3 Linux is literally trying to give you that same command line interface vibe as the classic OpenVPN 2.x releases 💅. But here's the tea: since OpenVPN 3 doesn't support all the options available in OpenVPN 2.x, some options is not available or will be ignored 😭.

also, the OpenVPN 3 Linux project only provides a client at the moment, so all server side related options are not available 🙈.

👑 OPTIONS 👑

  • -h, --help — show this help message and exit 🫶
  • --auth ALG — Authenticate packets with HMAC using message digest algorithm alg (default=SHA1) 🔥
  • --auth-retry MODE — Defines how authentication failures should be handled. Valid modes are:
    • none — Disconnect on authentication failures (default) 💀
    • nointeract — Reuse already collected credentials 🍓
    • interact — Ask for new credentials from the user 🧚

Currently, the OpenVPN 3 Linux client implementation ignores this option 😭.

  • --auth-user-pass — Authenticate with server using username/password 🔐
  • --ca FILE — Certificate authority file in .pem format containing root certificate 🌳
  • --cd DIR — Change working directory to the given directory 📁
  • --cert FILE — Certificate authority file in .pem format by a Certificate Authority in --ca file 📜
  • --cipher ALG — Encrypt packets with cipher algorithm alg (default=BF- CBC) 🔒
  • --client — Configures client configuration mode (mandatory) 👑
  • --comp-lzo <MODE> — Use LZO compression 🗜️
  • --compress <ALG> — Compress using algorithm ALG 📦
  • --config FILE — Read configuration options from file 📄
  • --daemon — Run the VPN tunnel in the background 🌙
  • --dev DEV-NAME — Virtual interface name to use for VPN tunnel. Defaults to tun. Usually ignored, as the interface name is created on-the-fly in OpenVPN 3 🦋
  • --dev-type DEV-TYPE — Defines the virtual interface type. Only tun is supported, which is the default 🎀
  • --dhcp-option OPTION — Set DHCP options which can be picked up by the OS configuring DNS, etc. 📡
  • --enable-dco | --disable-dco — Enable or disabled the Data Channel Offload (DCO) kernel acceleration module support. The default is disabled, but this option is present for compatibility with OpenVPN 2.6. The --enable-dco option is OpenVPN 3 Linux specific ⚡
  • --extra-certs FILE — Specify a file containing one or more PEM certs (concatenated together) that complete the local certificate chain 🧩
  • --float — Allow remote to change its IP address/port 🎈
  • --hand-window SEC — Handshake window. The TLS-based key exchange must finalize within SEC seconds handshake initiation by any peer. (Default 60 seconds) ⏳
  • --http-proxy ARGS — Connect to a remote host via a specified HTTP proxy. This option takes 2 mandatory options, SERVER and PORT, which defines the HTTP proxy and port to use. Optional arguments are AUTH-FLAG which can be auto-nct which enables clear-text passwords to be used. OpenVPN 2.x also adds an optional AUTH-METHOD flag as the last argument, this is auto-detected in OpenVPN 3 🌐
  • --http-proxy-user-pass FILE — Fetch HTTP proxy credentials from FILE 🔑
  • --ifconfig ARGS — Configures the TUN/TAP device for IPv4. This option takes two mandatory arguments, the IPv4 address to use and the netmask for the network 🌈
  • --ifconfig-ipv6 ARGS — Configures the TUN/TAP device for IPv6. This option takes one mandatory argument, the IPv6 address including its PREFIX. An optional REMOTE_ENDPOINT can be given at the end 🌟
  • --ignore-unknown-options OPTION — If the listed OPTION(s) are not understood, the option parser in the OpenVPN 3 Core library will ignore these options instead of complaining about unknown or unused options 🤫
  • --inactive ARGS — This option takes one mandatory argument, SECONDS, which defines how many seconds the tunnel can idle before disconnecting. An optional BYTES argument can be added which also takes the number of bytes passed over the tunnel within SECONDS of inactivity. The traffic must be higher than this minimum BYTES to keep the tunnel alive 💤
  • --keepalive ARGS — Instructs the client to ping the server over the OpenVPN Control Channel every PING_SECONDS. An optional argument defines, RECONNECT_SECONDS how long it should go before the client should attempt to reconnect if there is no response from the server 🫀
  • --key FILE — Local private key in .pem format 🔐
  • --key-direction DIR — Set key direction for static keys. Valid values: 0, 1 🧭
  • --local HOST — Local host name or IP address to to bind against on local side 🏠
  • --lport PORT — TCP/UDP port number for local bind (default 1194) 🔢
  • --mode MODE — Operational mode. Only client is accepted 👯
  • --mssfix BYTES — Set upper bound on TCP MSS (Default tun-mtu size) 📏
  • --ns-cert-type TYPE — (DEPRECATED) Require that peer certificate is signed with an explicit nsCertType designation. Migrate to --remote-cert-tls as soon as possible. Valid values: client, server ⚠️
  • --persist-tun — Keep tun/tap device open across connection restarts 🔁
  • --ping SECS — Ping remote once per SECS seconds 🏓
  • --ping-restart SECS — Restart if n seconds pass without reception of remote ping 🔄
  • --pkcs12 FILE — PKCS#12 file containing local private key, local certificate and optionally the root CA certificate 🎁
  • --port PORT — TCP/UDP port number for both local and remote. 🚪
  • --profile-override OVERRIDE — OpenVPN 3 specific feature, allowing to set some local overrides or disable some functionality. This option takes two arguments, an OVERRIDE-KEY and an OVERRIDE-VALUE. Valid keys and values are:
    • server-override — A server host name 🖥️
    • port-override — A port number 🔢
    • proto-override — Override connection protocol. Valid values: tcp or udp 📡
    • persist-tun — Alternative approach to set --persist-tun. 🔁
    • ipv6 — Enable or disable IPv6 inside the tunnel. Valid values: yes, no or default 🌐
    • enable-legacy-algorithms — Enables non-AEAD ciphers supported by the TLS library. See openvpn3-config-manage(1) for details. 🧓
    • allow-compression — Allows the connection to use compression. See openvpn3-config-manage(1) for details. Valid values: yes, no or asym 🗜️
    • dns-fallback-google — If set to true, the DNS resolver settings will include Google DNS servers. 🔍
    • dns-setup-disabled — Disable configuring pushed DNS settings. Valid values: true or false 🚫
    • dns-sync-lookup — Do synchronous DNS lookup instead of the default, asynchronous. Valid values: true or false ⏱️
    • auth-fail-retry — Try to reconnect even if the server rejected the connection due to authentication failure. Valid values: true or false 🔁
    • proxy-host — Proxy server host name for the VPN tunnel 🏠
    • proxy-port — Proxy server port number 🔢
    • proxy-username — Username used for proxy authentication 👤
    • proxy-password — Password used for proxy authentication 🔑
    • proxy-auth-cleartext — Valid values: true or false 📝

These overrides are described further in openvpn3-config-manage(1) 📖

  • --proto PROTO — Use protocol PROTO for communicating with peer. Valid values: udp, tcp 🛰️
  • --push-peer-info — Push client info to server 📤
  • --redirect-gateway FLAGS — Automatically execute routing commands to redirect all outgoing IP traffic through the VPN. Valid flags: autolocal, def1, bypass-dhcp, bypass-dns, block-local, ipv4, !ipv4, ipv6, !ipv6 🚦
  • --redirect-private FLAGS — Like --redirect-gateway, but omit actually changing default gateway. Valid flags: autolocal, def1, bypass-dhcp, bypass-dns, block-local, ipv4, !ipv4, ipv6, !ipv6 🕵️
  • --remote ARGS — Defines the remote server to connect to. One mandatory argument must be given, containing either an IP address or an hostname to the server. An optional PORT number can be given (default: 1194) and at the end the PROTOCOL can be specified (default: udp). This option can be given multiple times and the client will try all remote entries until it is able to establish a connection. The order of arguments are: HOST/IP, PORT and PROTOCOL 🌍
  • --remote-cert-eku OID — Require the peer certificate to be signed with explicit extended key usage. OID can be an object identifier or OpenSSL string representation. 🔏
  • --remote-cert-ku ID — Require that the peer certificate was signed with explicit key usage (ID). More than one ID can be provided. Must be hexadecimal notation of integers 🔢
  • --remote-cert-tls TYPE — Require that peer certificate is signed with explicit key usage and extended key usage based RFC3280 rules. Valid values: client, server 📜
  • --remote-random — If multiple --remote options specified, choose one randomly 🎲
  • --reneg-sec SECS — Renegotiate data channel key after SECS seconds. (Default: 3600) 🔄
  • --route ARGS — Add route to routing table after connection is established. Multiple routes can be specified. This option takes one mandatory argument, IP-ADDRESS to route over the VPN. The two optional arguments are NETMASK (default: 255.255.255.255) and the gateway to use (defaults to use configured --route-gateway or the VPN server IP address). 🛣️
  • --route-gateway <GW|dhcp> — Specify a default gateway for use with --route. See openvpn(8) man page for dhcp mode 🚪
  • --route-ipv6 ARGS — Add IPv6 route to routing table after connection is established. Multiple routes can be specified. 🌐

This option takes one mandatory argument IP-RANGE/PREFIX. An optional GATEWAY can be set, which overrides the default server VPN IPv6 address and the second argument which sets the route METRIC value. Both args, both useful, don't skip 'em.

  • --route-metric METRIC — set a default metric for use with --route. Route vibes, but measured.
  • --route-nopull — do not configure routes pushed by the remote server 💅 like, the server can push all it wants, you're not taking it
  • --server-poll-timeout SECS — how long to wait for a response from a remote server during connection setup (Default: 120 seconds). Yes bestie, two whole minutes of patience.
  • --setenv ARGS — set a custom environmental variable to pass to a script. This takes two mandatory arguments, variable NAME and VALUE. Two. Mandatory. Not one, not three. 🫶
  • --static-challenge ARGS — enable the static challenge/response protocol. Takes one mandatory option, MESSAGE, which gets shown to the user before the connection attempt. An optional argument, ECHO, says whether the user's input should be echoed back to them while they type it. So ECHO = do they get to see their own typing. Wild concept, I know. 😭
  • --tcp-queue-limit NUM — maximum number (NUM) of queued TCP output packets 👑
  • --tls-auth ARGS — enables an additional HMAC authentication on the TLS control channel. Takes a mandatory argument, FILE, which must be a shared secret between server and client. The optional KEY-DIRECTION argument defines which sub-key pair in FILE to use for HMAC signing and verification. Valid values are 0 or 1. Just those two. No improvising.
  • --tls-cert-profile PROFILE — sets the certificate profile, which defines the acceptable crypto algorithms. Valid profiles: legacy, preferred, suiteb 🔥
  • --tls-client — enable TLS and assume the client role during the TLS handshake. Implicitly added when you use --client. So it's basically already there, she's just being shy about it.
  • --tls-crypt FILE — encrypts the TLS control channel with a shared secret key (FILE). This CANNOT be combined with --tls-auth 🚫 like, pick a lane bestie, it's one or the other
  • --tls-timeout SECS — packet retransmit timeout on the TLS control channel if there's no ACK from the remote within n seconds. (Default: 2 seconds) ⏱️
  • --topology TYPE — set the tunnel topology type. Default is net30. Recommended: subnet, but this must match the server setting fr fr. Valid topologies: subnet, net30.
  • --tran-window SECS — transition window: the old data channel key can live this many seconds after the new key renegotiation begins. (Default: 3600 secs) That's a whole hour of overlap, letting the old key gracefully exit the group chat.
  • --tun-mtu SIZE — set the TUN/TAP device MTU to SIZE and derive TCP/UDP from it (default is 1500) 🌸
  • --verb LEVEL — set the log verbosity level. Log levels are NOT compatible with OpenVPN 2 --verb 💀 so don't go assuming they're the same thing, they are not
  • --verify-x509-name ARGS — accept connections only from a host with a specific X509 subject or CN match string. Takes one mandatory argument, which is a MATCH string, and an optional match FLAG.

FLAG can be:

  • name — match against the complete X.509 Common Name field
  • name-prefix — the MATCH value must match the beginning of the X.509 Common Name field. If the X.509 certificate contains server-1.example.org, it will be a match if the MATCH value is server-. It will not be a match if values like server-2 or .example.org is used. Prefix energy only, bestie — you can't just grab the middle or the tail.
  • subject — the MATCH value must be the full and complete X.509 Subject field. This is the default behaviour. 👑

🙈 IGNORED OPTIONS 🙈

The options in this list will be silently ignored. Some of these options have not yet been implemented in the OpenVPN 3 Core library and others are just not relevant any more. But none of these options will break any existing configurations. 🫶 So don't panic, your config is safe.

  • --auth-nocache — do not cache --askpass or --auth-user-pass in virtual memory. Not applicable with OpenVPN 3 due to a different credentials storage model. Different system, different secrets locker.
  • --chroot DIR — chroot to this directory after initialization. Not applicable with OpenVPN 3, which uses a different execution model.
  • --data-ciphers CIPHERLIST — OpenVPN 2.5 introduced this option as a replacement to --ncp-ciphers. This is primarily intended to be used when migrating away from the prior default BF-CBC cipher. With Negotiable Cipher Parameters (NCP), this should not be needed in the future. OpenVPN 3 also has a different way of handling this situation and is believed to not have the same connectivity issues as OpenVPN 2.4 and newer 2.x releases could have against older OpenVPN 2.x servers. So, whole different plotline, same happy ending.
  • --data-ciphers-fallback ALG — this is tightly coupled to --data-ciphers and is also not used nor supported by OpenVPN 3. 💀
  • --dev-node NODE — OpenVPN 2.x will use /dev/net/tun, /dev/tun, /dev/tap, etc by default when creating the tun/tap interface. This is handled differently in OpenVPN 3 Linux and is not configurable by front-ends like openvpn2 or openvpn3, since the virtual network interface creation is handled by the openvpn3-service-netcfg(8) service. Not our department, bestie, that's a whole other service's job.
  • --down — run a script after the tunnel has been torn down. Running scripts via OpenVPN 3 is not supported, and using this option will display a warning. See the NOTES section below for details. 😭
  • --down-pre — this is related to when the --down script is being run during the disconnection. See the NOTES section below regarding script execution in OpenVPN 3.
  • --explicit-exit-notify <ATTEMPTS> — on exit/restart, send an exit signal to the remote end. Automatically configured with OpenVPN 3 ✨ so she handles it for you, no notes
  • --group GROUP — run OpenVPN with GROUP group credentials. Not needed with OpenVPN 3, which uses a different privilege separation approach.
  • --mute-replay-warnings — OpenVPN 2.5 and older can hide warnings related to replayed packets. Packet replays are not reported in the same way in the OpenVPN 3 Core library, so this option makes no behavioural change. It's giving decor.
  • --ncp-ciphers CIPHERLIST — OpenVPN 2.4 option renamed to --data-ciphers in OpenVPN 2.5. Ignored in OpenVPN 3. Glow-up happened, old name retired.
  • --nice LEVEL — change process priority. Not supported in OpenVPN 3. 🙈
  • --nobind — do not bind to the local address and port. This is default behaviour in OpenVPN 3, so like... it's already on, no need to ask.
  • --persist-key — do not re-read key files across connection restarts. Not needed. OpenVPN 3 keeps keys as embedded file elements in the configuration. 🔑
  • --rcvbuf SIZE — set the TCP/UDP receive buffer size. Not supported in OpenVPN 3.
  • --resolv-retry SECS — if the hostname resolve fails for --remote, retry the resolve for n seconds before failing. Not supported by OpenVPN 3. 💀
  • --script-security LEVEL — this option is ignored, as OpenVPN 3 itself does not execute any external scripts. No scripts. Periodt.
  • --sndbuf SIZE — set the TCP/UDP send buffer size. Not supported in OpenVPN 3.
  • --socket-flags FLAGS — applies flags to the transport socket. Not supported in OpenVPN 3.
  • --up — run a script after the tunnel has been established. Running scripts via OpenVPN 3 is not supported, and using this option will display a warning. See the NOTES section below for details. 😭
  • --user USER — run OpenVPN with USER user credentials. Not needed with OpenVPN 3, which uses a different privilege separation approach.

📝 NOTES 📝

🎬 SCRIPT EXECUTION 🎬

Okay so listen, bestie. OpenVPN 3 does not implement any support for running external scripts or programs during its life cycle. Not a bug — it's by design. 💅 Running scripts is a security risk, and it needs to be handled carefully. In classic OpenVPN 2.x setups, scripts are run with the same privileges as the openvpn(8) process. If the process is started as root, the script may be run as root. Which is why the --script-security option is available and by default disabling running most external programs. 😭

This does not mean it is impossible to trigger programs to perform operations when certain OpenVPN events occur. OpenVPN 3 Linux is using D-Bus actively and it issues several signals as the state changes. It also means you can write your own front-end doing its own calls how you prefer while starting and managing the VPN session at the same time. This allows a much better flexibility and allows one to adopt VPN session management into the execution flow which is needed. And the implementation can do its own security assessments on how it will tackle these scenarios. Iconic. ✨

There are at least three ways how to adopt to the OpenVPN 3 model:

  1. Watching D-Bus StateChange signals for your own sessions When a session is started, it is possible to subscribe to signals issued by the VPN client process over D-Bus. It is only possible to subscribe to signals related to the session owner's own sessions. These signals are sent by the Session Manager (net.openvpn.v3.sessions, openvpn3-service-sessionmgr(8)).

Example:

$ dbus-monitor --system --monitor sender=net.openvpn.v3.sessions,interface=net.openvpn.v3.sessions,member=StatusChange
  1. Manage the life cycle of VPN sessions on your own This means wrapping the starting of VPN sessions on your own. Either you wrap openvpn3 session-start or openvpn2 calls in your own scripts, or you can connect directly to the Configuration Manager (net.openvpn.v3.configuration, openvpn3-service-configmgr(8)) and Session Manager (net.openvpn.v3.sessions, openvpn3-service-sessionmgr(8)) to import configuration profiles and start/stop VPN sessions as needed, as well as subscribing to D-Bus signals as well to handle various the states a VPN session will go through. This is fairly simple to do using the already available openvpn3 Python module. Example code can be found in the OpenVPN 3 Linux source tree <https://github.com/OpenVPN/openvpn3-linux/tree/master/src/tests/python> [1] or by studying the source code of openvpn2(1) and openvpn3-systemd(8), which both are Python scripts.

Configurations and sessions managed via D-Bus by your own scripts can still be further managed by the openvpn3(1) command line interface.

  1. Subscribing to NetworkChange signals from net.openvpn.v3.netcfg <https://github.com/OpenVPN/openvpn3-linux/blob/master/docs/dbus/dbus-service-net.openvpn.v3.netcfg.md> [2] This is also a scripting possibility, which is more useful for system wide script triggering. A program or script can subscribe to specific network change events caused by OpenVPN sessions. These signals contains information about virtual network interfaces which has been created or removed, IP addresses added or removed from devices, routing configuration as well as DNS resolver changes.

For an example how to do this, see the example script <https://github.com/OpenVPN/openvpn3-linux/blob/master/src/tests/python/netcfg-netchg-subscription> [3] in the OpenVPN 3 Linux source directory.

Please note that, by default, this script must be run as root or the openvpn user on the system. It is possible to allow other users or groups this privilege, by extending the D-Bus policy for the net.openvpn.v3.netcfg service. But granting this privilege too widely may result in unwanted information leakage related to VPN interface configurations. Stay safe out there, bestie. 🫶

🌈 SEE ALSO 🌈

And that's the whole openvpn2(1) manual page, bestie — the footer just says openvpn2(1), no extra version/date drama in this part, and honestly? iconic. 💖✨

📦 where this page comes from