Commit f500c49c authored by David Sommerseth's avatar David Sommerseth Committed by Gert Doering
Browse files

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: default avatarGert Doering <>

* 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

Signed-off-by: David Sommerseth's avatarDavid Sommerseth <>
Acked-by: default avatarGert Doering <>
Message-Id: <>

Signed-off-by: default avatarGert Doering <>

* 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's avatarDavid Sommerseth <>
Acked-by: default avatarGert Doering <>
Message-Id: <>

Signed-off-by: default avatarGert Doering <>

* 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's avatarDavid Sommerseth <>
Acked-by: default avatarGert Doering <>
Message-Id: <>

Signed-off-by: default avatarGert Doering <>

* 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's avatarDavid Sommerseth <>
Acked-by: default avatarGert Doering <>
Message-Id: <>

Signed-off-by: default avatarGert Doering <>
parent c83b197a
......@@ -49,6 +49,7 @@
......@@ -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
path to systemd-ask-password utility
......@@ -235,6 +234,8 @@ ENVIRONMENT for ./configure:
Path of systemd unit directory [default=LIBDIR/systemd/system]
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])
# 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])
# 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"
if test "${WIN32}" = "yes"; then
test -z "${MAN2HTML}" && AC_MSG_ERROR([man2html is required for win32])
if test "${enable_plugin_auth_pam}" = "yes"; then
if test "${enable_pam_dlopen}" = "yes"; then
......@@ -5,29 +5,69 @@
# packet encryption, packet authentication, and
# packet compression.
# Copyright (C) 2002-2018 OpenVPN Inc <>
# Copyright (C) 2002-2020 OpenVPN Inc <>
# Copyright (C) 2006-2012 Alon Bar-Lev <>
CLEANFILES = openvpn.8.html
SUBDIRS = doxygen
dist_doc_DATA = \
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 \
dist_noinst_DATA = \
README.plugins interactive-service-notes.rst
if WIN32
openvpn.8 :
$(RST2MAN) $(srcdir)/$@.rst > $@
@echo "Missing python-docutils - skipping man page generation"
$(RST2HTML) $(srcdir)/openvpn.8.rst > $@
@echo "Missing python-docutils - skipping man/html page generation"
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
openvpn.8 openvpn.8.html
if WIN32
dist_man_MANS = openvpn.8
dist-hook : openvpn.8 openvpn.8.html
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:
* Quickstart on .rst
* reStructuredText Markup Specifictaion (.rst)
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 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`).
Preserve initially resolved local IP address and port number across
``SIGUSR1`` or ``--ping-restart`` restarts.
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
--rcvbuf size
Set the TCP/UDP socket receive buffer size. Defaults to operating system
--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
--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.
Client Options
The client options are used when connecting to an OpenVPN server configured
to use ``--server``, ``--server-bridge``, or ``--mode server`` in its
Allow client to pull DNS names from server (rather than being limited to
IP address) for ``--ifconfig``, ``--route``, and ``--route-gateway``.
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``
Authenticate with server using username/password.
Valid syntaxes:
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
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:
Client will exit with a fatal error (this is the default).
Client will retry the connection without requerying
for an ``--auth-user-pass`` username/password. Use this option for
unattended clients.
Client will requery for an ``--auth-user-pass``
username/password and/or private key password before attempting a
Note that while this option cannot be pushed, it can be controlled from
the management interface.
A helper directive designed to simplify the configuration of OpenVPN's
client mode. This directive is equivalent to:
--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
client-nat snat
client-nat dnat
``network/netmask`` (for example :code:``) defines
the local view of a resource from the client perspective, while
``alias/netmask`` (for example :code:``) 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
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
--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`).
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
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.
remote 1194
remote 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
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
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.
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.
Prepend a random string (6 bytes, 12 hex characters) to hostname to
prevent DNS caching. For example, "" would be modified to
--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.
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
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.