mlvpn - documentation

MLVPN is Open Source software, licensed under the BSD License.

Source code is available on github https://github.com/zehome/MLVPN/

User guide

What is mlvpn

mlvpn is a piece of software, similar to OpenVPN, which can create a network tunnel between two computers.

mlvpn encapsulates network packets, using UDP and send them encrypted over the internet to another location.

The primary use of mlvpn is to create bonded/aggregated network links in order to benefit from the bandwidth of multiple links.

Still, mlvpn can be used as a regular secure tunnel daemon, capable of handling failover scenarios.

Features

  • Bandwidth aggregation of multiple internet connections
  • Automatic failover, without changing IP addresses or interrupting TCP connections in case of a failure
  • Encrypt and authenticate connections using libsodium.
  • Hot configuration reload (by signaling SIGHUP)
  • Scriptable monitoring
  • Remote monitoring through UNIX socket or TCP/HTTP socket. (JSON API)

Limitations

Getting started in mlvpn

Introduction

If you haven’t, read What is mlvpn.

Installation

Debian wheezy

If you trust me, you can use the mlvpn debian repository for Debian wheezy:

# Add the mlvpn repository signature
sudo apt-key adv --keyserver pgp.mit.edu --recv 3324C952
echo "deb http://debian.mlvpn.fr wheezy/" >/etc/apt/sources.list.d/mlvpn.list
sudo apt-get update
sudo apt-get install mlvpn

Warning

PLEASE DO NOT USE THIS REPOSITORY YET.

Debian jessie/sid

If you trust me, you can use the mlvpn debian repository for Debian sid:

# Add the mlvpn repository signature
sudo apt-key adv --keyserver pgp.mit.edu --recv 3324C952
echo "deb http://debian.mlvpn.fr unstable/" >/etc/apt/sources.list.d/mlvpn.list
sudo apt-get update
sudo apt-get install mlvpn
OpenBSD

Refer to the README.OpenBSD file inside the mlvpn repository for OpenBSD build instructions.

FreeBSD
pkg install git libev libsodium
git clone --branch freebsd https://github.com/zehome/MLVPN mlvpn
cd mlvpn
make

Note

This port is not tested often and may break.

Install from source

Please refer to the README.md file inside the mlvpn repository for source build instructions.

Configuration

mlvpn is using two configuration files for every tunnel you want to make.

mlvpn.conf

mlvpn.conf(5) is an ini-style configuration. It’s used to set the interface name, the secret-key, network configuration of the multiple links and path to the second configration script.

Please refer the the mlvpn.conf(5) manpage for further informations.

Note

access the manpage using: man mlvpn.conf

mlvpn_updown.sh

mlvpn_updown.sh is a script called by mlvpn when status change occurs in mlvpn.

For example, when mlvpn is launched and a link is activated, mlvpn_updown.sh is called in order to bring the tunnel device up and ready for communication.

Checking mlvpn status using ps

You can check what mlvpn is doing at any time by using standard unix command ps.

mlvpn spawns two process. One privileged running as root with [priv] in it’s name.

The other running as the user you have selected with running mlvpn –user.

Example:

root     30222 30221  0 23:17 pts/8    00:00:00 mlvpn: adsl3g [priv]
ed       30223 30222  0 23:17 pts/8    00:00:00 mlvpn: adsl3g !3g @adsl

This output means tunnel 3g is down, and adsl is up.

Tunnel prefix reference
  • ‘!’ means down
  • ‘@’ means up & running
  • ‘~’ means up but lossy (above the configured threshold)

Hot reloading mlvpn configuration

mlvpn supports hot configuration reloading. You can reload the configuration by sending the SIGHUP signal to any process.

kill -HUP $(pidof mlvpn)
# or pkill -HUP mlvpn

Warning

Hot reloading the configuration forces every established link to be disconnected and reconnected.

Security in mlvpn

Security is a very strong focus for the mlvpn project.

mlvpn tries it’s best to protect your systems and your datas by using privilege separation, strong cryptography, and continuous integration.

Privilege separation

mlvpn needs to access the kernel in order to create a tunnel device, and in order to configure the device. (needs root)

In order to limit the scope of privileges, mlvpn spawns a small process, called the [priv] process, then another one.

The priv process only performs the tasks where it needs privileges:
  • tunnel interface creation
  • tunnel interface configuration
  • open the mlvpn configuration file
  • name resolution (requires to be out of the chroot)

The other process is run as an unprivileged user (usually _mlvpn or mlvpn), in a chroot. It handles all the hard work exposed to the outside world.

This is the same technique used in OpenSSH.

Cryptography

mlvpn uses libsodium for all the cryptographic needs.

In particular, mlvpn uses secret-key authenticated encryption.

Cryptography is used for two purposes:
  • Authentication
  • Data protection
Authentication

mlvpn just uses a very simple protocol in order to make sure it communicates only if the two sides share the same secret key.

The secret key is stored as plain text in the mlvpn configuration file.

This configuration file must be owned by root, and chmoded to 0600 to prevent any other user from reading / writing to it.

Every control packet sent by mlvpn is encrypted and authenticated by both sides.

Authentication is done using Poly1305 MAC.

Encryption

Data packets can be encrypted/authenticated as well, but this can be disabled by using the cleartext_data configuration flag.

This can be usefull if your on a budget, with lack of CPU.

If your data are going to the internet anyway, there is no point in trying to cipher them another time using mlvpn. (encrypting an ssh or https connections does not give you much benefit)

