[Openvpn-devel,v3,15/25] dco: add documentation for ovpn-dco-linux

Message ID 20220805093703.27940-1-a@unstable.cc
State Accepted
Headers show
Series None | expand

Commit Message

Antonio Quartulli Aug. 4, 2022, 11:37 p.m. UTC
Signed-off-by: Antonio Quartulli <a@unstable.cc>

Changes from v2:
* more adjustments

Changes from v1:
* removed text about TCP drop (cannot reproduce at the moment)
* clarified version requirements for p2p and client mode
 Changes.rst                           |   9 ++
 README.dco.md                         | 122 ++++++++++++++++++++++++++
 doc/man-sections/advanced-options.rst |  13 +++
 doc/man-sections/server-options.rst   |   6 ++
 4 files changed, 150 insertions(+)
 create mode 100644 README.dco.md


Frank Lichtenheld Aug. 5, 2022, 12:04 a.m. UTC | #1
On Fri, Aug 05, 2022 at 11:37:03AM +0200, Antonio Quartulli wrote:
> Signed-off-by: Antonio Quartulli <a@unstable.cc>
> ---
> Changes from v2:
> * more adjustments

Acked-By: Frank Lichtenheld <frank@lichtenheld.com>

Gert Doering Aug. 5, 2022, 12:58 a.m. UTC | #2
Taking an easy one out of sequence... (but it means I have to tackle
14/ really quick now, otherwise this is all wrong).

Your patch has been applied to the master branch.

commit fba724e3fc958b5704dc22dd14ec93f4bb4d9e34
Author: Antonio Quartulli
Date:   Fri Aug 5 11:37:03 2022 +0200

     dco: add documentation for ovpn-dco-linux

     Signed-off-by: Antonio Quartulli <a@unstable.cc>
     Acked-by: Frank Lichtenheld <frank@lichtenheld.com>
     Message-Id: <20220805093703.27940-1-a@unstable.cc>
     URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg24817.html
     Signed-off-by: Gert Doering <gert@greenie.muc.de>

kind regards,

Gert Doering


diff --git a/Changes.rst b/Changes.rst
index 67a23c79..275f8d64 100644
--- a/Changes.rst
+++ b/Changes.rst
@@ -79,6 +79,15 @@  Cookie based handshake for UDP server
     shake. The tls-crypt-v2 option allows controlling if older clients are
+Data channel offloading with ovpn-dco
+    2.6.0+ implements support for data-channel offloading where the data packets
+    are directly processed and forwarded in kernel space thanks to the ovpn-dco
+    kernel module. The userspace openvpn program acts purely as a control plane
+    application. Note that DCO will use DATA_V2 packets in P2P mode, therefore,
+    this implies that peers must be running 2.6.0+ in order to have P2P-NCP
+    which brings DATA_V2 packet support.
 Deprecated features
 ``inetd`` has been removed
