@@ -49,6 +49,7 @@ version.sh

 msvc-env-local.bat

 config-msvc-local.h

 config-msvc-version.h

+doc/openvpn.8

 doc/openvpn.8.html

 /doc/doxygen/html/

 /doc/doxygen/latex/

@@ -227,7 +227,6 @@ ENVIRONMENT for ./configure:

   ROUTE       full path to route utility

   IPROUTE     full path to ip utility

   NETSTAT     path to netstat utility

-  MAN2HTML    path to man2html utility

   GIT         path to git utility

   SYSTEMD_ASK_PASSWORD

               path to systemd-ask-password utility

@@ -235,6 +234,8 @@ ENVIRONMENT for ./configure:

               Path of systemd unit directory [default=LIBDIR/systemd/system]

   TMPFILES_DIR

               Path of tmpfiles directory [default=LIBDIR/tmpfiles.d]

+  RST2MAN     Path to rst2man utility

+  RST2HTML    Path to rst2html utility

 ENVIRONMENT variables adjusting parameters related to dependencies

@@ -354,7 +354,6 @@ AC_ARG_VAR([IFCONFIG], [full path to ipconfig utility])

 AC_ARG_VAR([ROUTE], [full path to route utility])

 AC_ARG_VAR([IPROUTE], [full path to ip utility])

 AC_ARG_VAR([NETSTAT], [path to netstat utility]) # tests

-AC_ARG_VAR([MAN2HTML], [path to man2html utility])

 AC_ARG_VAR([GIT], [path to git utility])

 AC_ARG_VAR([SYSTEMD_ASK_PASSWORD], [path to systemd-ask-password utility])

 AC_ARG_VAR([SYSTEMD_UNIT_DIR], [Path of systemd unit directory @<:@default=LIBDIR/systemd/system@:>@])

@@ -364,13 +363,21 @@ AC_PATH_PROGS([ROUTE], [route],, [$PATH:/usr/local/sbin:/usr/sbin:/sbin])

 AC_PATH_PROGS([IPROUTE], [ip],, [$PATH:/usr/local/sbin:/usr/sbin:/sbin])

 AC_PATH_PROGS([SYSTEMD_ASK_PASSWORD], [systemd-ask-password],, [$PATH:/usr/local/bin:/usr/bin:/bin])

 AC_CHECK_PROGS([NETSTAT], [netstat], [netstat], [$PATH:/usr/local/sbin:/usr/sbin:/sbin:/etc]) # tests

-AC_CHECK_PROGS([MAN2HTML], [man2html])

 AC_CHECK_PROGS([GIT], [git]) # optional

 AC_DEFINE_UNQUOTED([IFCONFIG_PATH], ["$IFCONFIG"], [Path to ifconfig tool])

 AC_DEFINE_UNQUOTED([IPROUTE_PATH], ["$IPROUTE"], [Path to iproute tool])

 AC_DEFINE_UNQUOTED([ROUTE_PATH], ["$ROUTE"], [Path to route tool])

 AC_DEFINE_UNQUOTED([SYSTEMD_ASK_PASSWORD_PATH], ["$SYSTEMD_ASK_PASSWORD"], [Path to systemd-ask-password tool])

+#

+#  man page generation - based on python-docutils

+#

+AC_ARG_VAR([RST2MAN], [path to rst2man utility])

+AC_ARG_VAR([RST2HTML], [path to rst2html utility])

+AC_CHECK_PROGS([RST2MAN], [rst2man])

+AC_CHECK_PROGS([RST2HTML], [rst2html])

+AM_CONDITIONAL([HAVE_PYDOCUTILS], [test "${RST2MAN}" -a "${RST2HTML}"])

+

 # Set -std=c99 unless user already specified a -std=

 case "${CFLAGS}" in

   *-std=*) ;;

@@ -1315,10 +1322,6 @@ if test "${enable_werror}" = "yes"; then

 	CFLAGS="${CFLAGS} -Werror"

 fi

