doc/man: convert openvpn.8 to split-up .rst files

To avoid keeping around a full-size openvpn.rst file which is never
needed but will take space in the repo forever, patches 01...04
of the big documentation overhaul projects were squashed togehter,
keeping the individual commit logs and URL references below.

Signed-off-by: Gert Doering <gert@greenie.muc.de>

* This is a combination of 4 commits.
* This is the 1st commit message:

doc/man: Add an .rst formatted version of the man page

This is the first step to move away from a manually editing g/nroff
encoded man page.

Some modifications was needed to ensure formatting was consistent and
rendered reasonably okay in GitHub and that the generated man page
(using rst2man) is looking as a proper man page.  Unsupported options
has also been moved into its own section.  HTML rendering directly
using rst2html has also been used to validate the conversion.

The rst2man and rst2html utilities comes from the python-docutils
project: https://docutils.sourceforge.io/

Signed-off-by: David Sommerseth <davids@openvpn.net>
Acked-by: Gert Doering <gert@greenie.muc.de>
Message-Id: <20200716225338.611-2-davids@openvpn.net>
URL: https://sourceforge.net/p/openvpn/mailman/message/37063370/
Signed-off-by: Gert Doering <gert@greenie.muc.de>

* This is the commit message #2:

doc/man: Replace old man page with generated man page

The doc/openvpn.8 and doc/openvpn.8.html files are now being removed
from the git tree, as it will be generated from the doc/openvpn.8.rst
file using python-docutils.

An additional dist-hook is added so these files are generated
automatically when source tarballs are generated for releases.  This
means users compiling directly from the source tarball will not need
python-docutils installed.

Signed-off-by: David Sommerseth <davids@openvpn.net>
Acked-by: Gert Doering <gert@greenie.muc.de>
Message-Id: <20200716225338.611-3-davids@openvpn.net>
URL: https://sourceforge.net/p/openvpn/mailman/message/37063373/
Signed-off-by: Gert Doering <gert@greenie.muc.de>

* This is the commit message #3:

doc/man: Split up and reorganize main man page

The openvpn.8.rst file is quite long and hard to edit, as it covers
several hundred options.  Some options were even documented multiple
places.  The example has also received some attention, cleaning up
old and outdated infomration.

In this commit the main man page is split up into multiple sections
and options are sorted into each of the corresponding section.
Inside each category, each option is for now sorted alphabetically.
The main openvpn.8.rst file is currently kept unchanged and will be
handled in the next commit.

Many language improvements contributed by Richard Bonhomme has also
been incorproated.

Signed-off-by: David Sommerseth <davids@openvpn.net>
Acked-by: Gert Doering <gert@greenie.muc.de>
Message-Id: <20200716225338.611-4-davids@openvpn.net>
URL: https://sourceforge.net/p/openvpn/mailman/message/37063376/
Signed-off-by: Gert Doering <gert@greenie.muc.de>

* This is the commit message #4:

doc/man: Complete openvpn.8.rst splitting

This rebuilds the openvpn.8.rst content by using the text which was
split out in the previous commit by using RST ..include statements.

Signed-off-by: David Sommerseth <davids@openvpn.net>
Acked-by: Gert Doering <gert@greenie.muc.de>
Message-Id: <20200716225338.611-5-davids@openvpn.net>
URL: https://sourceforge.net/p/openvpn/mailman/message/37063377/
Signed-off-by: Gert Doering <gert@greenie.muc.de>

1 files changed, 768 insertions, 0 deletions