Encryption is done using the XSalsa20 algorithm.

Fequently Asked Questions

How much mlvpn costs

Free. mlvpn is licenced under the open source BSD licence.

Troubleshooting

mlvpn does not launch

Launch mlvpn manually in debug mode: .. code-block:: sh

mlvpn –user _mlvpn -c /etc/mlvpn.conf –debug -Dprotocol -v

Check your permissions: .. code-block:: sh

chmod 0600 /etc/mlvpn/mlvpn.conf chmod 0700 /etc/mlvpn/mlvpn_updown.sh chown root /etc/mlvpn/mlvpn.conf /etc/mlvpn/mlvpn_updown.sh
mlvpn does not create the tunnel interface

Follow mlvpn does not launch.

Example scenarios

Filtering

The filtering system in mlvpn can be used when you use mlvpn in an aggregated scenario.

Some protocols will suffer a lot from packets received out-of-order, or from packet loss, like VoIP systems.

In order to avoid that problem, mlvpn includes a system called “filters”.

In mlvpn.conf, the [filters] section defines static paths for the matched expression.

Expressions are standard BPF expressions. (like in tcpdump or any other libpcap program)

Filters are order sensitive.

ADSL and SDSL with reordering enabled and VoIP

In such a scenario, we want to aggregate the traffic from every protocol except for SIP UDP port 5060.

mlvpn.conf

[general]
# This configuration is not complete, please refer to the example
# configuration file provided with your distribution package.
#
reorder_buffer_size 64
loss_tolerence = 50

[filters]
sdsl = udp port 5060
adsl = udp port 5060

[sdsl]
remotehost = sdslgw.mlvpn.fr
remoteport = 5080

[adsl]
remotehost = adslgw.mlvpn.fr
remoteport = 5081

Explanation

This configuration, when all links are up forces packets matching the “udp port 5060” BPF expression to be sent only on the sdsl link.

If the sdsl link is not available, then the second matching interface will be choosen.

Filters are EXCLUSIVE FIRST MATCH. That means if a packet matches an expression, and the interface is ready to receive data, filtering STOPS and the packet is sent.

Order is VERY important is that situation in order to let you choose the prefered path.

Developer guide

Building debian packages for mlvpn

Requirements

sudo apt-get install pbuilder cowbuilder git-buildpackage

Prepare build environments

Configure pbuilder

.pbuilderrc:

# Template loosely taken from http://www.kirya.net/articles/build-i386-packages-on-amd64/
# do not specify variables when running cowbuilder --create or --update
if [ -f debian/changelog ]; then
        [ -z "$ARCH" ] && ARCH=$(dpkg --print-architecture)
        [ -z "$DIST" ] && DIST=$(dpkg-parsechangelog | sed -n 's/^Distribution: //p')
fi
PDEBUILD_PBUILDER="cowbuilder --build --basepath /var/cache/pbuilder/base-${DIST}_${ARCH}.cow"
DEBBUILDOPTS="-d ${OPTS}"
ARCHITECTURE=${ARCH}
BUILDRESULT=~/build-area
MIRRORSITE=http://ftp.fr.debian.org/debian
EXTRAPACKAGES="$EXTRAPACKAGES lintian apt-utils"
AUTO_DEBSIGN=yes
HOOKDIR=${HOME}/.pbuilder/hooks/
PKGNAME_LOGFILE_EXTENTION="_${ARCH}.build"
# Allow a local repository for external backported dependencies.
OTHERMIRROR="deb [trusted=yes] file://${HOME}/build-area ./"
BINDMOUNTS="${HOME}/build-area"
Generate base images for pbuilder
for arch in i386 amd64; do
    sudo cowbuilder --config ~/.pbuilderrc --create --distribution wheezy --architecture $arch --basepath /var/cache/pbuilder/base-wheezy_$arch.cow
    sudo cowbuilder --config ~/.pbuilderrc --update --distribution wheezy --architecture $arch --basepath /var/cache/pbuilder/base-wheezy_$arch.cow
done

Build packages

libsodium13 (for wheezy)
dget -x http://ftp.fr.debian.org/debian/pool/main/libs/libsodium/libsodium_1.0.0-1.dsc
cd libsodium_1.0.0
for dist in wheezy; do
    for arch in amd64 i386; do
        DIST=$dist ARCH=$arch pdebuild --debbuildopts -b
    done
done
mlvpn
git clone git@github.com:zehome/MLVPN.git mlvpn
cd mlvpn
git checkout debian-unstable
for dist in wheezy; do
    for arch in amd64 i386; do
        DIST=$dist ARCH=$arch git-buildpackage --git-builder="pdebuild --debbuildopts -b"
    done
done

Building mlvpn on OpenBSD

Install since OpenBSD 5.9

mlvpn is part of OpenBSD port system since OpenBSD 5.9. You can install it as a package:

pkg_add mlvpn

Installing requirements

pkg_add git autoconf automake libev libsodium

Building mlvpn

export AUTOCONF_VERSION=2.69
export AUTOMAKE_VERSION=1.14
export CPPFLAGS="-I/usr/local/include $CPPFLAGS"
export LDFLAGS="-L/usr/local/lib $LDFLAGS"
git clone https://github.com/zehome/MLVPN mlvpn
cd mlvpn
./autogen.sh
./configure
make

Configuration

Example configuration files for OpenBSD are located in /usr/local/share/examples/mlvpn/.

Indices and tables