-if test "${WIN32}" = "yes"; then

-	test -z "${MAN2HTML}" && AC_MSG_ERROR([man2html is required for win32])

-fi

-

 if test "${enable_plugin_auth_pam}" = "yes"; then

 	PLUGIN_AUTH_PAM_CFLAGS="${LIBPAM_CFLAGS}"

 	if test "${enable_pam_dlopen}" = "yes"; then

@@ -5,29 +5,69 @@

 #             packet encryption, packet authentication, and

 #             packet compression.

 #

-#  Copyright (C) 2002-2018 OpenVPN Inc <sales@openvpn.net>

+#  Copyright (C) 2002-2020 OpenVPN Inc <sales@openvpn.net>

 #  Copyright (C) 2006-2012 Alon Bar-Lev <alon.barlev@gmail.com>

 #

 MAINTAINERCLEANFILES = \

 	$(srcdir)/Makefile.in

-CLEANFILES = openvpn.8.html

-

 SUBDIRS = doxygen

 dist_doc_DATA = \

-	management-notes.txt

+	management-notes.txt openvpn.8.rst \

+	man-sections/advanced-options.rst \

+	man-sections/client-options.rst \

+	man-sections/connection-profiles.rst \

+	man-sections/encryption-options.rst \

+	man-sections/examples.rst \

+	man-sections/generic-options.rst \

+	man-sections/inline-files.rst \

+	man-sections/link-options.rst \

+	man-sections/log-options.rst \

+	man-sections/management-options.rst \

+	man-sections/network-config.rst \

+	man-sections/pkcs11-options.rst \

+	man-sections/plugin-options.rst \

+	man-sections/protocol-options.rst \

+	man-sections/proxy-options.rst \

+	man-sections/signals.rst \

+	man-sections/script-options.rst \

+	man-sections/server-options.rst \

+	man-sections/tls-options.rst \

+	man-sections/unsupported-options.rst \

+	man-sections/vpn-network-options.rst \

+	man-sections/windows-options.rst

 dist_noinst_DATA = \

 	README.plugins interactive-service-notes.rst

-if WIN32

+openvpn.8 :

+if HAVE_PYDOCUTILS

+	$(RST2MAN) $(srcdir)/$@.rst > $@

+else

+	@echo "Missing python-docutils - skipping man page generation"

+endif

+

+openvpn.8.html:

+if HAVE_PYDOCUTILS

+	$(RST2HTML) $(srcdir)/openvpn.8.rst > $@

+else

+	@echo "Missing python-docutils - skipping man/html page generation"

+endif

+

+if HAVE_PYDOCUTILS

 dist_noinst_DATA += openvpn.8

-nodist_html_DATA = openvpn.8.html

-openvpn.8.html: $(srcdir)/openvpn.8

-	$(MAN2HTML) < $(srcdir)/openvpn.8 > openvpn.8.html

+dist_html_DATA = openvpn.8.html

+

+# Failsafe - do not delete these files unless we can recreate them

+CLEANFILES = \

+	 openvpn.8 openvpn.8.html

+

+if WIN32

 else

 dist_man_MANS = openvpn.8

 endif

+endif

+dist-hook : openvpn.8 openvpn.8.html

new file mode 100644

@@ -0,0 +1,22 @@

+

+man page documentation

+======================

+

+The man page content maintained in the openvpn.8.rst file and proper man and

+the html version of the man page are generated using python-docutils.  Both

+the man page and html file are generated during 'make dist' or 'make distcheck'

+and should be distributed inside the tarball by default.

+

+Users compiling OpenVPN from the tarball should not need to regenerate the

+man/html files unless the source file needs to be modified.

+

+Further information:

+

+* Python docutils project:

+  https://docutils.sourceforge.io/

+

+* Quickstart on .rst

+  https://docutils.sourceforge.io/docs/user/rst/quickstart.html

+

