Documentation > Installation > Other distros

Jool Installation

Index

  1. Introduction
    1. Kbuild vs DKMS
  2. Installing Dependencies
  3. Downloading the Code
  4. Compilation and Installation
    1. Installation via Kbuild
    2. Installation via DKMS

Introduction

Jool is seven binaries:

  • Two kernel modules you can hook up to Linux. One of them is the SIIT implementation and the other one is the Stateful NAT64. They are the translating components and do most of the work.
  • Two userspace clients which can be used to configure each module.
  • Two shared objects that iptables uses to enable ip[6]tables -j JOOL[_SIIT]-style rules.
  • An optional userspace daemon that can synchronize state between different NAT64 Jool instances.

This document will explain how to compile and install all of that on most Linux distributions.

In following console segments, $ indicates the command can be executed freely; # means it requires admin privileges.

Kbuild vs DKMS

Before you start, you need to decide whether you will install the modules via Kbuild or DKMS.

Kbuild is Linux’s bare bones module building infrastructure, while DKMS is a more robust framework. Though Kbuild is easier to get started, DKMS is recommended because it has several other benefits. In particular, DKMS takes care of automatically recompiling the modules every time you update your kernel. (If, on the other hand, you choose Kbuild, you will have to do this manually.)

Installing Dependencies

You need a kernel that is supported by the version of Jool that you’re using.

Aside from that, you will need your build essentials. Some distributions already ship them by default, so omit this step in those cases.

Debian CentOS Arch Linux openSUSE Ubuntu Server
user@T:~# apt install build-essential pkg-config
user@T:~# yum install gcc
user@T:~# pacman -S base-devel
user@T:~# zypper install gcc make
user@T:~# apt install gcc make

The modules need your kernel headers:

Ubuntu/Debian CentOS openSUSE Raspberry Pi
user@T:~# apt install linux-headers-$(uname -r)
user@T:~# yum install kernel-devel
user@T:~# yum install kernel-headers
user@T:~# zypper install kernel-source
user@T:~$ # See https://github.com/NICMx/Jool/issues/158

The userspace clients and the daemon need the Development Library and Headers for libnl-genl-3:

user@T:~# apt install libnl-genl-3-dev

The iptables shared object needs the Netfilter xtables Library development files:

user@T:~# apt install libxtables-dev

If you will install Jool via DKMS, you will need DKMS itself:

user@T:~# apt install dkms

If you’re going to clone the git repository, you need git and the autotools:

Ubuntu CentOS
user@T:~# apt install git autoconf
user@T:~# yum install git automake

And if you don’t, you will need a .tar.gz extraction tool:

user@T:~# apt install tar

Downloading the Code

You have two options:

  1. Official tarballs hosted at Downloads.
  2. Cloning the Git repository.
tarballs git clone
$ wget https://github.com/NICMx/releases/raw/master/Jool/jool_3.6.0-rc2.tar.gz
$ tar -xzf jool_3.6.0-rc2.tar.gz
$ git clone https://github.com/NICMx/Jool.git
 

The repository version sometimes includes slight bugfixes not present in the latest official tarball, which you can access by sticking to the latest commit of the master branch. (Tarballs and master are considered stable, other branches are development.)

Compilation and Installation

Choose either Kbuild or DKMS; you don’t need both.

! By the way: We’re aiming for completely immaculate code. If you get compilation warnings in your platform when you issue make, please report them.

Installation via Kbuild

! Let me say it again: A new kernel (including your distro’s automatic kernel updates) will obsolete the binaries generated here. If you insist on using Kbuild, you will need to recompile and reinstall Jool yourself whenever this happens.

tarball git clone
user@T:~$ cd jool-3.6.0-rc2/
user@T:~$
user@T:~$ ./configure
user@T:~$ make
user@T:~# make install
user@T:~$ cd Jool/
user@T:~$ ./autogen.sh
user@T:~$ ./configure
user@T:~$ make
user@T:~# make install

! Kernels 3.7 and up want you to sign your kernel modules to make sure you’re loading them in a responsible manner.

But if your kernel was not configured to require this feature (the kernels of many distros don’t), you won’t have much of an issue here. The output of make install will output “Can’t read private key”; this looks like an error, but is actually a warning, so you can continue the installation peacefully.

Sorry; if your kernel was compiled to require module signing, you probably know what you’re doing, so I’ll skip the instructions to make that work.

Installation via DKMS

With DKMS, the kernel modules and the userspace applications need to be installed separately.

This is how you compile and install the kernel modules:

tarball git clone
user@T:~# dkms install jool-3.6.0-rc2/
user@T:~# dkms install Jool/

And this is how you compile and install the userspace applications:

tarball git clone
user@T:~$ cd jool-3.6.0-rc2/
user@T:~$
user@T:~$ ./configure
user@T:~$ cd src/usr/
user@T:~$ make
user@T:~# make install
user@T:~$ cd Jool/
user@T:~$ ./autogen.sh
user@T:~$ ./configure
user@T:~$ cd src/usr/
user@T:~$ make
user@T:~# make install