ovpn-dco

ovpn-dco copied to clipboard

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

This repository contains a linux kernel module implementing the data channel of the OpenVPN protocol in the linux kernel.

This kernel module allows OpenVPN to offload any data plane management to the linux kernel, thus allowing it to exploit any Linux low level API, while avoiding expensive and slow payload transfer between kernel space and user space.

** NOTE ** ovpn-dco is currently under heavy development, therefore neither its userspace API nor the code itself is considered stable and may change radically over time.

** Kernel compatibility ** ovpn-dco is developed against the latest David Miller's net-next tree. However, a compat layer is provided to allow people to compile ovpn-dco against older kernel versions.

== 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 [email protected]

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