Documentation > Installation > Kernel modules

Kernel Modules Installation

Index

  1. Introduction
  2. Requirements
  3. Downloading the Code
  4. Compilation and Installation
    1. Installation via DKMS
    2. Installation via Kbuild

Introduction

Jool is five binaries:

  1. 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 all you need to get started; this document explains how to install them.
  2. Two userspace applications which can be used to configure each module. They have their own installation document.
  3. One userspace daemon used to synchronize sessions between different Jool kernel modules.

Requirements

Because there are so many different Linux versions out there, distributing the modules’ binaries is not feasible; you need to compile them yourself.

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

Valid kernels

Jool supports kernels starting from Linux 3.2. uname -r will print your kernel version.

$ /bin/uname -r
3.5.0-45-generic
$ # OK, fine.

Build Essentials

Several distributions already include them; omit this step in those cases.

Debian CentOS Arch Linux openSUSE Ubuntu Server
# apt-get install build-essential
# yum install gcc
# pacman -S base-devel
# zypper install gcc make
# apt-get install gcc make

Kernel headers

All kernel modules depend on them; they tell Jool the parameters Linux was compiled with. Most distros host them in their repositories.

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

Network interfaces

Translating packets using only one interface is possible, but two (one for IPv4, one for IPv6) is more intuitive.

Therefore, if you’re using these documents for learning purposes, two interfaces are recommended:

$ /sbin/ip link show
(...)
2: eth0: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN qlen 1000
    link/ether 08:00:27:3d:24:77 brd ff:ff:ff:ff:ff:ff
3: eth1: <BROADCAST,MULTICAST> mtu 1500 qdisc noop state DOWN qlen 1000
    link/ether 08:00:27:ca:18:c8 brd ff:ff:ff:ff:ff:ff

DKMS

DKMS is a framework for kernel module management. It is optional but recommended (reasons below).

# apt-get install dkms

Downloading the Code

You have two options:

  1. Official releases are hosted in the Download page.
    These will prove less convoluted when you install the userspace applications.
  2. There’s the Git repository (“Clone or download” > “Download ZIP”).
    If you know your git, you can also clone it: git clone https://github.com/NICMx/Jool.git
    The repository version might include slight bugfixes not present in the latest official release, which you can access by sticking to the latest commit of the master branch (we do all the risky development elsewhere).

Note! The Git repository was recently renamed from “NAT64” to “Jool”. Links to the old name should be automatically redirected to the new one so this shouldn’t be too confusing.

Compilation and Installation

You have two options: Kbuild and DKMS.

Kbuild is the bare bones module building infrastructure, and (as long as your kernel was compiled with kernel module support) your system most likely already has it.

On the other hand, DKMS is recommended because it is far more robust. It allows creating packages for deb/rpm-based distributions containing pre-built kernel modules, handles recompiling the binaries whenever the kernel gets updated, and has a well-documented uninstallation mechanism.

Installation via DKMS

Official release Git version
$ unzip Jool-<version>.zip
# dkms install Jool-<version>
$ unzip master.zip
# dkms install Jool-master

Installation via Kbuild

! Keep in mind: Module binaries depend on kernel version. The binaries generated here will become obsolete when you update your kernel. If you insist on using Kbuild, you need to recompile/reinstall Jool yourself whenever this happens.

Official release Git version
$ unzip Jool-<version>.zip
$ cd Jool-<version>/mod
$ make
# make install
$ unzip master.zip
$ cd Jool-master/mod
$ make
# 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.

Note! If you only want to compile the SIIT binary, you can speed things up by running the make commands in the mod/stateless folder. Similarly, if you only want the NAT64, do so in mod/stateful.