diff --git a/README.dco.md b/README.dco.md
new file mode 100644
index 00000000..702c5cf3
--- /dev/null
+++ b/README.dco.md
@@ -0,0 +1,122 @@ 
+OpenVPN data channel offload
+2.6.0+ implements support for data-channel offloading where the data packets
+are directly processed and forwarded in kernel space thanks to the ovpn-dco
+kernel module. The userspace openvpn program acts purely as a control plane
+Overview of current release
+- See the "Limitations by design" and "Current limitations" sections for
+  features that are not and/or will not be supported by OpenVPN + ovpn-dco.
+Getting started (Linux)
+- Use a recent Linux kernel. Linux 5.4.0 and newer are known to work with
+  ovpn-dco.
+Get the ovpn-dco module from one these urls and build it:
+* https://gitlab.com/openvpn/ovpn-dco
+* https://github.com/OpenVPN/ovpn-dco
+    git clone https://github.com/OpenVPN/ovpn-dco
+    cd ovpn-dco
+    make
+    sudo make install
+If you want to report bugs please ensure to compile ovpn-dco with
+`make DEBUG=1` and include any debug message being printed by the
+kernel (you can view those messages with `dmesg`).
+Clone and build OpenVPN (or use OpenVPN 2.6+). For example:
+    git clone https://github.com/openvpn/openvpn.git
+    cd openvpn
+    autoreconf -vi
+    ./configure --enable-dco
+    make
+    sudo make install # Or just run src/openvpn/openvpn
+When starting openvpn it will automatically detect DCO support and use the
+kernel module. Add the option `--disable-dco` to disable data channel offload
+support. If the configuration contains an option that is incompatible with
+data channel offloading, OpenVPN will automatically disable DCO support and
+warn the user.
+Should OpenVPN be configured to use a feature that is not supported by ovpn-dco
+or should the ovpn-dco kernel module not be available on the system, you will
+see a message like
+    Note: Kernel support for ovpn-dco missing, disabling data channel offload.
+in your log.
+DCO and P2P mode
+DCO is also available when running OpenVPN in P2P mode without `--pull` / 
+`--client` option. P2P mode is useful for scenarios when the OpenVPN tunnel
+should not interfere with overall routing and behave more like a "dumb" tunnel,
+like GRE.
+However, DCO requires DATA_V2 to be enabled, which is available for P2P mode
+only in OpenVPN 2.6 and later.
+OpenVPN prints a diagnostic message for the P2P NCP result when running in P2P
+    P2P mode NCP negotiation result: TLS_export=1, DATA_v2=1, peer-id 9484735, cipher=AES-256-GCM
+Double check that you have `DATA_v2=1` in your output and a supported AEAD
+cipher (AES-XXX-GCM or CHACHA20POLY1305).
+Routing with ovpn-dco
+The ovpn-dco kernel module implements a more transparent approach to
+configuring routes to clients (aka "iroutes") and consults the main kernel
+routing tables for forwarding decisions.
+- Each client has a VPN IPv4 and/or a VPN IPv6 assigned to it;
+- additional IP ranges can be routed to a client by adding a route with
+  a client VPN IP as the gateway/nexthop (i.e. ip route add a.b.c.d/24 via
+  $VPNIP);
+- due to the point above, there is no real need to add a companion `--route` for
+  each `--iroute` directive, unless you want to blackhole traffic when the
+  specific client is not connected;
+- no internal routing is available. If you need truly internal routes, this can
+  be achieved either with filtering using `iptables` or using `ip rule`;
+- client-to-client behaviour, as implemented in userspace, does not exist:
+  packets always reach the tunnel interface and are then re-routed to the
+  destination peer based on the system routing table.
+Limitations by design
+- Layer 3 (dev tun) only;
+- only the following AEAD ciphers are currently supported: Chacha20-Poly1305
+  and AES-GCM-128/192/256;
+- no support for compression or compression framing:
+  - see also the `--compress migrate` option to move to a setup without
+    compression;
+- various features not implemented since they have better replacements:
+  - `--shaper`, use tc instead;
+  - packet manipulation, use nftables/iptables instead;
+- OpenVPN 2.4.0 is the minimum version required for peers to connect:
+  - older versions are missing support for the AEAD ciphers;
+- topology subnet is the only supported `--topology` for servers;
+- iroute directives install routes on the host operating system, see also
+  Routing with ovpn-dco.
+Current implementation limitations
+- `--persist-tun` not tested;
+- IPv6 mapped IPv4 addresses need Linux 5.4.189+/5.10.110+/5.12+ to work;
+- some incompatible options may not properly fallback to non-dco;
+- no per client statistics. Only total statistics available on the interface.
diff --git a/doc/man-sections/advanced-options.rst b/doc/man-sections/advanced-options.rst
index 5157c561..d5a6b4f2 100644
--- a/doc/man-sections/advanced-options.rst
+++ b/doc/man-sections/advanced-options.rst
@@ -91,3 +91,16 @@  used when debugging or testing out special usage scenarios.
   *(Linux only)* Set the TX queue length on the TUN/TAP interface.
   Currently defaults to operating system default.
+  Disables the opportunistic use of data channel offloading if available.
+  Without this option, OpenVPN will opportunistically use DCO mode if
+  the config options and the running kernel supports using DCO.
+  Data channel offload currently requires data-ciphers to only contain
+  AEAD ciphers (AES-GCM and Chacha20-Poly1305) and Linux with the
+  ovpn-dco module.
+  Note that some options have no effect or cannot be used when DCO mode
+  is enabled.
+  On platforms that do not support DCO ``disable-dco`` has no effect.
diff --git a/doc/man-sections/server-options.rst b/doc/man-sections/server-options.rst
index 04f4b4fb..54ea8b66 100644
--- a/doc/man-sections/server-options.rst
+++ b/doc/man-sections/server-options.rst
@@ -325,6 +325,12 @@  fast hardware. SSL/TLS authentication must be used in this mode.
   from the kernel to OpenVPN. Once in OpenVPN, the ``--iroute`` directive
   routes to the specific client.
+  However, when using DCO, the ``--iroute`` directive is usually enough
+  for DCO to fully configure the routing table. The extra ``--route``
+  directive is required only if the expected behaviour is to route the
+  traffic for a specific network to the VPN interface also when the
+  responsible client is not connected (traffic will then be dropped).
   This option must be specified either in a client instance config file
   using ``--client-config-dir`` or dynamically generated using a
   ``--client-connect`` script.