openvpn Documentation

--show-gateway
 --show-gateway IPv4-target
 --show-gateway IPv6-target

hash-size r v

When both client and server are at least running OpenVPN 2.5, that the order of
the ciphers of the server's ``--data-ciphers`` is used to pick the data cipher.
That means that the first cipher in that list that is also in the client's
``--data-ciphers`` list is chosen. If no common cipher is found the client is rejected
with a AUTH_FAILED message (as seen in client log):

    AUTH: Received control message: AUTH_FAILED,Data channel cipher negotiation failed (no shared cipher)

OpenVPN 2.5 and later will only allow the ciphers specified in ``--data-ciphers``.
If ``--data-ciphers`` is not set the default is :code:`AES-256-GCM:AES-128-GCM`.
In 2.6 and later the default is changed to
:code:`AES-256-GCM:AES-128-GCM:CHACHA20-POLY1305` when Chacha20-Poly1305 is available.

For backwards compatibility OpenVPN 2.6 and later with ``--compat-mode 2.4.x``
(or lower) and OpenVPN 2.5 will automatically add a cipher specified using the
``--cipher`` option to this list.

OpenVPN 2.4 clients
```````````````````
The negotiation support in OpenVPN 2.4 was the first iteration of the implementation
and still had some quirks. Its main goal was "upgrade to AES-256-GCM when possible".
An OpenVPN 2.4 client that is built against a crypto library that supports AES in GCM
mode and does not have ``--ncp-disable`` will always announce support for
``AES-256-GCM`` and ``AES-128-GCM`` to a server by sending :code:`IV_NCP=2`.

This only causes a problem if ``--ncp-ciphers`` option has been changed from the
default of :code:`AES-256-GCM:AES-128-GCM` to a value that does not include
these two ciphers. When an OpenVPN server tries to use ``AES-256-GCM`` or
``AES-128-GCM`` the connection will then fail. It is therefore recommended to
always have the ``AES-256-GCM`` and ``AES-128-GCM`` ciphers to the ``--ncp-ciphers``
options to avoid this behaviour.

OpenVPN 3 clients
`````````````````
Clients based on the OpenVPN 3.x library (https://github.com/openvpn/openvpn3/)
do not have a configurable ``--ncp-ciphers`` or ``--data-ciphers`` option. Newer
versions by default disable legacy AES-CBC, BF-CBC, and DES-CBC ciphers.
These clients will always announce support for all their supported AEAD ciphers
(``AES-256-GCM``, ``AES-128-GCM`` and in newer versions also ``Chacha20-Poly1305``).

To support OpenVPN 3.x based clients at least one of these ciphers needs to be
included in the server's ``--data-ciphers`` option.


OpenVPN 2.3 and older clients (and clients with ``--ncp-disable``)

When a client indicates support for ``AES-128-GCM`` and ``AES-256-GCM``
(with ``IV_NCP=2``) an OpenVPN 2.4 server will send the first
cipher of the ``--ncp-ciphers`` to the OpenVPN client regardless of what
the cipher is. To emulate the behaviour of an OpenVPN 2.4 client as close
as possible and have compatibility to a setup that depends on this quirk,
adding ``AES-128-GCM`` and ``AES-256-GCM`` to the client's ``--data-ciphers``
option is required. OpenVPN 2.5+ will only announce the ``IV_NCP=2`` flag if
those ciphers are present.

OpenVPN 2.3 and older servers (and servers with ``--ncp-disable``)

The ``--cipher`` option defaulted to ``BF-CBC`` in OpenVPN 2.4 and older
version. The default was never changed to ensure backwards compatibility.
In OpenVPN 2.5 this behaviour has now been changed so that if the ``--cipher``
is not explicitly set it does not allow the weak ``BF-CBC`` cipher any more
and needs to explicitly added as ``--cipher BFC-CBC`` or added to
``--data-ciphers``.

We strongly recommend to switching away from BF-CBC to a
more secure cipher as soon as possible instead.

---

## File: doc/man-sections/client-options.rst

Client Options
--------------
The client options are used when connecting to an OpenVPN server configured
to use ``--server``, ``--server-bridge``, or ``--mode server`` in its
configuration.

--allow-pull-fqdn
  Allow client to pull DNS names from server (rather than being limited to
  IP address) for ``--ifconfig``, ``--route``, and ``--route-gateway``.

--allow-recursive-routing
  When this option is set, OpenVPN will not drop incoming tun packets with
  same destination as host.

--auth-token token
  This is not an option to be used directly in any configuration files,
  but rather push this option from a ``--client-connect`` script or a
  ``--plugin`` which hooks into the :code:`OPENVPN_PLUGIN_CLIENT_CONNECT`
  or :code:`OPENVPN_PLUGIN_CLIENT_CONNECT_V2` calls. This option provides a
  possibility to replace the clients password with an authentication token
  during the lifetime of the OpenVPN client.

  Whenever the connection is renegotiated and the
  ``--auth-user-pass-verify`` script or ``--plugin`` making use of the
  :code:`OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY` hook is triggered, it will
  pass over this token as the password instead of the password the user
  provided. The authentication token can only be reset by a full reconnect
  where the server can push new options to the client. The password the
  user entered is never preserved once an authentication token has been
  set. If the OpenVPN server side rejects the authentication token then
  the client will receive an :code:`AUTH_FAILED` and disconnect.

  The purpose of this is to enable two factor authentication methods, such
  as HOTP or TOTP, to be used without needing to retrieve a new OTP code
  each time the connection is renegotiated. Another use case is to cache
  authentication data on the client without needing to have the users
  password cached in memory during the life time of the session.

  To make use of this feature, the ``--client-connect`` script or
  ``--plugin`` needs to put
  ::

     push "auth-token UNIQUE_TOKEN_VALUE"

  into the file/buffer for dynamic configuration data. This will then make
  the OpenVPN server to push this value to the client, which replaces the
  local password with the ``UNIQUE_TOKEN_VALUE``.

  Newer clients (2.4.7+) will fall back to the original password method
  after a failed auth. Older clients will keep using the token value and
  react according to ``--auth-retry``

--auth-token-user base64username
  Companion option to ``--auth-token``. This options allows one to override
  the username used by the client when reauthenticating with the ``auth-token``.
  It also allows one to use ``--auth-token`` in setups that normally do not use
  username and password.

  The username has to be base64 encoded.

--auth-user-pass
  Authenticate with server using username/password.

  Valid syntaxes:
  ::

      auth-user-pass
      auth-user-pass up

  If ``up`` is present, it must be a file containing username/password on 2
  lines or a flag named :code:`username-only` to indicate no password
  should be prompted for. In the former case, if the password line is missing
  in the file, OpenVPN will prompt for one.

  If ``up`` is omitted, username/password will be prompted from the
  console.

  This option can also be inlined
  ::

    <auth-user-pass>
    username
    [password]
    </auth-user-pass>

  where password is optional, and will be prompted from the console if
  missing.

  The :code:`username-only` flag is meant to be used with SSO authentication.
  In this case the user will be asked for a username but not password. Instead,
  a dummy password :code:`[[BLANK]]` is generated internally and submitted to
  the server. See management-notes.txt for how this option affects username/password
  prompt via the management interface. For the console, it simply eliminates
  the password prompt.

  The :code:`username-only` flag cannot be used along with embedding username and/or
  password in the config file, or while reading them from an external file. In
  such cases, if only username is relevant and no password prompt is desired, a
  dummy password like 'no_passsword' should be embedded as well. This flag is also
  incompatible with the ``--static-challenge`` option and legacy ``dynamic challenge``
  protocol.

  The server configuration must specify an ``--auth-user-pass-verify``
  script to verify the username/password provided by the client.

--auth-retry type
  Controls how OpenVPN responds to username/password verification errors
  such as the client-side response to an :code:`AUTH_FAILED` message from
  the server or verification failure of the private key password.

  Normally used to prevent auth errors from being fatal on the client
  side, and to permit username/password requeries in case of error.

  An :code:`AUTH_FAILED` message is generated by the server if the client
  fails ``--auth-user-pass`` authentication, or if the server-side
  ``--client-connect`` script returns an error status when the client
  tries to connect.

  ``type`` can be one of:

  :code:`none`
      Client will exit with a fatal error (this is the default).

  :code:`nointeract`
      Client will retry the connection without requerying
      for an ``--auth-user-pass`` username/password. Use this option for
      unattended clients.

  :code:`interact`
      Client will requery for an ``--auth-user-pass``
      username/password and/or private key password before attempting a
      reconnection.

  Note that while this option cannot be pushed, it can be controlled from
  the management interface.

--client
  A helper directive designed to simplify the configuration of OpenVPN's
  client mode. This directive is equivalent to:
  ::

       pull
       tls-client

--client-nat args
  This pushable client option sets up a stateless one-to-one NAT rule on
  packet addresses (not ports), and is useful in cases where routes or
  ifconfig settings pushed to the client would create an IP numbering
  conflict.

  Valid syntax:
  ::

      client-nat snat|dnat network netmask alias

  Examples:
  ::

      client-nat snat 192.168.0.0 255.255.0.0 10.64.0.0
      client-nat dnat 10.64.0.0 255.255.0.0 192.168.0.0

  ``network`` and ``netmask`` (for example :code:`192.168.0.0
  255.255.0.0`) define the local view of a resource from the client
  perspective, while ``alias`` (for example :code:`10.64.0.0`) defines the
  remote view from the server perspective using the same netmask.

  Use :code:`snat` (source NAT) for resources owned by the client and
  :code:`dnat` (destination NAT) for remote resources.

  Set ``--verb 6`` for debugging info showing the transformation of
  src/dest addresses in packets.

--connect-retry args
  Wait ``n`` seconds between connection attempts (default :code:`1`).
  Repeated reconnection attempts are slowed down after 5 retries per
  remote by doubling the wait time after each unsuccessful attempt.

  Valid syntaxes:
  ::

     connect retry n
     connect retry n max

  If the optional argument ``max`` is specified, the maximum wait time in
  seconds gets capped at that value (default :code:`300`).

--connect-retry-max n
  ``n`` specifies the number of times each ``--remote`` or
  ``<connection>`` entry is tried. Specifying ``n`` as :code:`1` would try
  each entry exactly once. A successful connection resets the counter.
  (default *unlimited*).

--connect-timeout n
  See ``--server-poll-timeout``.

--dns args
  Client DNS configuration to be used with the connection.

  Valid syntaxes:
  ::

     dns search-domains domain [domain ...]
     dns server n address addr[:port] [addr[:port] ...]
     dns server n resolve-domains domain [domain ...]
     dns server n dnssec yes|optional|no
     dns server n transport DoH|DoT|plain
     dns server n sni server-name

  The ``--dns search-domains`` directive takes one or more domain names
  to be added as DNS domain suffixes. If it is repeated multiple times within
  a configuration the domains are appended, thus e.g. domain names pushed by
  a server will amend locally defined ones.

  The ``--dns server`` directive is used to configure DNS server ``n``.
  The server id ``n`` must be a value between -128 and 127. For pushed
  DNS server options it must be between 0 and 127. The server id is used
  to group options and also for ordering the list of configured DNS servers;
  lower numbers come first. DNS servers being pushed to a client replace
  already configured DNS servers with the same server id. Only the group of
  options corresponding to the lowest server id is applied.

  The ``address`` option configures the IPv4 and / or IPv6 address(es) of
  the DNS server. Up to eight addresses can be specified per DNS server.
  Optionally a port can be appended after a colon. IPv6 addresses need to
  be enclosed in brackets if a port is appended.

  The ``resolve-domains`` option takes one or more DNS domains used to define
  a split-dns or dns-routing setup, where only the given domains are resolved
  by the server. Systems which do not support fine grained DNS domain
  configuration will ignore this setting.

  The ``dnssec`` option is used to configure validation of DNSSEC records.
  While the exact semantics may differ for resolvers on different systems,
  ``yes`` likely makes validation mandatory, ``no`` disables it, and ``optional``
  uses it opportunistically.

  The ``transport`` option enables DNS-over-HTTPS (``DoH``) or DNS-over-TLS (``DoT``)
  for a DNS server. The ``sni`` option can be used with them to specify the
  ``server-name`` for TLS server name indication.

  Each server has to have at least one address configured for a configuration
  to be valid. All the other options can be omitted.

  Note that not all options may be supported on all platforms. As soon support
  for different systems is implemented, information will be added here how
  unsupported options are treated.

  The ``--dns`` option will eventually obsolete the ``--dhcp-option`` directive.
  Until then it will replace configuration at the places ``--dhcp-option`` puts it,
  so that ``--dns`` overrides ``--dhcp-option``. Thus, ``--dns`` can be used today
  to migrate from ``--dhcp-option``.

  Windows only:

  #. If tap-windows6 is in use, dns servers are set by DHCP by default.
     In this case only ``--dns search-domains`` and ``--dns server n address ..``
     with the lowest value of ``n`` are interpreted. All other ``--dns`` options
     are ignored. Use of the dco driver is the recommended way to make use of these
     new features.

  #. If ``--dns server n resolve-domains`` is in use, the DNS server addresses
     corresponding to ``n`` are set on the interface only if ``search-domains`` is
     also specified.  Otherwise these DNS addresses are used only for NRPT rules for
     split-DNS.

--explicit-exit-notify n
  In UDP client mode or point-to-point mode, send server/peer an exit
  notification if tunnel is restarted or OpenVPN process is exited. In
  client mode, on exit/restart, this option will tell the server to
  immediately close its client instance object rather than waiting for a
  timeout.

  If both server and client support sending this message using the control
  channel, the message will be sent as control-channel message. Otherwise
  the message is sent as data-channel message, which will be ignored by
  data-channel offloaded peers.

  The **n** parameter (default :code:`1` if not present) controls the
  maximum number of attempts that the client will try to resend the exit
  notification message if messages are sent in data-channel mode.

  In UDP server mode, send :code:`RESTART` control channel command to
  connected clients. The ``n`` parameter (default :code:`1` if not present)
  controls client behavior. With ``n`` = :code:`1` client will attempt to
  reconnect to the same server, with ``n`` = :code:`2` client will advance
  to the next server.

  OpenVPN will not send any exit notifications unless this option is
  enabled.

--inactive args
  Causes OpenVPN to exit after ``n`` seconds of inactivity on the TUN/TAP
  device. The time length of inactivity is measured since the last
  incoming or outgoing tunnel packet. The default value is 0 seconds,
  which disables this feature.

  Valid syntaxes:
  ::

       inactive n
       inactive n bytes

  If the optional ``bytes`` parameter is included, exit if less than
  ``bytes`` of combined in/out traffic are produced on the tun/tap device
  in ``n`` seconds.

  In any case, OpenVPN's internal ping packets (which are just keepalives)
  and TLS control packets are not considered "activity", nor are they
  counted as traffic, as they are used internally by OpenVPN and are not
  an indication of actual user activity.

  NOTE: on FreeBSD with DCO, due to platform limits, the previous paragraph
  is not correct.  In that case, encapsulation overhead and keepalives are
  counted, so using this feature needs a sufficiently-high ``bytes`` value to
  take these extra numbers into account.

--proto-force p
  When iterating through connection profiles, only consider profiles using
  protocol ``p`` (:code:`tcp` \| :code:`udp`).

  Note that this specifically only filters by the transport layer
  protocol, i.e. UDP or TCP. This does not affect whether IPv4 or
  IPv6 is used as IP protocol.

  For implementation reasons the option accepts the :code:`4` and :code:`6`
  suffixes when specifying the protocol
  (i.e. :code:`udp4` / :code:`udp6` / :code:`tcp4` / :code:`tcp6`).
  However, these behave the same as without the suffix and should be avoided
  to prevent confusion.

--pull
  This option must be used on a client which is connecting to a
  multi-client server. It indicates to OpenVPN that it should accept
  options pushed by the server, provided they are part of the legal set of
  pushable options (note that the ``--pull`` option is implied by
  ``--client`` ).

  In particular, ``--pull`` allows the server to push routes to the
  client, so you should not use ``--pull`` or ``--client`` in situations
  where you don't trust the server to have control over the client's
  routing table.

--pull-filter args
  Filter options on the client pushed by the server to the client.

  Valid syntaxes:
  ::

     pull-filter accept text
     pull-filter ignore text
     pull-filter reject text

  Filter options received from the server if the option starts with
  :code:`text`.  The action flag :code:`accept` allows the option,
  :code:`ignore` removes it and :code:`reject` flags an error and triggers
  a :code:`SIGUSR1` restart. The filters may be specified multiple times,
  and each filter is applied in the order it is specified. The filtering of
  each option stops as soon as a match is found. Unmatched options are accepted
  by default.

  Prefix comparison is used to match :code:`text` against the received option so
  that
  ::

      pull-filter ignore "route"

  would remove all pushed options starting with ``route`` which would
  include, for example, ``route-gateway``. Enclose *text* in quotes to
  embed spaces.

  ::

      pull-filter accept "route 192.168.1."
      pull-filter ignore "route "

  would remove all routes that do not start with ``192.168.1``.

  *Note* that :code:`reject` may result in a repeated cycle of failure and
  reconnect, unless multiple remotes are specified and connection to the
  next remote succeeds. To silently ignore an option pushed by the server,
  use :code:`ignore`.

  *Warning:* ``pull-filter`` cannot be relied upon as a security measure to
  protect against offending options pushed by a server. For example, the
  filter could be defeated by pushing options with extra spaces between
  tokens or other formatting variations.

--push-peer-info
  Push additional information about the client to server. The following
  data is always pushed to the server:

  :code:`IV_VER=<version>`
        The client OpenVPN version

  :code:`IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win]`
        The client OS platform

  :code:`IV_PROTO`
    Details about protocol extensions that the peer supports. The
    variable is a bitfield and the bits are defined as follows:

    - bit 0: Reserved, should always be zero
    - bit 1: The peer supports peer-id floating mechanism
    - bit 2: The client expects a push-reply and the server may
      send this reply without waiting for a push-request first.
    - bit 3: The client is capable of doing key derivation using
      RFC5705 key material exporter.
    - bit 4: The client is capable of accepting additional arguments
      to the ``AUTH_PENDING`` message.
    - bit 5: The client supports doing feature negotiation in P2P mode
    - bit 6: The client is capable of parsing and receiving the ``--dns`` pushed option
    - bit 7: The client is capable of sending exit notification via control channel using ``EXIT`` message. Also, the client is accepting the protocol-flags pushed option for the EKM capability
    - bit 8: The client is capable of accepting ``AUTH_FAILED,TEMP`` messages
    - bit 9: The client is capable of dynamic tls-crypt
    - bit 10: The client is capable of data epoch keys

  :code:`IV_NCP=2`
        Negotiable ciphers, client supports ``--cipher`` pushed by
        the server, a value of 2 or greater indicates client supports
        *AES-GCM-128* and *AES-GCM-256*. IV_NCP is *deprecated* in
        favor of ``IV_CIPHERS``.

  :code:`IV_CIPHERS=<data-ciphers>`
        The client announces the list of supported ciphers configured with the
        ``--data-ciphers`` option to the server.

  :code:`IV_MTU=<max_mtu>`
        The client announces the support of pushable MTU and the maximum MTU
        it is willing to accept.

  :code:`IV_GUI_VER=<gui_id> <version>`
        The UI version of a UI if one is running, for example
        :code:`de.blinkt.openvpn 0.5.47` for the Android app.
        This may be set by the client UI/GUI using ``--setenv``.

  :code:`IV_SSO=[crtext,][openurl,][proxy_url]`
        Additional authentication methods supported by the client.
        This may be set by the client UI/GUI using ``--setenv``.

  The following flags depend on which compression formats are compiled in
  and whether compression is allowed by options. See `Protocol options`_
  for more details.

    :code:`IV_LZO=1`
        If client supports LZO compression.

    :code:`IV_LZO_STUB=1`
        If client was built with LZO stub capability. This is only sent if
        ``IV_LZO=1`` is not sent. This means the client can talk to a server
        configured with ``--comp-lzo no``.

    :code:`IV_LZ4=1` and :code:`IV_LZ4v2=1`
        If the client supports LZ4 compression.

    :code:`IV_COMP_STUB=1` and :code:`IV_COMP_STUBv2=1`
        If the client supports stub compression. This means the client can talk
        to a server configured with ``--compress``.

  When ``--push-peer-info`` is enabled the additional information consists
  of the following data:

  :code:`IV_HWADDR=<string>`
        This is intended to be a unique and persistent ID of the client.
        The string value can be any readable ASCII string up to 64 bytes.
        OpenVPN 2.x and some other implementations use the MAC address of
        the client's interface used to reach the default gateway. If this
        string is generated by the client, it should be consistent and
        preserved across independent sessions and preferably
        re-installations and upgrades.

  :code:`IV_SSL=<version string>`
        The ssl library version used by the client, e.g.
        :code:`OpenSSL 1.0.2f 28 Jan 2016`.

  :code:`IV_PLAT_VER=x.y`
        The version of the operating system, e.g. 6.1 for Windows 7.
        This may be set by the client UI/GUI using ``--setenv``.
        On Windows systems it is automatically determined by openvpn
        itself.  On other platforms OpenVPN will default to sending
        the information returned by the ``uname()`` system call in
        the ``release`` field, which is usually the currently running
        kernel version.  This is highly system specific, though.

  :code:`UV_<name>=<value>`
        Client environment variables whose names start with
        :code:`UV_`

--remote args
  Remote host name or IP address, port and protocol.

  Valid syntaxes:
  ::

     remote host
     remote host port
     remote host port proto

  The ``port`` and ``proto`` arguments are optional. The OpenVPN client
  will try to connect to a server at ``host:port``.  The ``proto`` argument
  indicates the protocol to use when connecting with the remote, and may be
  :code:`tcp` or :code:`udp`.  To enforce IPv4 or IPv6 connections add a
  :code:`4` or :code:`6` suffix; like :code:`udp4` / :code:`udp6`
  / :code:`tcp4` / :code:`tcp6`.

  On the client, multiple ``--remote`` options may be specified for
  redundancy, each referring to a different OpenVPN server, in the order
  specified by the list of ``--remote`` options. Specifying multiple
  ``--remote`` options for this purpose is a special case of the more
  general connection-profile feature. See the ``<connection>``
  documentation below.

  The client will move on to the next host in the list, in the event of
  connection failure. Note that at any given time, the OpenVPN client will
  at most be connected to one server.

  Examples:
  ::

     remote server1.example.net
     remote server1.example.net 1194
     remote server2.example.net 1194 tcp

  *Note:*
     Since UDP is connectionless, connection failure is defined by
     the ``--ping`` and ``--ping-restart`` options.

     Also, if you use multiple ``--remote`` options, AND you are dropping
     root privileges on the client with ``--user`` and/or ``--group`` AND
     the client is running a non-Windows OS, if the client needs to switch
     to a different server, and that server pushes back different TUN/TAP
     or route settings, the client may lack the necessary privileges to
     close and reopen the TUN/TAP interface. This could cause the client
     to exit with a fatal error.

  If ``--remote`` is unspecified, OpenVPN will listen for packets from any
  IP address, but will not act on those packets unless they pass all
  authentication tests. This requirement for authentication is binding on
  all potential peers, even those from known and supposedly trusted IP
  addresses (it is very easy to forge a source IP address on a UDP
  packet).

  When used in TCP mode, ``--remote`` will act as a filter, rejecting
  connections from any host which does not match ``host``.

  If ``host`` is a DNS name which resolves to multiple IP addresses,
  OpenVPN will try them in the order that the system getaddrinfo()
  presents them, so priorization and DNS randomization is done by the
  system library. Unless an IP version is forced by the protocol
  specification (4/6 suffix), OpenVPN will try both IPv4 and IPv6
  addresses, in the order getaddrinfo() returns them.

--remote-random
  When multiple ``--remote`` address/ports are specified, or if connection
  profiles are being used, initially randomize the order of the list as a
  kind of basic load-balancing measure.

--remote-random-hostname
  Prepend a random string (6 bytes, 12 hex characters) to hostname to
  prevent DNS caching. For example, "foo.bar.gov" would be modified to
  "<random-chars>.foo.bar.gov".

--resolv-retry n
  If hostname resolve fails for ``--remote``, retry resolve for ``n``
  seconds before failing.

  Set ``n`` to :code:`infinite` to retry indefinitely.

  By default, ``--resolv-retry infinite`` is enabled. You can disable by
  setting n=0.

--preresolve
  Resolve configured ``--remote``, ``--local``, ``--http-proxy``, and
  ``--socks-proxy`` hostnames at startup before opening the connection.

  The resolved addresses are cached and reused for reconnects, so OpenVPN
  will not re-resolve these hostnames after the initial connection attempt.
  This can help configurations where DNS is unavailable while the VPN is
  down, but can be counter-productive for dynamic DNS names or when roaming
  between networks where address family availability changes, such as
  DNS64/NAT64.

--single-session
  After initially connecting to a remote peer, disallow any new
  connections. Using this option means that a remote peer cannot connect,
  disconnect, and then reconnect.

  If the daemon is reset by a signal or ``--ping-restart``, it will allow
  one new connection.

  ``--single-session`` can be used with ``--ping-exit`` or ``--inactive``
  to create a single dynamic session that will exit when finished.

--server-poll-timeout n
  When connecting to a remote server do not wait for more than ``n``
  seconds for a response before trying the next server. The default value
  is :code:`120`. This timeout includes proxy and TCP connect timeouts.

--static-challenge args
  Enable static challenge/response protocol

  Valid syntax:
  ::

     static-challenge text echo [format]

  The ``text`` challenge text is presented to the user which describes what
  information is requested.  The ``echo`` flag indicates if the user's
  input should be echoed on the screen.  Valid ``echo`` values are
  :code:`0` or :code:`1`. The optional ``format`` indicates whether
  the password and response should be combined using the SCRV1 protocol
  (``format`` = :code:`scrv1`) or simply concatenated (``format`` = :code:`concat`).
  :code:`scrv1` is the default.

  See management-notes.txt in the OpenVPN distribution for a description of
  the OpenVPN challenge/response protocol.

.. include:: proxy-options.rst

---

## File: doc/man-sections/connection-profiles.rst

CONNECTION PROFILES
===================

Client configuration files may contain multiple remote servers which
it will attempt to connect against.  But there are some configuration
options which are related to specific ``--remote`` options.  For these
use cases, connection profiles are the solution.

By encapsulating the ``--remote`` option and related options within
``<connection>`` and ``</connection>``, these options are handled as a
group.

An OpenVPN client will try each connection profile sequentially until it
achieves a successful connection.

``--remote-random`` can be used to initially "scramble" the connection
list.

Here is an example of connection profile usage::

   client
   dev tun

   <connection>
   remote 198.19.34.56 1194 udp
   </connection>

   <connection>
   remote 198.19.34.56 443 tcp
   </connection>

   <connection>
   remote 198.19.34.56 443 tcp
   http-proxy 192.168.0.8 8080
   </connection>

   <connection>
   remote 198.19.36.99 443 tcp
   http-proxy 192.168.0.8 8080
   </connection>

   persist-tun
   pkcs12 client.p12
   remote-cert-tls server
   verb 3

First we try to connect to a server at 198.19.34.56:1194 using UDP. If
that fails, we then try to connect to 198.19.34.56:443 using TCP. If
that also fails, then try connecting through an HTTP proxy at
192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to connect
through the same proxy to a server at 198.19.36.99:443 using TCP.

The following OpenVPN options may be used inside of a ``<connection>``
block:

``bind``, ``connect-retry``, ``connect-retry-max``, ``connect-timeout``,
``explicit-exit-notify``, ``float``, ``fragment``, ``http-proxy``,
``http-proxy-option``, ``key-direction``, ``link-mtu``, ``local``,
``lport``, ``mssfix``, ``mtu-disc``, ``nobind``, ``port``, ``proto``,
``remote``, ``rport``, ``socks-proxy``, ``tls-auth``, ``tls-crypt``,
``tls-crypt-v2``, ``tun-mtu and``, ``tun-mtu-extra``.

A defaulting mechanism exists for specifying options to apply to all
``<connection>`` profiles. If any of the above options (with the
exception of ``remote`` ) appear outside of a ``<connection>`` block,
but in a configuration file which has one or more ``<connection>``
blocks, the option setting will be used as a default for
``<connection>`` blocks which follow it in the configuration file.

For example, suppose the ``nobind`` option were placed in the sample
configuration file above, near the top of the file, before the first
``<connection>`` block. The effect would be as if ``nobind`` were
declared in all ``<connection>`` blocks below it.

---

## File: doc/man-sections/encryption-options.rst

Encryption Options
------------------

SSL Library information
```````````````````````

--show-ciphers
  (Standalone) Show all cipher algorithms to use with the ``--cipher``
  option.

--show-digests
  (Standalone) Show all message digest algorithms to use with the
  ``--auth`` option.

--show-tls
  (Standalone) Show all TLS ciphers supported by the crypto library.
  OpenVPN uses TLS to secure the control channel, over which the keys that
  are used to protect the actual VPN traffic are exchanged. The TLS
  ciphers will be sorted from highest preference (most secure) to lowest.

  Be aware that whether a cipher suite in this list can actually work
  depends on the specific setup of both peers (e.g. both peers must
  support the cipher, and an ECDSA cipher suite will not work if you are
  using an RSA certificate, etc.).

--show-engines
  (Standalone) Show currently available hardware-based crypto acceleration
  engines supported by the OpenSSL library.

--show-groups
  (Standalone) Show all available elliptic curves/groups to use with the
  ``--ecdh-curve`` and ``tls-groups`` options.

Generating key material
```````````````````````

--genkey args
  (Standalone) Generate a key to be used of the type keytype. if keyfile
  is left out or empty the key will be output on stdout. See the following
  sections for the different keytypes.

  Valid syntax:
  ::

     --genkey keytype keyfile

  Valid keytype arguments are:

  :code:`secret`                Standard OpenVPN shared secret keys

  :code:`tls-crypt`             Alias for :code:`secret`

  :code:`tls-auth`              Alias for :code:`secret`

  :code:`auth-token`            Key used for ``--auth-gen-token-key``

  :code:`tls-crypt-v2-server`   TLS Crypt v2 server key

  :code:`tls-crypt-v2-client`   TLS Crypt v2 client key


  Examples:
  ::

     $ openvpn --genkey secret shared.key
     $ openvpn --genkey tls-crypt shared.key
     $ openvpn --genkey tls-auth shared.key
     $ openvpn --genkey tls-crypt-v2-server v2crypt-server.key
     $ openvpn --tls-crypt-v2 v2crypt-server.key --genkey tls-crypt-v2-client v2crypt-client-1.key

  * Generating *Shared Secret Keys*
    Generate a shared secret, for use with the ``--tls-auth``
    or ``--tls-crypt`` options.

    Syntax:
    ::

       $ openvpn --genkey tls-crypt|tls-auth keyfile

    The key is saved in ``keyfile``. Both variants (``tls-crypt`` and
    ``tls-auth``) generate the same type of key. The aliases are added for
    convenience.

    This file must be shared with the peer over a pre-existing secure
    channel such as ``scp``\(1).

  * Generating *TLS Crypt v2 Server key*
    Generate a ``--tls-crypt-v2`` key to be used by an OpenVPN server.
    The key is stored in ``keyfile``.

    Syntax:
    ::

       --genkey tls-crypt-v2-server keyfile

  * Generating *TLS Crypt v2 Client key*
    Generate a --tls-crypt-v2 key to be used by OpenVPN clients.  The
    key is stored in ``keyfile``.

    Syntax
    ::

       --genkey tls-crypt-v2-client keyfile [metadata]

    If supplied, include the supplied ``metadata`` in the wrapped client
    key. This metadata must be supplied in base64-encoded form. The
    metadata must be at most 733 bytes long (980 characters in base64, though
    note that 980 base64 characters can encode more than 733 bytes).

    If no metadata is supplied, OpenVPN will use a 64-bit unix timestamp
    representing the current time in UTC, encoded in network order, as
    metadata for the generated key.

    A tls-crypt-v2 client key is wrapped using a server key. To generate a
    client key, the user must therefore supply the server key using the
    ``--tls-crypt-v2`` option.

    Servers can use ``--tls-crypt-v2-verify`` to specify a metadata
    verification command.

  * Generate *Authentication Token key*
    Generate a new secret that can be used with **--auth-gen-token-secret**

    Syntax:
    ::

       --genkey auth-token [keyfile]

    *Note:*
       This file should be kept secret to the server as anyone that has
       access to this file will be able to generate auth tokens that the
       OpenVPN server will accept as valid.

.. include:: renegotiation.rst
.. include:: tls-options.rst
.. include:: pkcs11-options.rst

---

## File: doc/man-sections/example-fingerprint.rst

Small OpenVPN setup with peer-fingerprint
=========================================
This section consists of instructions how to build a small OpenVPN setup with the
:code:`peer-fingerprint` option. This has the advantage of being easy to setup
and should be suitable for most small lab and home setups without the need for a PKI.
For bigger scale setup setting up a PKI (e.g. via easy-rsa) is still recommended.

Both server and client configuration can be further modified to customise the
setup.

Server setup
------------
1. Install openvpn

   Compile from source-code (see ``INSTALL`` file) or install via a distribution (apt/yum/ports)
   or via installer (Windows).

2. Generate a self-signed certificate for the server::

    openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:secp384r1 -keyout server.key -out server.crt -nodes -sha256 -days 3650 -subj '/CN=server'

3. Generate SHA256 fingerprint of the server certificate

   Use the OpenSSL command line utility to view the fingerprint of just
   created certificate::

    openssl x509 -fingerprint -sha256 -in server.crt -noout

   This outputs something similar to::

     SHA256 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


4. Write a server configuration (``server.conf``)::

    # The server certificate we created in step 1
    cert server.crt
    key server.key

    dh none
    dev tun

    # Listen on IPv6+IPv4 simultaneously
    proto udp6

    # The ip address the server will distribute
    server 10.8.0.0 255.255.255.0
    server-ipv6 fd00:6f76:706e::/64

    # A tun-mtu of 1400 avoids problems of too big packets after VPN encapsulation
    tun-mtu 1400

    # The fingerprints of your clients. After adding/removing one here restart the
    # server
    
    

    # Notify clients when you restart the server to reconnect quickly
    explicit-exit-notify 1

    # Ping every 60s, restart if no data received for 5 minutes
    keepalive 60 300

    # Uncomment the line below if you want to have persistent IP addresses
    # ifconfig-pool-persist  /etc/openvpn/server/ipp.txt

    # Uncomment the line below to push a DNS server to clients
    # push "dhcp-option DNS 1.1.1.1"

5. Add at least one client as described in the client section.

6. Start the server.
    - On systemd based distributions move ``server.crt``, ``server.key`` and
      ``server.conf`` to ``/etc/openvpn/server`` and start it via systemctl::

          sudo mv server.conf server.key server.crt /etc/openvpn/server

          sudo systemctl start openvpn-server@server

Adding a client
---------------
1. Install OpenVPN

2. Generate a self-signed certificate for the client. In this example the client
   name is alice. Each client should have a unique name. Replace alice with a
   different name for each client.
   ::

      openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:secp384r1 -keyout - -nodes -sha256 -days 3650 -subj '/CN=alice'

   This generate a certificate and a key for the client. The output of the command will look
   something like this::

      -----BEGIN PRIVATE KEY-----
      [base64 content]
      -----END PRIVATE KEY-----
      -----
      -----BEGIN CERTIFICATE-----
      [base 64 content]
      -----END CERTIFICATE-----


3. Create a new client configuration file. In this example we will name the file
   ``alice.ovpn``::

      # The name of your server to connect to
      remote yourserver.example.net
      client
      # use a random source port instead the fixed 1194
      nobind

      # Uncomment the following line if you want to route
      # all traffic via the VPN
      # redirect-gateway def1 ipv6

      # To set a DNS server
      # dhcp-option DNS 192.168.234.1

      <key>
      -----BEGIN PRIVATE KEY-----
      [Insert here the key created in step 2]
      -----END PRIVATE KEY-----
      </key>
      <cert>
      -----BEGIN CERTIFICATE-----
      [Insert here the certificate created in step 2]
      -----END CERTIFICATE-----
      </cert>

      # This is the fingerprint of the server that we trust. We generated this fingerprint
      # in step 2 of the server setup
      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

      # The tun-mtu of the client should match the server MTU
      tun-mtu 1400
      dev tun


4. Generate the fingerprint of the client certificate. For that we will
   let OpenSSL read the client configuration file as the x509 command will
   ignore anything that is not between the begin and end markers of the certificate::

      openssl x509 -fingerprint -sha256 -noout -in alice.ovpn

   This will again output something like::

        SHA256 Fingerprint=ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00:ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00

5. Edit the ``server.conf`` configuration file and add this new client
   fingerprint as additional line  between :code:``
   and :code:``

   After adding *two* clients the part of configuration would look like this::

      
      ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00:ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00
      99:88:77:66:55:44:33:22:11:00:ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00:88:77:66:55:44:33
      

6. (optional) if the client is an older client that does not support the
   :code:`peer-fingerprint` (e.g. OpenVPN 2.5 and older, OpenVPN Connect 3.3
   and older), the client config ``alice.ovpn`` can be modified to still work with
   these clients.

   Remove the line starting with :code:`peer-fingerprint`. Then
   add a new :code:`<ca>` section at the end of the configuration file
   with the contents of the ``server.crt`` created in step 2 of the
   server setup. The end of ``alice.ovpn`` file should look like::

      [...]  # Beginning of the file skipped
      </cert>

      # The tun-mtu of the client should match the server MTU
      tun-mtu 1400
      dev tun

      <ca>
      [contents of the server.crt]
      </ca>

   Note that we put the :code:`<ca>` section after the :code:`<cert>` section
   to make the fingerprint generation from step 4 still work since it will
   only use the first certificate it finds.

7. Import the file into the OpenVPN client or just use the
   :code:`openvpn alice.ovpn` to start the VPN.

---

## File: doc/man-sections/examples.rst

EXAMPLES
========

Prior to running these examples, you should have OpenVPN installed on
two machines with network connectivity between them. If you have not yet
installed OpenVPN, consult the INSTALL file included in the OpenVPN
distribution.


Firewall Setup:
---------------

If firewalls exist between the two machines, they should be set to
forward the port OpenVPN is configured to use, in both directions.
The default for OpenVPN is 1194/udp.  If you do not have control
over the firewalls between the two machines, you may still be able to
use OpenVPN by adding ``--ping 15`` to each of the ``openvpn`` commands
used below in the examples (this will cause each peer to send out a UDP
ping to its remote peer once every 15 seconds which will cause many
stateful firewalls to forward packets in both directions without an
explicit firewall rule).

Please see your operating system guides for how to configure the firewall
on your systems.


VPN Address Setup:
------------------

For purposes of our example, our two machines will be called
``bob.example.com`` and ``alice.example.com``. If you are constructing a
VPN over the internet, then replace ``bob.example.com`` and
``alice.example.com`` with the internet hostname or IP address that each
machine will use to contact the other over the internet.

Now we will choose the tunnel endpoints. Tunnel endpoints are private IP
addresses that only have meaning in the context of the VPN. Each machine
will use the tunnel endpoint of the other machine to access it over the
VPN. In our example, the tunnel endpoint for bob.example.com will be
10.4.0.1 and for alice.example.com, 10.4.0.2.

Once the VPN is established, you have essentially created a secure
alternate path between the two hosts which is addressed by using the
tunnel endpoints. You can control which network traffic passes between
the hosts (a) over the VPN or (b) independently of the VPN, by choosing
whether to use (a) the VPN endpoint address or (b) the public internet
address, to access the remote host. For example if you are on
bob.example.com and you wish to connect to ``alice.example.com`` via
``ssh`` without using the VPN (since **ssh** has its own built-in security)
you would use the command ``ssh alice.example.com``. However in the same
scenario, you could also use the command ``telnet 10.4.0.2`` to create a
telnet session with alice.example.com over the VPN, that would use the
VPN to secure the session rather than ``ssh``.

You can use any address you wish for the tunnel endpoints but make sure
that they are private addresses (such as those that begin with 10 or
192.168) and that they are not part of any existing subnet on the
networks of either peer, unless you are bridging. If you use an address
that is part of your local subnet for either of the tunnel endpoints,
you will get a weird feedback loop.


Example 1: A simple tunnel without security (not recommended)
-------------------------------------------------------------

Since :code:`tun` is the default device type, ``--dev`` is optional; when it
is omitted OpenVPN creates a dynamically-named ``tunX`` device. The examples
below still name the device (``--dev tun1``) explicitly for clarity.

On bob::

   openvpn --remote alice.example.com --dev tun1 \
            --ifconfig 10.4.0.1 10.4.0.2 --verb 9

On alice::

   openvpn --remote bob.example.com --dev tun1 \
            --ifconfig 10.4.0.2 10.4.0.1 --verb 9

Now verify the tunnel is working by pinging across the tunnel.

On bob::

   ping 10.4.0.2

On alice::

   ping 10.4.0.1

The ``--verb 9`` option will produce verbose output, similar to the
``tcpdump``\(8) program. Omit the ``--verb 9`` option to have OpenVPN run
quietly.


Example 2: A tunnel with self-signed certificates and fingerprint
-----------------------------------------------------------------

First build a self-signed certificate on bob and display its fingerprint.

::

   openssl req -x509 -newkey ec:<(openssl ecparam -name secp384r1) -keyout bob.pem -out bob.pem -nodes -sha256 -days 3650 -subj '/CN=bob'
   openssl x509 -noout -sha256 -fingerprint -in bob.pem

and the same on alice::

   openssl req -x509 -newkey ec:<(openssl ecparam -name secp384r1) -keyout alice.pem -out alice.pem -nodes -sha256 -days 3650 -subj '/CN=alice'
   openssl x509 -noout -sha256 -fingerprint -in alice.pem


These commands will build a text file called ``bob.pem`` or ``alice.pem`` (in ascii format)
that contain both self-signed certificate and key and show the fingerprint of the certificates.
Transfer the fingerprints  over a secure medium such as by using
the ``scp``\(1) or ``ssh``\(1) program.

On bob::

   openvpn --ifconfig 10.4.0.1 10.4.0.2 --tls-server --dev tun --dh none \
           --cert bob.pem --key bob.pem --cipher AES-256-GCM \
           --peer-fingerprint "$fingerprint_of_alices_cert"

On alice::

   openvpn --remote bob.example.com --tls-client --dev tun1   \
           --ifconfig 10.4.0.2 10.4.0.1 --cipher AES-256-GCM  \
           --cert alice.pem --key alice.pem                   \
           --peer-fingerprint "$fingerprint_of_bobs_cert"

Now verify the tunnel is working by pinging across the tunnel.

On bob::

   ping 10.4.0.2

On alice::

   ping 10.4.0.1

Note: This example use a elliptic curve (``secp384``), which allows
``--dh`` to be set to ``none``.

Example 3: A tunnel with full PKI and TLS-based security
--------------------------------------------------------

For this test, we will designate ``bob`` as the TLS client and ``alice``
as the TLS server.

*Note:*
    The client or server designation only has
    meaning for the TLS subsystem. It has no bearing on OpenVPN's
    peer-to-peer, UDP-based communication model.*

First, build a separate certificate/key pair for both bob and alice (see
above where ``--cert`` is discussed for more info). Then construct
Diffie Hellman parameters (see above where ``--dh`` is discussed for
more info). You can also use the included test files :code:`client.crt`,
:code:`client.key`, :code:`server.crt`, :code:`server.key` and
:code:`ca.crt`. The ``.crt`` files are certificates/public-keys, the
``.key`` files are private keys, and :code:`ca.crt` is a certification
authority who has signed both :code:`client.crt` and :code:`server.crt`.
For Diffie Hellman parameters you can use the included file
:code:`dh2048.pem`.

*WARNING:*
    All client, server, and certificate authority certificates
    and keys included in the OpenVPN distribution are totally
    insecure and should be used for testing only.

On bob::

   openvpn --remote alice.example.com --dev tun1    \
           --ifconfig 10.4.0.1 10.4.0.2             \
           --tls-client --ca ca.crt                 \
           --cert client.crt --key client.key       \
           --reneg-sec 60 --verb 5

On alice::

   openvpn --remote bob.example.com --dev tun1      \
           --ifconfig 10.4.0.2 10.4.0.1             \
           --tls-server --dh dh1024.pem --ca ca.crt \
           --cert server.crt --key server.key       \
           --reneg-sec 60 --verb 5

Now verify the tunnel is working by pinging across the tunnel.

On bob::

   ping 10.4.0.2

On alice::

   ping 10.4.0.1

Notice the ``--reneg-sec 60`` option we used above. That tells OpenVPN
to renegotiate the data channel keys every minute. Since we used
``--verb 5`` above, you will see status information on each new key
negotiation.

For production operations, a key renegotiation interval of 60 seconds is
probably too frequent. Omit the ``--reneg-sec 60`` option to use
OpenVPN's default key renegotiation interval of one hour.


Routing:
--------

Assuming you can ping across the tunnel, the next step is to route a
real subnet over the secure tunnel. Suppose that bob and alice have two
network interfaces each, one connected to the internet, and the other to
a private network. Our goal is to securely connect both private
networks. We will assume that bob's private subnet is *10.0.0.0/24* and
alice's is *10.0.1.0/24*.

First, ensure that IP forwarding is enabled on both peers. On Linux,
enable routing::

    echo 1 > /proc/sys/net/ipv4/ip_forward

This setting is not persistent.  Please see your operating systems
documentation how to properly configure IP forwarding, which is also
persistent through system boots.

If your system is configured with a firewall.  Please see your operating
systems guide on how to configure the firewall.  You typically want to
allow traffic coming from and going to the tun/tap adapter OpenVPN is
configured to use.

On bob::

   route add -net 10.0.1.0 netmask 255.255.255.0 gw 10.4.0.2

On alice::

   route add -net 10.0.0.0 netmask 255.255.255.0 gw 10.4.0.1

Now any machine on the *10.0.0.0/24* subnet can access any machine on the
*10.0.1.0/24* subnet over the secure tunnel (or vice versa).

In a production environment, you could put the route command(s) in a
script and execute with the ``--up`` option.

---

## File: doc/man-sections/generic-options.rst

Generic Options
---------------
This section covers generic options which are accessible regardless of
which mode OpenVPN is configured as.

--help

  Show options.

--auth-nocache
  Don't cache ``--askpass`` or ``--auth-user-pass`` username/passwords in
  virtual memory.

  If specified, this directive will cause OpenVPN to immediately forget
  username/password inputs after they are used. As a result, when OpenVPN
  needs a username/password, it will prompt for input from stdin, which
  may be multiple times during the duration of an OpenVPN session.

  When using ``--auth-nocache`` in combination with a user/password file
  and ``--chroot`` or ``--daemon``, make sure to use an absolute path.

--cd dir
  Change directory to ``dir`` prior to reading any files such as
  configuration files, key files, scripts, etc. ``dir`` should be an
  absolute path, with a leading "/", and without any references to the
  current directory such as :code:`.` or :code:`..`.

  This option is useful when you are running OpenVPN in ``--daemon`` mode,
  and you want to consolidate all of your OpenVPN control files in one
  location.

--chroot dir
  Chroot to ``dir`` after initialization. ``--chroot`` essentially
  redefines ``dir`` as being the top level directory tree (/). OpenVPN
  will therefore be unable to access any files outside this tree. This can
  be desirable from a security standpoint.

  Since the chroot operation is delayed until after initialization, most
  OpenVPN options that reference files will operate in a pre-chroot
  context.

  In many cases, the ``dir`` parameter can point to an empty directory,
  however complications can result when scripts or restarts are executed
  after the chroot operation.

  Note: The SSL library will probably need ``/dev/urandom`` to be available
  inside the chroot directory ``dir``. This is because SSL libraries
  occasionally need to collect fresh randomness. Newer linux kernels and some
  BSDs implement a getrandom() or getentropy() syscall that removes the
  need for ``/dev/urandom`` to be available.

--compat-mode version
  This option provides a convenient way to alter the defaults of OpenVPN
  to be more compatible with the version ``version`` specified. All of
  the changes this option applies can also be achieved using individual
  configuration options.

  The version specified with this option is the version of OpenVPN peer
  OpenVPN should try to be compatible with. In general OpenVPN should be
  compatible with the last two previous version without this option. E.g.
  OpenVPN 2.6.0 should be compatible with 2.5.x and 2.4.x without this option.
  However, there might be some edge cases that still require this option even
  in these cases.

  Note: Using this option reverts defaults to no longer recommended
  values and should be avoided if possible.

  The following table details what defaults are changed depending on the
  version specified.

  - 2.5.x or lower: ``--allow-compression asym`` is automatically added
    to the configuration if no other compression options are present.
  - 2.4.x or lower: The cipher in ``--cipher`` is appended to
    ``--data-ciphers``.
  - 2.3.x or lower: ``--data-ciphers-fallback`` is automatically added with
    the same cipher as ``--cipher``.
  - 2.3.6 or lower: ``--tls-version-min 1.0`` is added to the configuration
    when ``--tls-version-min`` is not explicitly set.

  If not required, this is option should be avoided. Setting this option can
  lower security or disable features like data-channel offloading.

--config file
  Load additional config options from ``file`` where each line corresponds
  to one command line option, but with the leading :code:`--` removed.

  If ``--config file`` is the only option to the openvpn command, the
  ``--config`` can be removed, and the command can be given as ``openvpn
  file``

  Note that configuration files can be nested to a reasonable depth.

  Double quotation or single quotation characters ("", '') can be used to
  enclose single parameters containing whitespace, and "#" or ";"
  characters in the first column can be used to denote comments.

  Note that OpenVPN 2.0 and higher performs backslash-based shell escaping
  for characters not in single quotations, so the following mappings
  should be observed:
  ::

      \\       Maps to a single backslash character (\).
      \"       Pass a literal doublequote character ("), don't
               interpret it as enclosing a parameter.
      \[SPACE] Pass a literal space or tab character, don't
               interpret it as a parameter delimiter.

  For example on Windows, use double backslashes to represent pathnames:
  ::

      secret "c:\\OpenVPN\\secret.key"


  For examples of configuration files, see
  https://openvpn.net/community-resources/how-to/

  Here is an example configuration file:
  ::

      #
      # Sample OpenVPN configuration file for
      # using a pre-shared static key.
      #
      # '#' or ';' may be used to delimit comments.

      # Use a dynamic tun device.
      dev tun

      # Our remote peer
      remote mypeer.mydomain

      # 10.1.0.1 is our local VPN endpoint
      # 10.1.0.2 is our remote VPN endpoint
      ifconfig 10.1.0.1 10.1.0.2

      # Our pre-shared static key
      secret static.key

