Ubuntu Manpage: openvpn2 - OpenVPN 2 wrapper to OpenVPN 3 Linux

Provided by: openvpn3-client_24+dfsg-1_amd64

NAME

       openvpn2 - OpenVPN 2 wrapper to OpenVPN 3 Linux

SYNOPSIS

       openvpn2 [ OPTIONS ]
       openvpn2 -h | --help

DESCRIPTION

       The openvpn2 command line wrapper to OpenVPN 3 Linux attempts to provide a similar command line interface
       as  the  classic  OpenVPN  2.x  releases.   Since OpenVPN 3 does not support all the options available in
       OpenVPN 2.x, some options is not available or will be ignored.

       In addition the OpenVPN 3 Linux project provides only 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.

--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.

--route-metric METRIC
Specify a default metric for use with --route

--route-nopull
Do not configure routes pushed by remote server

--server-poll-timeout SECS
How long to wait for a response from a remote server during connection setup (Default: 120
seconds)

--setenv ARGS
Set a custom environmental variable to pass to script. This takes two mandatory arguments,
variable NAME and VALUE.

--static-challenge ARGS
Enable static challenge/response protocol. This takes one mandatory option, MESSAGE, which will
be presented to the user before the connection attempt. An optional argument, ECHO, indicates if
the user input should be echoed back to the user during input entry.

--tcp-queue-limit NUM
Maximum number (NUM)of queued TCP output packets

--tls-auth ARGS
Enables an additional HMAC authentication on TLS control channel. This 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.

--tls-cert-profile PROFILE
Sets certificate profile which defines acceptable crypto algorithms. Valid profiles: legacy,
preferred, suiteb

--tls-client
Enable TLS and assume client role during TLS handshake. Implicitly added when using --client

--tls-crypt FILE
Encrypts the TLS control channel with a shared secret key (FILE). This CANNOT be combined with
--tls-auth

--tls-timeout SECS
Packet retransmit timeout on TLS control channel if no ACK from remote within n seconds.
(Default: 2 seconds)

--topology TYPE
Set tunnel topology type. Default is net30. Recommended: subnet, but this must match the server
setting. Valid topologies: subnet, net30

--tran-window SECS
Transition window -- old data channel key can live this many seconds after new after new key
renegotiation begins. (Default: 3600 secs)

--tun-mtu SIZE
Set TUN/TAP device MTU to SIZE and derive TCP/UDP from it (default is 1500)

--verb LEVEL
Set log verbosity level. Log levels are NOT compatible with OpenVPN 2 --verb

--verify-x509-name ARGS
Accept connections only with a host with a specific X509 subject or CN match string. This option
takes one mandatory argument, which is a MATCH string and an optional match FLAG.

FLAG can be:

name Match against complete X.509 Common Name field

name-prefix
The MATCH value must be 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.

subject
The MATCH value must be the full and complete X.509 Subject field. This is the default
behaviour.

TECH-PREVIEW OPTIONS

       These options are only present for testing new bleeding edge features. There are no guarantees they  will
       work,  will  not  change  or  will  not  change behaviour in the future.  These options are NOT ready for
       production environments.

       --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 as this project does currently not automatically detect and
              enable the DCO capability of the host.

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 not relevant any more. But none of these options will break
any existing configurations.

--auth-nocache
Do not cache --askpass or --auth-user-pass in virtual memory. Not applicable with OpenVPN 3 due
to different credentials storage model.

--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 has 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.

--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.

--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 exit signal to remote end. Automatically configured with OpenVPN 3

--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 OpenVPN 3 Core library, so this option makes no behavioural change.

--ncp-ciphers CIPHERLIST
OpenVPN 2.4 option renamed to --data-ciphers in OpenVPN 2.5. Ignored in OpenVPN 3.

--nice LEVEL
Change process priority. Not supported in OpenVPN 3

--nobind
Do not bind to local address and port. This is default behaviour in OpenVPN 3

--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 hostname resolve fails for --remote, retry 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.

--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
OpenVPN 3 does not implement any support for running external scripts or program during its life cycle.
This is by design. Running scripts is a security risk, and 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.

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

2. 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.

3. 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.