mirror of
https://github.com/OpenVPN/openvpn.git
synced 2024-09-20 20:03:13 +02:00
f500c49c8e
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>
76 lines
2.5 KiB
ReStructuredText
76 lines
2.5 KiB
ReStructuredText
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.
|