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

new file mode 100644

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

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

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