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.

# Install dependencies
# DO NOT install libsodium from package on OpenBSD 5.6 or older
pkg_add git autoconf automake libev libsodium
# Adjust to your needs
export AUTOCONF_VERSION=2.69
export AUTOMAKE_VERSION=1.15
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
# Install
sudo make install
sudo mkdir /etc/mlvpn
sudo cp /usr/local/share/doc/mlvpn/mlvpn.conf /etc/mlvpn/
sudo cp /usr/local/share/doc/mlvpn/mlvpn_updown.sh /etc/mlvpn/
sudo chown -R root /etc/mlvpn
sudo chmod 660 /etc/mlvpn/mlvpn.conf
sudo chmod 700 /etc/mlvpn/mlvpn_updown.sh
# Create a system user for mlvpn (unprivileged)
sudo groupadd _mlvpn
sudo useradd -c "mlvpn Daemon" -d /var/empty -s /sbin/nologin -L daemon -g _mlvpn _mlvpn
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(1) 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(1) 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.

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 used (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. Check your permissions on mlvpn.conf (0600) and mlvpn_updown.sh (0700), owned by root

bandwidth agregation is terribad

TODO

Example scenarios

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

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 examples/mlvpn_updown.sh.

Indices and tables