+* reStructuredText Markup Specifictaion (.rst)

+  https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html

new file mode 100644

@@ -0,0 +1,106 @@

+Standalone Debug Options

+------------------------

+

+--show-gateway args

+  (Standalone) Show current IPv4 and IPv6 default gateway and interface

+  towards the gateway (if the protocol in question is enabled).

+

+  Valid syntax:

+  ::

+

+     --show-gateway

+     --show-gateway IPv6-target

+

+  If an IPv6 target address is passed as argument, the IPv6 route for this

+  host is reported.

+

+

+Advanced Expert Options

+-----------------------

+These are options only required when special tweaking is needed, often

+used when debugging or testing out special usage scenarios.

+

+--hash-size args

+  Set the size of the real address hash table to ``r`` and the virtual

+  address table to ``v``.

+

+  Valid syntax:

+  ::

+

+     hash-size r v

+

+  By default, both tables are sized at 256 buckets.

+

+--bcast-buffers n

+  Allocate ``n`` buffers for broadcast datagrams (default :code:`256`).

+

+--persist-local-ip

+  Preserve initially resolved local IP address and port number across

+  ``SIGUSR1`` or ``--ping-restart`` restarts.

+

+--persist-remote-ip

+  Preserve most recently authenticated remote IP address and port number

+  across :code:`SIGUSR1` or ``--ping-restart`` restarts.

+

+--prng args

+  *(Advanced)* Change the PRNG (Pseudo-random number generator) parameters

+

+  Valid syntaxes:

+  ::

+

+     prng alg

+     prng alg nsl

+

+  Changes the PRNG to use digest algorithm **alg** (default :code:`sha1`),

+  and set ``nsl`` (default :code:`16`) to the size in bytes of the nonce

+  secret length (between 16 and 64).

+

+  Set ``alg`` to :code:`none` to disable the PRNG and use the OpenSSL

+  RAND\_bytes function instead for all of OpenVPN's pseudo-random number

+  needs.

+

+--rcvbuf size

+  Set the TCP/UDP socket receive buffer size. Defaults to operating system

+  default.

+

+--shaper n

+  Limit bandwidth of outgoing tunnel data to ``n`` bytes per second on the

+  TCP/UDP port. Note that this will only work if mode is set to

+  :code:`p2p`.  If you want to limit the bandwidth in both directions, use

+  this option on both peers.

+

+  OpenVPN uses the following algorithm to implement traffic shaping: Given

+  a shaper rate of ``n`` bytes per second, after a datagram write of ``b``

+  bytes is queued on the TCP/UDP port, wait a minimum of ``(b / n)``

+  seconds before queuing the next write.

+

+  It should be noted that OpenVPN supports multiple tunnels between the

+  same two peers, allowing you to construct full-speed and reduced

+  bandwidth tunnels at the same time, routing low-priority data such as

+  off-site backups over the reduced bandwidth tunnel, and other data over

+  the full-speed tunnel.

+

+  Also note that for low bandwidth tunnels (under 1000 bytes per second),

+  you should probably use lower MTU values as well (see above), otherwise

+  the packet latency will grow so large as to trigger timeouts in the TLS

+  layer and TCP connections running over the tunnel.

+

+  OpenVPN allows ``n`` to be between 100 bytes/sec and 100 Mbytes/sec.

+

+--sndbuf size

+  Set the TCP/UDP socket send buffer size. Defaults to operating system

+  default.

+

+--tcp-queue-limit n

+  Maximum number of output packets queued before TCP (default :code:`64`).

+

+  When OpenVPN is tunneling data from a TUN/TAP device to a remote client

+  over a TCP connection, it is possible that the TUN/TAP device might

+  produce data at a faster rate than the TCP connection can support. When

+  the number of output packets queued before sending to the TCP socket

+  reaches this limit for a given client connection, OpenVPN will start to

+  drop outgoing packets directed at this client.

+

+--txqueuelen n

