[Openvpn-devel] man: Describe --proto options better

Message ID 20171005232542.30007-1-davids@openvpn.net
State Changes Requested
Delegated to: David Sommerseth
Headers show
Series
  • [Openvpn-devel] man: Describe --proto options better
Related show

Commit Message

David Sommerseth Oct. 5, 2017, 11:25 p.m.
The --proto options changed a bit in OpenVPN v2.4.  This tries to
expand this section, explaining the new variants and how they
related to older OpenVPN versions.

Signed-off-by: David Sommerseth <davids@openvpn.net>
---
 doc/openvpn.8 | 37 ++++++++++++++++++++++++++++++++++---
 1 file changed, 34 insertions(+), 3 deletions(-)

Comments

Gert Doering Nov. 3, 2017, 7:09 p.m. | #1
Hi,

On Fri, Oct 06, 2017 at 01:25:42AM +0200, David Sommerseth wrote:
> The --proto options changed a bit in OpenVPN v2.4.  This tries to
> expand this section, explaining the new variants and how they
> related to older OpenVPN versions.

As discussed on IRC, this is not fully right yet.  I'm somewhat too
lazy to write up a proper patch, so I'll just write it up again.

Client and server are slightly different, as are 2.3/2.4.  So:

 client/2.3
    --proto udp/tcp    -> IPv4-only
    --proto udp6/tcp6  -> IPv6-only
       (no way to get "use what the server advertises in DNS")

 client/2.4
    --proto udp4/tcp4  -> IPv4-only
    --proto udp6/tcp6  -> IPv6-only
    --proto udp/tcp    -> "ask DNS, and try IPv6 and/or IPv4, whatever
                          comes back from DNS and works"

 server/2.3
    --proto udp/tcp    -> IPv4-only
    --proto udp6/tcp6  -> IPv6-only *or* dual-stack, depending on 
                          "net.inet6.ip6.v6only" sysctl (1 -> ipv6-only)

 server/2.4
    --proto udp4/tcp4  -> IPv4-only
    --proto udp6/tcp6  -> dual-stack or IPv6-only, depending on the
                          setting of "--bind [ipv6only]" (default is dual)
    --proto udp/tcp    -> "ask getaddrinfo() what the recommended value for
                          a listening socket is, and use that" - this can
                          result in an IPv4-only (INADDR_ANY) or an IPv6/
                          dual-stack socket (IN6ADDR_ANY_INIT)

                          So, for best results, use "udp6/tcp6" on machines 
                          that have IPv6 active, and only fallback to "udp/tcp"
                          when you *know* that udp6/tcp6 isn't working (e.g.
                          because some smart guy removed ipv6.ko from the 
                          system).

The slightly undefined behaviour of the 2.4/server side wrt "udp/tcp" is
something we should fix to always get dual-stack unless that fails, and
then fall back to IPv4-only - but that's slightly complicated (socket.c)
and needs lots of cross-platform testing, so "nobody has done it yet"

gert

Patch

diff --git a/doc/openvpn.8 b/doc/openvpn.8
index a4189ac2..ca4c652e 100644
--- a/doc/openvpn.8
+++ b/doc/openvpn.8
@@ -413,10 +413,10 @@  Use protocol
 for communicating with remote host.
 .B p
 can be
-.B udp,
-.B tcp\-client,
+.B udp, udp4, udp6
+.B tcp\-client, tcp4\-client, tcp6\-client,
 or
-.B tcp\-server.
+.B tcp\-server, tcp4\-server, tcp6\-server.
 
 The default protocol is
 .B udp
@@ -445,6 +445,37 @@  option) and try again infinite or up to N retries (adjustable via the
 option).  Both TCP client and server will simulate
 a SIGUSR1 restart signal if either side resets the connection.
 
+When using just
+.B udp
+or
+.B tcp
+(not udp4/udp6/tcp4/tcp6) OpenVPN will deploy a dual-stack approach connecting
+to remote hosts and binding to local interfaces.  If a hostname resolves to
+both an IPv4 and IPv6 address, OpenVPN will most commonly try to connect using
+IPv6 first before trying the IPv4 address; this is decided by the operating
+system's resolver.  To enforce OpenVPN to only use either IPv4 or IPv6, the
+.B udp4/tcp4
+and
+.B udp6/tcp6
+variants needs to be used.
+
+A quick overview of what gives the most similar behaviour between OpenVPN 2.3
+and v2.4.
+
+.nf
+.ft 3
+.in +4
+.B \ OpenVPN 2.3\ \ \ \ \ OpenVPN 2.4
+==============================
+ udp             udp4
+ udp6            udp
+ tcp-server      tcp4-server
+ tcp6-server     tcp-server
+ tcp-client      tcp4-client
+ tcp6-client     tcp-client
+.in -4
+.fi
+
 OpenVPN is designed to operate optimally over UDP, but TCP capability is provided
 for situations where UDP cannot be used.
 In comparison with UDP, TCP will usually be