Userspace Application

-- WIP

This is what you can do with the userspace application under the usr/ folder. See Static Bindings for an intro.

--pool6

Syntax:

jool --pool6 [<operation>] [--prefix <prefix>]

Arguments:

<operation> := --display | --add | --remove
<prefix> := <prefix address>/<prefix length>

Description:

Interacts with Jool's IPv6 pool. The pool dictates which packets coming from the IPv6 side are processed; if an incoming packet's destination address has one of the IPv6 prefixes, the packet is translated. Otherwise it is handed to the kernel to either be forwarded in some other way or handed to the upper layers.

About the operations:

• Using --display, the application prints Jool's current prefixes. The --prefix parameter is ignored. This is the default operation.
• Using --add, Jool adds the --prefix prefix to the pool.
• Using --remove, Jool deletes the --prefix prefix from the pool.

Examples:

# Display the current prefixes.
./jool --pool6
# Remove the default prefix.
./jool --pool6 --remove --prefix 64:ff9b::/96
# Return the default prefix.
./jool --pool6 --add --prefix 64:ff9b::/96

--pool4

Syntax:

jool --pool4 [<operation>] [--address <IPv4 address>]

Arguments:

<operation> := --display | --add | --remove

Description:

Interacts with Jool's IPv4 pool. The pool dictates which packets coming from the IPv4 side are processed; if an incoming packet's destination address is listed in the pool, the packet is translated. Otherwise it is handed to the kernel to either be forwarded in some other way or handed to the upper layers.

About the operations:

• Using --display, the application prints Jool's current addresses. The --address parameter is ignored. This is the default operation.
• Using --add, Jool adds <IPv4 address> to the pool.
• Using --remove, Jool deletes <IPv4 address> from the pool.

Examples:

# Display the current addresses.
./jool --pool4
# Remove one of default addresses.
./jool --pool4 --remove --address 192.168.2.2
# Return the address.
./jool --pool4 --add --address 192.168.2.2

--bib

Syntax:

jool --bib [<operation>] <protocols> [--bib4 <bib4>] [--bib6 <bib6>]

Arguments:

<operation> := --display | --add | --remove
<protocols> := [--tcp] [--udp] [--icmp]
<bib4> := <IPv4 address>#(<port> | <ICMP identifier>)
<bib6> := <IPv6 address>#(<port> | <ICMP identifier>)

Description:

Interacts with Jool's Binding Information Base (BIB). Records in this database map IPv6 transport addresses (of the IPv6 nodes the NAT64 is servicing) with their current IPv4 transport address (from the NAT64's pool). For example, if you see the following output:

$ jool --bib --tcp
TCP:
[Dynamic] 4.4.4.4#44 - 6::6#66
  (Fetched 1 entries.)

Then some node from the IPv4 side is chatting 6::6 on port 66 using the TCP protocol. Jool is fooling the IPv4 node into thinking that 6::6#66's address is 4.4.4.4 on port 44. If you want more details on the relationship (such as the IPv4 node's address), head over to --session.