--daemon progname
  Become a daemon after all initialization functions are completed.

  Valid syntaxes::

    daemon
    daemon progname

  This option will cause all message and error output to be sent to the syslog
  file (such as :code:`/var/log/messages`), except for the output of
  scripts and ifconfig commands, which will go to :code:`/dev/null` unless
  otherwise redirected. The syslog redirection occurs immediately at the
  point that ``--daemon`` is parsed on the command line even though the
  daemonization point occurs later. If one of the ``--log`` options is
  present, it will supersede syslog redirection.

  The optional ``progname`` parameter will cause OpenVPN to report its
  program name to the system logger as ``progname``. This can be useful in
  linking OpenVPN messages in the syslog file with specific tunnels. When
  unspecified, ``progname`` defaults to :code:`openvpn`.

  When OpenVPN is run with the ``--daemon`` option, it will try to delay
  daemonization until the majority of initialization functions which are
  capable of generating fatal errors are complete. This means that
  initialization scripts can test the return status of the openvpn command
  for a fairly reliable indication of whether the command has correctly
  initialized and entered the packet forwarding event loop.

  In OpenVPN, the vast majority of errors which occur after initialization
  are non-fatal.

  Note: as soon as OpenVPN has daemonized, it can not ask for usernames,
  passwords, or key pass phrases anymore. This has certain consequences,
  namely that using a password-protected private key will fail unless the
  ``--askpass`` option is used to tell OpenVPN to ask for the pass phrase.

  Further, using ``--daemon`` together with ``--auth-user-pass`` (entered
  on console) and ``--auth-nocache`` will fail as soon as key
  renegotiation (and reauthentication) occurs.

