diff options
Diffstat (limited to 'doc/man-sections/client-options.rst')
| -rw-r--r-- | doc/man-sections/client-options.rst | 369 |
1 files changed, 369 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..c5b7ad9 --- /dev/null +++ b/doc/man-sections/client-options.rst @@ -0,0 +1,369 @@ +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 to override + the username used by the client when reauthenticating with the ``auth-token``. + It also allows 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. 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, 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 "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 |