+  *(Linux only)* Set the TX queue length on the TUN/TAP interface.

+  Currently defaults to 100.

new file mode 100644

@@ -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

new file mode 100644

@@ -0,0 +1,75 @@

+CONNECTION PROFILES

+===================

+

+Client configuration files may contain multiple remote servers which

+it will attempt to connect against.  But there are some configuration

+options which are related to specific ``--remote`` options.  For these

+use cases, connection profiles are the solution.

+

+By enacpulating the ``--remote`` option and related options within

+``<connection>`` and ``</connection>``, these options are handled as a

+group.

+

+An OpenVPN client will try each connection profile sequentially until it

+achieves a successful connection.

+

+``--remote-random`` can be used to initially "scramble" the connection

+list.

+

+Here is an example of connection profile usage:

+::

+

+   client

+   dev tun

+

+   <connection>

+   remote 198.19.34.56 1194 udp

+   </connection>

+

+   <connection>

+   remote 198.19.34.56 443 tcp

+   </connection>

+

+   <connection>

+   remote 198.19.34.56 443 tcp

+   http-proxy 192.168.0.8 8080

+   </connection>

+

+   <connection>

+   remote 198.19.36.99 443 tcp

+   http-proxy 192.168.0.8 8080

+   </connection>

+

+   persist-key

+   persist-tun

+   pkcs12 client.p12

+   remote-cert-tls server

+   verb 3

+

+First we try to connect to a server at 198.19.34.56:1194 using UDP. If

+that fails, we then try to connect to 198.19.34.56:443 using TCP. If

+that also fails, then try connecting through an HTTP proxy at

+192.168.0.8:8080 to 198.19.34.56:443 using TCP. Finally, try to connect

+through the same proxy to a server at 198.19.36.99:443 using TCP.

+

+The following OpenVPN options may be used inside of a ``<connection>``

+block:

+

+``bind``, ``connect-retry``, ``connect-retry-max``, ``connect-timeout``,

+``explicit-exit-notify``, ``float``, ``fragment``, ``http-proxy``,

+``http-proxy-option``, ``key-direction``, ``link-mtu``, ``local``,

+``lport``, ``mssfix``, ``mtu-disc``, ``nobind``, ``port``, ``proto``,

+``remote``, ``rport``, ``socks-proxy``, ``tls-auth``, ``tls-crypt``,

+``tun-mtu and``, ``tun-mtu-extra``.

+

+A defaulting mechanism exists for specifying options to apply to all

+``<connection>`` profiles. If any of the above options (with the

+exception of ``remote`` ) appear outside of a ``<connection>`` block,

+but in a configuration file which has one or more ``<connection>``

+blocks, the option setting will be used as a default for

+``<connection>`` blocks which follow it in the configuration file.

+

+For example, suppose the ``nobind`` option were placed in the sample

+configuration file above, near the top of the file, before the first

+``<connection>`` block. The effect would be as if ``nobind`` were

+declared in all ``<connection>`` blocks below it.

new file mode 100644

@@ -0,0 +1,135 @@

+Encryption Options

+==================

+

+SSL Library information

+-----------------------

+

+--show-ciphers

+  (Standalone) Show all cipher algorithms to use with the ``--cipher``

+  option.

+

+--show-digests

+  (Standalone) Show all message digest algorithms to use with the

+  ``--auth`` option.

+

+--show-tls

+  (Standalone) Show all TLS ciphers supported by the crypto library.

+  OpenVPN uses TLS to secure the control channel, over which the keys that

+  are used to protect the actual VPN traffic are exchanged. The TLS

+  ciphers will be sorted from highest preference (most secure) to lowest.

+

+  Be aware that whether a cipher suite in this list can actually work

+  depends on the specific setup of both peers (e.g. both peers must

+  support the cipher, and an ECDSA cipher suite will not work if you are

+  using an RSA certificate, etc.).

+

+--show-engines

+  (Standalone) Show currently available hardware-based crypto acceleration