--disable-occ
  **DEPRECATED** Disable "options consistency check" (OCC) in configurations
  that do not use TLS.

  Don't output a warning message if option inconsistencies are detected
  between peers. An example of an option inconsistency would be where one
  peer uses ``--dev tun`` while the other peer uses ``--dev tap``.

  Use of this option is discouraged, but is provided as a temporary fix in
  situations where a recent version of OpenVPN must connect to an old
  version.

--engine engine-name
  Enable OpenSSL hardware-based crypto engine functionality.

  Valid syntaxes::

    engine
    engine engine-name

  If ``engine-name`` is specified, use a specific crypto engine. Use the
  ``--show-engines`` standalone option to list the crypto engines which
  are supported by OpenSSL.

--group group
  Similar to the ``--user`` option, this option changes the group ID of
  the OpenVPN process to ``group`` after initialization.

--ignore-unknown-option args
  Valid syntax:
  ::

     ignore-unknown-option opt1 opt2 opt3 ... optN

  When one of options ``opt1 ... optN`` is encountered in the configuration
  file the configuration file parsing does not fail if this OpenVPN version
  does not support the option. Multiple ``--ignore-unknown-option`` options
  can be given to support a larger number of options to ignore.

  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.

  ``--ignore-unknown-option`` is available since OpenVPN 2.3.3.

--iproute cmd
  Set alternate command to execute instead of default ``iproute2`` command.
  May be used in order to execute OpenVPN in unprivileged environment.

--keying-material-exporter args
  Save Exported Keying Material [RFC5705] of ``len`` bytes (must be between 16
  and 4095 bytes) using ``label`` in environment
  (:code:`exported_keying_material`) for use by plugins in
  :code:`OPENVPN_PLUGIN_TLS_FINAL` callback.

  Valid syntax:
  ::

    keying-material-exporter label len

  Note that exporter ``labels`` have the potential to collide with existing
  PRF labels. In order to prevent this, labels *MUST* begin with
  :code:`EXPORTER`.

--mlock
  Disable paging by calling the POSIX mlockall function. Requires that
  OpenVPN be initially run as root (though OpenVPN can subsequently
  downgrade its UID using the ``--user`` option).

  Using this option ensures that key material and tunnel data are never
  written to disk due to virtual memory paging operations which occur
  under most modern operating systems. It ensures that even if an attacker
  was able to crack the box running OpenVPN, he would not be able to scan
  the system swap file to recover previously used ephemeral keys, which
  are used for a period of time governed by the ``--reneg`` options (see
  below), then are discarded.

  The downside of using ``--mlock`` is that it will reduce the amount of
  physical memory available to other applications.

  The limit on how much memory can be locked and how that limit
  is enforced are OS-dependent. On Linux the default limit that an
  unprivileged process may lock (RLIMIT_MEMLOCK) is low, and if
  privileges are dropped later, future memory allocations will very
  likely fail. The limit can be increased using ulimit or systemd
  directives depending on how OpenVPN is started.

  If the platform has the getrlimit(2) system call, OpenVPN will check
  for the amount of mlock-able memory before calling mlockall(2), and
  tries to increase the limit to 100 MB if less than this is configured.
  100 Mb is somewhat arbitrary - it is enough for a moderately-sized
  OpenVPN deployment, but the memory usage might go beyond that if the
  number of concurrent clients is high.

