path: root/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 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