The BIB is a very fundamental aspect of stateful NAT64. If you want Jool to be able to translate a packet stream, then you need a corresponding record in the BIB.
When translating from IPv6 to IPv4, Jool has enough information to create bindings on its own. As such, you do not need to create manual bindings for traffic IPv6 nodes are going to start.
Jool cannot create entries when traffic is started from IPv4 because there's not enough information to create the record. If IPv4 nodes are supposed to be able to start communication (eg. you want to publish a IPv6 node's service to the IPv4 world) then you need to create manual bindings (here's the walkthrough).

(When I say "start communication" I mean the first packet in a stream. If the IPv4 node is going to answer a request from a IPv6, it counts as a packet from the same stream. Hence you don't need static BIB entries for these.)

Jool automatically kills dynamic entries once their sessions expire; Jool never automatically kills static entries. Both kind of entries can be deleted manually.

The database consists of three separate tables; one for TCP bindings, one for UDP bindings, and one for ICMP bindings. As a result, if you add an entry (eg. 66::66#6 <-> 44.44.44.44#4) manually to one of the tables (eg. TCP), then Jool will not attempt to translate a first IPv4 request to the same address#port and different protocol (eg. 44.44.44.44#4 on UDP).

About the operations:

• Using --display, the application prints Jool's current BIB. --bib6 and --bib4 are ignored. This is the default operation.
• Using --add, Jool adds the entry resulting from the --bib6 and --bib4 paremeters to the BIB. Note that the --bib4 component is an address assigned to the NAT64, so make sure you have added it to the IPv4 pool.
• Using --remove, Jool deletes the entry. Since both components are unique accross all entries from the same table, you only need to supply one of the --bib* arguments.

About the protocols:

The command will only affect the tables mentioned by these parameters.

Examples:

# Display only the TCP and the UDP tables.
./jool --bib --display --tcp --udp
# Add an entry to the UDP table.
./jool --bib --add --udp --bib6 6::6#66 --bib4 4.4.4.4#44
# Remove the entry we just added.
./jool --bib --remove --udp --bib6 6::6#66

--session

Syntax:

jool --session [<operation>] <protocols>

Arguments:

<operation> := --display
<protocols> := [--tcp] [--udp] [--icmp]

Description:

Sessions mostly exist so the NAT64 can decide when BIB entries should die. You can also use them to know exactly who is speaking to your IPv6 nodes. In a future release you will also be able to define filtering policies based on them.

When you create a static BIB entry, it's normally because you want to publish a service to the IPv4 network. Several IPv4 nodes might then talk to your server at the same time, and because the entry only stores local IPv4 address, they will all use the same one. For each BIB entry, there are one or several session entries. Each session entry describes one connection.

You can use this command to get details on each connection's relevant members.

About the operations:

This pretty much only exists for symmetry. The only supported operation is the default one, so you can ignore it if you want.

About the protocols:

The command will filter out the tables not mentioned in this list.

Examples:

# Display only the ICMP table.
./jool --session --display --icmp
# Same, shorter version.
./jool --session --icmp
# Same, shorter+ version.
./jool -si

--filtering

Syntax:

jool --filtering <flag key> <new value>

Description:

These are several values that affect the way Jool behaves during the "Filtering and Updating" step. This step happens while packets are being processed, and its purpose is to drop packets on certain circumstances and update the database so future packets can be identified.

The following flag keys are available:

Flag	Name	Type	Default	Description
--dropAddr	Address-dependent filtering	Boolean	OFF	TODO
--dropInfo	Filtering of ICMPv6 info messages	Boolean	OFF	TODO
--dropTCP	Dropping externally initiated TCP connections	Boolean	OFF	TODO
--toUDP	UDP session lifetime	Integer (seconds)	5 minutes	TODO
--toTCPest	TCP established session lifetime	Integer (seconds)	2 hours	TODO
--toTCPtrans	TCP transitory session lifetime	Integer (seconds)	4 minutes	TODO
--toICMP	ICMP session lifetime	Integer (seconds)	1 minute	TODO

--translate

Syntax:

jool --translate <flag key> <new value>

Description:

These are several values that affect the way Jool behaves during the "Translating the Packet" step. This step happens while packets are being processed, and its purpose is to actually change their content (flipping protocols).

The following flag keys are available:

Flag	Name	Type	Default	Description
--setTC	Override IPv6 traffic class	Boolean	OFF	TODO
--setTOS	Override IPv4 type of service	Boolean	OFF	TODO
--TOS	IPv4 type of service	Integer	0	TODO
--setDF	DF flag always on	Boolean	ON	TODO
--genID	Generate IPv4 identification	Boolean	OFF	TODO
--boostMTU	Decrease MTU failure rate	Boolean	ON	TODO
--plateaus	MTU plateaus	List of Integers separated by commas (If you need whitespace, remember to quote).	"65535, 32000, 17914, 8166, 4352, 2002, 1492, 1006, 508, 296, 68"	TODO
--head	Packet reserved head room	Integer (bytes)	0	TODO
--tail	Packet reserved tail room	Integer (bytes)	0	TODO