New upstream version 2.5~beta1upstream/2.5_beta1

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