Documentation: Various syntax fixes and text improvements

This started as a fix for #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 #606
Change-Id: Iee535f1502ab3dcb7bde7f2593c2e122d27d9189
Signed-off-by: Frank Lichtenheld <[email protected]>
Acked-by: Gert Doering <[email protected]>
Gerrit URL: https://gerrit.openvpn.net/c/openvpn/+/1414
Message-Id: <[email protected]>
URL: https://www.mail-archive.com/[email protected]/msg34878.html
Signed-off-by: Gert Doering <[email protected]>

Author: flichtenheld

doc/man-sections/cipher-negotiation.rst

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

doc/man-sections/client-options.rst

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

doc/man-sections/example-fingerprint.rst

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

doc/man-sections/examples.rst

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

doc/man-sections/protocol-options.rst

@@ -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``).
 

doc/man-sections/script-options.rst

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

doc/man-sections/server-options.rst

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

doc/man-sections/signals.rst

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

doc/man-sections/tls-options.rst

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

doc/man-sections/virtual-routing-and-forwarding.rst

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