--nice n
  Change process priority after initialization (``n`` greater than 0 is
  lower priority, ``n`` less than zero is higher priority).

--providers providers
  Load the list of (OpenSSL) providers. This is mainly useful for using an
  external provider for key management like tpm2-openssl or to load the
  legacy provider with

  ::

      --providers legacy default

  Behaviour of changing this option between :code:`SIGHUP` might not be well behaving.
  If you need to change/add/remove this option, fully restart OpenVPN.

--remap-usr1 signal
  Control whether internally or externally generated :code:`SIGUSR1` signals
  are remapped to :code:`SIGHUP` (restart without persisting state) or
  :code:`SIGTERM` (exit).

  ``signal`` can be set to :code:`SIGHUP` or :code:`SIGTERM`. By default,
  no remapping occurs.

--script-security level
  This directive offers policy-level control over OpenVPN's usage of
  external programs and scripts. Lower ``level`` values are more
  restrictive, higher values are more permissive. Settings for ``level``:

  :code:`0`
      Strictly no calling of external programs.

  :code:`1`
      (Default) Only call built-in executables such as ifconfig,
      ip, route, or netsh.

  :code:`2`
      Allow calling of built-in executables and user-defined
      scripts.

  :code:`3`
      Allow passwords to be passed to scripts via environmental
      variables (potentially unsafe).

  OpenVPN releases before v2.3 also supported a ``method`` flag which
  indicated how OpenVPN should call external commands and scripts. This
  could be either :code:`execve` or :code:`system`. As of OpenVPN 2.3, this
  flag is no longer accepted.

  Some directives such as ``--up`` allow options to be passed to the
  external script. In these cases make sure the script name does not
  contain any spaces or the configuration parser will choke because it
  can't determine where the script name ends and script options start.

  On Windoes it is a strict requirement to have the full path to the script
  interpreter when running non-executables files. This is not needed for
  executable files, such as .exe, .com, .bat or .cmd files. For example,
  if you have a Visual Basic script, you must use this syntax::

     --up 'C:\\Windows\\System32\\wscript.exe C:\\Program\ Files\\OpenVPN\\config\\my-up-script.vbs'

  Please note the single quote marks and the escaping of the backslashes
  (``\\``) and the space character.

