mirror of
https://github.com/OpenVPN/openvpn.git
synced 2026-02-18 18:19:42 -05:00
Documentation: Various syntax fixes and text improvements
This started as a fix for OpenVPN/openvpn#606 but while reviewing the documentation referenced from there I identified more and more issues. There a few classes of changes in here: - Fix wrong `...` syntax, which makes no sense in rst. - Remove some very old references to OpenVPN v1 behavior. - Fix typos or other small text issues. Note: The usage of ``...`` vs :code:`...` is very inconsistent, but fixing that is outside of the scope of this patch. I have tried to make it at least locally consistent. Github: Fixes OpenVPN/openvpn#606 Change-Id: Iee535f1502ab3dcb7bde7f2593c2e122d27d9189 Signed-off-by: Frank Lichtenheld <frank@lichtenheld.com> Acked-by: Gert Doering <gert@greenie.muc.de> Gerrit URL: https://gerrit.openvpn.net/c/openvpn/+/1414 Message-Id: <20251208114224.10223-1-gert@greenie.muc.de> URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg34878.html Signed-off-by: Gert Doering <gert@greenie.muc.de>
This commit is contained in:
Frank Lichtenheld
Gert Doering
parent
0ff66c056f
commit
bd8d03e91a
12 changed files with 52 additions and 69 deletions
|
|
@ -30,13 +30,13 @@ The negotiation support in OpenVPN 2.4 was the first iteration of the implementa
|
|||
and still had some quirks. Its main goal was "upgrade to AES-256-GCM when possible".
|
||||
An OpenVPN 2.4 client that is built against a crypto library that supports AES in GCM
|
||||
mode and does not have ``--ncp-disable`` will always announce support for
|
||||
`AES-256-GCM` and `AES-128-GCM` to a server by sending :code:`IV_NCP=2`.
|
||||
``AES-256-GCM`` and ``AES-128-GCM`` to a server by sending :code:`IV_NCP=2`.
|
||||
|
||||
This only causes a problem if ``--ncp-ciphers`` option has been changed from the
|
||||
default of :code:`AES-256-GCM:AES-128-GCM` to a value that does not include
|
||||
these two ciphers. When an OpenVPN server tries to use `AES-256-GCM` or
|
||||
`AES-128-GCM` the connection will then fail. It is therefore recommended to
|
||||
always have the `AES-256-GCM` and `AES-128-GCM` ciphers to the ``--ncp-ciphers``
|
||||
these two ciphers. When an OpenVPN server tries to use ``AES-256-GCM`` or
|
||||
``AES-128-GCM`` the connection will then fail. It is therefore recommended to
|
||||
always have the ``AES-256-GCM`` and ``AES-128-GCM`` ciphers to the ``--ncp-ciphers``
|
||||
options to avoid this behaviour.
|
||||
|
||||
OpenVPN 3 clients
|
||||
|
|
@ -45,7 +45,7 @@ Clients based on the OpenVPN 3.x library (https://github.com/openvpn/openvpn3/)
|
|||
do not have a configurable ``--ncp-ciphers`` or ``--data-ciphers`` option. Newer
|
||||
versions by default disable legacy AES-CBC, BF-CBC, and DES-CBC ciphers.
|
||||
These clients will always announce support for all their supported AEAD ciphers
|
||||
(`AES-256-GCM`, `AES-128-GCM` and in newer versions also `Chacha20-Poly1305`).
|
||||
(``AES-256-GCM``, ``AES-128-GCM`` and in newer versions also ``Chacha20-Poly1305``).
|
||||
|
||||
To support OpenVPN 3.x based clients at least one of these ciphers needs to be
|
||||
included in the server's ``--data-ciphers`` option.
|
||||
|
|
@ -66,12 +66,12 @@ cipher used by the client is necessary.
|
|||
|
||||
OpenVPN 2.4 server
|
||||
``````````````````
|
||||
When a client indicates support for `AES-128-GCM` and `AES-256-GCM`
|
||||
When a client indicates support for ``AES-128-GCM`` and ``AES-256-GCM``
|
||||
(with ``IV_NCP=2``) an OpenVPN 2.4 server will send the first
|
||||
cipher of the ``--ncp-ciphers`` to the OpenVPN client regardless of what
|
||||
the cipher is. To emulate the behaviour of an OpenVPN 2.4 client as close
|
||||
as possible and have compatibility to a setup that depends on this quirk,
|
||||
adding `AES-128-GCM` and `AES-256-GCM` to the client's ``--data-ciphers``
|
||||
adding ``AES-128-GCM`` and ``AES-256-GCM`` to the client's ``--data-ciphers``
|
||||
option is required. OpenVPN 2.5+ will only announce the ``IV_NCP=2`` flag if
|
||||
those ciphers are present.
|
||||
|
||||
|
|
@ -90,10 +90,10 @@ cipher used by the server is necessary.
|
|||
|
||||
Blowfish in CBC mode (BF-CBC) deprecation
|
||||
`````````````````````````````````````````
|
||||
The ``--cipher`` option defaulted to `BF-CBC` in OpenVPN 2.4 and older
|
||||
The ``--cipher`` option defaulted to ``BF-CBC`` in OpenVPN 2.4 and older
|
||||
version. The default was never changed to ensure backwards compatibility.
|
||||
In OpenVPN 2.5 this behaviour has now been changed so that if the ``--cipher``
|
||||
is not explicitly set it does not allow the weak `BF-CBC` cipher any more
|
||||
is not explicitly set it does not allow the weak ``BF-CBC`` cipher any more
|
||||
and needs to explicitly added as ``--cipher BFC-CBC`` or added to
|
||||
``--data-ciphers``.
|
||||
|
||||
|
|
|
|||
|
|
@ -437,8 +437,8 @@ configuration.
|
|||
This may be set by the client UI/GUI using ``--setenv``.
|
||||
On Windows systems it is automatically determined by openvpn
|
||||
itself. On other platforms OpenVPN will default to sending
|
||||
the information returned by the `uname()` system call in
|
||||
the `release` field, which is usually the currently running
|
||||
the information returned by the ``uname()`` system call in
|
||||
the ``release`` field, which is usually the currently running
|
||||
kernel version. This is highly system specific, though.
|
||||
|
||||
:code:`UV_<name>=<value>`
|
||||
|
|
|
|||
|
|
@ -12,29 +12,26 @@ Server setup
|
|||
------------
|
||||
1. Install openvpn
|
||||
|
||||
Compile from source-code (see `INSTALL` file) or install via a distribution (apt/yum/ports)
|
||||
Compile from source-code (see ``INSTALL`` file) or install via a distribution (apt/yum/ports)
|
||||
or via installer (Windows).
|
||||
|
||||
2. Generate a self-signed certificate for the server:
|
||||
::
|
||||
2. Generate a self-signed certificate for the server::
|
||||
|
||||
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:secp384r1 -keyout server.key -out server.crt -nodes -sha256 -days 3650 -subj '/CN=server'
|
||||
|
||||
3. Generate SHA256 fingerprint of the server certificate
|
||||
|
||||
Use the OpenSSL command line utility to view the fingerprint of just
|
||||
created certificate:
|
||||
::
|
||||
created certificate::
|
||||
|
||||
openssl x509 -fingerprint -sha256 -in server.crt -noout
|
||||
|
||||
This outputs something similar to:
|
||||
::
|
||||
This outputs something similar to::
|
||||
|
||||
SHA256 Fingerprint=00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff
|
||||
|
||||
|
||||
4. Write a server configuration (`server.conf`)::
|
||||
4. Write a server configuration (``server.conf``)::
|
||||
|
||||
# The server certificate we created in step 1
|
||||
cert server.crt
|
||||
|
|
@ -73,10 +70,8 @@ Server setup
|
|||
5. Add at least one client as described in the client section.
|
||||
|
||||
6. Start the server.
|
||||
- On systemd based distributions move `server.crt`, `server.key` and
|
||||
`server.conf` to :code:`/etc/openvpn/server` and start it via systemctl
|
||||
|
||||
::
|
||||
- On systemd based distributions move ``server.crt``, ``server.key`` and
|
||||
``server.conf`` to ``/etc/openvpn/server`` and start it via systemctl::
|
||||
|
||||
sudo mv server.conf server.key server.crt /etc/openvpn/server
|
||||
|
||||
|
|
@ -94,8 +89,7 @@ Adding a client
|
|||
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:secp384r1 -keyout - -nodes -sha256 -days 3650 -subj '/CN=alice'
|
||||
|
||||
This generate a certificate and a key for the client. The output of the command will look
|
||||
something like this:
|
||||
::
|
||||
something like this::
|
||||
|
||||
-----BEGIN PRIVATE KEY-----
|
||||
[base64 content]
|
||||
|
|
@ -107,9 +101,7 @@ Adding a client
|
|||
|
||||
|
||||
3. Create a new client configuration file. In this example we will name the file
|
||||
`alice.ovpn`:
|
||||
|
||||
::
|
||||
``alice.ovpn``::
|
||||
|
||||
# The name of your server to connect to
|
||||
remote yourserver.example.net
|
||||
|
|
@ -146,24 +138,19 @@ Adding a client
|
|||
|
||||
4. Generate the fingerprint of the client certificate. For that we will
|
||||
let OpenSSL read the client configuration file as the x509 command will
|
||||
ignore anything that is not between the begin and end markers of the certificate:
|
||||
|
||||
::
|
||||
ignore anything that is not between the begin and end markers of the certificate::
|
||||
|
||||
openssl x509 -fingerprint -sha256 -noout -in alice.ovpn
|
||||
|
||||
This will again output something like
|
||||
::
|
||||
This will again output something like::
|
||||
|
||||
SHA256 Fingerprint=ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00:ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00
|
||||
|
||||
5. Edit the `server.conf` configuration file and add this new client
|
||||
5. Edit the ``server.conf`` configuration file and add this new client
|
||||
fingerprint as additional line between :code:`<peer-fingerprint>`
|
||||
and :code:`</peer-fingerprint>`
|
||||
|
||||
After adding *two* clients the part of configuration would look like this:
|
||||
|
||||
::
|
||||
After adding *two* clients the part of configuration would look like this::
|
||||
|
||||
<peer-fingerprint>
|
||||
ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00:ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00
|
||||
|
|
@ -172,15 +159,13 @@ Adding a client
|
|||
|
||||
6. (optional) if the client is an older client that does not support the
|
||||
:code:`peer-fingerprint` (e.g. OpenVPN 2.5 and older, OpenVPN Connect 3.3
|
||||
and older), the client config `alice.ovpn` can be modified to still work with
|
||||
and older), the client config ``alice.ovpn`` can be modified to still work with
|
||||
these clients.
|
||||
|
||||
Remove the line starting with :code:`peer-fingerprint`. Then
|
||||
add a new :code:`<ca>` section at the end of the configuration file
|
||||
with the contents of the :code:`server.crt` created in step 2 of the
|
||||
server setup. The end of `alice.ovpn` file should like:
|
||||
|
||||
::
|
||||
with the contents of the ``server.crt`` created in step 2 of the
|
||||
server setup. The end of ``alice.ovpn`` file should look like::
|
||||
|
||||
[...] # Beginning of the file skipped
|
||||
</cert>
|
||||
|
|
|
|||
|
|
@ -132,7 +132,7 @@ On alice::
|
|||
|
||||
ping 10.4.0.1
|
||||
|
||||
Note: This example use a elliptic curve (`secp384`), which allows
|
||||
Note: This example use a elliptic curve (``secp384``), which allows
|
||||
``--dh`` to be set to ``none``.
|
||||
|
||||
Example 3: A tunnel with full PKI and TLS-based security
|
||||
|
|
|
|||
|
|
@ -185,7 +185,7 @@ configured in a compatible way between both the local and remote side.
|
|||
:code:`AES-192-CBC`.
|
||||
|
||||
Cipher negotiation is enabled in client-server mode only. I.e. if
|
||||
``--mode`` is set to `server` (server-side, implied by setting
|
||||
``--mode`` is set to ``server`` (server-side, implied by setting
|
||||
``--server`` ), or if ``--pull`` is specified (client-side, implied by
|
||||
setting ``--client``).
|
||||
|
||||
|
|
|
|||
|
|
@ -149,7 +149,7 @@ SCRIPT HOOKS
|
|||
:code:`auth_pending_file`. The first line must be the timeout in
|
||||
seconds, the required method on the second line (e.g. crtext) and
|
||||
third line must be the EXTRA as documented in the
|
||||
``client-pending-auth`` section of `doc/management.txt`.
|
||||
``client-pending-auth`` section of ``doc/management.txt``.
|
||||
|
||||
This directive is designed to enable a plugin-style interface for
|
||||
extending OpenVPN's authentication capabilities.
|
||||
|
|
@ -588,7 +588,7 @@ permitted character class for each string:
|
|||
|
||||
*--auth-user-pass username*
|
||||
Same as Common Name, with one exception:
|
||||
starting with OpenVPN 2.0.1, the username is passed to the
|
||||
The username is passed to the
|
||||
:code:`OPENVPN_PLUGIN_AUTH_USER_PASS_VERIFY` plugin in its raw form,
|
||||
without string remapping.
|
||||
|
||||
|
|
@ -597,11 +597,9 @@ permitted character class for each string:
|
|||
a character which will cause the C library isprint() function to
|
||||
return true.
|
||||
|
||||
*--client-config-dir filename as derived from common name or`username*
|
||||
Alphanumeric, underbar ('\_'), dash ('-'), and dot ('.') except for "."
|
||||
or ".." as standalone strings. As of v2.0.1-rc6, the at ('@') character
|
||||
has been added as well for compatibility with the common name character
|
||||
class.
|
||||
*--client-config-dir filename as derived from common name or username*
|
||||
Alphanumeric, underbar ('\_'), dash ('-'), at ('@'), and dot ('.')
|
||||
except for "." or ".." as standalone strings.
|
||||
|
||||
*Environmental variable names*
|
||||
Alphanumeric or underbar ('\_').
|
||||
|
|
@ -620,7 +618,7 @@ Environmental Variables
|
|||
Once set, a variable is persisted indefinitely until it is reset by a
|
||||
new value or a restart,
|
||||
|
||||
As of OpenVPN 2.0-beta12, in server mode, environmental variables set by
|
||||
In server mode, environmental variables set by
|
||||
OpenVPN are scoped according to the client objects they are associated
|
||||
with, so there should not be any issues with scripts having access to
|
||||
stale, previously set variables which refer to different client
|
||||
|
|
@ -861,7 +859,7 @@ instances.
|
|||
|
||||
:code:`route_ipv6_{parm}_{n}`
|
||||
A set of variables which define each IPv6 route to be added, and are
|
||||
set prior to **--up** script execution.
|
||||
set prior to ``--up`` script execution.
|
||||
|
||||
``parm`` will be one of :code:`network`, :code:`gateway` or
|
||||
:code:`metric`. ``route_ipv6_network_{n}`` contains :code:`netmask`
|
||||
|
|
@ -877,9 +875,9 @@ instances.
|
|||
:code:`route_redirect_gateway_ipv4`
|
||||
|
||||
:code:`route_redirect_gateway_ipv6`
|
||||
Set to `1` if the corresponding default gateway should be redirected
|
||||
into the tunnel, and to `2` if also the local LAN segment should be
|
||||
blocked (`block-local`). Not set otherwise. Set prior to **--up** script
|
||||
Set to :code:`1` if the corresponding default gateway should be redirected
|
||||
into the tunnel, and to :code:`2` if also the local LAN segment should be
|
||||
blocked (:code:`block-local`). Not set otherwise. Set prior to ``--up`` script
|
||||
execution.
|
||||
|
||||
:code:`script_context`
|
||||
|
|
|
|||
|
|
@ -509,7 +509,7 @@ fast hardware. SSL/TLS authentication must be used in this mode.
|
|||
``--rcvbuf``, ``--session-timeout``
|
||||
|
||||
Note: using ``--push`` requires OpenVPN to run in ``--mode server`` (or
|
||||
using of one of `--server`, `--server-bridge` helper directives).
|
||||
using of one of ``--server``, ``--server-bridge`` helper directives).
|
||||
|
||||
--push-remove opt
|
||||
Selectively remove all ``--push`` options matching "opt" from the option
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ SIGNALS
|
|||
connections.
|
||||
|
||||
:code:`SIGUSR1`
|
||||
Like :code:`SIGHUP``, except don't re-read configuration file, and
|
||||
Like :code:`SIGHUP`, except don't re-read configuration file, and
|
||||
possibly don't close and reopen TUN/TAP device, re-read key files,
|
||||
preserve local IP address/port, or preserve most recently authenticated
|
||||
remote IP address/port based on ``--persist-tun``, ``--persist-local-ip``
|
||||
|
|
|
|||
|
|
@ -220,7 +220,7 @@ certificates and keys: https://github.com/OpenVPN/easy-rsa
|
|||
Local peer's private key in .pem format or a URI. Use the private key
|
||||
which was generated when you built your peer's certificate (see
|
||||
``--cert file`` above). URI is supported only when built with OpenSSL 3.0
|
||||
or later and any required providers are loaded. (See `--cert` for more details).
|
||||
or later and any required providers are loaded. (See ``--cert`` for more details).
|
||||
|
||||
--pkcs12 file
|
||||
Specify a PKCS #12 file containing local private key, local certificate,
|
||||
|
|
@ -390,7 +390,7 @@ certificates and keys: https://github.com/OpenVPN/easy-rsa
|
|||
by using ``--ecdh-curve``, the groups for ecdh will also be picked
|
||||
from this list.
|
||||
|
||||
OpenVPN maps the curve name `secp256r1` to `prime256v1` to allow
|
||||
OpenVPN maps the curve name ``secp256r1`` to ``prime256v1`` to allow
|
||||
specifying the same tls-groups option for mbedTLS and OpenSSL.
|
||||
|
||||
Warning: this option not only affects elliptic curve certificates
|
||||
|
|
@ -404,7 +404,7 @@ certificates and keys: https://github.com/OpenVPN/easy-rsa
|
|||
The following profiles are supported:
|
||||
|
||||
:code:`insecure`
|
||||
Identical for mbed TLS to `legacy`
|
||||
Identical for mbed TLS to :code:`legacy`
|
||||
|
||||
:code:`legacy` (default)
|
||||
SHA1 and newer, RSA 2048-bit+, any elliptic curve.
|
||||
|
|
@ -433,7 +433,7 @@ certificates and keys: https://github.com/OpenVPN/easy-rsa
|
|||
OpenVPN will migrate to 'preferred' as default in the future. Please
|
||||
ensure that your keys already comply.
|
||||
|
||||
*WARNING:* ``--tls-ciphers``, ``--tls-ciphersuites`` and ``tls-groups``
|
||||
*WARNING:* ``--tls-cipher``, ``--tls-ciphersuites`` and ``tls-groups``
|
||||
These options are expert features, which - if used correctly - can
|
||||
improve the security of your VPN connection. But it is also easy to
|
||||
unwittingly use them to carefully align a gun with your foot, or just
|
||||
|
|
@ -442,7 +442,7 @@ certificates and keys: https://github.com/OpenVPN/easy-rsa
|
|||
--tls-cipher l
|
||||
A list ``l`` of allowable TLS ciphers delimited by a colon (":code:`:`").
|
||||
|
||||
These setting can be used to ensure that certain cipher suites are used
|
||||
This setting can be used to ensure that certain cipher suites are used
|
||||
(or not used) for the TLS connection. OpenVPN uses TLS to secure the
|
||||
control channel, over which the keys that are used to protect the actual
|
||||
VPN traffic are exchanged.
|
||||
|
|
@ -452,7 +452,7 @@ certificates and keys: https://github.com/OpenVPN/easy-rsa
|
|||
OpenSSL and/or mbed TLS documentation for details on the cipher list
|
||||
interpretation.
|
||||
|
||||
For OpenSSL, the ``--tls-cipher`` is used for TLS 1.2 and below.
|
||||
For OpenSSL, the ``--tls-cipher`` option is used for TLS 1.2 and below.
|
||||
|
||||
Use ``--show-tls`` to see a list of TLS ciphers supported by your crypto
|
||||
library.
|
||||
|
|
@ -466,7 +466,7 @@ certificates and keys: https://github.com/OpenVPN/easy-rsa
|
|||
Same as ``--tls-cipher`` but for TLS 1.3 and up. mbed TLS has no
|
||||
TLS 1.3 support yet and only the ``--tls-cipher`` setting is used.
|
||||
|
||||
The default for `--tls-ciphersuites` is to use the crypto library's
|
||||
The default for ``--tls-ciphersuites`` is to use the crypto library's
|
||||
default.
|
||||
|
||||
--tls-client
|
||||
|
|
|
|||
|
|
@ -35,7 +35,7 @@ Move :code:`eth0` into :code:`vrf_external`
|
|||
ip link set master vrf_external dev eth0
|
||||
|
||||
Any prefixes configured on :code:`eth0` will be moved from the :code`main`
|
||||
routing table into routing table `1023`
|
||||
routing table into routing table :code:`1023`
|
||||
|
||||
|
||||
VRF setup with ifupdown
|
||||
|
|
|
|||
|
|
@ -161,7 +161,7 @@ https://www.oberhumer.com/opensource/lzo/
|
|||
COPYRIGHT
|
||||
=========
|
||||
|
||||
Copyright (C) 2002-2020 OpenVPN Inc This program is free software; you
|
||||
Copyright (C) 2002-2025 OpenVPN Inc This program is free software; you
|
||||
can redistribute it and/or modify it under the terms of the GNU General
|
||||
Public License version 2 as published by the Free Software Foundation.
|
||||
|
||||
|
|
|
|||
|
|
@ -4108,8 +4108,8 @@ show_available_tls_ciphers(const char *cipher_list, const char *cipher_list_tls1
|
|||
show_available_tls_ciphers_list(cipher_list, tls_cert_profile, false);
|
||||
|
||||
printf("\n"
|
||||
"Be aware that that whether a cipher suite in this list can actually work\n"
|
||||
"depends on the specific setup of both peers. See the man page entries of\n"
|
||||
"Note: Whether a cipher suite in this list can actually work depends\n"
|
||||
"on the specific setup of both peers. See the man page entries of\n"
|
||||
"--tls-cipher and --show-tls for more details.\n\n");
|
||||
}
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue