Documentation > Basic Tutorials > SIIT

Basic SIIT Run


  1. Introduction
  2. Sample Network
  3. Jool
  4. Testing
  5. Stopping Jool
  6. Afterwords


This document explains how to run Jool in stock SIIT mode. Follow the link for more details on what to expect.

Software-wise, only a successful install of Jool’s kernel module is required. The userspace application is out of the scope of this document on purpose.

In case you’re wondering, you can follow along these tutorials using virtual machines or alternate interface types just fine (Jool is not married to physical “ethX” interfaces).

Sample Network

You don’t need all the nodes shown in the diagram to follow along; you can get away with only A, T and V; the rest are very similar to A and V and are shown for illustrative purposes only.

Figure 1 - Sample Network

We will pretend I have address block to distribute among my IPv6 nodes.

Jool requires T to be Linux. The rest can be anything you want, as long as it implements the network protocol it’s connected to. You are also free to configure the networks using any manager you want.

For the sake of simplicity however, the examples below assume every node is Linux and everything is being configured statically using the well-known ip command (and friends). Depending on your distro, your mileage might vary on how to get the network manager out of the way (assuming that’s what you want). Just to clarify, the point of service network-manager stop below is to claim control over your interface addresses and routes (otherwise the ip commands might be ineffectual).

Also to simplify, routing will be reduced to default all unknown traffic towards T. Note that there is nothing martian about anyone’s configuration otherwise.

This is nodes A through E:

user@A:~# service network-manager stop
user@A:~# /sbin/ip link set eth0 up
user@A:~# # Replace ".8" depending on which node you're on.
user@A:~# /sbin/ip addr add 2001:db8:: dev eth0
user@A:~# /sbin/ip route add default via 2001:db8::

Nodes V through Z:

user@V:~# service network-manager stop
user@V:~# /sbin/ip link set eth0 up
user@V:~# # Replace ".16" depending on which node you're on.
user@V:~# /sbin/ip addr add dev eth0
user@V:~# /sbin/ip route add default via

Node T:

user@T:~# service network-manager stop
user@T:~# /sbin/ip link set eth0 up
user@T:~# /sbin/ip addr add 2001:db8:: dev eth0
user@T:~# /sbin/ip link set eth1 up
user@T:~# /sbin/ip addr add dev eth1

Because we haven’t turned T into a translator yet, nodes A through E still cannot interact with V through Z, but you might want to make sure T can ping everyone before continuing.

Next, enable forwarding on T.

user@T:~# sysctl -w net.ipv4.conf.all.forwarding=1
user@T:~# sysctl -w net.ipv6.conf.all.forwarding=1

Note! These sysctls make sense conceptually, but Jool doesn’t actually depend on them, currently.

What happens is, if you omit them in kernels 3.5 and below, everything will seem to work, but Linux will drop some important ICMP traffic. Skipping them in kernels 3.6 and above doesn’t actually yield known adverse consequences.

Whether this inconsistency is a bug in older or newer kernels is a rather philosophical topic. On the other hand, Jool 4.0 will almost certainly require forwarding, so you might as well start preparing your scripts.

The only caveat you need to keep in mind before inserting Jool is that you need to get rid of receive offloads in the translating machine. Do that by means of ethtool:

user@T:~# ethtool --offload eth0 gro off
user@T:~# ethtool --offload eth0 lro off
user@T:~# ethtool --offload eth1 gro off
user@T:~# ethtool --offload eth1 lro off

(If it complains it cannot change something, keep in mind it can already be off; run sudo ethtool --show-offload [interface] to figure it out.)


This is the insertion syntax:

Most Distros OpenWRT
user@T:~# /sbin/modprobe [--first-time] jool_siit \
		[pool6=<IPv6 prefix>] \
		[blacklist=<IPv4 prefixes>] \
		[pool6791=<IPv4 prefixes>] \
user@T:~# insmod jool_siit \
		[pool6=<IPv6 prefix>] \
		[blacklist=<IPv4 prefixes>] \
		[pool6791=<IPv4 prefixes>] \

See Kernel Module Options for a description of each argument. The following suffices for our sample network:

Most Distros OpenWRT
user@T:~# /sbin/modprobe --first-time jool_siit pool6=2001:db8::/96
user@T:~# insmod jool_siit pool6=2001:db8::/96

That means the IPv6 representation of any IPv4 address is going to be 2001:db8::<IPv4 address>. See below for examples.


If something doesn’t work, try the FAQ.

Try to ping A from V like this:

user@V:~$ ping
PING ( 56(84) bytes of data.
64 bytes from icmp_seq=1 ttl=63 time=7.45 ms
64 bytes from icmp_seq=2 ttl=63 time=1.64 ms
64 bytes from icmp_seq=3 ttl=63 time=4.22 ms
64 bytes from icmp_seq=4 ttl=63 time=2.32 ms
--- ping statistics ---
4 packets transmitted, 4 received, 0% packet loss, time 3006ms
rtt min/avg/max/mdev = 1.649/3.914/7.450/2.249 ms

Then ping V from A:

user@A:~$ ping6 2001:db8::
PING 2001:db8:: 56 data bytes
64 bytes from 2001:db8::c000:210: icmp_seq=1 ttl=63 time=3.57 ms
64 bytes from 2001:db8::c000:210: icmp_seq=2 ttl=63 time=10.5 ms
64 bytes from 2001:db8::c000:210: icmp_seq=3 ttl=63 time=1.38 ms
64 bytes from 2001:db8::c000:210: icmp_seq=4 ttl=63 time=2.63 ms
--- 2001:db8:: ping statistics ---
4 packets transmitted, 4 received, 0% packet loss, time 3003ms
rtt min/avg/max/mdev = 1.384/4.529/10.522/3.546 ms

How about hooking up a server in X and access it from D:

Figure 1 - IPv6 TCP from an IPv4 node

Then maybe another one in C and request from W:

Figure 2 - IPv4 TCP from an IPv6 node

Stopping Jool

Revert the modprobe using the -r flag to shut down Jool:

Most Distros OpenWRT
user@T:~# /sbin/modprobe -r jool_siit
user@T:~# rmmod jool_siit


  1. More complex setups might require you to consider the MTU notes.
  2. The modprobe insertion and removal mechanism is fine if all you need is a simple single SIIT, but if you want to enclose it in a network namespace, or need multiple Jool instances in a single machine, check out --instance.
  3. Please note that none of what was done in this tutorial survives reboots! Documentation on persistence will be released in the future.

The next tutorial covers EAMT SIIT. It is also recommended because it introduces usage to Jool’s userspace applications.