== OpenVPN Data Channel Offload in the linux kernel (ovpn-dco) ==

** MAINTENANCE MODE **
This repository is currently in maintenance mode and we only accept important
and meaningful bugfixes.

For the new version of the DCO linux kernel module, please refer to the following
repository:

  https://github.com/OpenVPN/ovpn-net-next

== License ==

ovpn-dco is released under the terms of the GPLv2 license.


== Submitting patches ==

Patches for ovpn-dco can be submitted to the openvpn-devel mailing list at
openvpn-devel@lists.sourceforge.net

The patch subject *must* start with "ovpn-dco:". This way patches for this
project can easily be dinstinguished from patches for other projects.
At the same time it is part of the kernel guidelines to have subjects starting
with a prefix identifying the component being modified (ovpn-dco in this case).

To generate patches, please use git-format-patch and git-send-email.


== Building ==

To build the ovpn-dco kernel module, just type:

$ make

in the root folder.
The Makefile will autodetect your running kernel and will try to use its
headers to get the code compiled.

If you want to build ovpn-dco against a kernel different from the one
running on the host, run:

$ make KERNEL_SRC=/path/to/the/kernel/tree

The control is passed to the kernel Makefile, therefore any kernel Makefile
argument can be specified on the command line and it will be passed
automatically.

Once done building, executing the command:

$ make install

will install the ovpn-dco.ko kernel module in the updates/ subfolder of
the kernel modules directory on your system.
It normally means `/lib/modules/$(uname -r)/updates/`.


== Testing ==

A basic pre-shared-key client (called ovpn-cli) is also provided in the
tests/ folder.
It can be compiled by typing:

$ make tests

One way to test ovpn-dco is to run multiple tun interfaces on the same hosts
associated with different network namespaces.
A script that takes care of setting up 2 NS and 2 interfaces is provided at
`tests/netns-test.sh`.

By running this script from the tests folder as follows:

$ cd tests
$ ./netns-test.sh

the host will configure a basic tunnel using a pre-shared key (the ovpn-cli
binary is used for this).

The 2 namespaces are named `peer0` and `peer1`. Each interface is respectively
configured with `5.5.5.1/24` and `5.5.5.2/24`.

At this point it is possible to make a basic ping test by executing:

$ ip netns exec peer0 ping 5.5.5.2

If the command above works, it means that the 2 interfaces are exchanging
traffic properly over the ovpn link.

Note: running kernel must have network namespaces support compiled in, but it
is fairly standard on modern Linux distros.

For reference, a sample kernel config file is provided in tests/qemu/config.net-next.
This config file is used for compiling a minimal kernel based on the net-next tree.


To run net-next, it's better to rely on any VM, so that the developer does not need
to worry about bugs or spurious kernel crashes. For this reason qemu is suggested
(but any other VM is fine too). At `tests/qemu/launch_deb2.sh` a sample script
can be found that shows how qemu can be launched for testing.


== Limitations ==

This is a list of current limitations which are planned to be removed as we move forward:
* Only AEAD mode and 'none' (with no auth) supported
* Only AES-GCM and CHACHA20POLY1305 ciphers supported