[Openvpn-devel] man: Improve --remote entry

Message ID 20200909183012.7504-1-davids@openvpn.net
State Accepted
Headers show
Series
  • [Openvpn-devel] man: Improve --remote entry
Related show

Commit Message

David Sommerseth Sept. 9, 2020, 6:30 p.m.
The --remote entry had a syntax mistake in the argument examples, which
was introduced during the .rst conversion.

In addition this section did not have a good flow.  So the text was
regrouped and re-organized a bit so related text pieces are now gathered
in the same context instead of being more spread out.

Signed-off-by: David Sommerseth <davids@openvpn.net>
---
 doc/man-sections/client-options.rst | 60 ++++++++++++++++-------------
 1 file changed, 34 insertions(+), 26 deletions(-)

Comments

Gert Doering Sept. 14, 2020, 10:16 a.m. | #1
Hi,

On Wed, Sep 09, 2020 at 08:30:12PM +0200, David Sommerseth wrote:
> +  *Note:*
> +     Since UDP is connectionless, connection failure is defined by
> +     the ``--ping`` and ``--ping-restart`` options.

While this is what the openvpn.8 man page used to say, it's technically
only valid for some variants of "peer2peer --secret" mode.  In TLS
mode, "connection failure" is defined by inability to establish a 
TLS handshake in the timeout time.

I'm going to merge this anyway ("because this is not new text"), but
we should come back and revisit these notes.  All these notes.  One day.

gert
Gert Doering Sept. 14, 2020, 10:21 a.m. | #2
Acked-by: Gert Doering <gert@greenie.muc.de>

I've compared this to the 2.4 man page, and it is indeed easier
to read and less unclear this way.

As written already, one day we need to go through the man pages
and throw out all NOTEs that refer to --secret mode, or clarify
what "running without --remote" really means...

Your patch has been applied to the master and release/2.5 branch.

commit 97ff64360745d27004e97043507ac788db23799c (master)
commit d1a7d83fe691d0cb4cfcc35085bfb8ded0396141 (release/2.5)
Author: David Sommerseth
Date:   Wed Sep 9 20:30:12 2020 +0200

     man: Improve --remote entry

     Signed-off-by: David Sommerseth <davids@openvpn.net>
     Acked-by: Gert Doering <gert@greenie.muc.de>
     Message-Id: <20200909183012.7504-1-davids@openvpn.net>
     URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg20935.html
     Signed-off-by: Gert Doering <gert@greenie.muc.de>


--
kind regards,

Gert Doering

Patch

diff --git a/doc/man-sections/client-options.rst b/doc/man-sections/client-options.rst
index ec1e3b11..af21fbcd 100644
--- a/doc/man-sections/client-options.rst
+++ b/doc/man-sections/client-options.rst
@@ -244,43 +244,51 @@  configuration.
   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.
+  Remote host name or IP address, port and protocol.
 
-  The OpenVPN client will try to connect to a server at ``host:port`` in
-  the order specified by the list of ``--remote`` options.
-
-  Examples:
+  Valid syntaxes:
   ::
 
-     remote server.example.net
-     remote server.example.net 1194
-     remote server.example.net tcp
+     remote host
+     remote host port
+     remote host port proto
 
-  ``proto`` indicates the protocol to use when connecting with the remote,
-  and may be :code:`tcp` or :code:`udp`.
+  The ``port`` and ``proto`` arguments are optional. The OpenVPN client
+  will try to connect to a server at ``host:port``.  The ``proto`` argument
+  indicates the protocol to use when connecting with the remote, and may be
+  :code:`tcp` or :code:`udp`.  To enforce IPv4 or IPv6 connections add a
+  :code:`4` or :code:`6` suffix; like :code:`udp4` / :code:`udp6`
+  / :code:`tcp4` / :code:`tcp6`.
 
-  For forcing IPv4 or IPv6 connection suffix tcp or udp with 4/6 like
-  udp4/udp6/tcp4/tcp6.
+  On the client, multiple ``--remote`` options may be specified for
+  redundancy, each referring to a different OpenVPN server, in the order
+  specified by the list of ``--remote`` options. Specifying multiple
+  ``--remote`` options for this purpose is a special case of the more
+  general connection-profile feature. See the ``<connection>``
+  documentation below.
 
   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.
+  Examples:
+  ::
 
-  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.
+     remote server1.example.net
+     remote server1.example.net 1194
+     remote server2.example.net 1194 tcp
+
+  *Note:*
+     Since UDP is connectionless, connection failure is defined by
+     the ``--ping`` and ``--ping-restart`` options.
+
+     Also, 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