summaryrefslogtreecommitdiff
path: root/doc/man-sections/client-options.rst
diff options
context:
space:
mode:
Diffstat (limited to 'doc/man-sections/client-options.rst')
-rw-r--r--doc/man-sections/client-options.rst353
1 files changed, 353 insertions, 0 deletions
diff --git a/doc/man-sections/client-options.rst b/doc/man-sections/client-options.rst
new file mode 100644
index 0000000..ec1e3b1
--- /dev/null
+++ b/doc/man-sections/client-options.rst
@@ -0,0 +1,353 @@
+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-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. If the password line is missing, OpenVPN will prompt for one.
+
+ If ``up`` is omitted, username/password will be prompted from the
+ console.
+
+ 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.
+
+ Examples:
+ ::
+
+ client-nat snat 192.168.0.0/255.255.0.0
+ client-nat dnat 10.64.0.0/255.255.0.0
+
+ ``network/netmask`` (for example :code:`192.168.0.0/255.255.0.0`) defines
+ the local view of a resource from the client perspective, while
+ ``alias/netmask`` (for example :code:`10.64.0.0/255.255.0.0`) defines the
+ remote view from the server perspective.
+
+ 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 n
+ Wait ``n`` seconds between connection attempts (default :code:`5`).
+ Repeated reconnection attempts are slowed down after 5 retries per
+ remote by doubling the wait time after each unsuccessful attempt. An
+ optional argument ``max`` specifies the maximum value of wait time in
+ seconds at which it gets capped (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``.
+
+--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.
+
+ 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.
+
+ 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.
+
+--proto-force p
+ When iterating through connection profiles, only consider profiles using
+ protocol ``p`` (:code:`tcp` \| :code:`udp`).
+
+--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`.
+
+--remote args
+ Remote host name or IP address. It supports two additional optional
+ arguments: ``port`` and ``proto``. On the client, multiple ``--remote``
+ options may be specified for redundancy, each referring to a different
+ OpenVPN server. Specifying multiple ``--remote`` options for this
+ purpose is a special case of the more general connection-profile
+ feature. See the ``<connection>`` documentation below.
+
+ The OpenVPN client will try to connect to a server at ``host:port`` in
+ the order specified by the list of ``--remote`` options.
+
+ Examples:
+ ::
+
+ remote server.example.net
+ remote server.example.net 1194
+ remote server.example.net tcp
+
+ ``proto`` indicates the protocol to use when connecting with the remote,
+ and may be :code:`tcp` or :code:`udp`.
+
+ For forcing IPv4 or IPv6 connection suffix tcp or udp with 4/6 like
+ udp4/udp6/tcp4/tcp6.
+
+ 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.
+
+ Note that since UDP is connectionless, connection failure is defined by
+ the ``--ping`` and ``--ping-restart`` options.
+
+ Note the following corner case: 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 "infinite" to retry indefinitely.
+
+ By default, ``--resolv-retry infinite`` is enabled. You can disable by
+ setting n=0.
+
+--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 120s. This timeout includes proxy and TCP connect timeouts.
+
+--static-challenge args
+ Enable static challenge/response protocol
+
+ Valid syntax:
+ ::
+
+ static-challenge text echo
+
+ 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`.
+
+ See management-notes.txt in the OpenVPN distribution for a description of
+ the OpenVPN challenge/response protocol.
+
+.. include:: proxy-options.rst