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
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
accepted.
+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
+application.
+
+
+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
+
+e.g.
+
+ 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
+mode:
+
+ 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.
+--disable-dco
+ 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.
--
2.35.1
_______________________________________________
Openvpn-devel mailing list
Openvpn-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/openvpn-devel
