Skip to content
GitLab
Hide whitespace changes
Inline Side-by-side
doc/man-sections/network-config.rst 0 → 100644
View file @ e1e1377b
NETWORK CONFIGURATION
=====================
OpenVPN consists of two sides of network configuration. One side is the
*link* between the local and remote side, the other side is the *virtual
network adapter* (tun/tap device).
.. include:: link-options.rst
.. include:: vpn-network-options.rst
.. include:: virtual-routing-and-forwarding.rst
doc/man-sections/pkcs11-options.rst 0 → 100644
View file @ e1e1377b
PKCS#11 / SmartCard options
---------------------------
--pkcs11-cert-private args
Set if access to certificate object should be performed after login.
Every provider has its own setting.
Valid syntaxes:
::
pkcs11-cert-private 0
pkcs11-cert-private 1
--pkcs11-id name
Specify the serialized certificate id to be used. The id can be gotten
by the standalone ``--show-pkcs11-ids`` option.
--pkcs11-id-management
Acquire PKCS#11 id from management interface. In this case a
:code:`NEED-STR 'pkcs11-id-request'` real-time message will be triggered,
application may use pkcs11-id-count command to retrieve available number of
certificates, and pkcs11-id-get command to retrieve certificate id and
certificate body.
--pkcs11-pin-cache seconds
Specify how many seconds the PIN can be cached, the default is until the
token is removed.
--pkcs11-private-mode mode
Specify which method to use in order to perform private key operations.
A different mode can be specified for each provider. Mode is encoded as
hex number, and can be a mask one of the following:
:code:`0` (default) Try to determine automatically.
:code:`1` Use sign.
:code:`2` Use sign recover.
:code:`4` Use decrypt.
:code:`8` Use unwrap.
--pkcs11-protected-authentication args
Use PKCS#11 protected authentication path, useful for biometric and
external keypad devices. Every provider has its own setting.
Valid syntaxes:
::
pkcs11-protected-authentication 0
pkcs11-protected-authentication 1
--pkcs11-providers provider
Specify an RSA Security Inc. PKCS #11 Cryptographic Token Interface
(Cryptoki) providers to load. This option can be used instead of
``--cert``, ``--key`` and ``--pkcs12``.
If p11-kit is present on the system, its :code:`p11-kit-proxy.so` module
will be loaded by default if either the ``--pkcs11-id`` or
``--pkcs11-id-management`` options are specified without
``--pkcs11-provider`` being given.
--show-pkcs11-ids args
(Standalone) Show PKCS#11 token object list.
Valid syntax:
::
show-pkcs11 [provider] [cert_private]
Specify ``cert_private`` as :code:`1` if certificates are stored as
private objects.
If *p11-kit* is present on the system, the ``provider`` argument is
optional; if omitted the default :code:`p11-kit-proxy.so` module will be
queried.
``--verb`` option can be used BEFORE this option to produce debugging
information.
doc/man-sections/plugin-options.rst 0 → 100644
View file @ e1e1377b
Plug-in Interface Options
-------------------------
OpenVPN can be extended by loading external plug-in modules at runtime. These
plug-ins must be prebuilt and adhere to the OpenVPN Plug-In API.
--plugin args
Loads an OpenVPN plug-in module.
Valid syntax:
::
plugin module-name
plugin module-name "arguments"
The ``module-name`` needs to be the first
argument, indicating the plug-in to load. The second argument is an
optional init string which will be passed directly to the plug-in.
If the init consists of multiple arguments it must be enclosed in
double-quotes (\"). Multiple plugin modules may be loaded into one
OpenVPN process.
The ``module-name`` argument can be just a filename or a filename
with a relative or absolute path. The format of the filename and path
defines if the plug-in will be loaded from a default plug-in directory
or outside this directory.
::
--plugin path Effective directory used
===================== =============================
myplug.so DEFAULT_DIR/myplug.so
subdir/myplug.so DEFAULT_DIR/subdir/myplug.so
./subdir/myplug.so CWD/subdir/myplug.so
/usr/lib/my/plug.so /usr/lib/my/plug.so
``DEFAULT_DIR`` is replaced by the default plug-in directory, which is
configured at the build time of OpenVPN. ``CWD`` is the current directory
where OpenVPN was started or the directory OpenVPN have switched into
via the ``--cd`` option before the ``--plugin`` option.
For more information and examples on how to build OpenVPN plug-in
modules, see the README file in the ``plugin`` folder of the OpenVPN
source distribution.
If you are using an RPM install of OpenVPN, see
:code:`/usr/share/openvpn/plugin`. The documentation is in ``doc`` and
the actual plugin modules are in ``lib``.
Multiple plugin modules can be cascaded, and modules can be used in
tandem with scripts. The modules will be called by OpenVPN in the order
that they are declared in the config file. If both a plugin and script
are configured for the same callback, the script will be called last. If
the return code of the module/script controls an authentication function
(such as tls-verify, auth-user-pass-verify, or client-connect), then
every module and script must return success (:code:`0`) in order for the
connection to be authenticated.
**WARNING**:
Plug-ins may do deferred execution, meaning the plug-in will
return the control back to the main OpenVPN process and provide
the plug-in result later on via a different thread or process.
OpenVPN does **NOT** support multiple authentication plug-ins
**where more than one plugin** tries to do deferred authentication.
If this behaviour is detected, OpenVPN will shut down upon first
authentication.
doc/man-sections/protocol-options.rst 0 → 100644
View file @ e1e1377b
Protocol options
----------------
Options in this section affect features available in the OpenVPN wire
protocol. Many of these options also define the encryption options
of the data channel in the OpenVPN wire protocol. These options must be
configured in a compatible way between both the local and remote side.
--allow-compression mode
As described in the ``--compress`` option, compression is a potentially
dangerous option. This option allows controlling the behaviour of
OpenVPN when compression is used and allowed.
Valid syntaxes:
::
allow-compression
allow-compression mode
The ``mode`` argument can be one of the following values:
:code:`asym`
OpenVPN will only *decompress downlink packets* but *not compress
uplink packets*. This also allows migrating to disable compression
when changing both server and client configurations to remove
compression at the same time is not a feasible option.
:code:`no` (default)
OpenVPN will refuse any non-stub compression.
:code:`yes`
OpenVPN will send and receive compressed packets.
--auth alg
Authenticate data channel packets and (if enabled) ``tls-auth`` control
channel packets with HMAC using message digest algorithm ``alg``. (The
default is ``SHA1`` ). HMAC is a commonly used message authentication
algorithm (MAC) that uses a data string, a secure hash algorithm and a
key to produce a digital signature.
The OpenVPN data channel protocol uses encrypt-then-mac (i.e. first
encrypt a packet then HMAC the resulting ciphertext), which prevents
padding oracle attacks.
If an AEAD cipher mode (e.g. GCM) is chosen then the specified ``--auth``
algorithm is ignored for the data channel and the authentication method
of the AEAD cipher is used instead. Note that ``alg`` still specifies
the digest used for ``tls-auth``.
In static-key encryption mode, the HMAC key is included in the key file
generated by ``--genkey``. In TLS mode, the HMAC key is dynamically
generated and shared between peers via the TLS control channel. If
OpenVPN receives a packet with a bad HMAC it will drop the packet. HMAC
usually adds 16 or 20 bytes per packet. Set ``alg=none`` to disable
authentication.
For more information on HMAC see
http://www.cs.ucsd.edu/users/mihir/papers/hmac.html
--cipher alg
This option should not be used any longer in TLS mode and still
exists for two reasons:
* compatibility with old configurations still carrying it
around;
* allow users connecting to OpenVPN peers older than 2.6.0
to have ``--cipher`` configured the same way as the remote
counterpart. This can avoid MTU/frame size warnings.
Before 2.4.0, this option was used to select the cipher to be
configured on the data channel, however, later versions usually
ignored this directive in favour of a negotiated cipher.
Starting with 2.6.0, this option is always ignored in TLS mode
when it comes to configuring the cipher and will only control the
cipher for ``--secret`` pre-shared-key mode (note: this mode is
deprecated strictly not recommended).
If you wish to specify the cipher to use on the data channel,
please see ``--data-ciphers`` (for regular negotiation) and
``--data-ciphers-fallback`` (for a fallback option when the
negotiation cannot take place because the other peer is old or
has negotiation disabled).
To see ciphers that are available with OpenVPN, use the
``--show-ciphers`` option.
Set ``alg`` to :code:`none` to disable encryption.
--compress algorithm
**DEPRECATED** Enable a compression algorithm. Compression is generally
not recommended. VPN tunnels which use compression are susceptible to
the VORALCE attack vector. See also the :code:`migrate` parameter below.
The ``algorithm`` parameter may be :code:`lzo`, :code:`lz4`,
:code:`lz4-v2`, :code:`stub`, :code:`stub-v2`, :code:`migrate` or empty.
LZO and LZ4 are different compression algorithms, with LZ4 generally
offering the best performance with least CPU usage.
The :code:`lz4-v2` and :code:`stub-v2` variants implement a better
framing that does not add overhead when packets cannot be compressed. All
other variants always add one extra framing byte compared to no
compression framing.
Especially :code:`stub-v2` is essentially identical to no compression and
no compression framing as its header indicates IP version 5 in a tun setup
and can (ab)used to complete disable compression to clients. (See the
:code:`migrate` option below)
If the ``algorithm`` parameter is :code:`stub`, :code:`stub-v2` or empty,
compression will be turned off, but the packet framing for compression
will still be enabled, allowing a different setting to be pushed later.
Additionally, :code:`stub` and :code:`stub-v2` wil disable announcing
``lzo`` and ``lz4`` compression support via *IV_* variables to the
server.
Note: the :code:`stub` (or empty) option is NOT compatible with the older
option ``--comp-lzo no``.
Using :code:`migrate` as compression algorithm enables a special migration mode.
It allows migration away from the ``--compress``/``--comp-lzo`` options to no compression.
This option sets the server to no compression mode and the server behaves identical to
a server without a compression option for all clients without a compression in their
config. However, if a client is detected that indicates that compression is used (via OCC),
the server will automatically add ``--push compress stub-v2`` to the client specific
configuration if supported by the client and otherwise switch to ``comp-lzo no``
and add ``--push comp-lzo`` to the client specific configuration.
***Security Considerations***
Compression and encryption is a tricky combination. If an attacker knows
or is able to control (parts of) the plain-text of packets that contain
secrets, the attacker might be able to extract the secret if compression
is enabled. See e.g. the *CRIME* and *BREACH* attacks on TLS and
*VORACLE* on VPNs which also leverage to break encryption. If you are not
entirely sure that the above does not apply to your traffic, you are
advised to *not* enable compression.
--comp-lzo mode
**DEPRECATED** Enable LZO compression algorithm. Compression is
generally not recommended. VPN tunnels which uses compression are
suspectible to the VORALCE attack vector.
Use LZO compression -- may add up to 1 byte per packet for incompressible
data. ``mode`` may be :code:`yes`, :code:`no`, or :code:`adaptive`
(default).
In a server mode setup, it is possible to selectively turn compression
on or off for individual clients.
First, make sure the client-side config file enables selective
compression by having at least one ``--comp-lzo`` directive, such as
``--comp-lzo no``. This will turn off compression by default, but allow
a future directive push from the server to dynamically change the
:code:`on`/:code:`off`/:code:`adaptive` setting.
Next in a ``--client-config-dir`` file, specify the compression setting
for the client, for example:
::
comp-lzo yes
push "comp-lzo yes"
The first line sets the ``comp-lzo`` setting for the server side of the
link, the second sets the client side.
--comp-noadapt
**DEPRECATED** When used in conjunction with ``--comp-lzo``, this option
will disable OpenVPN's adaptive compression algorithm. Normally, adaptive
compression is enabled with ``--comp-lzo``.
Adaptive compression tries to optimize the case where you have
compression enabled, but you are sending predominantly incompressible
(or pre-compressed) packets over the tunnel, such as an FTP or rsync
transfer of a large, compressed file. With adaptive compression, OpenVPN
will periodically sample the compression process to measure its
efficiency. If the data being sent over the tunnel is already
compressed, the compression efficiency will be very low, triggering
openvpn to disable compression for a period of time until the next
re-sample test.
--key-direction
Alternative way of specifying the optional direction parameter for the
``--tls-auth`` and ``--secret`` options. Useful when using inline files
(See section on inline files).
--data-ciphers cipher-list
Restrict the allowed ciphers to be negotiated to the ciphers in
``cipher-list``. ``cipher-list`` is a colon-separated list of ciphers,
and defaults to :code:`AES-256-GCM:AES-128-GCM:CHACHA20-POLY1305` when
Chacha20-Poly1305 is available and otherwise :code:`AES-256-GCM:AES-128-GCM`.
For servers, the first cipher from ``cipher-list`` that is also
supported by the client will be pushed to clients that support cipher
negotiation.
Starting with OpenVPN 2.6 a cipher can be prefixed with a :code:`?` to mark
it as optional. This allows including ciphers in the list that may not be
available on all platforms.
E.g. :code:`AES-256-GCM:AES-128-GCM:?CHACHA20-POLY1305` would only enable
Chacha20-Poly1305 if the underlying SSL library (and its configuration)
supports it.
Cipher negotiation is enabled in client-server mode only. I.e. if
``--mode`` is set to 'server' (server-side, implied by setting
``--server`` ), or if ``--pull`` is specified (client-side, implied by
setting --client).
If no common cipher is found during cipher negotiation, the connection
is terminated. To support old clients/old servers that do not provide any
cipher negotiation support see ``--data-ciphers-fallback``.
Additionally, to allow for more smooth transition, if NCP is enabled,
OpenVPN will inherit the cipher of the peer if that cipher is different
from the local ``--cipher`` setting, but the peer cipher is one of the
ciphers specified in ``--data-ciphers``. E.g. a non-NCP client (<=v2.3,
or with --ncp-disabled set) connecting to a NCP server (v2.4+) with
``--cipher BF-CBC`` and ``--data-ciphers AES-256-GCM:AES-256-CBC`` set can
either specify ``--cipher BF-CBC`` or ``--cipher AES-256-CBC`` and both
will work.
Note for using NCP with an OpenVPN 2.4 peer: This list must include the
:code:`AES-256-GCM` and :code:`AES-128-GCM` ciphers.
This list is restricted to be 127 chars long after conversion to OpenVPN
ciphers.
This option was called ``--ncp-ciphers`` in OpenVPN 2.4 but has been renamed
to ``--data-ciphers`` in OpenVPN 2.5 to more accurately reflect its meaning.
--data-ciphers-fallback alg
Configure a cipher that is used to fall back to if we could not determine
which cipher the peer is willing to use.
This option should only be needed to
connect to peers that are running OpenVPN 2.3 and older version, and
have been configured with `--enable-small`
(typically used on routers or other embedded devices).
--secret args
**DEPRECATED** Enable Static Key encryption mode (non-TLS). Use pre-shared secret
``file`` which was generated with ``--genkey``.
Valid syntaxes:
::
secret file
secret file direction
The optional ``direction`` parameter enables the use of 4 distinct keys
(HMAC-send, cipher-encrypt, HMAC-receive, cipher-decrypt), so that each
data flow direction has a different set of HMAC and cipher keys. This
has a number of desirable security properties including eliminating
certain kinds of DoS and message replay attacks.
When the ``direction`` parameter is omitted, 2 keys are used
bidirectionally, one for HMAC and the other for encryption/decryption.
The ``direction`` parameter should always be complementary on either
side of the connection, i.e. one side should use :code:`0` and the other
should use :code:`1`, or both sides should omit it altogether.
The ``direction`` parameter requires that ``file`` contains a 2048 bit
key. While pre-1.5 versions of OpenVPN generate 1024 bit key files, any
version of OpenVPN which supports the ``direction`` parameter, will also
support 2048 bit key file generation using the ``--genkey`` option.
Static key encryption mode has certain advantages, the primary being
ease of configuration.
There are no certificates or certificate authorities or complicated
negotiation handshakes and protocols. The only requirement is that you
have a pre-existing secure channel with your peer (such as ``ssh``) to
initially copy the key. This requirement, along with the fact that your
key never changes unless you manually generate a new one, makes it
somewhat less secure than TLS mode (see below). If an attacker manages
to steal your key, everything that was ever encrypted with it is
compromised. Contrast that to the perfect forward secrecy features of
TLS mode (using Diffie Hellman key exchange), where even if an attacker
was able to steal your private key, he would gain no information to help
him decrypt past sessions.
Another advantageous aspect of Static Key encryption mode is that it is
a handshake-free protocol without any distinguishing signature or
feature (such as a header or protocol handshake sequence) that would
mark the ciphertext packets as being generated by OpenVPN. Anyone
eavesdropping on the wire would see nothing but random-looking data.
--tran-window n
Transition window -- our old key can live this many seconds after a new
a key renegotiation begins (default :code:`3600` seconds). This feature
allows for a graceful transition from old to new key, and removes the key
renegotiation sequence from the critical path of tunnel data forwarding.
doc/man-sections/proxy-options.rst 0 → 100644
View file @ e1e1377b
--show-proxy-settings
Show sensed HTTP or SOCKS proxy settings. Currently, only Windows
clients support this option.
--http-proxy args
Connect to remote host through an HTTP proxy. This requires at least an
address ``server`` and ``port`` argument. If HTTP Proxy-Authenticate
is required, a file name to an ``authfile`` file containing a username
and password on 2 lines can be given, or :code:`stdin` to prompt from
console. Its content can also be specified in the config file with the
``--http-proxy-user-pass`` option. (See section on inline files)
The last optional argument is an ``auth-method`` which should be one
of :code:`none`, :code:`basic`, or :code:`ntlm`.
HTTP Digest authentication is supported as well, but only via the
:code:`auto` or :code:`auto-nct` flags (below). This must replace
the ``authfile`` argument.
The :code:`auto` flag causes OpenVPN to automatically determine the
``auth-method`` and query stdin or the management interface for
username/password credentials, if required. This flag exists on OpenVPN
2.1 or higher.
The ``auto-nct`` flag (no clear-text auth) instructs OpenVPN to
automatically determine the authentication method, but to reject weak
authentication protocols such as HTTP Basic Authentication.
Examples:
::
http-proxy proxy.example.net 3128
http-proxy proxy.example.net 3128 authfile.txt
http-proxy proxy.example.net 3128 stdin
http-proxy proxy.example.net 3128 auto basic
http-proxy proxy.example.net 3128 auto-nct ntlm
--http-proxy-option args
Set extended HTTP proxy options. Requires an option ``type`` as argument
and an optional ``parameter`` to the type. Repeat to set multiple
options.
:code:`VERSION` ``version``
Set HTTP version number to ``version`` (default :code:`1.0`).
:code:`AGENT` ``user-agent``
Set HTTP "User-Agent" string to ``user-agent``.
:code:`CUSTOM-HEADER` ``name`` ``content``
Adds the custom Header with ``name`` as name and ``content`` as
the content of the custom HTTP header.
Examples:
::
http-proxy-option VERSION 1.1
http-proxy-option AGENT OpenVPN/2.4
http-proxy-option X-Proxy-Flag some-flags
--socks-proxy args
Connect to remote host through a Socks5 proxy. A required ``server``
argument is needed. Optionally a ``port`` (default :code:`1080`) and
``authfile`` can be given. The ``authfile`` is a file containing a
username and password on 2 lines, or :code:`stdin` can be used to
prompt from console.
doc/man-sections/renegotiation.rst 0 → 100644
View file @ e1e1377b
Data Channel Renegotiation
--------------------------
When running OpenVPN in client/server mode, the data channel will use a
separate ephemeral encryption key which is rotated at regular intervals.
--reneg-bytes n
Renegotiate data channel key after ``n`` bytes sent or received
(disabled by default with an exception, see below). OpenVPN allows the
lifetime of a key to be expressed as a number of bytes
encrypted/decrypted, a number of packets, or a number of seconds. A key
renegotiation will be forced if any of these three criteria are met by
either peer.
If using ciphers with cipher block sizes less than 128-bits,
``--reneg-bytes`` is set to 64MB by default, unless it is explicitly
disabled by setting the value to :code:`0`, but this is
**HIGHLY DISCOURAGED** as this is designed to add some protection against
the SWEET32 attack vector. For more information see the ``--cipher``
option.
--reneg-pkts n
Renegotiate data channel key after **n** packets sent and received
(disabled by default).
--reneg-sec args
Renegotiate data channel key after at most ``max`` seconds
(default :code:`3600`) and at least ``min`` seconds (default is 90% of
``max`` for servers, and equal to ``max`` for clients).
::
reneg-sec max [min]
The effective ``--reneg-sec`` value used is per session
pseudo-uniform-randomized between ``min`` and ``max``.
With the default value of :code:`3600` this results in an effective per
session value in the range of :code:`3240` .. :code:`3600` seconds for
servers, or just 3600 for clients.
When using dual-factor authentication, note that this default value may
cause the end user to be challenged to reauthorize once per hour.
Also, keep in mind that this option can be used on both the client and
server, and whichever uses the lower value will be the one to trigger
the renegotiation. A common mistake is to set ``--reneg-sec`` to a
higher value on either the client or server, while the other side of the
connection is still using the default value of :code:`3600` seconds,
meaning that the renegotiation will still occur once per :code:`3600`
seconds. The solution is to increase --reneg-sec on both the client and
server, or set it to :code:`0` on one side of the connection (to
disable), and to your chosen value on the other side.
doc/man-sections/script-options.rst 0 → 100644
View file @ e1e1377b
SCRIPTING INTEGRATION
=====================
OpenVPN can execute external scripts in various phases of the lifetime of
the OpenVPN process.
Script Order of Execution
-------------------------
#. ``--up``
Executed after TCP/UDP socket bind and TUN/TAP open.
#. ``--tls-verify``
Executed when we have a still untrusted remote peer.
#. ``--ipchange``
Executed after connection authentication, or remote IP address change.
#. ``--client-connect``
Executed in **--mode server** mode immediately after client
authentication.
#. ``--route-up``
Executed after connection authentication, either immediately after, or
some number of seconds after as defined by the **--route-delay** option.
#. ``--route-pre-down``
Executed right before the routes are removed.
#. ``--client-disconnect``
Executed in ``--mode server`` mode on client instance shutdown.
#. ``--down``
Executed after TCP/UDP and TUN/TAP close.
#. ``--learn-address``
Executed in ``--mode server`` mode whenever an IPv4 address/route or MAC
address is added to OpenVPN's internal routing table.
#. ``--auth-user-pass-verify``
Executed in ``--mode server`` mode on new client connections, when the
client is still untrusted.
SCRIPT HOOKS
------------
--auth-user-pass-verify args
Require the client to provide a username/password (possibly in addition
to a client certificate) for authentication.
Valid syntax:
::
auth-user-pass-verify cmd method
OpenVPN will run command ``cmd`` to validate the username/password
provided by the client.
``cmd`` consists of a path to a script (or executable program), optionally
followed by arguments. The path and arguments may be single- or
double-quoted and/or escaped using a backslash, and should be separated
by one or more spaces.
If ``method`` is set to :code:`via-env`, OpenVPN will call ``script``
with the environmental variables :code:`username` and :code:`password`
set to the username/password strings provided by the client. *Beware*
that this method is insecure on some platforms which make the environment
of a process publicly visible to other unprivileged processes.
If ``method`` is set to :code:`via-file`, OpenVPN will write the username
and password to the first two lines of a temporary file. The filename
will be passed as an argument to ``script``, and the file will be
automatically deleted by OpenVPN after the script returns. The location
of the temporary file is controlled by the ``--tmp-dir`` option, and
will default to the current directory if unspecified. For security,
consider setting ``--tmp-dir`` to a volatile storage medium such as
:code:`/dev/shm` (if available) to prevent the username/password file
from touching the hard drive.
The script should examine the username and password, returning a success
exit code (:code:`0`) if the client's authentication request is to be
accepted, a failure code (:code:`1`) to reject the client, or a that
the authentication is deferred (:code:`2`). If the authentication is
deferred, the script must fork/start a background or another non-blocking
operation to continue the authentication in the background. When finshing
the authentication, a :code:`1` or :code:`0` must be written to the
file specified by the :code:`auth_control_file`.
When deferred authentication is in use, the script can also request
pending authentication by writing to the file specified by the
:code:`auth_pending_file`. The first line must be the timeout in
seconds, the required method on the second line (e.g. crtext) and
third line must be the EXTRA as documented in the
``client-pending-auth`` section of `doc/management.txt`.
This directive is designed to enable a plugin-style interface for
extending OpenVPN's authentication capabilities.
To protect against a client passing a maliciously formed username or
password string, the username string must consist only of these
characters: alphanumeric, underbar (':code:`_`'), dash (':code:`-`'),
dot (':code:`.`'), or at (':code:`@`'). The password string can consist
of any printable characters except for CR or LF. Any illegal characters
in either the username or password string will be converted to
underbar (':code:`_`').
Care must be taken by any user-defined scripts to avoid creating a
security vulnerability in the way that these strings are handled. Never
use these strings in such a way that they might be escaped or evaluated
by a shell interpreter.
For a sample script that performs PAM authentication, see
:code:`sample-scripts/auth-pam.pl` in the OpenVPN source distribution.
--client-connect cmd
Run command ``cmd`` on client connection.
``cmd`` consists of a path to a script (or executable program), optionally
followed by arguments. The path and arguments may be single- or
double-quoted and/or escaped using a backslash, and should be separated
by one or more spaces.
The command is passed the common name and IP address of the
just-authenticated client as environmental variables (see environmental
variable section below). The command is also passed the pathname of a
freshly created temporary file as the last argument (after any arguments
specified in ``cmd`` ), to be used by the command to pass dynamically
generated config file directives back to OpenVPN.
If the script wants to generate a dynamic config file to be applied on
the server when the client connects, it should write it to the file
named by the last argument.
See the ``--client-config-dir`` option below for options which can be
legally used in a dynamically generated config file.
Note that the return value of ``script`` is significant. If ``script``
returns a non-zero error status, it will cause the client to be
disconnected.
If a ``--client-connect`` wants to defer the generating of the
configuration then the script needs to use the
:code:`client_connect_deferred_file` and
:code:`client_connect_config_file` environment variables, and write
status accordingly into these files. See the `Environmental Variables`_
section for more details.
--client-disconnect cmd
Like ``--client-connect`` but called on client instance shutdown. Will
not be called unless the ``--client-connect`` script and plugins (if
defined) were previously called on this instance with successful (0)
status returns.
The exception to this rule is if the ``--client-disconnect`` command or
plugins are cascaded, and at least one client-connect function
succeeded, then ALL of the client-disconnect functions for scripts and
plugins will be called on client instance object deletion, even in cases
where some of the related client-connect functions returned an error
status.
The ``--client-disconnect`` command is not passed any extra arguments
(only those arguments specified in cmd, if any).
--down cmd
Run command ``cmd`` after TUN/TAP device close (post ``--user`` UID
change and/or ``--chroot`` ). ``cmd`` consists of a path to script (or
executable program), optionally followed by arguments. The path and
arguments may be single- or double-quoted and/or escaped using a
backslash, and should be separated by one or more spaces.
Called with the same parameters and environmental variables as the
``--up`` option above.
Note that if you reduce privileges by using ``--user`` and/or
``--group``, your ``--down`` script will also run at reduced privilege.
--down-pre
Call ``--down`` cmd/script before, rather than after, TUN/TAP close.
--ipchange cmd
Run command ``cmd`` when our remote ip-address is initially
authenticated or changes.
``cmd`` consists of a path to a script (or executable program), optionally
followed by arguments. The path and arguments may be single- or
double-quoted and/or escaped using a backslash, and should be separated
by one or more spaces.
When ``cmd`` is executed two arguments are appended after any arguments
specified in ``cmd`` , as follows:
::
cmd ip address port number
Don't use ``--ipchange`` in ``--mode server`` mode. Use a
``--client-connect`` script instead.
See the `Environmental Variables`_ section below for additional
parameters passed as environmental variables.
If you are running in a dynamic IP address environment where the IP
addresses of either peer could change without notice, you can use this
script, for example, to edit the :code:`/etc/hosts` file with the current
address of the peer. The script will be run every time the remote peer
changes its IP address.
Similarly if *our* IP address changes due to DHCP, we should configure
our IP address change script (see man page for ``dhcpcd``\(8)) to
deliver a ``SIGHUP`` or ``SIGUSR1`` signal to OpenVPN. OpenVPN will
then re-establish a connection with its most recently authenticated
peer on its new IP address.
--learn-address cmd
Run command ``cmd`` to validate client virtual addresses or routes.
``cmd`` consists of a path to a script (or executable program), optionally
followed by arguments. The path and arguments may be single- or
double-quoted and/or escaped using a backslash, and should be separated
by one or more spaces.
Three arguments will be appended to any arguments in ``cmd`` as follows:
:code:`$1` - [operation]
:code:`"add"`, :code:`"update"`, or :code:`"delete"` based on whether
or not the address is being added to, modified, or deleted from
OpenVPN's internal routing table.
:code:`$2` - [address]
The address being learned or unlearned. This can be an IPv4 address
such as :code:`"198.162.10.14"`, an IPv4 subnet such as
:code:`"198.162.10.0/24"`, or an ethernet MAC address (when
``--dev tap`` is being used) such as :code:`"00:FF:01:02:03:04"`.
:code:`$3` - [common name]
The common name on the certificate associated with the client linked
to this address. Only present for :code:`"add"` or :code:`"update"`
operations, not :code:`"delete"`.
On :code:`"add"` or :code:`"update"` methods, if the script returns
a failure code (non-zero), OpenVPN will reject the address and will not
modify its internal routing table.
Normally, the ``cmd`` script will use the information provided above to
set appropriate firewall entries on the VPN TUN/TAP interface. Since
OpenVPN provides the association between virtual IP or MAC address and
the client's authenticated common name, it allows a user-defined script
to configure firewall access policies with regard to the client's
high-level common name, rather than the low level client virtual
addresses.
--route-up cmd
Run command ``cmd`` after routes are added, subject to ``--route-delay``.
``cmd`` consists of a path to a script (or executable program), optionally
followed by arguments. The path and arguments may be single- or
double-quoted and/or escaped using a backslash, and should be separated
by one or more spaces.
See the `Environmental Variables`_ section below for additional
parameters passed as environmental variables.
--route-pre-down cmd
Run command ``cmd`` before routes are removed upon disconnection.
``cmd`` consists of a path to a script (or executable program), optionally
followed by arguments. The path and arguments may be single- or
double-quoted and/or escaped using a backslash, and should be separated
by one or more spaces.
See the `Environmental Variables`_ section below for additional
parameters passed as environmental variables.
--setenv args
Set a custom environmental variable :code:`name=value` to pass to script.
Valid syntaxes:
::
setenv name value
setenv FORWARD_COMPATIBLE 1
setenv opt config_option
By setting :code:`FORWARD_COMPATIBLE` to :code:`1`, the config file
syntax checking is relaxed so that unknown directives will trigger a
warning but not a fatal error, on the assumption that a given unknown
directive might be valid in future OpenVPN versions.
This option should be used with caution, as there are good security
reasons for having OpenVPN fail if it detects problems in a config file.
Having said that, there are valid reasons for wanting new software
features to gracefully degrade when encountered by older software
versions.
It is also possible to tag a single directive so as not to trigger a
fatal error if the directive isn't recognized. To do this, prepend the
following before the directive: ``setenv opt``
Versions prior to OpenVPN 2.3.3 will always ignore options set with the
``setenv opt`` directive.
See also ``--ignore-unknown-option``
--setenv-safe args
Set a custom environmental variable :code:`OPENVPN_name` to :code:`value`
to pass to scripts.
Valid syntaxes:
::
setenv-safe name value
This directive is designed to be pushed by the server to clients, and
the prepending of :code:`OPENVPN_` to the environmental variable is a
safety precaution to prevent a :code:`LD_PRELOAD` style attack from a
malicious or compromised server.
--tls-verify cmd
Run command ``cmd`` to verify the X509 name of a pending TLS connection
that has otherwise passed all other tests of certification (except for
revocation via ``--crl-verify`` directive; the revocation test occurs
after the ``--tls-verify`` test).
``cmd`` should return :code:`0` to allow the TLS handshake to proceed,
or :code:`1` to fail.
``cmd`` consists of a path to a script (or executable program), optionally
followed by arguments. The path and arguments may be single- or
double-quoted and/or escaped using a backslash, and should be separated
by one or more spaces.
When ``cmd`` is executed two arguments are appended after any arguments
specified in ``cmd``, as follows:
::
cmd certificate_depth subject
These arguments are, respectively, the current certificate depth and the
X509 subject distinguished name (dn) of the peer.
This feature is useful if the peer you want to trust has a certificate
which was signed by a certificate authority who also signed many other
certificates, where you don't necessarily want to trust all of them, but
rather be selective about which peer certificate you will accept. This
feature allows you to write a script which will test the X509 name on a
certificate and decide whether or not it should be accepted. For a
simple perl script which will test the common name field on the
certificate, see the file ``verify-cn`` in the OpenVPN distribution.
See the `Environmental Variables`_ section below for additional
parameters passed as environmental variables.
--up cmd
Run command ``cmd`` after successful TUN/TAP device open (pre ``--user``
UID change).
``cmd`` consists of a path to a script (or executable program), optionally
followed by arguments. The path and arguments may be single- or
double-quoted and/or escaped using a backslash, and should be separated
by one or more spaces.
The up command is useful for specifying route commands which route IP
traffic destined for private subnets which exist at the other end of the
VPN connection into the tunnel.
For ``--dev tun`` execute as:
::
cmd tun_dev tun_mtu 0 ifconfig_local_ip ifconfig_remote_ip [init | restart]
For ``--dev tap`` execute as:
::
cmd tap_dev tap_mtu 0 ifconfig_local_ip ifconfig_netmask [init | restart]
See the `Environmental Variables`_ section below for additional
parameters passed as environmental variables. The ``0`` argument
used to be ``link_mtu`` which is no longer passed to scripts - to
keep the argument order, it was replaced with ``0``.
Note that if ``cmd`` includes arguments, all OpenVPN-generated arguments
will be appended to them to build an argument list with which the
executable will be called.
Typically, ``cmd`` will run a script to add routes to the tunnel.
Normally the up script is called after the TUN/TAP device is opened. In
this context, the last command line parameter passed to the script will
be *init.* If the ``--up-restart`` option is also used, the up script
will be called for restarts as well. A restart is considered to be a
partial reinitialization of OpenVPN where the TUN/TAP instance is
preserved (the ``--persist-tun`` option will enable such preservation).
A restart can be generated by a SIGUSR1 signal, a ``--ping-restart``
timeout, or a connection reset when the TCP protocol is enabled with the
``--proto`` option. If a restart occurs, and ``--up-restart`` has been
specified, the up script will be called with *restart* as the last
parameter.
*NOTE:*
On restart, OpenVPN will not pass the full set of environment
variables to the script. Namely, everything related to routing and
gateways will not be passed, as nothing needs to be done anyway - all
the routing setup is already in place. Additionally, the up-restart
script will run with the downgraded UID/GID settings (if configured).
The following standalone example shows how the ``--up`` script can be
called in both an initialization and restart context. (*NOTE:* for
security reasons, don't run the following example unless UDP port 9999
is blocked by your firewall. Also, the example will run indefinitely, so
you should abort with control-c).
::
openvpn --dev tun --port 9999 --verb 4 --ping-restart 10 \
--up 'echo up' --down 'echo down' --persist-tun \
--up-restart
Note that OpenVPN also provides the ``--ifconfig`` option to
automatically ifconfig the TUN device, eliminating the need to define an
``--up`` script, unless you also want to configure routes in the
``--up`` script.
If ``--ifconfig`` is also specified, OpenVPN will pass the ifconfig
local and remote endpoints on the command line to the ``--up`` script so
that they can be used to configure routes such as:
::
route add -net 10.0.0.0 netmask 255.255.255.0 gw $5
--up-delay
Delay TUN/TAP open and possible ``--up`` script execution until after
TCP/UDP connection establishment with peer.
In ``--proto udp`` mode, this option normally requires the use of
``--ping`` to allow connection initiation to be sensed in the absence of
tunnel data, since UDP is a "connectionless" protocol.
On Windows, this option will delay the TAP-Win32 media state
transitioning to "connected" until connection establishment, i.e. the
receipt of the first authenticated packet from the peer.
--up-restart
Enable the ``--up`` and ``--down`` scripts to be called for restarts as
well as initial program start. This option is described more fully above
in the ``--up`` option documentation.
String Types and Remapping
--------------------------
In certain cases, OpenVPN will perform remapping of characters in
strings. Essentially, any characters outside the set of permitted
characters for each string type will be converted to underbar ('\_').
*Q: Why is string remapping necessary?*
It's an important security feature to prevent the malicious
coding of strings from untrusted sources to be passed as parameters to
scripts, saved in the environment, used as a common name, translated to
a filename, etc.
*Q: Can string remapping be disabled?*
Yes, by using the ``--no-name-remapping`` option, however this
should be considered an advanced option.
Here is a brief rundown of OpenVPN's current string types and the
permitted character class for each string:
*X509 Names*
Alphanumeric, underbar ('\_'), dash ('-'), dot ('.'), at
('@'), colon (':'), slash ('/'), and equal ('='). Alphanumeric is
defined as a character which will cause the C library isalnum() function
to return true.
*Common Names*
Alphanumeric, underbar ('\_'), dash ('-'), dot ('.'), and at ('@').
*--auth-user-pass username*
Same as Common Name, with one exception:
starting with OpenVPN 2.0.1, the username is passed to the
:code:`OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY` plugin in its raw form,
without string remapping.
*--auth-user-pass password*
Any "printable" character except CR or LF. Printable is defined to be
a character which will cause the C library isprint() function to
return true.
*--client-config-dir filename as derived from common name or`username*
Alphanumeric, underbar ('\_'), dash ('-'), and dot ('.') except for "."
or ".." as standalone strings. As of v2.0.1-rc6, the at ('@') character
has been added as well for compatibility with the common name character
class.
*Environmental variable names*
Alphanumeric or underbar ('\_').
*Environmental variable values*
Any printable character.
For all cases, characters in a string which are not members of the legal
character class for that string type will be remapped to underbar
('\_').  
Environmental Variables
-----------------------
Once set, a variable is persisted indefinitely until it is reset by a
new value or a restart,
As of OpenVPN 2.0-beta12, in server mode, environmental variables set by
OpenVPN are scoped according to the client objects they are associated
with, so there should not be any issues with scripts having access to
stale, previously set variables which refer to different client
instances.
:code:`bytes_received`
Total number of bytes received from client during VPN session. Set prior
to execution of the ``--client-disconnect`` script.
:code:`bytes_sent`
Total number of bytes sent to client during VPN session. Set prior to
execution of the ``--client-disconnect`` script.
:code:`client_connect_config_file`
The path to the configuration file that should be written to by the
``--client-connect`` script (optional, if per-session configuration
is desired). This is the same file name as passed via command line
argument on the call to the ``--client-connect`` script.
:code:`client_connect_deferred_file`
This file can be optionally written to in order to to communicate a
status code of the ``--client-connect`` script or plgin. Only the
first character in the file is relevant. It must be either :code:`1`
to indicate normal script execution, :code:`0` indicates an error (in
the same way that a non zero exit status does) or :code:`2` to indicate
that the script deferred returning the config file.
For deferred (background) handling, the script or plugin MUST write
:code:`2` to the file to indicate the deferral and then return with
exit code :code:`0` to signal ``deferred handler started OK``.
A background process or similar must then take care of writing the
configuration to the file indicated by the
:code:`client_connect_config_file` environment variable and when
finished, write the a :code:`1` to this file (or :code:`0` in case of
an error).
The absence of any character in the file when the script finishes
executing is interpreted the same as :code:`1`. This allows scripts
that are not written to support the defer mechanism to be used
unmodified.
:code:`common_name`
The X509 common name of an authenticated client. Set prior to execution
of ``--client-connect``, ``--client-disconnect`` and
``--auth-user-pass-verify`` scripts.
:code:`config`
Name of first ``--config`` file. Set on program initiation and reset on
SIGHUP.
:code:`daemon`
Set to "1" if the ``--daemon`` directive is specified, or "0" otherwise.
Set on program initiation and reset on SIGHUP.
:code:`daemon_log_redirect`
Set to "1" if the ``--log`` or ``--log-append`` directives are
specified, or "0" otherwise. Set on program initiation and reset on
SIGHUP.
:code:`dev`
The actual name of the TUN/TAP device, including a unit number if it
exists. Set prior to ``--up`` or ``--down`` script execution.
:code:`dev_idx`
On Windows, the device index of the TUN/TAP adapter (to be used in
netsh.exe calls which sometimes just do not work right with interface
names). Set prior to ``--up`` or ``--down`` script execution.
:code:`dns_*`
The ``--dns`` configuration options will be made available to script
execution through this set of environment variables. Variables appear
only if the corresponding option has a value assigned. For the semantics
of each individual variable, please refer to the documentation for ``--dns``.
::
dns_search_domain_{n}
dns_server_{n}_address4
dns_server_{n}_port4
dns_server_{n}_address6
dns_server_{n}_port6
dns_server_{n}_resolve_domain_{m}
dns_server_{n}_exclude_domain_{m}
dns_server_{n}_dnssec
dns_server_{n}_transport
dns_server_{n}_sni
:code:`foreign_option_{n}`
An option pushed via ``--push`` to a client which does not natively
support it, such as ``--dhcp-option`` on a non-Windows system, will be
recorded to this environmental variable sequence prior to ``--up``
script execution.
:code:`ifconfig_broadcast`
The broadcast address for the virtual ethernet segment which is derived
from the ``--ifconfig`` option when ``--dev tap`` is used. Set prior to
OpenVPN calling the :code:`ifconfig` or :code:`netsh` (windows version
of ifconfig) commands which normally occurs prior to ``--up`` script
execution.
:code:`ifconfig_ipv6_local`
The local VPN endpoint IPv6 address specified in the
``--ifconfig-ipv6`` option (first parameter). Set prior to OpenVPN
calling the :code:`ifconfig` or code:`netsh` (windows version of
ifconfig) commands which normally occurs prior to ``--up`` script
execution.
:code:`ifconfig_ipv6_netbits`
The prefix length of the IPv6 network on the VPN interface. Derived
from the /nnn parameter of the IPv6 address in the ``--ifconfig-ipv6``
option (first parameter). Set prior to OpenVPN calling the
:code:`ifconfig` or :code:`netsh` (windows version of ifconfig)
commands which normally occurs prior to ``--up`` script execution.
:code:`ifconfig_ipv6_remote`
The remote VPN endpoint IPv6 address specified in the
``--ifconfig-ipv6`` option (second parameter). Set prior to OpenVPN
calling the :code:`ifconfig` or :code:`netsh` (windows version of
ifconfig) commands which normally occurs prior to ``--up`` script
execution.
:code:`ifconfig_local`
The local VPN endpoint IP address specified in the ``--ifconfig``
option (first parameter). Set prior to OpenVPN calling the
:code:`ifconfig` or :code:`netsh` (windows version of ifconfig)
commands which normally occurs prior to ``--up`` script execution.
:code:`ifconfig_remote`
The remote VPN endpoint IP address specified in the ``--ifconfig``
option (second parameter) when ``--dev tun`` is used. Set prior to
OpenVPN calling the :code:`ifconfig` or :code:`netsh` (windows version
of ifconfig) commands which normally occurs prior to ``--up`` script
execution.
:code:`ifconfig_netmask`
The subnet mask of the virtual ethernet segment that is specified as
the second parameter to ``--ifconfig`` when ``--dev tap`` is being
used. Set prior to OpenVPN calling the :code:`ifconfig` or
:code:`netsh` (windows version of ifconfig) commands which normally
occurs prior to ``--up`` script execution.
:code:`ifconfig_pool_local_ip`
The local virtual IP address for the TUN/TAP tunnel taken from an
``--ifconfig-push`` directive if specified, or otherwise from the
ifconfig pool (controlled by the ``--ifconfig-pool`` config file
directive). Only set for ``--dev tun`` tunnels. This option is set on
the server prior to execution of the ``--client-connect`` and
``--client-disconnect`` scripts.
:code:`ifconfig_pool_netmask`
The virtual IP netmask for the TUN/TAP tunnel taken from an
``--ifconfig-push`` directive if specified, or otherwise from the
ifconfig pool (controlled by the ``--ifconfig-pool`` config file
directive). Only set for ``--dev tap`` tunnels. This option is set on
the server prior to execution of the ``--client-connect`` and
``--client-disconnect`` scripts.
:code:`ifconfig_pool_remote_ip`
The remote virtual IP address for the TUN/TAP tunnel taken from an
``--ifconfig-push`` directive if specified, or otherwise from the
ifconfig pool (controlled by the ``--ifconfig-pool`` config file
directive). This option is set on the server prior to execution of the
``--client-connect`` and ``--client-disconnect`` scripts.
:code:`link_mtu`
No longer passed to scripts since OpenVPN 2.6.0. Used to be the
maximum packet size (not including the IP header) of tunnel data in
UDP tunnel transport mode.
:code:`local`
The ``--local`` parameter. Set on program initiation and reset on
SIGHUP.
:code:`local_port`
The local port number or name, specified by ``--port`` or ``--lport``.
Set on program initiation and reset on SIGHUP.
:code:`password`
The password provided by a connecting client. Set prior to
``--auth-user-pass-verify`` script execution only when the ``via-env``
modifier is specified, and deleted from the environment after the script
returns.
:code:`proto`
The ``--proto`` parameter. Set on program initiation and reset on
SIGHUP.
:code:`remote_{n}`
The ``--remote`` parameter. Set on program initiation and reset on
SIGHUP.
:code:`remote_port_{n}`
The remote port number, specified by ``--port`` or ``--rport``. Set on
program initiation and reset on SIGHUP.
:code:`route_net_gateway`
The pre-existing default IP gateway in the system routing table. Set
prior to ``--up`` script execution.
:code:`route_vpn_gateway`
The default gateway used by ``--route`` options, as specified in either
the ``--route-gateway`` option or the second parameter to
``--ifconfig`` when ``--dev tun`` is specified. Set prior to ``--up``
script execution.
:code:`route_{parm}_{n}`
A set of variables which define each route to be added, and are set
prior to ``--up`` script execution.
``parm`` will be one of :code:`network`, :code:`netmask"`,
:code:`gateway`, or :code:`metric`.
``n`` is the OpenVPN route number, starting from 1.
If the network or gateway are resolvable DNS names, their IP address
translations will be recorded rather than their names as denoted on the
command line or configuration file.
:code:`route_ipv6_{parm}_{n}`
A set of variables which define each IPv6 route to be added, and are
set prior to **--up** script execution.
``parm`` will be one of :code:`network`, :code:`gateway` or
:code:`metric`. ``route_ipv6_network_{n}`` contains :code:`netmask`
as :code:`/nnn`, unlike IPv4 where it is passed in a separate environment
variable.
``n`` is the OpenVPN route number, starting from 1.
If the network or gateway are resolvable DNS names, their IP address
translations will be recorded rather than their names as denoted on the
command line or configuration file.
:code:`peer_cert`
Temporary file name containing the client certificate upon connection.
Useful in conjunction with ``--tls-verify``.
:code:`script_context`
Set to "init" or "restart" prior to up/down script execution. For more
information, see documentation for ``--up``.
:code:`script_type`
Prior to execution of any script, this variable is set to the type of
script being run. It can be one of the following: :code:`up`,
:code:`down`, :code:`ipchange`, :code:`route-up`, :code:`tls-verify`,
:code:`auth-user-pass-verify`, :code:`client-connect`,
:code:`client-disconnect` or :code:`learn-address`. Set prior to
execution of any script.
:code:`signal`
The reason for exit or restart. Can be one of :code:`sigusr1`,
:code:`sighup`, :code:`sigterm`, :code:`sigint`, :code:`inactive`
(controlled by ``--inactive`` option), :code:`ping-exit` (controlled
by ``--ping-exit`` option), :code:`ping-restart` (controlled by
``--ping-restart`` option), :code:`connection-reset` (triggered on TCP
connection reset), :code:`error` or :code:`unknown` (unknown signal).
This variable is set just prior to down script execution.
:code:`time_ascii`
Client connection timestamp, formatted as a human-readable time string.
Set prior to execution of the ``--client-connect`` script.
:code:`time_duration`
The duration (in seconds) of the client session which is now
disconnecting. Set prior to execution of the ``--client-disconnect``
script.
:code:`time_unix`
Client connection timestamp, formatted as a unix integer date/time
value. Set prior to execution of the ``--client-connect`` script.
:code:`tls_digest_{n}` / :code:`tls_digest_sha256_{n}`
Contains the certificate SHA1 / SHA256 fingerprint, where ``n`` is the
verification level. Only set for TLS connections. Set prior to execution
of ``--tls-verify`` script.
:code:`tls_id_{n}`
A series of certificate fields from the remote peer, where ``n`` is the
verification level. Only set for TLS connections. Set prior to execution
of ``--tls-verify`` script.
:code:`tls_serial_{n}`
The serial number of the certificate from the remote peer, where ``n``
is the verification level. Only set for TLS connections. Set prior to
execution of ``--tls-verify`` script. This is in the form of a decimal
string like "933971680", which is suitable for doing serial-based OCSP
queries (with OpenSSL, do not prepend "0x" to the string) If something
goes wrong while reading the value from the certificate it will be an
empty string, so your code should check that. See the
:code:`contrib/OCSP_check/OCSP_check.sh` script for an example.
:code:`tls_serial_hex_{n}`
Like :code:`tls_serial_{n}`, but in hex form (e.g.
:code:`12:34:56:78:9A`).
:code:`tun_mtu`
The MTU of the TUN/TAP device. Set prior to ``--up`` or ``--down``
script execution.
:code:`trusted_ip` / :code:`trusted_ip6`)
Actual IP address of connecting client or peer which has been
authenticated. Set prior to execution of ``--ipchange``,
``--client-connect`` and ``--client-disconnect`` scripts. If using ipv6
endpoints (udp6, tcp6), :code:`trusted_ip6` will be set instead.
:code:`trusted_port`
Actual port number of connecting client or peer which has been
authenticated. Set prior to execution of ``--ipchange``,
``--client-connect`` and ``--client-disconnect`` scripts.
:code:`untrusted_ip` / :code:`untrusted_ip6`
Actual IP address of connecting client or peer which has not been
authenticated yet. Sometimes used to *nmap* the connecting host in a
``--tls-verify`` script to ensure it is firewalled properly. Set prior
to execution of ``--tls-verify`` and ``--auth-user-pass-verify``
scripts. If using ipv6 endpoints (udp6, tcp6), :code:`untrusted_ip6`
will be set instead.
:code:`untrusted_port`
Actual port number of connecting client or peer which has not been
authenticated yet. Set prior to execution of ``--tls-verify`` and
``--auth-user-pass-verify`` scripts.
:code:`username`
The username provided by a connecting client. Set prior to
``--auth-user-pass-verify`` script execution only when the
:code:`via-env` modifier is specified.
:code:`X509_{n}_{subject_field}`
An X509 subject field from the remote peer certificate, where ``n`` is
the verification level. Only set for TLS connections. Set prior to
execution of ``--tls-verify`` script. This variable is similar to
:code:`tls_id_{n}` except the component X509 subject fields are broken
out, and no string remapping occurs on these field values (except for
remapping of control characters to ":code:`_`"). For example, the
following variables would be set on the OpenVPN server using the sample
client certificate in sample-keys (client.crt). Note that the
verification level is 0 for the client certificate and 1 for the CA
certificate.
::
X509_0_emailAddress=me@myhost.mydomain
X509_0_CN=Test-Client
X509_0_O=OpenVPN-TEST
X509_0_ST=NA
X509_0_C=KG
X509_1_emailAddress=me@myhost.mydomain
X509_1_O=OpenVPN-TEST
X509_1_L=BISHKEK
X509_1_ST=NA
X509_1_C=KG
doc/man-sections/server-options.rst 0 → 100644
View file @ e1e1377b
Server Options
--------------
Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode is
supported, and can be enabled with the ``--mode server`` option. In
server mode, OpenVPN will listen on a single port for incoming client
connections. All client connections will be routed through a single tun
or tap interface. This mode is designed for scalability and should be
able to support hundreds or even thousands of clients on sufficiently
fast hardware. SSL/TLS authentication must be used in this mode.
--auth-gen-token args
Returns an authentication token to successfully authenticated clients.
Valid syntax:
::
auth-gen-token [lifetime] [external-auth]
After successful user/password authentication, the OpenVPN server will
with this option generate a temporary authentication token and push that
to the client. On the following renegotiations, the OpenVPN client will pass
this token instead of the users password. On the server side the server
will do the token authentication internally and it will NOT do any
additional authentications against configured external user/password
authentication mechanisms.
The tokens implemented by this mechanism include an initial timestamp and
a renew timestamp and are secured by HMAC.
The ``lifetime`` argument defines how long the generated token is valid.
The lifetime is defined in seconds. If lifetime is not set or it is set
to :code:`0`, the token will never expire.
The token will expire either after the configured ``lifetime`` of the
token is reached or after not being renewed for more than 2 \*
``reneg-sec`` seconds. Clients will be sent renewed tokens on every TLS
renogiation to keep the client's token updated. This is done to
invalidate a token if a client is disconnected for a sufficiently long
time, while at the same time permitting much longer token lifetimes for
active clients.
This feature is useful for environments which are configured to use One
Time Passwords (OTP) as part of the user/password authentications and
that authentication mechanism does not implement any auth-token support.
When the :code:`external-auth` keyword is present the normal
authentication method will always be called even if auth-token succeeds.
Normally other authentications method are skipped if auth-token
verification succeeds or fails.
This option postpones this decision to the external authentication
methods and checks the validity of the account and do other checks.
In this mode the environment will have a ``session_id`` variable that
holds the session id from auth-gen-token. Also an environment variable
``session_state`` is present. This variable indicates whether the
auth-token has succeeded or not. It can have the following values:
:code:`Initial`
No token from client.
:code:`Authenticated`
Token is valid and not expired.
:code:`Expired`
Token is valid but has expired.
:code:`Invalid`
Token is invalid (failed HMAC or wrong length)
:code:`AuthenticatedEmptyUser` / :code:`ExpiredEmptyUser`
The token is not valid with the username sent from the client but
would be valid (or expired) if we assume an empty username was
used instead. These two cases are a workaround for behaviour in
OpenVPN 3. If this workaround is not needed these two cases should
be handled in the same way as :code:`Invalid`.
**Warning:** Use this feature only if you want your authentication
method called on every verification. Since the external authentication
is called it needs to also indicate a success or failure of the
authentication. It is strongly recommended to return an authentication
failure in the case of the Invalid/Expired auth-token with the
external-auth option unless the client could authenticate in another
acceptable way (e.g. client certificate), otherwise returning success
will lead to authentication bypass (as does returning success on a wrong
password from a script).
--auth-gen-token-secret file
Specifies a file that holds a secret for the HMAC used in
``--auth-gen-token`` If ``file`` is not present OpenVPN will generate a
random secret on startup. This file should be used if auth-token should
validate after restarting a server or if client should be able to roam
between multiple OpenVPN servers with their auth-token.
--auth-user-pass-optional
Allow connections by clients that do not specify a username/password.
Normally, when ``--auth-user-pass-verify`` or
``--management-client-auth`` are specified (or an authentication plugin
module), the OpenVPN server daemon will require connecting clients to
specify a username and password. This option makes the submission of a
username/password by clients optional, passing the responsibility to the
user-defined authentication module/script to accept or deny the client
based on other factors (such as the setting of X509 certificate fields).
When this option is used, and a connecting client does not submit a
username/password, the user-defined authentication module/script will
see the username and password as being set to empty strings (""). The
authentication module/script MUST have logic to detect this condition
and respond accordingly.
--ccd-exclusive
Require, as a condition of authentication, that a connecting client has
a ``--client-config-dir`` file.
--client-config-dir dir
Specify a directory ``dir`` for custom client config files. After a
connecting client has been authenticated, OpenVPN will look in this
directory for a file having the same name as the client's X509 common
name. If a matching file exists, it will be opened and parsed for
client-specific configuration options. If no matching file is found,
OpenVPN will instead try to open and parse a default file called
"DEFAULT", which may be provided but is not required. Note that the
configuration files must be readable by the OpenVPN process after it has
dropped it's root privileges.
This file can specify a fixed IP address for a given client using
``--ifconfig-push``, as well as fixed subnets owned by the client using
``--iroute``.
One of the useful properties of this option is that it allows client
configuration files to be conveniently created, edited, or removed while
the server is live, without needing to restart the server.
The following options are legal in a client-specific context: ``--push``,
``--push-reset``, ``--push-remove``, ``--iroute``, ``--ifconfig-push``,
``--vlan-pvid`` and ``--config``.
--client-to-client
Because the OpenVPN server mode handles multiple clients through a
single tun or tap interface, it is effectively a router. The
``--client-to-client`` flag tells OpenVPN to internally route
client-to-client traffic rather than pushing all client-originating
traffic to the TUN/TAP interface.
When this option is used, each client will "see" the other clients which
are currently connected. Otherwise, each client will only see the
server. Don't use this option if you want to firewall tunnel traffic
using custom, per-client rules.
--disable
Disable a particular client (based on the common name) from connecting.
Don't use this option to disable a client due to key or password
compromise. Use a CRL (certificate revocation list) instead (see the
``--crl-verify`` option).
This option must be associated with a specific client instance, which
means that it must be specified either in a client instance config file
using ``--client-config-dir`` or dynamically generated using a
``--client-connect`` script.
--connect-freq args
Allow a maximum of ``n`` new connections per ``sec`` seconds from
clients.
Valid syntax:
::
connect-freq n sec
This is designed to contain DoS attacks which flood the server
with connection requests using certificates which will ultimately fail
to authenticate.
This is an imperfect solution however, because in a real DoS scenario,
legitimate connections might also be refused.
For the best protection against DoS attacks in server mode, use
``--proto udp`` and either ``--tls-auth`` or ``--tls-crypt``.
--duplicate-cn
Allow multiple clients with the same common name to concurrently
connect. In the absence of this option, OpenVPN will disconnect a client
instance upon connection of a new client having the same common name.
--ifconfig-pool args
Set aside a pool of subnets to be dynamically allocated to connecting
clients, similar to a DHCP server.
Valid syntax:
::
ifconfig-pool start-IP end-IP [netmask]
For tun-style tunnels, each client
will be given a /30 subnet (for interoperability with Windows clients).
For tap-style tunnels, individual addresses will be allocated, and the
optional ``netmask`` parameter will also be pushed to clients.
--ifconfig-ipv6-pool args
Specify an IPv6 address pool for dynamic assignment to clients.
Valid args:
::
ifconfig-ipv6-pool ipv6addr/bits
The pool starts at ``ipv6addr`` and matches the offset determined from
the start of the IPv4 pool. If the host part of the given IPv6
address is ``0``, the pool starts at ``ipv6addr`` +1.
--ifconfig-pool-persist args
Persist/unpersist ifconfig-pool data to ``file``, at ``seconds``
intervals (default :code:`600`), as well as on program startup and shutdown.
Valid syntax:
::
ifconfig-pool-persist file [seconds]
The goal of this option is to provide a long-term association between
clients (denoted by their common name) and the virtual IP address
assigned to them from the ifconfig-pool. Maintaining a long-term
association is good for clients because it allows them to effectively
use the ``--persist-tun`` option.
``file`` is a comma-delimited ASCII file, formatted as
:code:`<Common-Name>,<IP-address>`.
If ``seconds`` = :code:`0`, ``file`` will be treated as read-only. This
is useful if you would like to treat ``file`` as a configuration file.
Note that the entries in this file are treated by OpenVPN as
*suggestions* only, based on past associations between a common name and
IP address. They do not guarantee that the given common name will always
receive the given IP address. If you want guaranteed assignment, use
``--ifconfig-push``
--ifconfig-push args
Push virtual IP endpoints for client tunnel, overriding the
``--ifconfig-pool`` dynamic allocation.
Valid syntax:
::
ifconfig-push local remote-netmask [alias]
The parameters ``local`` and ``remote-netmask`` are set according to the
``--ifconfig`` directive which you want to execute on the client machine
to configure the remote end of the tunnel. Note that the parameters
``local`` and ``remote-netmask`` are from the perspective of the client,
not the server. They may be DNS names rather than IP addresses, in which
case they will be resolved on the server at the time of client
connection.
The optional ``alias`` parameter may be used in cases where NAT causes
the client view of its local endpoint to differ from the server view. In
this case ``local/remote-netmask`` will refer to the server view while
``alias/remote-netmask`` will refer to the client view.
This option must be associated with a specific client instance, which
means that it must be specified either in a client instance config file
using ``--client-config-dir`` or dynamically generated using a
``--client-connect`` script.
Remember also to include a ``--route`` directive in the main OpenVPN
config file which encloses ``local``, so that the kernel will know to
route it to the server's TUN/TAP interface.
OpenVPN's internal client IP address selection algorithm works as
follows:
1. Use ``--client-connect script`` generated file for static IP
(first choice).
2. Use ``--client-config-dir`` file for static IP (next choice).
3. Use ``--ifconfig-pool`` allocation for dynamic IP (last
choice).
--ifconfig-ipv6-push args
for ``--client-config-dir`` per-client static IPv6 interface
configuration, see ``--client-config-dir`` and ``--ifconfig-push`` for
more details.
Valid syntax:
::
ifconfig-ipv6-push ipv6addr/bits ipv6remote
--multihome
Configure a multi-homed UDP server. This option needs to be used when a
server has more than one IP address (e.g. multiple interfaces, or
secondary IP addresses), and is not using ``--local`` to force binding
to one specific address only. This option will add some extra lookups to
the packet path to ensure that the UDP reply packets are always sent
from the address that the client is talking to. This is not supported on
all platforms, and it adds more processing, so it's not enabled by
default.
*Notes:*
- This option is only relevant for UDP servers.
- If you do an IPv6+IPv4 dual-stack bind on a Linux machine with
multiple IPv4 address, connections to IPv4 addresses will not
work right on kernels before 3.15, due to missing kernel
support for the IPv4-mapped case (some distributions have
ported this to earlier kernel versions, though).
--iroute args
Generate an internal route to a specific client. The ``netmask``
parameter, if omitted, defaults to :code:`255.255.255.255`.
Valid syntax:
::
iroute network [netmask]
This directive can be used to route a fixed subnet from the server to a
particular client, regardless of where the client is connecting from.
Remember that you must also add the route to the system routing table as
well (such as by using the ``--route`` directive). The reason why two
routes are needed is that the ``--route`` directive routes the packet
from the kernel to OpenVPN. Once in OpenVPN, the ``--iroute`` directive
routes to the specific client.
However, when using DCO, the ``--iroute`` directive is usually enough
for DCO to fully configure the routing table. The extra ``--route``
directive is required only if the expected behaviour is to route the
traffic for a specific network to the VPN interface also when the
responsible client is not connected (traffic will then be dropped).
This option must be specified either in a client instance config file
using ``--client-config-dir`` or dynamically generated using a
``--client-connect`` script.
The ``--iroute`` directive also has an important interaction with
``--push "route ..."``. ``--iroute`` essentially defines a subnet which
is owned by a particular client (we will call this client *A*). If you
would like other clients to be able to reach *A*'s subnet, you can use
``--push "route ..."`` together with ``--client-to-client`` to effect
this. In order for all clients to see *A*'s subnet, OpenVPN must push
this route to all clients EXCEPT for *A*, since the subnet is already
owned by *A*. OpenVPN accomplishes this by not not pushing a route to
a client if it matches one of the client's iroutes.
--iroute-ipv6 args
for ``--client-config-dir`` per-client static IPv6 route configuration,
see ``--iroute`` for more details how to setup and use this, and how
``--iroute`` and ``--route`` interact.
Valid syntax:
::
iroute-ipv6 ipv6addr/bits
--max-clients n
Limit server to a maximum of ``n`` concurrent clients.
--max-routes-per-client n
Allow a maximum of ``n`` internal routes per client (default
:code:`256`). This is designed to help contain DoS attacks where an
authenticated client floods the server with packets appearing to come
from many unique MAC addresses, forcing the server to deplete virtual
memory as its internal routing table expands. This directive can be used
in a ``--client-config-dir`` file or auto-generated by a
``--client-connect`` script to override the global value for a particular
client.
Note that this directive affects OpenVPN's internal routing table, not
the kernel routing table.
--opt-verify
Clients that connect with options that are incompatible with those of the
server will be disconnected.
Options that will be compared for compatibility include ``dev-type``,
``link-mtu``, ``tun-mtu``, ``proto``, ``ifconfig``,
``comp-lzo``, ``fragment``, ``keydir``, ``cipher``,
``auth``, ``keysize``, ``secret``, ``no-replay``,
``tls-auth``, ``key-method``, ``tls-server``
and ``tls-client``.
This option requires that ``--disable-occ`` NOT be used.
--port-share args
Share OpenVPN TCP with another service
Valid syntax:
::
port-share host port [dir]
When run in TCP server mode, share the OpenVPN port with another
application, such as an HTTPS server. If OpenVPN senses a connection to
its port which is using a non-OpenVPN protocol, it will proxy the
connection to the server at ``host``:``port``. Currently only designed to
work with HTTP/HTTPS, though it would be theoretically possible to
extend to other protocols such as ssh.
``dir`` specifies an optional directory where a temporary file with name
N containing content C will be dynamically generated for each proxy
connection, where N is the source IP:port of the client connection and C
is the source IP:port of the connection to the proxy receiver. This
directory can be used as a dictionary by the proxy receiver to determine
the origin of the connection. Each generated file will be automatically
deleted when the proxied connection is torn down.
Not implemented on Windows.
--push option
Push a config file option back to the client for remote execution. Note
that ``option`` must be enclosed in double quotes (:code:`""`). The
client must specify ``--pull`` in its config file. The set of options
which can be pushed is limited by both feasibility and security. Some
options such as those which would execute scripts are banned, since they
would effectively allow a compromised server to execute arbitrary code
on the client. Other options such as TLS or MTU parameters cannot be
pushed because the client needs to know them before the connection to the
server can be initiated.
This is a partial list of options which can currently be pushed:
``--route``, ``--route-gateway``, ``--route-delay``,
``--redirect-gateway``, ``--ip-win32``, ``--dhcp-option``, ``--dns``,
``--inactive``, ``--ping``, ``--ping-exit``, ``--ping-restart``,
``--setenv``, ``--auth-token``, ``--persist-key``, ``--persist-tun``,
``--echo``, ``--comp-lzo``, ``--socket-flags``, ``--sndbuf``,
``--rcvbuf``
--push-remove opt
Selectively remove all ``--push`` options matching "opt" from the option
list for a client. ``opt`` is matched as a substring against the whole
option string to-be-pushed to the client, so ``--push-remove route``
would remove all ``--push route ...`` and ``--push route-ipv6 ...``
statements, while ``--push-remove "route-ipv6 2001:"`` would only remove
IPv6 routes for :code:`2001:...` networks.
``--push-remove`` can only be used in a client-specific context, like in
a ``--client-config-dir`` file, or ``--client-connect`` script or plugin
-- similar to ``--push-reset``, just more selective.
*NOTE*: to *change* an option, ``--push-remove`` can be used to first
remove the old value, and then add a new ``--push`` option with the new
value.
*NOTE 2*: due to implementation details, 'ifconfig' and 'ifconfig-ipv6'
can only be removed with an exact match on the option (
:code:`push-remove ifconfig`), no substring matching and no matching on
the IPv4/IPv6 address argument is possible.
--push-reset
Don't inherit the global push list for a specific client instance.
Specify this option in a client-specific context such as with a
``--client-config-dir`` configuration file. This option will ignore
``--push`` options at the global config file level.
*NOTE*: ``--push-reset`` is very thorough: it will remove almost
all options from the list of to-be-pushed options. In many cases,
some of these options will need to be re-configured afterwards -
specifically, ``--topology subnet`` and ``--route-gateway`` will get
lost and this will break client configs in many cases. Thus, for most
purposes, ``--push-remove`` is better suited to selectively remove
push options for individual clients.
--server args
A helper directive designed to simplify the configuration of OpenVPN's
server mode. This directive will set up an OpenVPN server which will
allocate addresses to clients out of the given network/netmask. The
server itself will take the :code:`.1` address of the given network for
use as the server-side endpoint of the local TUN/TAP interface. If the
optional :code:`nopool` flag is given, no dynamic IP address pool will
prepared for VPN clients.
Valid syntax:
::
server network netmask [nopool]
For example, ``--server 10.8.0.0 255.255.255.0`` expands as follows:
::
mode server
tls-server
push "topology [topology]"
if dev tun AND (topology == net30 OR topology == p2p):
ifconfig 10.8.0.1 10.8.0.2
if !nopool:
ifconfig-pool 10.8.0.4 10.8.0.251
route 10.8.0.0 255.255.255.0
if client-to-client:
push "route 10.8.0.0 255.255.255.0"
else if topology == net30:
push "route 10.8.0.1"
if dev tap OR (dev tun AND topology == subnet):
ifconfig 10.8.0.1 255.255.255.0
if !nopool:
ifconfig-pool 10.8.0.2 10.8.0.253 255.255.255.0
push "route-gateway 10.8.0.1"
if route-gateway unset:
route-gateway 10.8.0.2
Don't use ``--server`` if you are ethernet bridging. Use
``--server-bridge`` instead.
--server-bridge args
A helper directive similar to ``--server`` which is designed to simplify
the configuration of OpenVPN's server mode in ethernet bridging
configurations.
Valid syntaxes:
::
server-bridge gateway netmask pool-start-IP pool-end-IP
server-bridge [nogw]
If ``--server-bridge`` is used without any parameters, it will enable a
DHCP-proxy mode, where connecting OpenVPN clients will receive an IP
address for their TAP adapter from the DHCP server running on the
OpenVPN server-side LAN. Note that only clients that support the binding
of a DHCP client with the TAP adapter (such as Windows) can support this
mode. The optional :code:`nogw` flag (advanced) indicates that gateway
information should not be pushed to the client.
To configure ethernet bridging, you must first use your OS's bridging
capability to bridge the TAP interface with the ethernet NIC interface.
For example, on Linux this is done with the :code:`brctl` tool, and with
Windows XP it is done in the Network Connections Panel by selecting the
ethernet and TAP adapters and right-clicking on "Bridge Connections".
Next you you must manually set the IP/netmask on the bridge interface.
The ``gateway`` and ``netmask`` parameters to ``--server-bridge`` can be
set to either the IP/netmask of the bridge interface, or the IP/netmask
of the default gateway/router on the bridged subnet.
Finally, set aside a IP range in the bridged subnet, denoted by
``pool-start-IP`` and ``pool-end-IP``, for OpenVPN to allocate to
connecting clients.
For example, ``server-bridge 10.8.0.4 255.255.255.0 10.8.0.128
10.8.0.254`` expands as follows:
::
mode server
tls-server
ifconfig-pool 10.8.0.128 10.8.0.254 255.255.255.0
push "route-gateway 10.8.0.4"
In another example, ``--server-bridge`` (without parameters) expands as
follows:
::
mode server
tls-server
push "route-gateway dhcp"
Or ``--server-bridge nogw`` expands as follows:
::
mode server
tls-server
--server-ipv6 args
Convenience-function to enable a number of IPv6 related options at once,
namely ``--ifconfig-ipv6``, ``--ifconfig-ipv6-pool`` and
``--push tun-ipv6``.
Valid syntax:
::
server-ipv6 ipv6addr/bits
Pushing of the ``--tun-ipv6`` directive is done for older clients which
require an explicit ``--tun-ipv6`` in their configuration.
--stale-routes-check args
Remove routes which haven't had activity for ``n`` seconds (i.e. the ageing
time). This check is run every ``t`` seconds (i.e. check interval).
Valid syntax:
::
stale-routes-check n [t]
If ``t`` is not present it defaults to ``n``.
This option helps to keep the dynamic routing table small. See also
``--max-routes-per-client``
--username-as-common-name
Use the authenticated username as the common-name, rather than the
common-name from the client certificate. Requires that some form of
``--auth-user-pass`` verification is in effect. As the replacement happens
after ``--auth-user-pass`` verification, the verification script or
plugin will still receive the common-name from the certificate.
The common_name environment variable passed to scripts and plugins invoked
after authentication (e.g, client-connect script) and file names parsed in
client-config directory will match the username.
--verify-client-cert mode
Specify whether the client is required to supply a valid certificate.
Possible ``mode`` options are:
:code:`none`
A client certificate is not required. the client needs to
authenticate using username/password only. Be aware that using this
directive is less secure than requiring certificates from all
clients.
If you use this directive, the entire responsibility of authentication
will rest on your ``--auth-user-pass-verify`` script, so keep in mind
that bugs in your script could potentially compromise the security of
your VPN.
``--verify-client-cert none`` is functionally equivalent to
``--client-cert-not-required``.
:code:`optional`
A client may present a certificate but it is not required to do so.
When using this directive, you should also use a
``--auth-user-pass-verify`` script to ensure that clients are
authenticated using a certificate, a username and password, or
possibly even both.
Again, the entire responsibility of authentication will rest on your
``--auth-user-pass-verify`` script, so keep in mind that bugs in your
script could potentially compromise the security of your VPN.
:code:`require`
This is the default option. A client is required to present a
certificate, otherwise VPN access is refused.
If you don't use this directive (or use ``--verify-client-cert require``)
but you also specify an ``--auth-user-pass-verify`` script, then OpenVPN
will perform double authentication. The client certificate verification
AND the ``--auth-user-pass-verify`` script will need to succeed in order
for a client to be authenticated and accepted onto the VPN.
--vlan-tagging
Server-only option. Turns the OpenVPN server instance into a switch that
understands VLAN-tagging, based on IEEE 802.1Q.
The server TAP device and each of the connecting clients is seen as a
port of the switch. All client ports are in untagged mode and the server
TAP device is VLAN-tagged, untagged or accepts both, depending on the
``--vlan-accept`` setting.
Ethernet frames with a prepended 802.1Q tag are called "tagged". If the
VLAN Identifier (VID) field in such a tag is non-zero, the frame is
called "VLAN-tagged". If the VID is zero, but the Priority Control Point
(PCP) field is non-zero, the frame is called "prio-tagged". If there is
no 802.1Q tag, the frame is "untagged".
Using the ``--vlan-pvid v`` option once per client (see
--client-config-dir), each port can be associated with a certain VID.
Packets can only be forwarded between ports having the same VID.
Therefore, clients with differing VIDs are completely separated from
one-another, even if ``--client-to-client`` is activated.
The packet filtering takes place in the OpenVPN server. Clients should
not have any VLAN tagging configuration applied.
The ``--vlan-tagging`` option is off by default. While turned off,
OpenVPN accepts any Ethernet frame and does not perform any special
processing for VLAN-tagged packets.
This option can only be activated in ``--dev tap mode``.
--vlan-accept args
Configure the VLAN tagging policy for the server TAP device.
Valid syntax:
::
vlan-accept all|tagged|untagged
The following modes are available:
:code:`tagged`
Admit only VLAN-tagged frames. Only VLAN-tagged packets are accepted,
while untagged or priority-tagged packets are dropped when entering
the server TAP device.
:code:`untagged`
Admit only untagged and prio-tagged frames. VLAN-tagged packets are
not accepted, while untagged or priority-tagged packets entering the
server TAP device are tagged with the value configured for the global
``--vlan-pvid`` setting.
:code:`all` (default)
Admit all frames. All packets are admitted and then treated like
untagged or tagged mode respectively.
*Note*:
Some vendors refer to switch ports running in :code:`tagged` mode
as "trunk ports" and switch ports running in :code:`untagged` mode
as "access ports".
Packets forwarded from clients to the server are VLAN-tagged with the
originating client's PVID, unless the VID matches the global
``--vlan-pvid``, in which case the tag is removed.
If no *PVID* is configured for a given client (see --vlan-pvid) packets
are tagged with 1 by default.
--vlan-pvid v
Specifies which VLAN identifier a "port" is associated with. Only valid
when ``--vlan-tagging`` is speficied.
In the client context, the setting specifies which VLAN ID a client is
associated with. In the global context, the VLAN ID of the server TAP
device is set. The latter only makes sense for ``--vlan-accept
untagged`` and ``--vlan-accept all`` modes.
Valid values for ``v`` go from :code:`1` through to :code:`4094`. The
global value defaults to :code:`1`. If no ``--vlan-pvid`` is specified in
the client context, the global value is inherited.
In some switch implementations, the *PVID* is also referred to as "Native
VLAN".
doc/man-sections/signals.rst 0 → 100644
View file @ e1e1377b
SIGNALS
=======
:code:`SIGHUP`
Cause OpenVPN to close all TUN/TAP and network connections, restart,
re-read the configuration file (if any), and reopen TUN/TAP and network
connections.
:code:`SIGUSR1`
Like :code:`SIGHUP``, except don't re-read configuration file, and
possibly don't close and reopen TUN/TAP device, re-read key files,
preserve local IP address/port, or preserve most recently authenticated
remote IP address/port based on ``--persist-tun``, ``--persist-key``,
``--persist-local-ip`` and ``--persist-remote-ip`` options respectively
(see above).
This signal may also be internally generated by a timeout condition,
governed by the ``--ping-restart`` option.
This signal, when combined with ``--persist-remote-ip``, may be sent
when the underlying parameters of the host's network interface change
such as when the host is a DHCP client and is assigned a new IP address.
See ``--ipchange`` for more information.
:code:`SIGUSR2`
Causes OpenVPN to display its current statistics (to the syslog file if
``--daemon`` is used, or stdout otherwise).
:code:`SIGINT`, :code:`SIGTERM`
Causes OpenVPN to exit gracefully.
doc/man-sections/tls-options.rst 0 → 100644
View file @ e1e1377b
TLS Mode Options
----------------
TLS mode is the most powerful crypto mode of OpenVPN in both security
and flexibility. TLS mode works by establishing control and data
channels which are multiplexed over a single TCP/UDP port. OpenVPN
initiates a TLS session over the control channel and uses it to exchange
cipher and HMAC keys to protect the data channel. TLS mode uses a robust
reliability layer over the UDP connection for all control channel
communication, while the data channel, over which encrypted tunnel data
passes, is forwarded without any mediation. The result is the best of
both worlds: a fast data channel that forwards over UDP with only the
overhead of encrypt, decrypt, and HMAC functions, and a control channel
that provides all of the security features of TLS, including
certificate-based authentication and Diffie Hellman forward secrecy.
To use TLS mode, each peer that runs OpenVPN should have its own local
certificate/key pair (``--cert`` and ``--key``), signed by the root
certificate which is specified in ``--ca``.
When two OpenVPN peers connect, each presents its local certificate to
the other. Each peer will then check that its partner peer presented a
certificate which was signed by the master root certificate as specified
in ``--ca``.
If that check on both peers succeeds, then the TLS negotiation will
succeed, both OpenVPN peers will exchange temporary session keys, and
the tunnel will begin passing data.
The OpenVPN project provides a set of scripts for managing RSA
certificates and keys: https://github.com/OpenVPN/easy-rsa
--askpass file
Get certificate password from console or ``file`` before we daemonize.
Valid syntaxes:
::
askpass
askpass file
For the extremely security conscious, it is possible to protect your
private key with a password. Of course this means that every time the
OpenVPN daemon is started you must be there to type the password. The
``--askpass`` option allows you to start OpenVPN from the command line.
It will query you for a password before it daemonizes. To protect a
private key with a password you should omit the ``-nodes`` option when
you use the ``openssl`` command line tool to manage certificates and
private keys.
If ``file`` is specified, read the password from the first line of
``file``. Keep in mind that storing your password in a file to a certain
extent invalidates the extra security provided by using an encrypted
key.
--ca file
Certificate authority (CA) file in .pem format, also referred to as the
*root* certificate. This file can have multiple certificates in .pem
format, concatenated together. You can construct your own certificate
authority certificate and private key by using a command such as:
::
openssl req -nodes -new -x509 -keyout ca.key -out ca.crt
Then edit your openssl.cnf file and edit the ``certificate`` variable to
point to your new root certificate ``ca.crt``.
For testing purposes only, the OpenVPN distribution includes a sample CA
certificate (ca.crt). Of course you should never use the test
certificates and test keys distributed with OpenVPN in a production
environment, since by virtue of the fact that they are distributed with
OpenVPN, they are totally insecure.
--capath dir
Directory containing trusted certificates (CAs and CRLs). Not available
with mbed TLS.
CAs in the capath directory are expected to be named <hash>.<n>. CRLs
are expected to be named <hash>.r<n>. See the ``-CApath`` option of
``openssl verify``, and the ``-hash`` option of ``openssl x509``,
``openssl crl`` and ``X509_LOOKUP_hash_dir()``\(3)
for more information.
Similar to the ``--crl-verify`` option, CRLs are not mandatory -
OpenVPN will log the usual warning in the logs if the relevant CRL is
missing, but the connection will be allowed.
--cert file
Local peer's signed certificate in .pem format -- must be signed by a
certificate authority whose certificate is in ``--ca file``. Each peer
in an OpenVPN link running in TLS mode should have its own certificate
and private key file. In addition, each certificate should have been
signed by the key of a certificate authority whose public key resides in
the ``--ca`` certificate authority file. You can easily make your own
certificate authority (see above) or pay money to use a commercial
service such as thawte.com (in which case you will be helping to finance
the world's second space tourist :). To generate a certificate, you can
use a command such as:
::
openssl req -nodes -new -keyout mycert.key -out mycert.csr
If your certificate authority private key lives on another machine, copy
the certificate signing request (mycert.csr) to this other machine (this
can be done over an insecure channel such as email). Now sign the
certificate with a command such as:
::
openssl ca -out mycert.crt -in mycert.csr
Now copy the certificate (mycert.crt) back to the peer which initially
generated the .csr file (this can be over a public medium). Note that
the ``openssl ca`` command reads the location of the certificate
authority key from its configuration file such as
:code:`/usr/share/ssl/openssl.cnf` -- note also that for certificate
authority functions, you must set up the files :code:`index.txt` (may be
empty) and :code:`serial` (initialize to :code:`01`).
--crl-verify args
Check peer certificate against a Certificate Revocation List.
Valid syntax:
::
crl-verify file/directory flag
Examples:
::
crl-verify crl-file.pem
crl-verify /etc/openvpn/crls dir
A CRL (certificate revocation list) is used when a particular key is
compromised but when the overall PKI is still intact.
Suppose you had a PKI consisting of a CA, root certificate, and a number
of client certificates. Suppose a laptop computer containing a client
key and certificate was stolen. By adding the stolen certificate to the
CRL file, you could reject any connection which attempts to use it,
while preserving the overall integrity of the PKI.
The only time when it would be necessary to rebuild the entire PKI from
scratch would be if the root certificate key itself was compromised.
The option is not mandatory - if the relevant CRL is missing, OpenVPN
will log a warning in the logs - e.g.
::
VERIFY WARNING: depth=0, unable to get certificate CRL
but the connection will be allowed. If the optional :code:`dir` flag
is specified, enable a different mode where the ``crl-verify`` is
pointed at a directory containing files named as revoked serial numbers
(the files may be empty, the contents are never read). If a client
requests a connection, where the client certificate serial number
(decimal string) is the name of a file present in the directory, it will
be rejected.
*Note:*
As the crl file (or directory) is read every time a peer
connects, if you are dropping root privileges with
``--user``, make sure that this user has sufficient
privileges to read the file.
--dh file
File containing Diffie Hellman parameters in .pem format (required for
``--tls-server`` only).
Set ``file`` to :code:`none` to disable Diffie Hellman key exchange (and
use ECDH only). Note that this requires peers to be using an SSL library
that supports ECDH TLS cipher suites (e.g. OpenSSL 1.0.1+, or
mbed TLS 2.0+).
Use ``openssl dhparam -out dh2048.pem 2048`` to generate 2048-bit DH
parameters. Diffie Hellman parameters may be considered public.
--ecdh-curve name
Specify the curve to use for elliptic curve Diffie Hellman. Available
curves can be listed with ``--show-curves``. The specified curve will
only be used for ECDH TLS-ciphers.
This option is not supported in mbed TLS builds of OpenVPN.
--extra-certs file
Specify a ``file`` containing one or more PEM certs (concatenated
together) that complete the local certificate chain.
This option is useful for "split" CAs, where the CA for server certs is
different than the CA for client certs. Putting certs in this file
allows them to be used to complete the local certificate chain without
trusting them to verify the peer-submitted certificate, as would be the
case if the certs were placed in the ``ca`` file.
--hand-window n
Handshake Window -- the TLS-based key exchange must finalize within
``n`` seconds of handshake initiation by any peer (default :code:`60`
seconds). If the handshake fails we will attempt to reset our connection
with our peer and try again. Even in the event of handshake failure we
will still use our expiring key for up to ``--tran-window`` seconds to
maintain continuity of transmission of tunnel data.
The ``--hand-window`` parameter also controls the amount of time that
the OpenVPN client repeats the pull request until it times out.
--key file
Local peer's private key in .pem format. Use the private key which was
generated when you built your peer's certificate (see ``--cert file``
above).
--pkcs12 file
Specify a PKCS #12 file containing local private key, local certificate,
and root CA certificate. This option can be used instead of ``--ca``,
``--cert``, and ``--key``. Not available with mbed TLS.
--remote-cert-eku oid
Require that peer certificate was signed with an explicit *extended key
usage*.
This is a useful security option for clients, to ensure that the host
they connect to is a designated server.
The extended key usage should be encoded in *oid notation*, or *OpenSSL
symbolic representation*.
--remote-cert-ku key-usage
Require that peer certificate was signed with an explicit
``key-usage``.
If present in the certificate, the :code:`keyUsage` value is validated by
the TLS library during the TLS handshake. Specifying this option without
arguments requires this extension to be present (so the TLS library will
verify it).
If ``key-usage`` is a list of usage bits, the :code:`keyUsage` field
must have *at least* the same bits set as the bits in *one of* the values
supplied in the ``key-usage`` list.
The ``key-usage`` values in the list must be encoded in hex, e.g.
::
remote-cert-ku a0
--remote-cert-tls type
Require that peer certificate was signed with an explicit *key usage*
and *extended key usage* based on RFC3280 TLS rules.
Valid syntaxes:
::
remote-cert-tls server
remote-cert-tls client
This is a useful security option for clients, to ensure that the host
they connect to is a designated server. Or the other way around; for a
server to verify that only hosts with a client certificate can connect.
The ``--remote-cert-tls client`` option is equivalent to
::
remote-cert-ku
remote-cert-eku "TLS Web Client Authentication"
The ``--remote-cert-tls server`` option is equivalent to
::
remote-cert-ku
remote-cert-eku "TLS Web Server Authentication"
This is an important security precaution to protect against a
man-in-the-middle attack where an authorized client attempts to connect
to another client by impersonating the server. The attack is easily
prevented by having clients verify the server certificate using any one
of ``--remote-cert-tls``, ``--verify-x509-name``, ``--peer-fingerprint``
or ``--tls-verify``.
--tls-auth args
Add an additional layer of HMAC authentication on top of the TLS control
channel to mitigate DoS attacks and attacks on the TLS stack.
Valid syntaxes:
::
tls-auth file
tls-auth file 0
tls-auth file 1
In a nutshell, ``--tls-auth`` enables a kind of "HMAC firewall" on
OpenVPN's TCP/UDP port, where TLS control channel packets bearing an
incorrect HMAC signature can be dropped immediately without response.
``file`` (required) is a file in OpenVPN static key format which can be
generated by ``--genkey``.
Older versions (up to OpenVPN 2.3) supported a freeform passphrase file.
This is no longer supported in newer versions (v2.4+).
See the ``--secret`` option for more information on the optional
``direction`` parameter.
``--tls-auth`` is recommended when you are running OpenVPN in a mode
where it is listening for packets from any IP address, such as when
``--remote`` is not specified, or ``--remote`` is specified with
``--float``.
The rationale for this feature is as follows. TLS requires a
multi-packet exchange before it is able to authenticate a peer. During
this time before authentication, OpenVPN is allocating resources (memory
and CPU) to this potential peer. The potential peer is also exposing
many parts of OpenVPN and the OpenSSL library to the packets it is
sending. Most successful network attacks today seek to either exploit
bugs in programs (such as buffer overflow attacks) or force a program to
consume so many resources that it becomes unusable. Of course the first
line of defense is always to produce clean, well-audited code. OpenVPN
has been written with buffer overflow attack prevention as a top
priority. But as history has shown, many of the most widely used network
applications have, from time to time, fallen to buffer overflow attacks.
So as a second line of defense, OpenVPN offers this special layer of
authentication on top of the TLS control channel so that every packet on
the control channel is authenticated by an HMAC signature and a unique
ID for replay protection. This signature will also help protect against
DoS (Denial of Service) attacks. An important rule of thumb in reducing
vulnerability to DoS attacks is to minimize the amount of resources a
potential, but as yet unauthenticated, client is able to consume.
``--tls-auth`` does this by signing every TLS control channel packet
with an HMAC signature, including packets which are sent before the TLS
level has had a chance to authenticate the peer. The result is that
packets without the correct signature can be dropped immediately upon
reception, before they have a chance to consume additional system
resources such as by initiating a TLS handshake. ``--tls-auth`` can be
strengthened by adding the ``--replay-persist`` option which will keep
OpenVPN's replay protection state in a file so that it is not lost
across restarts.
It should be emphasized that this feature is optional and that the key
file used with ``--tls-auth`` gives a peer nothing more than the power
to initiate a TLS handshake. It is not used to encrypt or authenticate
any tunnel data.
Use ``--tls-crypt`` instead if you want to use the key file to not only
authenticate, but also encrypt the TLS control channel.
--tls-groups list
A list of allowable groups/curves in order of preference.
Set the allowed elliptic curves/groups for the TLS session.
These groups are allowed to be used in signatures and key exchange.
mbedTLS currently allows all known curves per default.
OpenSSL 1.1+ restricts the list per default to
::
"X25519:secp256r1:X448:secp521r1:secp384r1".
If you use certificates that use non-standard curves, you
might need to add them here. If you do not force the ecdh curve
by using ``--ecdh-curve``, the groups for ecdh will also be picked
from this list.
OpenVPN maps the curve name `secp256r1` to `prime256v1` to allow
specifying the same tls-groups option for mbedTLS and OpenSSL.
Warning: this option not only affects elliptic curve certificates
but also the key exchange in TLS 1.3 and using this option improperly
will disable TLS 1.3.
--tls-cert-profile profile
Set the allowed cryptographic algorithms for certificates according to
``profile``.
The following profiles are supported:
:code:`insecure`
Identical for mbed TLS to `legacy`
:code:`legacy` (default)
SHA1 and newer, RSA 2048-bit+, any elliptic curve.
:code:`preferred`
SHA2 and newer, RSA 2048-bit+, any elliptic curve.
:code:`suiteb`
SHA256/SHA384, ECDSA with P-256 or P-384.
This option is only fully supported for mbed TLS builds. OpenSSL builds
use the following approximation:
:code:`insecure`
sets "security level 0"
:code:`legacy` (default)
sets "security level 1"
:code:`preferred`
sets "security level 2"
:code:`suiteb`
sets "security level 3" and ``--tls-cipher "SUITEB128"``.
OpenVPN will migrate to 'preferred' as default in the future. Please
ensure that your keys already comply.
*WARNING:* ``--tls-ciphers``, ``--tls-ciphersuites`` and ``tls-groups``
These options are expert features, which - if used correctly - can
improve the security of your VPN connection. But it is also easy to
unwittingly use them to carefully align a gun with your foot, or just
break your connection. Use with care!
--tls-cipher l
A list ``l`` of allowable TLS ciphers delimited by a colon (":code:`:`").
These setting can be used to ensure that certain cipher suites are used
(or not used) for the TLS connection. OpenVPN uses TLS to secure the
control channel, over which the keys that are used to protect the actual
VPN traffic are exchanged.
The supplied list of ciphers is (after potential OpenSSL/IANA name
translation) simply supplied to the crypto library. Please see the
OpenSSL and/or mbed TLS documentation for details on the cipher list
interpretation.
For OpenSSL, the ``--tls-cipher`` is used for TLS 1.2 and below.
Use ``--show-tls`` to see a list of TLS ciphers supported by your crypto
library.
The default for ``--tls-cipher`` is to use mbed TLS's default cipher list
when using mbed TLS or
:code:`DEFAULT:!EXP:!LOW:!MEDIUM:!kDH:!kECDH:!DSS:!PSK:!SRP:!kRSA` when
using OpenSSL.
--tls-ciphersuites l
Same as ``--tls-cipher`` but for TLS 1.3 and up. mbed TLS has no
TLS 1.3 support yet and only the ``--tls-cipher`` setting is used.
The default for `--tls-ciphersuites` is to use the crypto library's
default.
--tls-client
Enable TLS and assume client role during TLS handshake.
--tls-crypt keyfile
Encrypt and authenticate all control channel packets with the key from
``keyfile``. (See ``--tls-auth`` for more background.)
Encrypting (and authenticating) control channel packets:
* provides more privacy by hiding the certificate used for the TLS
connection,
* makes it harder to identify OpenVPN traffic as such,
* provides "poor-man's" post-quantum security, against attackers who will
never know the pre-shared key (i.e. no forward secrecy).
In contrast to ``--tls-auth``, ``--tls-crypt`` does *not* require the
user to set ``--key-direction``.
**Security Considerations**
All peers use the same ``--tls-crypt`` pre-shared group key to
authenticate and encrypt control channel messages. To ensure that IV
collisions remain unlikely, this key should not be used to encrypt more
than 2^48 client-to-server or 2^48 server-to-client control channel
messages. A typical initial negotiation is about 10 packets in each
direction. Assuming both initial negotiation and renegotiations are at
most 2^16 (65536) packets (to be conservative), and (re)negotiations
happen each minute for each user (24/7), this limits the tls-crypt key
lifetime to 8171 years divided by the number of users. So a setup with
1000 users should rotate the key at least once each eight years. (And a
setup with 8000 users each year.)
If IV collisions were to occur, this could result in the security of
``--tls-crypt`` degrading to the same security as using ``--tls-auth``.
That is, the control channel still benefits from the extra protection
against active man-in-the-middle-attacks and DoS attacks, but may no
longer offer extra privacy and post-quantum security on top of what TLS
itself offers.
For large setups or setups where clients are not trusted, consider using
``--tls-crypt-v2`` instead. That uses per-client unique keys, and
thereby improves the bounds to 'rotate a client key at least once per
8000 years'.
--tls-crypt-v2 keyfile
Valid syntax:
::
tls-crypt-v2 keyfile
tls-crypt-v2 keyfile force-cookie
tls-crypt-v2 keyfile allow-noncookie
Use client-specific tls-crypt keys.
For clients, ``keyfile`` is a client-specific tls-crypt key. Such a key
can be generated using the :code:`--genkey tls-crypt-v2-client` option.
For servers, ``keyfile`` is used to unwrap client-specific keys supplied
by the client during connection setup. This key must be the same as the
key used to generate the client-specific key (see :code:`--genkey
tls-crypt-v2-client`).
On servers, this option can be used together with the ``--tls-auth`` or
``--tls-crypt`` option. In that case, the server will detect whether the
client is using client-specific keys, and automatically select the right
mode.
The optional parameters :code:`force-cookie` allows only tls-crypt-v2
clients that support a cookie based stateless three way handshake that
avoids replay attacks and state exhaustion on the server side (OpenVPN
2.6 and later). The option :code:`allow-noncookie` explicitly allows
older tls-crypt-v2 clients. The default is (currently)
:code:`allow-noncookie`.
--tls-crypt-v2-verify cmd
Run command ``cmd`` to verify the metadata of the client-specific
tls-crypt-v2 key of a connecting client. This allows server
administrators to reject client connections, before exposing the TLS
stack (including the notoriously dangerous X.509 and ASN.1 stacks) to
the connecting client.
OpenVPN supplies the following environment variables to the command:
* :code:`script_type` is set to :code:`tls-crypt-v2-verify`
* :code:`metadata_type` is set to :code:`0` if the metadata was user
supplied, or :code:`1` if it's a 64-bit unix timestamp representing
the key creation time.
* :code:`metadata_file` contains the filename of a temporary file that
contains the client metadata.
The command can reject the connection by exiting with a non-zero exit
code.
--tls-exit
Exit on TLS negotiation failure.
--tls-export-cert directory
Store the certificates the clients use upon connection to this
directory. This will be done before ``--tls-verify`` is called. The
certificates will use a temporary name and will be deleted when the
tls-verify script returns. The file name used for the certificate is
available via the ``peer_cert`` environment variable.
--tls-server
Enable TLS and assume server role during TLS handshake. Note that
OpenVPN is designed as a peer-to-peer application. The designation of
client or server is only for the purpose of negotiating the TLS control
channel.
--tls-timeout n
Packet retransmit timeout on TLS control channel if no acknowledgment
from remote within ``n`` seconds (default :code:`2`). When OpenVPN sends
a control packet to its peer, it will expect to receive an
acknowledgement within ``n`` seconds or it will retransmit the packet,
subject to a TCP-like exponential backoff algorithm. This parameter only
applies to control channel packets. Data channel packets (which carry
encrypted tunnel data) are never acknowledged, sequenced, or
retransmitted by OpenVPN because the higher level network protocols
running on top of the tunnel such as TCP expect this role to be left to
them.
--tls-version-min args
Sets the minimum TLS version we will accept from the peer (default in
2.6.0 and later is "1.2").
Valid syntax:
::
tls-version-min version ['or-highest']
Examples for version include :code:`1.0`, :code:`1.1`, or :code:`1.2`. If
:code:`or-highest` is specified and version is not recognized, we will
only accept the highest TLS version supported by the local SSL
implementation.
--tls-version-max version
Set the maximum TLS version we will use (default is the highest version
supported). Examples for version include :code:`1.0`, :code:`1.1`, or
:code:`1.2`.
--verify-hash args
**DEPRECATED** Specify SHA1 or SHA256 fingerprint for level-1 cert.
Valid syntax:
::
verify-hash hash [algo]
The level-1 cert is the CA (or intermediate cert) that signs the leaf
certificate, and is one removed from the leaf certificate in the
direction of the root. When accepting a connection from a peer, the
level-1 cert fingerprint must match ``hash`` or certificate verification
will fail. Hash is specified as XX:XX:... For example:
::
AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16
The ``algo`` flag can be either :code:`SHA1` or :code:`SHA256`. If not
provided, it defaults to :code:`SHA1`.
This option can also be inlined
::
<verify-hash>
00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff
11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00
</verify-hash>
If the option is inlined, ``algo`` is always :code:`SHA256`.
--peer-fingerprint args
Specify a SHA256 fingerprint or list of SHA256 fingerprints to verify
the peer certificate against. The peer certificate must match one of the
fingerprint or certificate verification will fail. The option can also
be inlined
Valid syntax:
::
peer-fingerprint AD:B0:95:D8:09:...
or inline:
::
<peer-fingerprint>
00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff
11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00
</peer-fingerprint>
When the ``--peer-fingerprint`` option is used, specifying a CA with ``--ca`` or ``--capath`` is
optional. This allows the he ``--peer-fingerprint`` to be used as alternative to a PKI with
self-signed certificates for small setups. See the examples section for such a setup.
--verify-x509-name args
Accept connections only if a host's X.509 name is equal to **name.** The
remote host must also pass all other tests of verification.
Valid syntax:
::
verify-x509 name type
Which X.509 name is compared to ``name`` depends on the setting of type.
``type`` can be :code:`subject` to match the complete subject DN
(default), :code:`name` to match a subject RDN or :code:`name-prefix` to
match a subject RDN prefix. Which RDN is verified as name depends on the
``--x509-username-field`` option. But it defaults to the common name
(CN), e.g. a certificate with a subject DN
::
C=KG, ST=NA, L=Bishkek, CN=Server-1
would be matched by:
::
verify-x509-name 'C=KG, ST=NA, L=Bishkek, CN=Server-1'
verify-x509-name Server-1 name
verify-x509-name Server- name-prefix
The last example is useful if you want a client to only accept
connections to :code:`Server-1`, :code:`Server-2`, etc.
``--verify-x509-name`` is a useful replacement for the ``--tls-verify``
option to verify the remote host, because ``--verify-x509-name`` works
in a ``--chroot`` environment without any dependencies.
Using a name prefix is a useful alternative to managing a CRL
(Certificate Revocation List) on the client, since it allows the client
to refuse all certificates except for those associated with designated
servers.
*NOTE:*
Test against a name prefix only when you are using OpenVPN
with a custom CA certificate that is under your control. Never use
this option with type :code:`name-prefix` when your client
certificates are signed by a third party, such as a commercial
web CA.
--x509-track attribute
Save peer X509 **attribute** value in environment for use by plugins and
management interface. Prepend a :code:`+` to ``attribute`` to save values
from full cert chain. Values will be encoded as
:code:`X509_<depth>_<attribute>=<value>`. Multiple ``--x509-track``
options can be defined to track multiple attributes.
--x509-username-field args
Fields in the X.509 certificate subject to be used as the username
(default :code:`CN`). If multiple fields are specified their values
will be concatenated into the one username using :code:`_` symbol
as a separator.
Valid syntax:
::
x509-username-field [ext:]fieldname [[ext:]fieldname...]
Typically, this option is specified with **fieldname** arguments as
either of the following:
::
x509-username-field emailAddress
x509-username-field ext:subjectAltName
x509-username-field CN serialNumber
The first example uses the value of the :code:`emailAddress` attribute
in the certificate's Subject field as the username. The second example
uses the :code:`ext:` prefix to signify that the X.509 extension
``fieldname`` :code:`subjectAltName` be searched for an rfc822Name
(email) field to be used as the username. In cases where there are
multiple email addresses in :code:`ext:fieldname`, the last occurrence
is chosen. The last example uses the value of the :code:`CN` attribute
in the Subject field, combined with the :code:`_` separator and the
hexadecimal representation of the certificate's :code:`serialNumber`.
When this option is used, the ``--verify-x509-name`` option will match
against the chosen ``fieldname`` instead of the Common Name.
Only the :code:`subjectAltName` and :code:`issuerAltName` X.509
extensions and :code:`serialNumber` X.509 attribute are supported.
**Please note:** This option has a feature which will convert an
all-lowercase ``fieldname`` to uppercase characters, e.g.,
:code:`ou` -> :code:`OU`. A mixed-case ``fieldname`` or one having the
:code:`ext:` prefix will be left as-is. This automatic upcasing feature is
deprecated and will be removed in a future release.
Non-compliant symbols are being replaced with the :code:`_` symbol, same as
the field separator, so concatenating multiple fields with such or :code:`_`
symbols can potentially lead to username collisions.
doc/man-sections/unsupported-options.rst 0 → 100644
View file @ e1e1377b
UNSUPPORTED OPTIONS
===================
Options listed in this section have been removed from OpenVPN and are no
longer supported
--client-cert-not-required
Removed in OpenVPN 2.5. This should be replaxed with
``--verify-client-cert none``.
--ifconfig-pool-linear
Removed in OpenVPN 2.5. This should be replaced with ``--topology p2p``.
--key-method
Removed in OpenVPN 2.5. This option should not be used, as using the old
``key-method`` weakens the VPN tunnel security. The old ``key-method``
was also only needed when the remote side was older than OpenVPN 2.0.
--no-iv
Removed in OpenVPN 2.5. This option should not be used as it weakens the
VPN tunnel security. This has been a NOOP option since OpenVPN 2.4.
--no-replay
Removed in OpenVPN 2.5. This option should not be used as it weakens the
VPN tunnel security.
--ns-cert-type
Removed in OpenVPN 2.5. The ``nsCertType`` field is no longer supported
in recent SSL/TLS libraries. If your certificates does not include *key
usage* and *extended key usage* fields, they must be upgraded and the
``--remote-cert-tls`` option should be used instead.
doc/man-sections/virtual-routing-and-forwarding.rst 0 → 100644
View file @ e1e1377b
Virtual Routing and Forwarding
------------------------------
Options in this section relates to configuration of virtual routing and
forwarding in combination with the underlying operating system.
As of today this is only supported on Linux, a kernel >= 4.9 is
recommended.
This could come in handy when for example the external network should be
only used as a means to connect to some VPN endpoints and all regular
traffic should only be routed through any tunnel(s). This could be
achieved by setting up a VRF and configuring the interface connected to
the external network to be part of the VRF. The examples below will cover
this setup.
Another option would be to put the tun/tap interface into a VRF. This could
be done by an up-script which uses the :code:`ip link set` command shown
below.
VRF setup with iproute2
```````````````````````
Create VRF :code:`vrf_external` and map it to routing table :code:`1023`
::
ip link add vrf_external type vrf table 1023
Move :code:`eth0` into :code:`vrf_external`
::
ip link set master vrf_external dev eth0
Any prefixes configured on :code:`eth0` will be moved from the :code`main`
routing table into routing table `1023`
VRF setup with ifupdown
```````````````````````
For Debian based Distributions :code:`ifupdown2` provides an almost drop-in
replacement for :code:`ifupdown` including VRFs and other features.
A configuration for an interface :code:`eth0` being part of VRF
code:`vrf_external` could look like this:
::
auto eth0
iface eth0
address 192.0.2.42/24
address 2001:db8:08:15::42/64
gateway 192.0.2.1
gateway 2001:db8:08:15::1
vrf vrf_external
auto vrf_external
iface vrf_external
vrf-table 1023
OpenVPN configuration
`````````````````````
The OpenVPN configuration needs to contain this line:
::
bind-dev vrf_external
Further reading
```````````````
Wikipedia has nice page one VRFs: https://en.wikipedia.org/wiki/Virtual_routing_and_forwarding
This talk from the Network Track of FrOSCon 2018 provides an overview about
advanced layer 2 and layer 3 features of Linux
- Slides: https://www.slideshare.net/BarbarossaTM/l2l3-fr-fortgeschrittene-helle-und-dunkle-magie-im-linuxnetzwerkstack
- Video (german): https://media.ccc.de/v/froscon2018-2247-l2\_l3\_fur\_fortgeschrittene\_-\_helle\_und\_dunkle\_magie\_im\_linux-netzwerkstack
doc/man-sections/vpn-network-options.rst 0 → 100644
View file @ e1e1377b
Virtual Network Adapter (VPN interface)
---------------------------------------
Options in this section relates to configuration of the virtual tun/tap
network interface, including setting the VPN IP address and network
routing.
--bind-dev device
(Linux only) Set ``device`` to bind the server socket to a
`Virtual Routing and Forwarding`_ device
--block-ipv6
On the client, instead of sending IPv6 packets over the VPN tunnel, all
IPv6 packets are answered with an ICMPv6 no route host message. On the
server, all IPv6 packets from clients are answered with an ICMPv6 no
route to host message. This options is intended for cases when IPv6
should be blocked and other options are not available. ``--block-ipv6``
will use the remote IPv6 as source address of the ICMPv6 packets if set,
otherwise will use :code:`fe80::7` as source address.
For this option to make sense you actually have to route traffic to the
tun interface. The following example config block would send all IPv6
traffic to OpenVPN and answer all requests with no route to host,
effectively blocking IPv6 (to avoid IPv6 connections from dual-stacked
clients leaking around IPv4-only VPN services).
**Client config**
::
--ifconfig-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1
--redirect-gateway ipv6
--block-ipv6
**Server config**
Push a "valid" ipv6 config to the client and block on the server
::
--push "ifconfig-ipv6 fd15:53b6:dead::2/64 fd15:53b6:dead::1"
--push "redirect-gateway ipv6"
--block-ipv6
Note: this option does not influence traffic sent from the server
towards the client (neither on the server nor on the client side).
This is not seen as necessary, as such traffic can be most easily
avoided by not configuring IPv6 on the server tun, or setting up a
server-side firewall rule.
--dev device
TUN/TAP virtual network device which can be :code:`tunX`, :code:`tapX`,
:code:`null` or an arbitrary name string (:code:`X` can be omitted for
a dynamic device.)
See examples section below for an example on setting up a TUN device.
You must use either tun devices on both ends of the connection or tap
devices on both ends. You cannot mix them, as they represent different
underlying network layers:
:code:`tun`
devices encapsulate IPv4 or IPv6 (OSI Layer 3)
:code:`tap`
devices encapsulate Ethernet 802.3 (OSI Layer 2).
Valid syntaxes:
::
dev tun2
dev tap4
dev ovpn
When the device name starts with :code:`tun` or :code:`tap`, the device
type is extracted automatically. Otherwise the ``--dev-type`` option
needs to be added as well.
--dev-node node
Explicitly set the device node rather than using :code:`/dev/net/tun`,
:code:`/dev/tun`, :code:`/dev/tap`, etc. If OpenVPN cannot figure out
whether ``node`` is a TUN or TAP device based on the name, you should
also specify ``--dev-type tun`` or ``--dev-type tap``.
Under Mac OS X this option can be used to specify the default tun
implementation. Using ``--dev-node utun`` forces usage of the native
Darwin tun kernel support. Use ``--dev-node utunN`` to select a specific
utun instance. To force using the :code:`tun.kext` (:code:`/dev/tunX`)
use ``--dev-node tun``. When not specifying a ``--dev-node`` option
openvpn will first try to open utun, and fall back to tun.kext.
On Windows systems, select the TAP-Win32 adapter which is named ``node``
in the Network Connections Control Panel or the raw GUID of the adapter
enclosed by braces. The ``--show-adapters`` option under Windows can
also be used to enumerate all available TAP-Win32 adapters and will show
both the network connections control panel name and the GUID for each
TAP-Win32 adapter.
--dev-type device-type
Which device type are we using? ``device-type`` should be :code:`tun`
(OSI Layer 3) or :code:`tap` (OSI Layer 2). Use this option only if
the TUN/TAP device used with ``--dev`` does not begin with :code:`tun`
or :code:`tap`.
--dhcp-option args
Set additional network parameters on supported platforms. May be specified
on the client or pushed from the server. On Windows these options are
handled by the ``tap-windows6`` driver by default or directly by OpenVPN
if dhcp is disabled or the ``wintun`` driver is in use. The
``OpenVPN for Android`` client also handles them internally.
On all other platforms these options are only saved in the client's
environment under the name :code:`foreign_option_{n}` before the
``--up`` script is called. A plugin or an ``--up`` script must be used to
pick up and interpret these as required. Many Linux distributions include
such scripts and some third-party user interfaces such as tunnelblick also
come with scripts that process these options.
Valid syntax:
::
dhcp-options type [parm]
:code:`DOMAIN` ``name``
Set Connection-specific DNS Suffix to :code:`name`.
:code:`ADAPTER_DOMAIN_SUFFIX` ``name``
Alias to :code:`DOMAIN`. This is a compatibility option, it
should not be used in new deployments.
:code:`DOMAIN-SEARCH` ``name``
Add :code:`name` to the domain search list.
Repeat this option to add more entries. Up to
10 domains are supported.
:code:`DNS` ``address``
Set primary domain name server IPv4 or IPv6 address.
Repeat this option to set secondary DNS server addresses.
Note: DNS IPv6 servers are currently set using netsh (the existing
DHCP code can only do IPv4 DHCP, and that protocol only permits
IPv4 addresses anywhere). The option will be put into the
environment, so an ``--up`` script could act upon it if needed.
:code:`WINS` ``address``
Set primary WINS server address (NetBIOS over TCP/IP Name Server).
Repeat this option to set secondary WINS server addresses.
:code:`NBDD` ``address``
Set primary NBDD server address (NetBIOS over TCP/IP Datagram
Distribution Server). Repeat this option to set secondary NBDD
server addresses.
:code:`NTP` ``address``
Set primary NTP server address (Network Time Protocol).
Repeat this option to set secondary NTP server addresses.
:code:`NBT` ``type``
Set NetBIOS over TCP/IP Node type. Possible options:
:code:`1`
b-node (broadcasts)
:code:`2`
p-node (point-to-point name queries to a WINS server)
:code:`4`
m-node (broadcast then query name server)
:code:`8`
h-node (query name server, then broadcast).
:code:`NBS` ``scope-id``
Set NetBIOS over TCP/IP Scope. A NetBIOS Scope ID provides an
extended naming service for the NetBIOS over TCP/IP (Known as NBT)
module. The primary purpose of a NetBIOS scope ID is to isolate
NetBIOS traffic on a single network to only those nodes with the
same NetBIOS scope ID. The NetBIOS scope ID is a character string
that is appended to the NetBIOS name. The NetBIOS scope ID on two
hosts must match, or the two hosts will not be able to communicate.
The NetBIOS Scope ID also allows computers to use the same computer
name, as they have different scope IDs. The Scope ID becomes a part
of the NetBIOS name, making the name unique. (This description of
NetBIOS scopes courtesy of NeonSurge@abyss.com)
:code:`DISABLE-NBT`
Disable Netbios-over-TCP/IP.
:code: `PROXY_HTTP` ``host`` ``port``
Sets a HTTP proxy that should be used when connected to the VPN.
This option currently only works on OpenVPN for Android and requires
Android 10 or later.
--ifconfig args
Set TUN/TAP adapter parameters. It requires the *IP address* of the local
VPN endpoint. For TUN devices in point-to-point mode, the next argument
must be the VPN IP address of the remote VPN endpoint. For TAP devices,
or TUN devices used with ``--topology subnet``, the second argument
is the subnet mask of the virtual network segment which is being created
or connected to.
For TUN devices, which facilitate virtual point-to-point IP connections
(when used in ``--topology net30`` or ``p2p`` mode), the proper usage of
``--ifconfig`` is to use two private IP addresses which are not a member
of any existing subnet which is in use. The IP addresses may be
consecutive and should have their order reversed on the remote peer.
After the VPN is established, by pinging ``rn``, you will be pinging
across the VPN.
For TAP devices, which provide the ability to create virtual ethernet
segments, or TUN devices in ``--topology subnet`` mode (which create
virtual "multipoint networks"), ``--ifconfig`` is used to set an IP
address and subnet mask just as a physical ethernet adapter would be
similarly configured. If you are attempting to connect to a remote
ethernet bridge, the IP address and subnet should be set to values which
would be valid on the the bridged ethernet segment (note also that DHCP
can be used for the same purpose).
This option, while primarily a proxy for the ``ifconfig``\(8) command,
is designed to simplify TUN/TAP tunnel configuration by providing a
standard interface to the different ifconfig implementations on
different platforms.
``--ifconfig`` parameters which are IP addresses can also be specified
as a DNS or /etc/hosts file resolvable name.
For TAP devices, ``--ifconfig`` should not be used if the TAP interface
will be getting an IP address lease from a DHCP server.
Examples:
::
# tun device in net30/p2p mode
ifconfig 10.8.0.2 10.8.0.1
# tun/tap device in subnet mode
ifconfig 10.8.0.2 255.255.255.0
--ifconfig-ipv6 args
Configure an IPv6 address on the *tun* device.
Valid syntax:
::
ifconfig-ipv6 ipv6addr/bits [ipv6remote]
The ``ipv6addr/bits`` argument is the IPv6 address to use. The
second parameter is used as route target for ``--route-ipv6`` if no
gateway is specified.
The ``--topology`` option has no influence with ``--ifconfig-ipv6``
--ifconfig-noexec
Don't actually execute ifconfig/netsh commands, instead pass
``--ifconfig`` parameters to scripts using environmental variables.
--ifconfig-nowarn
Don't output an options consistency check warning if the ``--ifconfig``
option on this side of the connection doesn't match the remote side.
This is useful when you want to retain the overall benefits of the
options consistency check (also see ``--disable-occ`` option) while only
disabling the ifconfig component of the check.
For example, if you have a configuration where the local host uses
``--ifconfig`` but the remote host does not, use ``--ifconfig-nowarn``
on the local host.
This option will also silence warnings about potential address conflicts
which occasionally annoy more experienced users by triggering "false
positive" warnings.
--lladdr address
Specify the link layer address, more commonly known as the MAC address.
Only applied to TAP devices.
--persist-tun
Don't close and reopen TUN/TAP device or run up/down scripts across
:code:`SIGUSR1` or ``--ping-restart`` restarts.
:code:`SIGUSR1` is a restart signal similar to :code:`SIGHUP`, but which
offers finer-grained control over reset options.
--redirect-gateway flags
Automatically execute routing commands to cause all outgoing IP traffic
to be redirected over the VPN. This is a client-side option.
This option performs three steps:
(1) Create a static route for the ``--remote`` address which
forwards to the pre-existing default gateway. This is done so that
``(3)`` will not create a routing loop.
(2) Delete the default gateway route.
(3) Set the new default gateway to be the VPN endpoint address
(derived either from ``--route-gateway`` or the second parameter to
``--ifconfig`` when ``--dev tun`` is specified).
When the tunnel is torn down, all of the above steps are reversed so
that the original default route is restored.
Option flags:
:code:`local`
Add the :code:`local` flag if both OpenVPN peers are directly
connected via a common subnet, such as with wireless. The
:code:`local` flag will cause step ``(1)`` above to be omitted.
:code:`autolocal`
Try to automatically determine whether to enable :code:`local`
flag above.
:code:`def1`
Use this flag to override the default gateway by using
:code:`0.0.0.0/1` and :code:`128.0.0.0/1` rather than
:code:`0.0.0.0/0`. This has the benefit of overriding but not
wiping out the original default gateway.
:code:`bypass-dhcp`
Add a direct route to the DHCP server (if it is non-local) which
bypasses the tunnel (Available on Windows clients, may not be
available on non-Windows clients).
:code:`bypass-dns`
Add a direct route to the DNS server(s) (if they are non-local)
which bypasses the tunnel (Available on Windows clients, may
not be available on non-Windows clients).
:code:`block-local`
Block access to local LAN when the tunnel is active, except for
the LAN gateway itself. This is accomplished by routing the local
LAN (except for the LAN gateway address) into the tunnel.
:code:`ipv6`
Redirect IPv6 routing into the tunnel. This works similar to
the :code:`def1` flag, that is, more specific IPv6 routes are added
(:code:`2000::/4`, :code:`3000::/4`), covering the whole IPv6
unicast space.
:code:`!ipv4`
Do not redirect IPv4 traffic - typically used in the flag pair
:code:`ipv6 !ipv4` to redirect IPv6-only.
--redirect-private flags
Like ``--redirect-gateway``, but omit actually changing the default gateway.
Useful when pushing private subnets.
--route args
Add route to routing table after connection is established. Multiple
routes can be specified. Routes will be automatically torn down in
reverse order prior to TUN/TAP device close.
Valid syntaxes:
::
route network/IP
route network/IP netmask
route network/IP netmask gateway
route network/IP netmask gateway metric
This option is intended as a convenience proxy for the ``route``\(8)
shell command, while at the same time providing portable semantics
across OpenVPN's platform space.
``netmask``
defaults to :code:`255.255.255.255` when not given
``gateway``
default taken from ``--route-gateway`` or the second
parameter to ``--ifconfig`` when ``--dev tun`` is specified.
``metric``
default taken from ``--route-metric`` if set, otherwise :code:`0`.
The default can be specified by leaving an option blank or setting it to
:code:`default`.
The ``network`` and ``gateway`` parameters can also be specified as a
DNS or :code:`/etc/hosts` file resolvable name, or as one of three special
keywords:
:code:`vpn_gateway`
The remote VPN endpoint address (derived either from
``--route-gateway`` or the second parameter to ``--ifconfig``
when ``--dev tun`` is specified).
:code:`net_gateway`
The pre-existing IP default gateway, read from the
routing table (not supported on all OSes).
:code:`remote_host`
The ``--remote`` address if OpenVPN is being run in
client mode, and is undefined in server mode.
--route-delay args
Valid syntaxes:
::
route-delay
route-delay n
route-delay n m
Delay ``n`` seconds (default :code:`0`) after connection establishment,
before adding routes. If ``n`` is :code:`0`, routes will be added
immediately upon connection establishment. If ``--route-delay`` is
omitted, routes will be added immediately after TUN/TAP device open and
``--up`` script execution, before any ``--user`` or ``--group`` privilege
downgrade (or ``--chroot`` execution.)
This option is designed to be useful in scenarios where DHCP is used to
set tap adapter addresses. The delay will give the DHCP handshake time
to complete before routes are added.
On Windows, ``--route-delay`` tries to be more intelligent by waiting
``w`` seconds (default :code:`30` by default) for the TAP-Win32 adapter
to come up before adding routes.
--route-ipv6 args
Setup IPv6 routing in the system to send the specified IPv6 network into
OpenVPN's *tun*.
Valid syntax:
::
route-ipv6 ipv6addr/bits [gateway] [metric]
The gateway parameter is only used for IPv6 routes across *tap* devices,
and if missing, the ``ipv6remote`` field from ``--ifconfig-ipv6`` or
``--route-ipv6-gateway`` is used.
--route-gateway arg
Specify a default *gateway* for use with ``--route``.
If :code:`dhcp` is specified as the parameter, the gateway address will
be extracted from a DHCP negotiation with the OpenVPN server-side LAN.
Valid syntaxes:
::
route-gateway gateway
route-gateway dhcp
--route-ipv6-gateway gw
Specify a default gateway ``gw`` for use with ``--route-ipv6``.
--route-metric m
Specify a default metric ``m`` for use with ``--route``.
--route-noexec
Don't add or remove routes automatically. Instead pass routes to
``--route-up`` script using environmental variables.
--route-nopull
When used with ``--client`` or ``--pull``, accept options pushed by
server EXCEPT for routes, block-outside-dns and dhcp options like DNS
servers.
When used on the client, this option effectively bars the server from
adding routes to the client's routing table, however note that this
option still allows the server to set the TCP/IP properties of the
client's TUN/TAP interface.
--topology mode
Configure virtual addressing topology when running in ``--dev tun``
mode. This directive has no meaning in ``--dev tap`` mode, which always
uses a :code:`subnet` topology.
If you set this directive on the server, the ``--server`` and
``--server-bridge`` directives will automatically push your chosen
topology setting to clients as well. This directive can also be manually
pushed to clients. Like the ``--dev`` directive, this directive must
always be compatible between client and server.
``mode`` can be one of:
:code:`net30`
Use a point-to-point topology, by allocating one /30 subnet
per client. This is designed to allow point-to-point semantics when some
or all of the connecting clients might be Windows systems. This is the
default on OpenVPN 2.0.
:code:`p2p`
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.
:code:`subnet`
Use a subnet rather than a point-to-point topology by
configuring the tun interface with a local IP address and subnet mask,
similar to the topology used in ``--dev tap`` and ethernet bridging
mode. This mode allocates a single IP address per connecting client and
works on Windows as well. Only available when server and clients are
OpenVPN 2.1 or higher, or OpenVPN 2.0.x which has been manually patched
with the ``--topology`` directive code. When used on Windows, requires
version 8.2 or higher of the TAP-Win32 driver. When used on \*nix,
requires that the tun driver supports an ``ifconfig``\(8) command which
sets a subnet instead of a remote endpoint IP address.
*Note:* Using ``--topology subnet`` changes the interpretation of the
arguments of ``--ifconfig`` to mean "address netmask", no longer "local
remote".
--tun-mtu n
Take the TUN device MTU to be **n** and derive the link MTU from it
(default :code:`1500`). In most cases, you will probably want to leave
this parameter set to its default value.
The MTU (Maximum Transmission Units) is the maximum datagram size in
bytes that can be sent unfragmented over a particular network path.
OpenVPN requires that packets on the control and data channels be sent
unfragmented.
MTU problems often manifest themselves as connections which hang during
periods of active usage.
It's best to use the ``--fragment`` and/or ``--mssfix`` options to deal
with MTU sizing issues.
--tun-mtu-extra n
Assume that the TUN/TAP device might return as many as ``n`` bytes more
than the ``--tun-mtu`` size on read. This parameter defaults to 0, which
is sufficient for most TUN devices. TAP devices may introduce additional
overhead in excess of the MTU size, and a setting of 32 is the default
when TAP devices are used. This parameter only controls internal OpenVPN
buffer sizing, so there is no transmission overhead associated with
using a larger value.
TUN/TAP standalone operations
-----------------------------
These two standalone operations will require ``--dev`` and optionally
``--user`` and/or ``--group``.
--mktun
(Standalone) Create a persistent tunnel on platforms which support them
such as Linux. Normally TUN/TAP tunnels exist only for the period of
time that an application has them open. This option takes advantage of
the TUN/TAP driver's ability to build persistent tunnels that live
through multiple instantiations of OpenVPN and die only when they are
deleted or the machine is rebooted.
One of the advantages of persistent tunnels is that they eliminate the
need for separate ``--up`` and ``--down`` scripts to run the appropriate
``ifconfig``\(8) and ``route``\(8) commands. These commands can be
placed in the the same shell script which starts or terminates an
OpenVPN session.
Another advantage is that open connections through the TUN/TAP-based
tunnel will not be reset if the OpenVPN peer restarts. This can be
useful to provide uninterrupted connectivity through the tunnel in the
event of a DHCP reset of the peer's public IP address (see the
``--ipchange`` option above).
One disadvantage of persistent tunnels is that it is harder to
automatically configure their MTU value (see ``--link-mtu`` and
``--tun-mtu`` above).
On some platforms such as Windows, TAP-Win32 tunnels are persistent by
default.
--rmtun
(Standalone) Remove a persistent tunnel.
doc/man-sections/windows-options.rst 0 → 100644
View file @ e1e1377b
Windows-Specific Options
-------------------------
--allow-nonadmin TAP-adapter
(Standalone) Set ``TAP-adapter`` to allow access from non-administrative
accounts. If ``TAP-adapter`` is omitted, all TAP adapters on the system
will be configured to allow non-admin access. The non-admin access
setting will only persist for the length of time that the TAP-Win32
device object and driver remain loaded, and will need to be re-enabled
after a reboot, or if the driver is unloaded and reloaded. This
directive can only be used by an administrator.
--block-outside-dns
Block DNS servers on other network adapters to prevent DNS leaks. This
option prevents any application from accessing TCP or UDP port 53 except
one inside the tunnel. It uses Windows Filtering Platform (WFP) and
works on Windows Vista or later.
This option is considered unknown on non-Windows platforms and
unsupported on Windows XP, resulting in fatal error. You may want to use
``--setenv opt`` or ``--ignore-unknown-option`` (not suitable for
Windows XP) to ignore said error. Note that pushing unknown options from
server does not trigger fatal errors.
--cryptoapicert select-string
*(Windows/OpenSSL Only)* Load the certificate and private key from the
Windows Certificate System Store.
Use this option instead of ``--cert`` and ``--key``.
This makes it possible to use any smart card, supported by Windows, but
also any kind of certificate, residing in the Cert Store, where you have
access to the private key. This option has been tested with a couple of
different smart cards (GemSAFE, Cryptoflex, and Swedish Post Office eID)
on the client side, and also an imported PKCS12 software certificate on
the server side.
To select a certificate, based on a substring search in the
certificate's subject:
::
cryptoapicert "SUBJ:Peter Runestig"
To select a certificate, based on certificate's thumbprint:
::
cryptoapicert "THUMB:f6 49 24 41 01 b4 ..."
The thumbprint hex string can easily be copy-and-pasted from the Windows
Certificate Store GUI.
--dhcp-release
Ask Windows to release the TAP adapter lease on shutdown. This option
has no effect now, as it is enabled by default starting with
OpenVPN 2.4.1.
--dhcp-renew
Ask Windows to renew the TAP adapter lease on startup. This option is
normally unnecessary, as Windows automatically triggers a DHCP
renegotiation on the TAP adapter when it comes up, however if you set
the TAP-Win32 adapter Media Status property to "Always Connected", you
may need this flag.
--ip-win32 method
When using ``--ifconfig`` on Windows, set the TAP-Win32 adapter IP
address and netmask using ``method``. Don't use this option unless you
are also using ``--ifconfig``.
:code:`manual`
Don't set the IP address or netmask automatically. Instead
output a message to the console telling the user to configure the
adapter manually and indicating the IP/netmask which OpenVPN
expects the adapter to be set to.
:code:`dynamic [offset] [lease-time]`
Automatically set the IP address and netmask by replying to DHCP
query messages generated by the kernel. This mode is probably the
"cleanest" solution for setting the TCP/IP properties since it
uses the well-known DHCP protocol. There are, however, two
prerequisites for using this mode:
(1) The TCP/IP properties for the TAP-Win32 adapter must be set
to "Obtain an IP address automatically", and
(2) OpenVPN needs to claim an IP address in the subnet for use
as the virtual DHCP server address.
By default in ``--dev tap`` mode, OpenVPN will take the normally
unused first address in the subnet. For example, if your subnet is
:code:`192.168.4.0 netmask 255.255.255.0`, then OpenVPN will take
the IP address :code:`192.168.4.0` to use as the virtual DHCP
server address. In ``--dev tun`` mode, OpenVPN will cause the DHCP
server to masquerade as if it were coming from the remote endpoint.
The optional offset parameter is an integer which is > :code:`-256`
and < :code:`256` and which defaults to 0. If offset is positive,
the DHCP server will masquerade as the IP address at network
address + offset. If offset is negative, the DHCP server will
masquerade as the IP address at broadcast address + offset.
The Windows :code:`ipconfig /all` command can be used to show what
Windows thinks the DHCP server address is. OpenVPN will "claim"
this address, so make sure to use a free address. Having said that,
different OpenVPN instantiations, including different ends of
the same connection, can share the same virtual DHCP server
address.
The ``lease-time`` parameter controls the lease time of the DHCP
assignment given to the TAP-Win32 adapter, and is denoted in
seconds. Normally a very long lease time is preferred because it
prevents routes involving the TAP-Win32 adapter from being lost
when the system goes to sleep. The default lease time is one year.
:code:`netsh`
Automatically set the IP address and netmask using the Windows
command-line "netsh" command. This method appears to work correctly
on Windows XP but not Windows 2000.
:code:`ipapi`
Automatically set the IP address and netmask using the Windows IP
Helper API. This approach does not have ideal semantics, though
testing has indicated that it works okay in practice. If you use
this option, it is best to leave the TCP/IP properties for the
TAP-Win32 adapter in their default state, i.e. "Obtain an IP
address automatically."
:code:`adaptive` (Default)
Try :code:`dynamic` method initially and fail over to :code:`netsh`
if the DHCP negotiation with the TAP-Win32 adapter does not succeed
in 20 seconds. Such failures have been known to occur when certain
third-party firewall packages installed on the client machine block
the DHCP negotiation used by the TAP-Win32 adapter. Note that if
the :code:`netsh` failover occurs, the TAP-Win32 adapter TCP/IP
properties will be reset from DHCP to static, and this will cause
future OpenVPN startups using the :code:`adaptive` mode to use
:code:`netsh` immediately, rather than trying :code:`dynamic` first.
To "unstick" the :code:`adaptive` mode from using :code:`netsh`,
run OpenVPN at least once using the :code:`dynamic` mode to restore
the TAP-Win32 adapter TCP/IP properties to a DHCP configuration.
--pause-exit
Put up a "press any key to continue" message on the console prior to
OpenVPN program exit. This option is automatically used by the Windows
explorer when OpenVPN is run on a configuration file using the
right-click explorer menu.
--register-dns
Run :code:`ipconfig /flushdns` and :code:`ipconfig /registerdns` on
connection initiation. This is known to kick Windows into recognizing
pushed DNS servers.
--route-method m
Which method ``m`` to use for adding routes on Windows?
:code:`adaptive` (default)
Try IP helper API first. If that fails, fall back to the route.exe
shell command.
:code:`ipapi`
Use IP helper API.
:code:`exe`
Call the route.exe shell command.
--service args
Should be used when OpenVPN is being automatically executed by another
program in such a context that no interaction with the user via display
or keyboard is possible.
Valid syntax:
::
service exit-event [0|1]
In general, end-users should never need to explicitly use this option,
as it is automatically added by the OpenVPN service wrapper when a given
OpenVPN configuration is being run as a service.
``exit-event`` is the name of a Windows global event object, and OpenVPN
will continuously monitor the state of this event object and exit when
it becomes signaled.
The second parameter indicates the initial state of ``exit-event`` and
normally defaults to 0.
Multiple OpenVPN processes can be simultaneously executed with the same
``exit-event`` parameter. In any case, the controlling process can
signal ``exit-event``, causing all such OpenVPN processes to exit.
When executing an OpenVPN process using the ``--service`` directive,
OpenVPN will probably not have a console window to output status/error
messages, therefore it is useful to use ``--log`` or ``--log-append`` to
write these messages to a file.
--show-adapters
(Standalone) Show available TAP-Win32 adapters which can be selected
using the ``--dev-node`` option. On non-Windows systems, the
``ifconfig``\(8) command provides similar functionality.
--show-net
(Standalone) Show OpenVPN's view of the system routing table and network
adapter list.
--show-net-up
Output OpenVPN's view of the system routing table and network adapter
list to the syslog or log file after the TUN/TAP adapter has been
brought up and any routes have been added.
--show-valid-subnets
(Standalone) Show valid subnets for ``--dev tun`` emulation. Since the
TAP-Win32 driver exports an ethernet interface to Windows, and since TUN
devices are point-to-point in nature, it is necessary for the TAP-Win32
driver to impose certain constraints on TUN endpoint address selection.
Namely, the point-to-point endpoints used in TUN device emulation must
be the middle two addresses of a /30 subnet (netmask 255.255.255.252).
--tap-sleep n
Cause OpenVPN to sleep for ``n`` seconds immediately after the TAP-Win32
adapter state is set to "connected".
This option is intended to be used to troubleshoot problems with the
``--ifconfig`` and ``--ip-win32`` options, and is used to give the
TAP-Win32 adapter time to come up before Windows IP Helper API
operations are applied to it.
--win-sys path
Set the Windows system directory pathname to use when looking for system
executables such as ``route.exe`` and ``netsh.exe``. By default, if this
directive is not specified, OpenVPN will use the SystemRoot environment
variable.
This option has changed behaviour since OpenVPN 2.3. Earlier you had to
define ``--win-sys env`` to use the SystemRoot environment variable,
otherwise it defaulted to :code:`C:\\WINDOWS`. It is not needed to use
the ``env`` keyword any more, and it will just be ignored. A warning is
logged when this is found in the configuration file.
--windows-driver drv
Specifies which tun driver to use. Values are :code:`tap-windows6`
(default) and :code:`wintun`. This is a Windows-only option.
:code:`wintun`" requires ``--dev tun`` and the OpenVPN process to run
elevated, or be invoked using the Interactive Service.
doc/management-notes.txt
View file @ e1e1377b
......@@ -137,6 +137,16 @@ history while simultaneously activating real-time updates:
The size of the echo buffer is currently hardcoded to 100
messages.
Generally speaking, the OpenVPN Core does not understand echo
messages at all (so a cooperating GUI and Server can use this
mechanism for arbitrary information transport).
This said, a few echo commands have been agreed upon between the
community maintained OpenVPN Windows GUI and Tunnelblick for MacOS,
and documentation of these can be found in doc/gui-notes.txt.
COMMAND -- exit, quit
---------------------
......@@ -189,7 +199,7 @@ Command examples:
COMMAND -- kill
---------------
In server mode, kill a particlar client instance.
In server mode, kill a particular client instance.
Command examples:
......@@ -397,6 +407,7 @@ RECONNECTING -- A restart has occurred.
EXITING -- A graceful exit is in progress.
RESOLVE -- (Client only) DNS lookup
TCP_CONNECT -- (Client only) Connecting to TCP server
AUTH_PENDING -- (Client only) Authentication pending
Command examples:
......@@ -427,6 +438,11 @@ Fields (e)-(h) are shown for CONNECTED state,
(e) is available starting from OpenVPN 2.1
(f)-(i) are available starting from OpenVPN 2.4
For AUTH_PENDING, if (c) is present, it would read
as "timeout number" where number is the number of seconds
before authentication will timeout. It is printed as an
unsigned integer (%u).
Real-time state notifications will have a ">STATE:" prefix
prepended to them.
......@@ -465,8 +481,12 @@ Command examples:
COMMAND -- version
------------------
Show the current OpenVPN and Management Interface versions.
Set the version (integer) of Management Interface supported by the
client or show the current OpenVPN and Management Interface versions.
Command examples:
version 2 -- Change management version of client to 2 (default = 1)
version -- Show the version of OpenVPN and its Management Interface
COMMAND -- auth-retry
---------------------
......@@ -588,6 +608,144 @@ interface to approve client connections.
CID,KID -- client ID and Key ID. See documentation for ">CLIENT:"
notification for more info.
COMMAND -- client-pending-auth (OpenVPN 2.5 or higher)
----------------------------------------------------
Instruct OpenVPN server to send AUTH_PENDING and INFO_PRE message
to signal a pending authenticating to the client. A pending auth means
that the connecting requires extra authentication like a one time
password or doing a single sign on via web.
client-pending-auth {CID} {EXTRA} {TIMEOUT}
The server will send AUTH_PENDING and INFO_PRE,{EXTRA} to the client. If the
client supports accepting keywords to AUTH_PENDING (announced via IV_PROTO),
TIMEOUT parameter will be also be announced to the client to allow it to modify
its own timeout. The client is expected to inform the user that authentication
is pending and display the extra information and also show the user the
remaining time to complete the auth if applicable.
Receiving an AUTH_PENDING message will make the client change its timeout to
the timeout proposed by the server, even if the timeout is shorter.
If the client does not receive a packet from the server for hand-window the
connection times out regardless of the timeout. This ensures that the connection
still times out relatively quickly in case of network problems. The client will
continuously send PULL_REQUEST messages to the server until the timeout is reached.
This message also triggers an ACK message from the server that resets the
hand-window based timeout.
Both client and server limit the maximum timeout to the smaller value of half the
--tls-reneg minimum time and --hand-window time (defaults to 60s).
For the format of {EXTRA} see below. For OpenVPN server this is a stateless
operation and needs to be followed by a client-deny/client-auth[-nt] command
(that is the result of the out of band authentication).
Before issuing a client-pending-auth to a client instead of a
client-auth/client-deny, the server should check the IV_SSO
environment variable for whether the method is supported. Currently
defined methods are crtext for challenge/response using text
(e.g., TOTP), openurl (deprecated) and webauth for opening a URL in
the client to continue authentication. A client supporting webauth and
crtext would set
setenv IV_SSO webauth,crtext
The variable name IV_SSO is historic as AUTH_PENDING was first used
to signal single sign on support. To keep compatibility with existing
implementations the name IV_SSO is kept in lieu of a better name.
The management interface of the client receives notification of
pending auth via
>STATE:datetime,AUTH_PENDING,[timeout number],,,,,
If {EXTRA} is present the client is informed using INFOMSG
notification as
>INFOMSG:{EXTRA}
where {EXTRA} is formatted as received from the server.
Currently defined formats for {EXTRA} are detailed below.
webauth and openurl
===================
For a web based extra authentication (like for
SSO/SAML) {EXTRA} should be
OPEN_URL:url
or
WEB_AUTH:flags:url
The OPEN_URL method is deprecated as it does not allow to send flags which
proved to be needed to signal certain behaviour to the client.
The client should ask the user to open the URL to continue.
The space in a control message is limited, so this url should be kept
short to avoid issues. If a longer url is required a URL that redirects
to the longer URL should be sent instead. The total length is limited to 1024
bytes which includes the INFO_PRE:WEB_AUTH:flags.
flags is a list of flags which are separated by commas. Currently defined
flags are:
- proxy (see next pargraph)
- hidden start the webview in hidden mode (see openvpn3 webauth documentation)
- external Do not use an internal webview but use an external browser. Some
authentication providers refuse to work in an internal webview.
A complete documentation how URLs should be handled on the client is available
in the openvpn3 repository:
https://github.com/OpenVPN/openvpn3/blob/master/doc/webauth.md
webauth with proxy
==================
This is a variant of webauth that allows opening a url via an
HTTP proxy. It could be used to avoid issues with OpenVPN connection's
persist-tun that may cause the web server to be unreachable.
The client should announce proxy in its IV_SSO and parse the
proxy flag in the WEB_AUTH message. The format of {EXTRA} in this case is
WEB_AUTH:proxy=<proxy>;<proxy_port>;<proxy_user_base64>;<proxy_password_base64>,flags:url
The proxy should be a literal IPv4 address or IPv6 address enclosed in [] to avoid
ambiguity in parsing. A literal IP address is preferred as DNS might not be
available when the client needs to open the url. The IP address will usually
be the address that client uses to connect to the VPN server. For dual-homed
VPN servers, the server should respond with the same address that the client
connects to.
This address is also usually excluded from being redirected over the VPN
by a host route. If the platform (like Android) uses another way of protecting
the VPN connection from routing loops, the client needs to also exclude the
connection to the proxy in the same manner.
Should another IP be used, then the VPN configuration should include a route
statement to exclude that address from being routed over the VPN.
crtext
=======
The format of {EXTRA} is similar to the already used two step authentication
described in Challenge/Response Protocol section of this document. Since
most of the fields are not necessary or can be inferred, only the <flags>
and <challenge_text> fields are used:
CR_TEXT:<flags>:<challenge_text>
<flags>: a series of optional, comma-separated flags:
E : echo the response when the user types it.
R : a response is required.
<challenge_text>: the challenge text to be shown to the user.
The client should return the response to the crtext challenge
using the cr-response command.
COMMAND -- client-deny (OpenVPN 2.1 or higher)
-----------------------------------------------
......@@ -627,118 +785,6 @@ Immediately kill a client instance by CID.
CID -- client ID. See documentation for ">CLIENT:" notification for more
info.
COMMAND -- client-pf (OpenVPN 2.1 or higher)
---------------------------------------------
Push a packet filter file to a specific client.
The OpenVPN server should have been started with the
--management-client-pf directive so that it will require that
VPN tunnel packets sent or received by client instances must
conform to that client's packet filter configuration.
client-pf {CID}
line_1
line_2
...
line_n
END
CID -- client ID. See documentation for ">CLIENT:" notification for
more info.
line_1 to line_n -- the packet filter configuration file for this
client.
Packet filter file grammar:
[CLIENTS DROP|ACCEPT]
{+|-}common_name1
{+|-}common_name2
. . .
[SUBNETS DROP|ACCEPT]
{+|-}subnet1
{+|-}subnet2
. . .
[END]
Subnet: IP-ADDRESS | IP-ADDRESS/NUM_NETWORK_BITS | "unknown"
CLIENTS refers to the set of clients (by their common-name) which
this instance is allowed ('+') to connect to, or is excluded ('-')
from connecting to. Note that in the case of client-to-client
connections, such communication must be allowed by the packet filter
configuration files of both clients AND the --client-to-client
directive must have been specified in the OpenVPN server config.
SUBNETS refers to IP addresses or IP address subnets which this
client instance may connect to ('+') or is excluded ('-') from
connecting to, and applies to IPv4 and ARP packets. The special
"unknown" tag refers to packets of unknown type, i.e. a packet that
is not IPv4 or ARP.
DROP or ACCEPT defines default policy when there is no explicit match
for a common-name or subnet. The [END] tag must exist.
Notes:
* The SUBNETS section currently only supports IPv4 addresses and
subnets.
* A given client or subnet rule applies to both incoming and
outgoing packets.
* The CLIENTS list is order-invariant. Because the list is stored
as a hash-table, the order of the list does not affect its function.
* The SUBNETS table is scanned sequentially, and the first item to
match is chosen. Therefore the SUBNETS table is NOT order-invariant.
* No client-to-client communication is allowed unless the
--client-to-client configuration directive is enabled AND
the CLIENTS list of BOTH clients allows the communication.
Example packet filter spec, as transmitted to the management interface:
client-pf 42
[CLIENTS ACCEPT]
-accounting
-enigma
[SUBNETS DROP]
-10.46.79.9
+10.0.0.0/8
[END]
END
The above example sets the packet filter policy for the client
identified by CID=42. This client may connect to all other clients
except those having a common name of "accounting" or "enigma".
The client may only interact with external IP addresses in the
10.0.0.0/8 subnet, however access to 10.46.79.9 is specifically
excluded.
Another example packet filter spec, as transmitted to the
management interface:
client-pf 99
[CLIENTS DENY]
+public
[SUBNETS ACCEPT]
+10.10.0.1
-10.0.0.0/8
-unknown
[END]
END
The above example sets the packet filter policy for the client
identified by CID=99. This client may not connect to any other
clients except those having a common name of "public". It may
interact with any external IP address except those in the
10.0.0.0/8 netblock. However interaction with one address in
the 10.0.0.0/8 netblock is allowed: 10.10.0.1. Also, the client
may not interact with external IP addresses using an "unknown"
protocol (i.e. one that is not IPv4 or ARP).
COMMAND -- remote (OpenVPN AS 2.1.5/OpenVPN 2.3 or higher)
--------------------------------------------
......@@ -802,34 +848,84 @@ To accept connecting to the host and port directly, use this command:
proxy NONE
COMMAND -- rsa-sig (OpenVPN 2.3 or higher)
------------------------------------------
COMMAND -- cr-response (OpenVPN 2.5 or higher)
-------------------------------------------------
Provides support for sending responses to a challenge/response
query via INFOMSG,CR_TEXT (client-only). The response should
be base64 encoded:
cr-response SGFsbG8gV2VsdCE=
This command is intended to be used after the client receives a
CR_TEXT challenge (see client-pending-auth section). The argument
to cr-response is the base64 encoded answer to the challenge and
depends on the challenge itself. For a TOTP challenge this would be
a number encoded as base64; for a challenge like "what day is it today?"
it would be a string encoded as base64.
COMMAND -- pk-sig (OpenVPN 2.5 or higher, management version > 1)
COMMAND -- rsa-sig (OpenVPN 2.3 or higher, management version <= 1)
-----------------------------------------------------------------
Provides support for external storage of the private key. Requires the
--management-external-key option. This option can be used instead of "key"
in client mode, and allows the client to run without the need to load the
actual private key. When the SSL protocol needs to perform an RSA sign
actual private key. When the SSL protocol needs to perform a sign
operation, the data to be signed will be sent to the management interface
via a notification as follows:
>RSA_SIGN:[BASE64_DATA]
>PK_SIGN:[BASE64_DATA],[ALG] (if client announces support for management version > 2)
>PK_SIGN:[BASE64_DATA] (if client announces support for management version > 1)
>RSA_SIGN:[BASE64_DATA] (only older clients will be prompted like this)
The management interface client should then create a PKCS#1 v1.5 signature of
The management interface client should then create an appropriate signature of
the (decoded) BASE64_DATA using the private key and return the SSL signature as
follows:
rsa-sig
pk-sig (or rsa-sig)
[BASE64_SIG_LINE]
.
.
.
END
Base64 encoded output of RSA_private_encrypt() (OpenSSL) or mbedtls_pk_sign()
(mbed TLS) will provide a correct signature.
Base 64 encoded output of RSA_private_encrypt for RSA or ECDSA_sign()
for EC using OpenSSL or mbedtls_pk_sign() using mbed TLS will provide a
correct signature.
The rsa-sig interface expects PKCS1 padded signatures for RSA keys
(RSA_PKCS1_PADDING). EC signatures are always unpadded.
This capability is intended to allow the use of arbitrary cryptographic
service providers with OpenVPN via the management interface.
New and updated clients are expected to use the version command to announce
a version > 1 and handle '>PK_SIGN' prompt and respond with 'pk-sig'.
The signature algorithm is indicated in the PK_SIGN request only if the
management client-version is > 2. In particular, to support TLS1.3 and
TLS1.2 using OpenSSL 1.1.1, unpadded signature support is required and this
can be indicated in the signing request only if the client version is > 2"
The currently defined padding algorithms are:
- RSA_PKCS1_PADDING - PKCS1 padding and RSA signature
- RSA_NO_PADDING - No padding may be added for the signature
- ECDSA - EC signature.
- RSA_PKCS1_PSS_PADDING,params - RSA signature with PSS padding
The params for PSS are specified as 'hashalg=name,saltlen=[max|digest]'.
The hashalg names are short common names such as SHA256, SHA224, etc.
PSS saltlen="digest" means use the same size as the hash to sign, while
"max" indicates maximum possible saltlen which is
'(nbits-1)/8 - hlen - 2'. Here 'nbits' is the number of bits in the
key modulus and 'hlen' the size in octets of the hash.
(See: RFC 8017 sec 8.1.1 and 9.1.1)
In the case of PKCS1_PADDING, when the hash algorithm is not legacy
MD5-SHA1, the hash is encoded with DigestInfo header before presenting
to the management interface. This is identical to CKM_RSA_PKCS in Cryptoki
as well as what RSA_private_encrypt() in OpenSSL expects.
COMMAND -- certificate (OpenVPN 2.4 or higher)
----------------------------------------------
Provides support for external storage of the certificate. Requires the
......@@ -920,6 +1016,9 @@ PASSWORD -- Used to tell the management interface client that OpenVPN
STATE -- Shows the current OpenVPN state, as controlled
by the "state" command.
INFOMSG -- Authentication related info from server such as
CR_TEXT or OPEN_URL. See description under client-pending-auth
The CLIENT notification
-----------------------
......@@ -969,6 +1068,35 @@ CLIENT notification types:
>CLIENT:ADDRESS,{CID},{ADDR},{PRI}
(5) Text based challenge/Response
>CLIENT:CR_RESPONSE,{CID},{KID},{response_base64}
>CLIENT:ENV,name1=val1
>CLIENT:ENV,name2=val2
>CLIENT:ENV,...
>CLIENT:ENV,END
Use of the cr-response command on the client side will trigger this
message on the server side.
CR_RESPONSE notification fulfills the same purpose as the
CRV1 response in the traditional challenge/response. See that section
below for more details. Since this uses the same cid as in the original
client-pending-auth challenge, we do not include the username and opaque
session data in this notification. The string {response_base64} only contains
the actual response received from the client.
It is important to note that OpenVPN2 merely passes the authentication
information and does not do any further checks. (E.g. if a CR was issued
before or if multiple CR responses were sent from the client or if
data has a valid base64 encoding)
This interface should be be sufficient for almost all challenge/response
system that can be implemented with a single round and base64 encoding of the
response. Mechanisms that need multiple rounds or more complex answers
should implement a different response type than CR_RESPONSE.
Variables:
CID -- Client ID, numerical ID for each connecting client, sequence = 0,1,2,...
......
doc/openvpn-examples.5.rst 0 → 100644
View file @ e1e1377b
===============================
openvpn examples
===============================
-------------------------
Secure IP tunnel daemon
-------------------------
:Manual section: 5
:Manual group: Configuration files
INTRODUCTION
============
This man page gives a few simple examples to create OpenVPN setups and configuration files.
.. include:: man-sections/example-fingerprint.rst
.. include:: man-sections/examples.rst
doc/openvpn.8 deleted 100644 → 0
View file @ e3856827
This source diff could not be displayed because it is too large. You can view the blob instead.
doc/openvpn.8.rst 0 → 100644
View file @ e1e1377b
=========
openvpn
=========
-------------------------
Secure IP tunnel daemon
-------------------------
:Manual section: 8
:Manual group: System Manager's Manual
SYNOPSIS
========
| ``openvpn`` [ options ... ]
| ``openvpn`` ``--help``
INTRODUCTION
============
OpenVPN is an open source VPN daemon by James Yonan. Because OpenVPN
tries to be a universal VPN tool offering a great deal of flexibility,
there are a lot of options on this manual page. If you're new to
OpenVPN, you might want to skip ahead to the examples section where you
will see how to construct simple VPNs on the command line without even
needing a configuration file.
Also note that there's more documentation and examples on the OpenVPN
web site: https://openvpn.net/
And if you would like to see a shorter version of this manual, see the
openvpn usage message which can be obtained by running **openvpn**
without any parameters.
DESCRIPTION
===========
OpenVPN is a robust and highly flexible VPN daemon. OpenVPN supports
SSL/TLS security, ethernet bridging, TCP or UDP tunnel transport through
proxies or NAT, support for dynamic IP addresses and DHCP, scalability
to hundreds or thousands of users, and portability to most major OS
platforms.
OpenVPN is tightly bound to the OpenSSL library, and derives much of its
crypto capabilities from it.
OpenVPN supports conventional encryption using a pre-shared secret key
**(Static Key mode)** or public key security **(SSL/TLS mode)** using
client & server certificates. OpenVPN also supports non-encrypted
TCP/UDP tunnels.
OpenVPN is designed to work with the **TUN/TAP** virtual networking
interface that exists on most platforms.
Overall, OpenVPN aims to offer many of the key features of IPSec but
with a relatively lightweight footprint.
OPTIONS
=======
OpenVPN allows any option to be placed either on the command line or in
a configuration file. Though all command line options are preceded by a
double-leading-dash ("--"), this prefix can be removed when an option is
placed in a configuration file.
.. include:: man-sections/generic-options.rst
.. include:: man-sections/log-options.rst
.. include:: man-sections/protocol-options.rst
.. include:: man-sections/client-options.rst
.. include:: man-sections/server-options.rst
.. include:: man-sections/encryption-options.rst
.. include:: man-sections/cipher-negotiation.rst
.. include:: man-sections/network-config.rst
.. include:: man-sections/script-options.rst
.. include:: man-sections/management-options.rst
.. include:: man-sections/plugin-options.rst
.. include:: man-sections/windows-options.rst
.. include:: man-sections/advanced-options.rst
.. include:: man-sections/unsupported-options.rst
.. include:: man-sections/connection-profiles.rst
.. include:: man-sections/inline-files.rst
.. include:: man-sections/signals.rst
FAQ
===
https://community.openvpn.net/openvpn/wiki/FAQ
HOWTO
=====
For a more comprehensive guide to setting up OpenVPN in a production
setting, see the OpenVPN HOWTO at
https://openvpn.net/community-resources/how-to/
PROTOCOL
========
For a description of OpenVPN's underlying protocol, see
https://openvpn.net/community-resources/openvpn-protocol/
WEB
===
OpenVPN's web site is at https://openvpn.net/
Go here to download the latest version of OpenVPN, subscribe to the
mailing lists, read the mailing list archives, or browse the SVN
repository.
BUGS
====
Report all bugs to the OpenVPN team info@openvpn.net
SEE ALSO
========
``openvpn-examples``\(5),
``dhcpcd``\(8),
``ifconfig``\(8),
``openssl``\(1),
``route``\(8),
``scp``\(1)
``ssh``\(1)
NOTES
=====
This product includes software developed by the OpenSSL Project
(https://www.openssl.org/)
For more information on the TLS protocol, see
http://www.ietf.org/rfc/rfc2246.txt
For more information on the LZO real-time compression library see
https://www.oberhumer.com/opensource/lzo/
COPYRIGHT
=========
Copyright (C) 2002-2020 OpenVPN Inc This program is free software; you
can redistribute it and/or modify it under the terms of the GNU General
Public License version 2 as published by the Free Software Foundation.
AUTHORS
=======
James Yonan james@openvpn.net
doc/tests/authentication-plugins.md 0 → 100644
View file @ e1e1377b
# TESTING OF MULTIPLE AUTHENTICATION PLUG-INS
OpenVPN 2.x can support loading and authenticating users through multiple
plug-ins at the same time. But it can only support a single plug-in doing
deferred authentication. However, a plug-in supporting deferred
authentication may be accompanied by other authentication plug-ins **not**
doing deferred authentication.
This is a test script useful to test the various combinations and order of
plug-in execution.
The configuration files are expected to be used from the root of the build
directory.
To build the needed authentication plug-in, run:
make -C sample/sample-plugins
## Test configs
* Client config
verb 4
dev tun
client
remote x.x.x.x
ca sample/sample-keys/ca.crt
cert sample/sample-keys/client.crt
key sample/sample-keys/client.key
auth-user-pass
* Base server config (`base-server.conf`)
verb 4
dev tun
server 10.8.0.0 255.255.255.0
dh sample/sample-keys/dh2048.pem
ca sample/sample-keys/ca.crt
cert sample/sample-keys/server.crt
key sample/sample-keys/server.key
## Test cases
### Test: *sanity-1*
This tests the basic authentication with an instant answer.
config base-server.conf
plugin multi-auth.so S1.1 0 foo bar
#### Expected results
- Username/password `foo`/`bar`: **PASS**
- Anything else: **FAIL**
### Test: *sanity-2*
This is similar to `sanity-1`, but does the authentication
through two plug-ins providing an instant reply.
config base-server.conf
plugin multi-auth.so S2.1 0 foo bar
plugin multi-auth.so S2.2 0 foo bar
#### Expected results
- Username/password `foo`/`bar`: **PASS**
- Anything else: **FAIL**
### Test: *sanity-3*
This is also similar to `sanity-1`, but uses deferred authentication
with a 1 second delay on the response.
plugin multi-auth.so S3.1 1000 foo bar
#### Expected results
- Username/password `foo`/`bar`: **PASS**
- Anything else: **FAIL**
### Test: *case-a*
Runs two authentications, the first one deferred by 1 second and the
second one providing an instant response.
plugin multi-auth.so A.1 1000 foo bar
plugin multi-auth.so A.2 0 foo bar
#### Expected results
- Username/password `foo`/`bar`: **PASS**
- Anything else: **FAIL**
### Test: *case-b*
This is similar to `case-a`, but the instant authentication response
is provided first before the deferred authentication.
plugin multi-auth.so B.1 0 foo bar
plugin multi-auth.so B.2 1000 test pass
#### Expected results
- **Always FAIL**
- This test should never pass, as each plug-in expects different
usernames and passwords.
### Test: *case-c*
This is similar to the two prior tests, but the authentication result
is returned instantly in both steps.
plugin multi-auth.so C.1 0 foo bar
plugin multi-auth.so C.2 0 foo2 bar2
#### Expected results
- **Always FAIL**
- This test should never pass, as each plug-in expects different
usernames and passwords.
### Test: *case-d*
This is similar to the `case-b` test, but the order of deferred
and instant response is reversed.
plugin ./multi-auth.so D.1 2000 test pass
plugin ./multi-auth.so D.2 0 foo bar
#### Expected results
- **Always FAIL**
- This test should never pass, as each plug-in expects different
usernames and passwords.
### Test: *case-e*
This test case will run two deferred authentication plug-ins. This is
**not** supported by OpenVPN, and should therefore fail instantly.
plugin ./multi-auth.so E1 1000 test1 pass1
plugin ./multi-auth.so E2 2000 test2 pass2
#### Expected results
- The OpenVPN server process should stop running
- An error about multiple deferred plug-ins being configured
should be seen in the server log.
doc/tls-crypt-v2.txt 0 → 100644
View file @ e1e1377b
Client-specific tls-crypt keys (--tls-crypt-v2)
===============================================
This document describes the ``--tls-crypt-v2`` option, which enables OpenVPN
to use client-specific ``--tls-crypt`` keys.
Rationale
---------
``--tls-auth`` and ``tls-crypt`` use a pre-shared group key, which is shared
among all clients and servers in an OpenVPN deployment. If any client or
server is compromised, the attacker will have access to this shared key, and it
will no longer provide any security. To reduce the risk of losing pre-shared
keys, ``tls-crypt-v2`` adds the ability to supply each client with a unique
tls-crypt key. This allows large organisations and VPN providers to profit
from the same DoS and TLS stack protection that small deployments can already
achieve using ``tls-auth`` or ``tls-crypt``.
Also, for ``tls-crypt``, even if all these peers succeed in keeping the key
secret, the key lifetime is limited to roughly 8000 years, divided by the
number of clients (see the ``--tls-crypt`` section of the man page). Using
client-specific keys, we lift this lifetime requirement to roughly 8000 years
for each client key (which "Should Be Enough For Everybody (tm)").
Introduction
------------
``tls-crypt-v2`` uses an encrypted cookie mechanism to introduce
client-specific tls-crypt keys without introducing a lot of server-side state.
The client-specific key is encrypted using a server key. The server key is the
same for all servers in a group. When a client connects, it first sends the
encrypted key to the server, such that the server can decrypt the key and all
messages can thereafter be encrypted using the client-specific key.
A wrapped (encrypted and authenticated) client-specific key can also contain
metadata. The metadata is wrapped together with the key, and can be used to
allow servers to identify clients and/or key validity. This allows the server
to abort the connection immediately after receiving the first packet, rather
than performing an entire TLS handshake. Aborting the connection this early
greatly improves the DoS resilience and reduces attack surface against
malicious clients that have the ``tls-crypt`` or ``tls-auth`` key. This is
particularly relevant for large deployments (think lost key or disgruntled
employee) and VPN providers (clients are not trusted).
To allow for a smooth transition, ``tls-crypt-v2`` is designed such that a
server can enable both ``tls-crypt-v2`` and either ``tls-crypt`` or
``tls-auth``. This is achieved by introducing a P_CONTROL_HARD_RESET_CLIENT_V3
opcode, that indicates that the client wants to use ``tls-crypt-v2`` for the
current connection.
For an exact specification and more details, read the Implementation section.
Implementation
--------------
When setting up a tls-crypt-v2 group (similar to generating a tls-crypt or
tls-auth key previously):
1. Generate a tls-crypt-v2 server key using OpenVPN's ``--genkey tls-crypt-v2-server``.
This key contains 2 512-bit keys, of which we use:
* the first 256 bits of key 1 as AES-256-CTR encryption key ``Ke``
* the first 256 bits of key 2 as HMAC-SHA-256 authentication key ``Ka``
This format is similar to the format for regular ``tls-crypt``/``tls-auth``
and data channel keys, which allows us to reuse code.
2. Add the tls-crypt-v2 server key to all server configs
(``tls-crypt-v2 /path/to/server.key``)
When provisioning a client, create a client-specific tls-crypt key:
1. Generate 2048 bits client-specific key ``Kc`` using OpenVPN's ``--genkey tls-crypt-v2-client``
2. Optionally generate metadata
The first byte of the metadata determines the type. The initial
implementation supports the following types:
0x00 (USER): User-defined free-form data.
0x01 (TIMESTAMP): 64-bit network order unix timestamp of key generation.
The timestamp can be used to reject too-old tls-crypt-v2 client keys.
User metadata could for example contain the users certificate serial, such
that the incoming connection can be verified against a CRL.
If no metadata is supplied during key generation, openvpn defaults to the
TIMESTAMP metadata type.
3. Create a wrapped client key ``WKc``, using the same nonce-misuse-resistant
SIV construction we use for tls-crypt:
``len = len(WKc)`` (16 bit, network byte order)
``T = HMAC-SHA256(Ka, len || Kc || metadata)``
``IV = 128 most significant bits of T``
``WKc = T || AES-256-CTR(Ke, IV, Kc || metadata) || len``
Note that the length of ``WKc`` can be computed before composing ``WKc``,
because the length of each component is known (and AES-256-CTR does not add
any padding).
4. Create a tls-crypt-v2 client key: PEM-encode ``Kc || WKc`` and store in a
file, using the header ``-----BEGIN OpenVPN tls-crypt-v2 client key-----``
and the footer ``-----END OpenVPN tls-crypt-v2 client key-----``. (The PEM
format is simple, and following PEM allows us to use the crypto lib function
for en/decoding.)
5. Add the tls-crypt-v2 client key to the client config
(``tls-crypt-v2 /path/to/client-specific.key``)
When setting up the openvpn connection:
1. The client reads the tls-crypt-v2 key from its config, and:
1. loads ``Kc`` as its tls-crypt key,
2. stores ``WKc`` in memory for sending to the server.
2. To start the connection, the client creates a P_CONTROL_HARD_RESET_CLIENT_V3
message, wraps it with tls-crypt using ``Kc`` as the key, and appends
``WKc``. (``WKc`` must not be encrypted, to prevent a chicken-and-egg
problem.)
3. The server receives the P_CONTROL_HARD_RESET_CLIENT_V3 message, and
1. reads the WKc length field from the end of the message, and extracts WKc
from the message
2. unwraps ``WKc``
3. uses unwrapped ``Kc`` to verify the remaining
P_CONTROL_HARD_RESET_CLIENT_V3 message's (encryption and) authentication.
The message is dropped and no error response is sent when either 3.1, 3.2 or
3.3 fails (DoS protection).
4. Server optionally checks metadata using a --tls-crypt-v2-verify script
This allows early abort of connection, *before* we expose any of the
notoriously dangerous TLS, X.509 and ASN.1 parsers and thereby reduces the
attack surface of the server.
The metadata is checked *after* the OpenVPN three-way handshake has
completed, to prevent DoS attacks. (That is, once the client has proved to
the server that it possesses Kc, by authenticating a packet that contains the
session ID picked by the server.)
A server should not send back any error messages if metadata verification
fails, to reduce attack surface and maximize DoS resilience.
6. Client and server use ``Kc`` for (un)wrapping any following control channel
messages.
HMAC Cookie support
-------------------
To avoid exhaustion attack and keeping state for connections that fail to
complete the three-way handshake, the OpenVPN server will use its own session
id as challenge that the client must repeat in the third packet of the
handshake. This introduces a problem. If the server does not keep the wrapped
client key from the initial packet, the server cannot decode the third packet.
Therefore, tls-crypt-v2 in 2.6 allows resending the wrapped key in the third
packet of the handshake with the P_CONTROL_WKC_V1 message. The modified
handshake is as follows (the rest of the handshake is unmodified):
1. The client creates the P_CONTROL_HARD_RESET_CLIENT_V3 message as before
but indicates that it supports resending the wrapped key. This is done
by setting the packet id of the replay id to 0x0f000000. The first byte
indicates the early negotiation support and the next byte the flags.
All tls-crypt-v2 implementations that support early negotiation, must
also support resending the wrapped key. The flags byte is therefore
empty.
2. The server responds with a P_CONTROL_HARD_RESET_V2 message. Instead of having
an empty payload like normally, the payload consists of TLV (type (uint16),
length (uint16), value) packets. TLV was chosen
to allow extensibility in the future. Currently only the following TLV is
defined:
flags - type 0x01, length 2.
Bit 1 indicates that the client needs to resend the WKc in the third packet.
3. Instead of normal P_ACK_V1 or P_CONTROL_V1 packet, the client will send a
P_CONTROL_WKC_V1 packet. The P_CONTROL_WKC_V1 is identical to a normal
P_CONTROL_V1 packet but with the WKc appended.
Normally the first message of the client is either P_ACK_V1, directly
followed by a P_CONTROL_V1 message that contains the TLS Client Hello or
just a P_CONTROL_V1 message. Instead of a P_ACK_V1 message the client should
send a P_CONTROL_WKC_V1 message with an empty payload. This message must
also include an ACK for the P_CONTROL_HARD_RESET_V2 message.
When directly sending the TLS Client Hello message in the P_CONTROL_WKC_V1
message, the client must ensure that the resulting P_CONTROL_WKC_V1 message
with the appended WKc does not extend the control message length.
Considerations
--------------
To allow for a smooth transition, the server implementation allows
``tls-crypt`` or ``tls-auth`` to be used simultaneously with ``tls-crypt-v2``.
This specification does not allow simultaneously using ``tls-crypt-v2`` and
connections without any control channel wrapping, because that would break DoS
resilience.
WKc includes a length field, so we leave the option for future extension of the
P_CONTROL_HEAD_RESET_CLIENT_V3 message open. (E.g. add payload to the reset to
indicate low-level protocol features.)
``tls-crypt-v2`` uses fixed crypto algorithms, because:
* The crypto is used before we can do any negotiation, so the algorithms have
to be predefined.
* The crypto primitives are chosen conservatively, making problems with these
primitives unlikely.
* Making anything configurable adds complexity, both in implementation and
usage. We should not add any more complexity than is absolutely necessary.
Potential ``tls-crypt-v2`` risks:
* Slightly more work on first connection (``WKc`` unwrap + hard reset unwrap)
than with ``tls-crypt`` (hard reset unwrap) or ``tls-auth`` (hard reset auth).
* Flexible metadata allow mistakes
(So we should make it easy to do it right. Provide tooling to create client
keys based on cert serial + CA fingerprint, provide script that uses CRL (if
available) to drop revoked keys.)