--setcon context
  Apply SELinux ``context`` after initialization. This essentially
  provides the ability to restrict OpenVPN's rights to only network I/O
  operations, thanks to SELinux. This goes further than ``--user`` and
  ``--chroot`` in that those two, while being great security features,
  unfortunately do not protect against privilege escalation by
  exploitation of a vulnerable system call. You can of course combine all
  three, but please note that since setcon requires access to /proc you
  will have to provide it inside the chroot directory (e.g. with mount
  --bind).

  Since the setcon operation is delayed until after initialization,
  OpenVPN can be restricted to just network-related system calls, whereas
  by applying the context before startup (such as the OpenVPN one provided
  in the SELinux Reference Policies) you will have to allow many things
  required only during initialization.

  Like with chroot, complications can result when scripts or restarts are
  executed after the setcon operation, which is why you should really
  consider using the ``--persist-tun`` option.

--status args
  Write operational status to ``file`` every ``n`` seconds. ``n`` defaults
  to :code:`60` if not specified.

  Valid syntaxes:
  ::

    status file
    status file n

  Status can also be written to the syslog by sending a :code:`SIGUSR2`
  signal.

  With multi-client capability enabled on a server, the status file
  includes a list of clients and a routing table. The output format can be
  controlled by the ``--status-version`` option in that case.

  For clients or instances running in point-to-point mode, it will contain
  the traffic statistics.

