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