+  engines supported by the OpenSSL library.

+

+--show-curves

+  (Standalone) Show all available elliptic curves to use with the

+  ``--ecdh-curve`` option.

+

+Generating key material

+-----------------------

+

+--genkey args

+  (Standalone) Generate a key to be used of the type keytype. if keyfile

+  is left out or empty the key will be output on stdout. See the following

+  sections for the different keytypes.

+

+  Valid syntax:

+  ::

+

+     --genkey keytype keyfile

+

+  Valid keytype arguments are:

+

+  :code:`secret`                Standard OpenVPN shared secret keys

+

+  :code:`tls-crypt`             Alias for :code:`secret`

+

+  :code:`tls-auth`              Alias for :code:`secret`

+

+  :code:`auth-token`            Key used for ``--auth-gen-token-key``

+

+  :code:`tls-crypt-v2-server`   TLS Crypt v2 server key

+

+  :code:`tls-crypt-v2-client`   TLS Crypt v2 client key

+

+

+  Examples:

+  ::

+

+     $ openvpn --genkey secret shared.key

+     $ openvpn --genkey tls-crypt shared.key

+     $ openvpn --genkey tls-auth shared.key

+     $ openvpn --genkey tls-crypt-v2-server v2crypt-server.key

+     $ openvpn --tls-crypt-v2 v2crypt-server.key --genkey tls-crypt-v2-client v2crypt-client-1.key

+

+  * Generating *Shared Secret Keys*

+    Generate a shared secret, for use with the ``--secret``, ``--tls-auth``

+    or ``--tls-crypt`` options.

+

+    Syntax:

+    ::

+

+       $ openvpn --genkey secret|tls-crypt|tls-auth keyfile

+

+    The key is saved in ``keyfile``. All three variants (``--secret``,

+    ``tls-crypt`` and ``tls-auth``) generate the same type of key. The

+    aliases are added for convenience.

+

+    If using this for ``--secret``, this file must be shared with the peer

+    over a pre-existing secure channel such as ``scp``\(1).

+

+  * Generating *TLS Crypt v2 Server key*

+    Generate a ``--tls-crypt-v2`` key to be used by an OpenVPN server.

+    The key is stored in ``keyfile``.

+

+    Syntax:

+    ::

+

+       --genkey tls-crypt-v2-server keyfile

+

+  * Generating *TLS Crypt v2 Client key*

+    Generate a --tls-crypt-v2 key to be used by OpenVPN clients.  The

+    key is stored in ``keyfile``.

+

+    Syntax

+    ::

+

+       --genkey tls-crypt-v2-client keyfile [metadata]

+

+    If supplied, include the supplied ``metadata`` in the wrapped client

+    key. This metadata must be supplied in base64-encoded form. The

+    metadata must be at most 735 bytes long (980 bytes in base64).

+

+    If no metadata is supplied, OpenVPN will use a 64-bit unix timestamp

+    representing the current time in UTC, encoded in network order, as

+    metadata for the generated key.

+

+    A tls-crypt-v2 client key is wrapped using a server key. To generate a

+    client key, the user must therefore supply the server key using the

+    ``--tls-crypt-v2`` option.

+

+    Servers can use ``--tls-crypt-v2-verify`` to specify a metadata

+    verification command.

+

+  * Generate *Authentication Token key*

+    Generate a new secret that can be used with **--auth-gen-token-secret**

+

+    Syntax:

+    ::

+

+       --genkey auth-token [keyfile]

+

+    *Note:*

+       This file should be kept secret to the server as anyone that has

+       access to this file will be able to generate auth tokens that the

+       OpenVPN server will accept as valid.

+

+.. include:: renegotiation.rst

+.. include:: tls-options.rst

+.. include:: pkcs11-options.rst

new file mode 100644

@@ -0,0 +1,240 @@

+EXAMPLES

+========

+

+Prior to running these examples, you should have OpenVPN installed on