--status-version n
  Set the status file format version number to ``n``.

  This only affects the status file on servers with multi-client
  capability enabled.  Valid status version values:

  :code:`1`
      Traditional format (default). The client list contains the
      following fields comma-separated: Common Name, Real Address, Bytes
      Received, Bytes Sent, Connected Since.

  :code:`2`
      A more reliable format for external processing. Compared to
      version :code:`1`, the client list contains some additional fields:
      Virtual Address, Virtual IPv6 Address, Username, Client ID, Peer ID,
      Data Channel Cipher. Future versions may extend the number of fields.

  :code:`3`
      Identical to :code:`2`, but fields are tab-separated.

--test-crypto
  Do a self-test of OpenVPN's crypto options by encrypting and decrypting
  test packets using the data channel encryption options specified above.
  This option does not require a peer to function, and therefore can be
  specified without ``--dev`` or ``--remote``.

  The typical usage of ``--test-crypto`` would be something like this:
  ::

     openvpn --test-crypto

  or

  ::

     openvpn --test-crypto --verb 9

  This option is very useful to test OpenVPN after it has been ported to a
  new platform, or to isolate problems in the compiler, OpenSSL crypto
  library, or OpenVPN's crypto code. Since it is a self-test mode,
  problems with encryption and authentication can be debugged
  independently of network and tunnel issues.

  Older versions of OpenVPN used the ``--secret`` argument to specify a
  static key for this test. Newer version generate a random key for the
  test.

