Basic SIIT Run

Index

Introduction
Sample Network
Jool
Testing
Stopping Jool
Afterwords

Introduction

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

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).

If you intend on using iptables Jool, basic familiarity with iptables is recommended.

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 198.51.100.8/29 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::198.51.100.8/120 dev eth0
user@A:~# /sbin/ip route add default via 2001:db8::198.51.100.1

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 192.0.2.16/24 dev eth0
user@V:~# /sbin/ip route add default via 192.0.2.1

Node T:

user@T:~# service network-manager stop
user@T:~# 
user@T:~# /sbin/ip link set eth0 up
user@T:~# /sbin/ip addr add 2001:db8::198.51.100.1/120 dev eth0
user@T:~# 
user@T:~# /sbin/ip link set eth1 up
user@T:~# /sbin/ip addr add 192.0.2.1/24 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.

Also, enable forwarding on T.

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

Jool

First, teach your kernel what SIIT is by attaching the jool_siit module to your kernel:

user@T:~# /sbin/modprobe jool_siit

user@T:~# insmod jool_siit

Then, create a SIIT instance and perform the bare minimum configuration:

user@T:~# # Create a Jool iptables instance named "example."
user@T:~# # Also, establish that the IPv6 representation of any IPv4 address should be
user@T:~# # `2001:db8::<IPv4 address>`. (See sections below for examples.)
user@T:~# jool_siit instance add "example" --iptables  --pool6 2001:db8::/96
user@T:~# 
user@T:~# # Tell iptables which traffic should be handled by our newly-created instance:
user@T:~# 
user@T:~# # IPv6: only packets from 2001:db8::198.51.100.8/125 to 2001:db8::192.0.2
user@T:~# ip6tables -t mangle -A PREROUTING \
>		-s 2001:db8::198.51.100.8/125 -d 2001:db8::192.0.2.0/120 \
>		-j JOOL_SIIT --instance "example"
user@T:~# # IPv4: Only packets from 192.0.2 to 198.51.100.8/29
user@T:~# iptables  -t mangle -A PREROUTING \
>		-s 192.0.2.0/24 -d 198.51.100.8/29 \
>		-j JOOL_SIIT --instance "example"

user@T:~# # Create a Jool iptables instance named "example."
user@T:~# # Also, establish that the IPv6 representation of any IPv4 address should be
user@T:~# # `2001:db8::<IPv4 address>`. (See sections below for examples.)
user@T:~# jool_siit instance add "example" --netfilter --pool6 2001:db8::/96 
user@T:~#
user@T:~# # All traffic gets SIIT'd in Netfilter mode.

Here’s Jool documentation on instance.

About those iptables rules:

Notice that -s and -d are two standard iptables matches I relatively arbitrarily chose according to the network provided. As per iptables contracts, you should be able to combine any matches as needed.

As far as transport protocols are concerned, SIIT Jool knows how to handle TCP and UDP (as well as ICMP if you count it). (By “know how to handle” I mean “update checksum pseudoheader” and other minor quirks.) Other transport protocols are translated on a best-effort basis. (ie. Jool translates the IP header, copies the rest as is, and hopes for the best.) This is the reason why we chose not to narrow the rules further by means of the --protocol match.

If you do choose to use the --protocol match, please do include a rule that matches ICMP, as it’s important that you don’t prevent the translation of ICMP errors, because they are required for imperative Internet upkeeping (such as Path MTU Discovery).

Testing

If something doesn’t work, try the FAQ. In particular, if you face noticeably low performance, try disabling offloads.

Try to ping A from V like this:

user@V:~$ ping 198.51.100.8
PING 198.51.100.8 (198.51.100.8) 56(84) bytes of data.
64 bytes from 198.51.100.8: icmp_seq=1 ttl=63 time=7.45 ms
64 bytes from 198.51.100.8: icmp_seq=2 ttl=63 time=1.64 ms
64 bytes from 198.51.100.8: icmp_seq=3 ttl=63 time=4.22 ms
64 bytes from 198.51.100.8: icmp_seq=4 ttl=63 time=2.32 ms
^C
--- 198.51.100.8 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::192.0.2.16
PING 2001:db8::192.0.2.16(2001:db8::c000:210) 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
^C
--- 2001:db8::192.0.2.16 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

Destroy your instance by reverting the instance add:

user@T:~# ip6tables -t mangle -D PREROUTING \
>		-s 2001:db8::198.51.100.8/125 -d 2001:db8::192.0.2.0/120 \
>		-j JOOL_SIIT --instance "example"
user@T:~# iptables  -t mangle -D PREROUTING \
>		-s 192.0.2.0/24 -d 198.51.100.8/29 \
>		-j JOOL_SIIT --instance "example"
user@T:~# jool_siit instance remove "example"

 
 
 
 
 
 
user@T:~# jool_siit instance remove "example"

And unteach SIIT from your kernel by reverting the modprobe if you want:

user@T:~# /sbin/modprobe -r jool_siit

user@T:~# rmmod jool_siit

Afterwords

More complex setups might require you to consider the MTU notes.
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.