diff --git a/doc/man-sections/server-options.rst b/doc/man-sections/server-options.rst
new file mode 100644
index 0000000..c24aec0
--- /dev/null
+++ b/doc/man-sections/server-options.rst
@@ -0,0 +1,768 @@
+Server Options
+--------------
+Starting with OpenVPN 2.0, a multi-client TCP/UDP server mode is
+supported, and can be enabled with the ``--mode server`` option. In
+server mode, OpenVPN will listen on a single port for incoming client
+connections. All client connections will be routed through a single tun
+or tap interface. This mode is designed for scalability and should be
+able to support hundreds or even thousands of clients on sufficiently
+fast hardware. SSL/TLS authentication must be used in this mode.
+
+--auth-gen-token args
+  Returns an authentication token to successfully authenticated clients.
+
+  Valid syntax:
+  ::
+
+     auth-gen-token [lifetime] [external-auth]
+
+  After successful user/password authentication, the OpenVPN server will
+  with this option generate a temporary authentication token and push that
+  to the client. On the following renegotiations, the OpenVPN client will pass
+  this token instead of the users password. On the server side the server
+  will do the token authentication internally and it will NOT do any
+  additional authentications against configured external user/password
+  authentication mechanisms.
+
+  The tokens implemented by this mechanism include an initial timestamp and
+  a renew timestamp and are secured by HMAC.
+
+  The ``lifetime`` argument defines how long the generated token is valid.
+  The lifetime is defined in seconds. If lifetime is not set or it is set
+  to :code:`0`, the token will never expire.
+
+  The token will expire either after the configured ``lifetime`` of the
+  token is reached or after not being renewed for more than 2 \*
+  ``reneg-sec`` seconds. Clients will be sent renewed tokens on every TLS
+  renogiation to keep the client's token updated. This is done to
+  invalidate a token if a client is disconnected for a sufficently long
+  time, while at the same time permitting much longer token lifetimes for
+  active clients.
+
+  This feature is useful for environments which are configured to use One
+  Time Passwords (OTP) as part of the user/password authentications and
+  that authentication mechanism does not implement any auth-token support.
+
+  When the :code:`external-auth` keyword is present the normal
+  authentication method will always be called even if auth-token succeeds.
+  Normally other authentications method are skipped if auth-token
+  verification suceeds or fails.
+
+  This option postpones this decision to the external authentication
+  methods and checks the validity of the account and do other checks.
+
+  In this mode the environment will have a ``session_id`` variable that
+  holds the session id from auth-gen-token. Also an environment variable
+  ``session_state`` is present. This variable indicates whether the
+  auth-token has succeeded or not. It can have the following values:
+
+  :code:`Initial`
+      No token from client.
+
+  :code:`Authenticated`
+      Token is valid and not expired.
+
+  :code:`Expired`
+      Token is valid but has expired.
+
+  :code:`Invalid`
+      Token is invalid (failed HMAC or wrong length)
+
+  :code:`AuthenticatedEmptyUser` / :code:`ExpiredEmptyUser`
+      The token is not valid with the username sent from the client but
+      would be valid (or expired) if we assume an empty username was
+      used instead.  These two cases are a workaround for behaviour in
+      OpenVPN 3.  If this workaround is not needed these two cases should
+      be handled in the same way as :code:`Invalid`.
+
+  **Warning:** Use this feature only if you want your authentication
+  method called on every verification. Since the external authentication
+  is called it needs to also indicate a success or failure of the
+  authentication. It is strongly recommended to return an authentication
+  failure in the case of the Invalid/Expired auth-token with the
+  external-auth option unless the client could authenticate in another
+  acceptable way (e.g. client certificate), otherwise returning success
+  will lead to authentication bypass (as does returning success on a wrong
+  password from a script).
+
+--auth-gen-token-secret file
+  Specifies a file that holds a secret for the HMAC used in
+  ``--auth-gen-token`` If ``file`` is not present OpenVPN will generate a
+  random secret on startup. This file should be used if auth-token should
+  validate after restarting a server or if client should be able to roam
+  between multiple OpenVPN servers with their auth-token.
+
+--auth-user-pass-optional
+  Allow connections by clients that do not specify a username/password.
+  Normally, when ``--auth-user-pass-verify`` or
+  ``--management-client-auth`` are specified (or an authentication plugin
+  module), the OpenVPN server daemon will require connecting clients to
+  specify a username and password. This option makes the submission of a
+  username/password by clients optional, passing the responsibility to the
+  user-defined authentication module/script to accept or deny the client
+  based on other factors (such as the setting of X509 certificate fields).
+  When this option is used, and a connecting client does not submit a
+  username/password, the user-defined authentication module/script will
+  see the username and password as being set to empty strings (""). The
+  authentication module/script MUST have logic to detect this condition
+  and respond accordingly.
+
+--ccd-exclusive
+  Require, as a condition of authentication, that a connecting client has
+  a ``--client-config-dir`` file.
+
+--client-config-dir dir
+  Specify a directory ``dir`` for custom client config files. After a
+  connecting client has been authenticated, OpenVPN will look in this
+  directory for a file having the same name as the client's X509 common
+  name. If a matching file exists, it will be opened and parsed for
+  client-specific configuration options. If no matching file is found,
+  OpenVPN will instead try to open and parse a default file called
+  "DEFAULT", which may be provided but is not required. Note that the
+  configuration files must be readable by the OpenVPN process after it has
+  dropped it's root privileges.
+
+  This file can specify a fixed IP address for a given client using
+  ``--ifconfig-push``, as well as fixed subnets owned by the client using
+  ``--iroute``.
+
+  One of the useful properties of this option is that it allows client
+  configuration files to be conveniently created, edited, or removed while
+  the server is live, without needing to restart the server.
+
+  The following options are legal in a client-specific context: ``--push``,
+  ``--push-reset``, ``--push-remove``, ``--iroute``, ``--ifconfig-push``,
+  ``--vlan-pvid`` and ``--config``.
+
+--client-to-client
+  Because the OpenVPN server mode handles multiple clients through a
+  single tun or tap interface, it is effectively a router. The
+  ``--client-to-client`` flag tells OpenVPN to internally route
+  client-to-client traffic rather than pushing all client-originating
+  traffic to the TUN/TAP interface.
+
+  When this option is used, each client will "see" the other clients which
+  are currently connected. Otherwise, each client will only see the
+  server. Don't use this option if you want to firewall tunnel traffic
+  using custom, per-client rules.
+
+--disable
+  Disable a particular client (based on the common name) from connecting.
+  Don't use this option to disable a client due to key or password
+  compromise. Use a CRL (certificate revocation list) instead (see the
+  ``--crl-verify`` option).
+
+  This option must be associated with a specific client instance, which
+  means that it must be specified either in a client instance config file
+  using ``--client-config-dir`` or dynamically generated using a
+  ``--client-connect`` script.
+
+--connect-freq args
+  Allow a maximum of ``n`` new connections per ``sec`` seconds from
+  clients.
+
+  Valid syntax:
+  ::
+
+     connect-freq n sec
+
+  This is designed to contain DoS attacks which flood the server
+  with connection requests using certificates which will ultimately fail
+  to authenticate.
+
+  This is an imperfect solution however, because in a real DoS scenario,
+  legitimate connections might also be refused.
+
+  For the best protection against DoS attacks in server mode, use
+  ``--proto udp`` and either ``--tls-auth`` or ``--tls-crypt``.
+
+--duplicate-cn
+  Allow multiple clients with the same common name to concurrently
+  connect. In the absence of this option, OpenVPN will disconnect a client
+  instance upon connection of a new client having the same common name.
+
+--ifconfig-pool args
+  Set aside a pool of subnets to be dynamically allocated to connecting
+  clients, similar to a DHCP server.
+
+  Valid syntax:
+  ::
+
+     ifconfig-pool start-IP end-IP [netmask]
+
+  For tun-style tunnels, each client
+  will be given a /30 subnet (for interoperability with Windows clients).
+  For tap-style tunnels, individual addresses will be allocated, and the
+  optional ``netmask`` parameter will also be pushed to clients.
+
+--ifconfig-ipv6-pool args
+  Specify an IPv6 address pool for dynamic assignment to clients.
+
+  Valid args:
+  ::
+
+     ifconfig-ipv6-pool ipv6addr/bits
+
+  The pool starts at ``ipv6addr`` and matches the offset determined from
+  the start of the IPv4 pool.
+
+--ifconfig-pool-persist args
+  Persist/unpersist ifconfig-pool data to ``file``, at ``seconds``
+  intervals (default :code:`600`), as well as on program startup and shutdown.
+
+  Valid syntax:
+  ::
+
+     ifconfig-pool-persist file [seconds]
+
+  The goal of this option is to provide a long-term association between
+  clients (denoted by their common name) and the virtual IP address
+  assigned to them from the ifconfig-pool. Maintaining a long-term
+  association is good for clients because it allows them to effectively
+  use the ``--persist-tun`` option.
+
+  ``file`` is a comma-delimited ASCII file, formatted as
+  :code:`<Common-Name>,<IP-address>`.
+
+  If ``seconds`` = :code:`0`, ``file`` will be treated as read-only. This
+  is useful if you would like to treat ``file`` as a configuration file.
+
+  Note that the entries in this file are treated by OpenVPN as
+  *suggestions* only, based on past associations between a common name and
+  IP address.  They do not guarantee that the given common name will always
+  receive the given IP address. If you want guaranteed assignment, use
+  ``--ifconfig-push``
+
+--ifconfig-push args
+  Push virtual IP endpoints for client tunnel, overriding the
+  ``--ifconfig-pool`` dynamic allocation.
+
+  Valid syntax:
+  ::
+
+     ifconfig-push local remote-netmask [alias]
+
+  The parameters ``local`` and ``remote-netmask`` are set according to the
+  ``--ifconfig`` directive which you want to execute on the client machine
+  to configure the remote end of the tunnel. Note that the parameters
+  ``local`` and ``remote-netmask`` are from the perspective of the client,
+  not the server. They may be DNS names rather than IP addresses, in which
+  case they will be resolved on the server at the time of client
+  connection.
+
+  The optional ``alias`` parameter may be used in cases where NAT causes
+  the client view of its local endpoint to differ from the server view. In
+  this case ``local/remote-netmask`` will refer to the server view while
+  ``alias/remote-netmask`` will refer to the client view.
+
+  This option must be associated with a specific client instance, which
+  means that it must be specified either in a client instance config file
+  using ``--client-config-dir`` or dynamically generated using a
+  ``--client-connect`` script.
+
+  Remember also to include a ``--route`` directive in the main OpenVPN
+  config file which encloses ``local``, so that the kernel will know to
+  route it to the server's TUN/TAP interface.
+
+  OpenVPN's internal client IP address selection algorithm works as
+  follows:
+
+  1.  Use ``--client-connect script`` generated file for static IP
+      (first choice).
+
+  2.  Use ``--client-config-dir`` file for static IP (next choice).
+
+  3.  Use ``--ifconfig-pool`` allocation for dynamic IP (last
+      choice).
+
+--ifconfig-ipv6-push args
+  for ``--client-config-dir`` per-client static IPv6 interface
+  configuration, see ``--client-config-dir`` and ``--ifconfig-push`` for
+  more details.
+
+  Valid syntax:
+  ::
+
+     ifconfig-ipv6-push ipv6addr/bits ipv6remote
+
+--inetd args
+  Valid syntaxes:
+  ::
+
+     inetd
+     inetd wait
+     inetd nowait
+     inetd wait progname
+
+  Use this option when OpenVPN is being run from the inetd or ``xinetd``\(8)
+  server.
+
+  The :code:`wait` and :code:`nowait` option must match what is specified
+  in the inetd/xinetd config file. The :code:`nowait` mode can only be used
+  with ``--proto tcp-server`` The default is :code:`wait`.  The
+  :code:`nowait` mode can be used to instantiate the OpenVPN daemon as a
+  classic TCP server, where client connection requests are serviced on a
+  single port number. For additional information on this kind of
+  configuration, see the OpenVPN FAQ:
+  https://community.openvpn.net/openvpn/wiki/325-openvpn-as-a--forking-tcp-server-which-can-service-multiple-clients-over-a-single-tcp-port
+
+  This option precludes the use of ``--daemon``, ``--local`` or
+  ``--remote``.  Note that this option causes message and error output to
+  be handled in the same way as the ``--daemon`` option. The optional
+  ``progname`` parameter is also handled exactly as in ``--daemon``.
+
+  Also note that in ``wait`` mode, each OpenVPN tunnel requires a separate
+  TCP/UDP port and a separate inetd or xinetd entry. See the OpenVPN 1.x
+  HOWTO for an example on using OpenVPN with xinetd:
+  https://openvpn.net/community-resources/1xhowto/
+
+--multihome
+  Configure a multi-homed UDP server. This option needs to be used when a
+  server has more than one IP address (e.g. multiple interfaces, or
+  secondary IP addresses), and is not using ``--local`` to force binding
+  to one specific address only. This option will add some extra lookups to
+  the packet path to ensure that the UDP reply packets are always sent
+  from the address that the client is talking to. This is not supported on
+  all platforms, and it adds more processing, so it's not enabled by
+  default.
+
+  *Notes:*
+    -  This option is only relevant for UDP servers.
+    -  If you do an IPv6+IPv4 dual-stack bind on a Linux machine with
+       multiple IPv4 address, connections to IPv4 addresses will not
+       work right on kernels before 3.15, due to missing kernel
+       support for the IPv4-mapped case (some distributions have
+       ported this to earlier kernel versions, though).
+
+--iroute args
+  Generate an internal route to a specific client. The ``netmask``
+  parameter, if omitted, defaults to :code:`255.255.255.255`.
+
+  Valid syntax:
+  ::
+
+     iroute network [netmask]
+
+  This directive can be used to route a fixed subnet from the server to a
+  particular client, regardless of where the client is connecting from.
+  Remember that you must also add the route to the system routing table as
+  well (such as by using the ``--route`` directive). The reason why two
+  routes are needed is that the ``--route`` directive routes the packet
+  from the kernel to OpenVPN. Once in OpenVPN, the ``--iroute`` directive
+  routes to the specific client.
+
+  This option must be specified either in a client instance config file
+  using ``--client-config-dir`` or dynamically generated using a
+  ``--client-connect`` script.
+
+  The ``--iroute`` directive also has an important interaction with
+  ``--push "route ..."``. ``--iroute`` essentially defines a subnet which
+  is owned by a particular client (we will call this client *A*). If you
+  would like other clients to be able to reach *A*'s subnet, you can use
+  ``--push "route ..."`` together with ``--client-to-client`` to effect
+  this. In order for all clients to see *A*'s subnet, OpenVPN must push
+  this route to all clients EXCEPT for *A*, since the subnet is already
+  owned by *A*. OpenVPN accomplishes this by not not pushing a route to
+  a client if it matches one of the client's iroutes.
+
+--iroute-ipv6 args
+  for ``--client-config-dir`` per-client static IPv6 route configuration,
+  see ``--iroute`` for more details how to setup and use this, and how
+  ``--iroute`` and ``--route`` interact.
+
+  Valid syntax:
+  ::
+
+     iroute-ipv6 ipv6addr/bits
+
+--max-clients n
+  Limit server to a maximum of ``n`` concurrent clients.
+
+--max-routes-per-client n
+  Allow a maximum of ``n`` internal routes per client (default
+  :code:`256`). This is designed to help contain DoS attacks where an
+  authenticated client floods the server with packets appearing to come
+  from many unique MAC addresses, forcing the server to deplete virtual
+  memory as its internal routing table expands. This directive can be used
+  in a ``--client-config-dir`` file or auto-generated by a
+  ``--client-connect`` script to override the global value for a particular
+  client.
+
+  Note that this directive affects OpenVPN's internal routing table, not
+  the kernel routing table.
+
+--opt-verify
+  Clients that connect with options that are incompatible with those of the
+  server will be disconnected.
+
+  Options that will be compared for compatibility include ``dev-type``,
+  ``link-mtu``, ``tun-mtu``, ``proto``, ``ifconfig``,
+  ``comp-lzo``, ``fragment``, ``keydir``, ``cipher``,
+  ``auth``, ``keysize``, ``secret``, ``no-replay``,
+  ``no-iv``, ``tls-auth``, ``key-method``, ``tls-server``
+  and ``tls-client``.
+
+  This option requires that ``--disable-occ`` NOT be used.
+
+--port-share args
+  Share OpenVPN TCP with another service
+
+  Valid syntax:
+  ::
+
+     port-share host port [dir]
+
+  When run in TCP server mode, share the OpenVPN port with another
+  application, such as an HTTPS server. If OpenVPN senses a connection to
+  its port which is using a non-OpenVPN protocol, it will proxy the
+  connection to the server at ``host``:``port``. Currently only designed to
+  work with HTTP/HTTPS, though it would be theoretically possible to
+  extend to other protocols such as ssh.
+
+  ``dir`` specifies an optional directory where a temporary file with name
+  N containing content C will be dynamically generated for each proxy
+  connection, where N is the source IP:port of the client connection and C
+  is the source IP:port of the connection to the proxy receiver. This
+  directory can be used as a dictionary by the proxy receiver to determine
+  the origin of the connection. Each generated file will be automatically
+  deleted when the proxied connection is torn down.
+
+  Not implemented on Windows.
+
+--push option
+  Push a config file option back to the client for remote execution. Note
+  that ``option`` must be enclosed in double quotes (:code:`""`). The
+  client must specify ``--pull`` in its config file. The set of options
+  which can be pushed is limited by both feasibility and security. Some
+  options such as those which would execute scripts are banned, since they
+  would effectively allow a compromised server to execute arbitrary code
+  on the client. Other options such as TLS or MTU parameters cannot be
+  pushed because the client needs to know them before the connection to the
+  server can be initiated.
+
+  This is a partial list of options which can currently be pushed:
+  ``--route``, ``--route-gateway``, ``--route-delay``,
+  ``--redirect-gateway``, ``--ip-win32``, ``--dhcp-option``,
+  ``--inactive``, ``--ping``, ``--ping-exit``, ``--ping-restart``,
+  ``--setenv``, ``--auth-token``, ``--persist-key``, ``--persist-tun``,
+  ``--echo``, ``--comp-lzo``, ``--socket-flags``, ``--sndbuf``,
+  ``--rcvbuf``
+
+--push-peer-info
+  Push additional information about the client to server. The following
+  data is always pushed to the server:
+
+  :code:`IV_VER=<version>`
+        The client OpenVPN version
+
+  :code:`IV_PLAT=[linux|solaris|openbsd|mac|netbsd|freebsd|win]`
+        The client OS platform
+
+  :code:`IV_LZO_STUB=1`
+        If client was built with LZO stub capability
+
+  :code:`IV_LZ4=1`
+        If the client supports LZ4 compressions.
+
+  :code:`IV_PROTO=2`
+        If the client supports peer-id floating mechanism
+
+  :code:`IV_NCP=2`
+        Negotiable ciphers, client supports ``--cipher`` pushed by
+        the server, a value of 2 or greater indicates client supports
+        *AES-GCM-128* and *AES-GCM-256*.
+
+  :code:`IV_CIPHERS=<ncp-ciphers>`
+        The client pushes the list of configured ciphers with the
+        ``--ciphers`` option to the server.
+
+  :code:`IV_GUI_VER=<gui_id> <version>`
+        The UI version of a UI if one is running, for example
+        :code:`de.blinkt.openvpn 0.5.47` for the Android app.
+
+  When ``--push-peer-info`` is enabled the additional information consists
+  of the following data:
+
+  :code:`IV_HWADDR=<mac address>`
+        The MAC address of clients default gateway
+
+  :code:`IV_SSL=<version string>`
+        The ssl version used by the client, e.g.
+        :code:`OpenSSL 1.0.2f 28 Jan 2016`.
+
+  :code:`IV_PLAT_VER=x.y`
+        The version of the operating system, e.g. 6.1 for Windows 7.
+
+  :code:`UV_<name>=<value>`
+        Client environment variables whose names start with
+        :code:`UV_`
+
+--push-remove opt
+  Selectively remove all ``--push`` options matching "opt" from the option
+  list for a client. ``opt`` is matched as a substring against the whole
+  option string to-be-pushed to the client, so ``--push-remove route``
+  would remove all ``--push route ...`` and ``--push route-ipv6 ...``
+  statements, while ``--push-remove "route-ipv6 2001:"`` would only remove
+  IPv6 routes for :code:`2001:...` networks.
+
+  ``--push-remove`` can only be used in a client-specific context, like in
+  a ``--client-config-dir`` file, or ``--client-connect`` script or plugin
+  -- similar to ``--push-reset``, just more selective.
+
+  *NOTE*: to *change* an option, ``--push-remove`` can be used to first
+  remove the old value, and then add a new ``--push`` option with the new
+  value.
+
+  *NOTE 2*: due to implementation details, 'ifconfig' and 'ifconfig-ipv6'
+  can only be removed with an exact match on the option (
+  :code:`push-remove ifconfig`), no substring matching and no matching on
+  the IPv4/IPv6 address argument is possible.
+
+--push-reset
+  Don't inherit the global push list for a specific client instance.
+  Specify this option in a client-specific context such as with a
+  ``--client-config-dir`` configuration file. This option will ignore
+  ``--push`` options at the global config file level.
+
+--server args
+  A helper directive designed to simplify the configuration of OpenVPN's
+  server mode. This directive will set up an OpenVPN server which will
+  allocate addresses to clients out of the given network/netmask. The
+  server itself will take the :code:`.1` address of the given network for
+  use as the server-side endpoint of the local TUN/TAP interface. If the
+  optional :code:`nopool` flag is given, no dynamic IP address pool will
+  prepared for VPN clients.
+
+  Valid syntax:
+  ::
+
+      server network netmask [nopool]
+
+  For example, ``--server 10.8.0.0 255.255.255.0`` expands as follows:
+  ::
+
+     mode server
+     tls-server
+     push "topology [topology]"
+
+     if dev tun AND (topology == net30 OR topology == p2p):
+       ifconfig 10.8.0.1 10.8.0.2
+       if !nopool:
+         ifconfig-pool 10.8.0.4 10.8.0.251
+       route 10.8.0.0 255.255.255.0
+       if client-to-client:
+         push "route 10.8.0.0 255.255.255.0"
+       else if topology == net30:
+         push "route 10.8.0.1"
+
+     if dev tap OR (dev tun AND topology == subnet):
+       ifconfig 10.8.0.1 255.255.255.0
+       if !nopool:
+         ifconfig-pool 10.8.0.2 10.8.0.253 255.255.255.0
+       push "route-gateway 10.8.0.1"
+       if route-gateway unset:
+         route-gateway 10.8.0.2
+
+  Don't use ``--server`` if you are ethernet bridging. Use
+  ``--server-bridge`` instead.
+
+--server-bridge args
+  A helper directive similar to ``--server`` which is designed to simplify
+  the configuration of OpenVPN's server mode in ethernet bridging
+  configurations.
+
+  Valid syntaxes:
+  ::
+
+      server-bridge gateway netmask pool-start-IP pool-end-IP
+      server-bridge [nogw]
+
+  If ``--server-bridge`` is used without any parameters, it will enable a
+  DHCP-proxy mode, where connecting OpenVPN clients will receive an IP
+  address for their TAP adapter from the DHCP server running on the
+  OpenVPN server-side LAN. Note that only clients that support the binding
+  of a DHCP client with the TAP adapter (such as Windows) can support this
+  mode. The optional :code:`nogw` flag (advanced) indicates that gateway
+  information should not be pushed to the client.
+
+  To configure ethernet bridging, you must first use your OS's bridging
+  capability to bridge the TAP interface with the ethernet NIC interface.
+  For example, on Linux this is done with the :code:`brctl` tool, and with
+  Windows XP it is done in the Network Connections Panel by selecting the
+  ethernet and TAP adapters and right-clicking on "Bridge Connections".
+
+  Next you you must manually set the IP/netmask on the bridge interface.
+  The ``gateway`` and ``netmask`` parameters to ``--server-bridge`` can be
+  set to either the IP/netmask of the bridge interface, or the IP/netmask
+  of the default gateway/router on the bridged subnet.
+
+  Finally, set aside a IP range in the bridged subnet, denoted by
+  ``pool-start-IP`` and ``pool-end-IP``, for OpenVPN to allocate to
+  connecting clients.
+
+  For example, ``server-bridge 10.8.0.4 255.255.255.0 10.8.0.128
+  10.8.0.254`` expands as follows:
+  ::
+
+    mode server
+    tls-server
+
+    ifconfig-pool 10.8.0.128 10.8.0.254 255.255.255.0
+    push "route-gateway 10.8.0.4"
+
+  In another example, ``--server-bridge`` (without parameters) expands as
+  follows:
+  ::
+
+    mode server
+    tls-server
+
+    push "route-gateway dhcp"
+
+  Or ``--server-bridge nogw`` expands as follows:
+  ::
+
+    mode server
+    tls-server
+
+--stale-routes-check args
+  Remove routes which haven't had activity for ``n`` seconds (i.e. the ageing
+  time).  This check is run every ``t`` seconds (i.e. check interval).
+
+  Valid syntax:
+  ::
+
+     stale-routes-check n [t]
+
+  If ``t`` is not present it defaults to ``n``.
+
+  This option helps to keep the dynamic routing table small. See also
+  ``--max-routes-per-client``
+
+--username-as-common-name
+  For ``--auth-user-pass-verify`` authentication, use the authenticated
+  username as the common name, rather than the common name from the client
+  cert.
+
+--verify-client-cert mode
+  Specify whether the client is required to supply a valid certificate.
+
+  Possible ``mode`` options are:
+
+  :code:`none`
+      A client certificate is not required. the client needs to
+      authenticate using username/password only. Be aware that using this
+      directive is less secure than requiring certificates from all
+      clients.
+
+      If you use this directive, the entire responsibility of authentication
+      will rest on your ``--auth-user-pass-verify`` script, so keep in mind
+      that bugs in your script could potentially compromise the security of
+      your VPN.
+
+      ``--verify-client-cert none`` is functionally equivalent to
+      ``--client-cert-not-required``.
+
+  :code:`optional`
+      A client may present a certificate but it is not required to do so.
+      When using this directive, you should also use a
+      ``--auth-user-pass-verify`` script to ensure that clients are
+      authenticated using a certificate, a username and password, or
+      possibly even both.
+
+      Again, the entire responsibility of authentication will rest on your
+      ``--auth-user-pass-verify`` script, so keep in mind that bugs in your
+      script could potentially compromise the security of your VPN.
+
+  :code:`require`
+      This is the default option. A client is required to present a
+      certificate, otherwise VPN access is refused.
+
+  If you don't use this directive (or use ``--verify-client-cert require``)
+  but you also specify an ``--auth-user-pass-verify`` script, then OpenVPN
+  will perform double authentication. The client certificate verification
+  AND the ``--auth-user-pass-verify`` script will need to succeed in order
+  for a client to be authenticated and accepted onto the VPN.
+
+--vlan-tagging
+  Server-only option. Turns the OpenVPN server instance into a switch that
+  understands VLAN-tagging, based on IEEE 802.1Q.
+
+  The server TAP device and each of the connecting clients is seen as a
+  port of the switch. All client ports are in untagged mode and the server
+  TAP device is VLAN-tagged, untagged or accepts both, depending on the
+  ``--vlan-accept`` setting.
+
+  Ethernet frames with a prepended 802.1Q tag are called "tagged". If the
+  VLAN Identifier (VID) field in such a tag is non-zero, the frame is
+  called "VLAN-tagged". If the VID is zero, but the Priority Control Point
+  (PCP) field is non-zero, the frame is called "prio-tagged". If there is
+  no 802.1Q tag, the frame is "untagged".
+
+  Using the ``--vlan-pvid v`` option once per client (see
+  --client-config-dir), each port can be associated with a certain VID.
+  Packets can only be forwarded between ports having the same VID.
+  Therefore, clients with differing VIDs are completely separated from
+  one-another, even if ``--client-to-client`` is activated.
+
+  The packet filtering takes place in the OpenVPN server. Clients should
+  not have any VLAN tagging configuration applied.
+
+  The ``--vlan-tagging`` option is off by default. While turned off,
+  OpenVPN accepts any Ethernet frame and does not perform any special
+  processing for VLAN-tagged packets.
+
+  This option can only be activated in ``--dev tap mode``.
+
+--vlan-accept args
+  Configure the VLAN tagging policy for the server TAP device.
+
+  Valid syntax:
+  ::
+
+     vlan-accept  all|tagged|untagged
+
+  The following modes are available:
+
+  :code:`tagged`
+      Admit only VLAN-tagged frames. Only VLAN-tagged packets are accepted,
+      while untagged or priority-tagged packets are dropped when entering
+      the server TAP device.
+
+  :code:`untagged`
+      Admit only untagged and prio-tagged frames.  VLAN-tagged packets are
+      not accepted, while untagged or priority-tagged packets entering the
+      server TAP device are tagged with the value configured for the global
+      ``--vlan-pvid`` setting.
+
+  :code:`all` (default)
+      Admit all frames.  All packets are admitted and then treated like
+      untagged or tagged mode respectively.
+
+  *Note*:
+      Some vendors refer to switch ports running in :code:`tagged` mode
+      as "trunk ports" and switch ports running in :code:`untagged` mode
+      as "access ports".
+
+  Packets forwarded from clients to the server are VLAN-tagged with the
+  originating client's PVID, unless the VID matches the global
+  ``--vlan-pvid``, in which case the tag is removed.
+
+  If no *PVID* is configured for a given client (see --vlan-pvid) packets
+  are tagged with 1 by default.
+
+--vlan-pvid v
+  Specifies which VLAN identifier a "port" is associated with. Only valid
+  when ``--vlan-tagging`` is speficied.
+
+  In the client context, the setting specifies which VLAN ID a client is
+  associated with. In the global context, the VLAN ID of the server TAP
+  device is set. The latter only makes sense for ``--vlan-accept
+  untagged`` and ``--vlan-accept all`` modes.
+
+  Valid values for ``v`` go from :code:`1` through to :code:`4094`. The
+  global value defaults to :code:`1`. If no ``--vlan-pvid`` is specified in
+  the client context, the global value is inherited.
+
+  In some switch implementations, the *PVID* is also referred to as "Native
+  VLAN".