--tmp-dir dir
  Specify a directory ``dir`` for temporary files instead of the default
  :code:`TMPDIR` (or "/tmp" if unset). Note that it must be writable by the main
  process after it has dropped root privileges.

  This directory will be used to communicate with scripts and plugins:

  * ``--client-connect`` scripts and :code:`OPENVPN_PLUGIN_CLIENT_CONNECT`
    plug-in hook to dynamically generate client-specific configuration
    :code:`client_connect_config_file` and return success/failure via
    :code:`client_connect_deferred_file` when using deferred client connect
    method

  * :code:`OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY` plug-in hooks returns
    success/failure via :code:`auth_control_file` when using deferred auth
    method and pending authentication via :code:`auth_pending_file`.

--user user
  Change the user ID of the OpenVPN process to ``user`` after
  initialization, dropping privileges in the process. This option is
  useful to protect the system in the event that some hostile party was
  able to gain control of an OpenVPN session. Though OpenVPN's security
  features make this unlikely, it is provided as a second line of defense.

  By setting ``user`` to an unprivileged user dedicated to run openvpn,
  the hostile party would be limited in what damage they could cause. Of
  course once you take away privileges, you cannot return them to an
  OpenVPN session. This means, for example, that if you want to reset an
  OpenVPN daemon with a :code:`SIGUSR1` signal (for example in response to
  a DHCP reset), you should make use of one or more of the ``--persist``
  options to ensure that OpenVPN doesn't need to execute any privileged
  operations in order to restart (such as re-reading key files or running
  ``ifconfig`` on the TUN device).

  NOTE: Previous versions of openvpn used :code:`nobody` as the example
  unpriviledged user. It is not recommended to actually use that user
  since it is usually used by other system services already. Always
  create a dedicated user for openvpn.

--writepid file
  Write OpenVPN's main process ID to ``file``.

---

## File: doc/man-sections/inline-files.rst

INLINE FILE SUPPORT
===================

OpenVPN allows including files in the main configuration for the ``--ca``,
``--cert``, ``--dh``, ``--extra-certs``, ``--key``, ``--pkcs12``,
``--crl-verify``, ``--http-proxy-user-pass``, ``--tls-auth``,
``--auth-gen-token-secret``, ``--peer-fingerprint``, ``--tls-crypt``,
``--tls-crypt-v2``, ``--verify-hash`` and ``--auth-user-pass`` options.

Each inline file started by the line ``<option>`` and ended by the line
``</option>``

Here is an example of an inline file usage

::

    <cert>
    -----BEGIN CERTIFICATE-----
    [...]
    -----END CERTIFICATE-----
    </cert>

When using the inline file feature with ``--pkcs12`` the inline file has
to be base64 encoded. Encoding of a .p12 file into base64 can be done
for example with OpenSSL by running :code:`openssl base64 -in input.p12`