Home

Introduction

Jool is an Open Source SIIT and NAT64 for Linux.

Status

As far as we know, Jool is a compliant SIIT and Stateful NAT64.

Our most mature version is 3.5.7, and our latest stable is 4.0.0.

Survey

a

News

2019-02-05

By the way: Per latest feeback, I added a few documentation blocks that, in retrospect, should have been written quite some time ago. If you’re interested, they are the notes at the end of the Vanilla SIIT and NAT64 “Jool” sections, and this FAQ entry. (Remember that browsers tend to cache static pages, so hit the Update button.)

2019-01-17

Jool 4.0.0 has been released.

Since the fifth release candidate:

  • Update the manpages.
  • Patch validation of pool6 during instance adds.

2019-01-09

It has been pointed to me that the new userspace interface warrants a change in major version number for the sake of proper semantic versioning.

Therefore, the fifth release candidate for Jool 4.0.0 is now available.

  • It adds support for $DESTDIR on the iptables binaries Makefile. (#272)
  • It applies latest feedback on atomic configuration:
    • It now supports static BIB entries. (But only if the operation is being used to create a new translator instance.)
    • The JSON parser is more consistent:
      • Duplicate and unknown tags are no longer allowed on any object contexts. (To make up for this, comment tags are now allowed on all object contexts.)
      • The entirety of the JSON file is now expected to contain all of the intended configuration at once; some sections are not incremental anymore.
    • See here for more details.

2019-01-04

The fourth release candidate for version 3.6.0 is now available. It commits support for kernel 4.19 and also adds support for 4.20.

2018-12-26

The third release candidate for version 3.6.0 is now available.

It patches several (Json) file reading bugs:

2018-12-14

The second release candidate for version 3.6.0 is now available.

It has two fixes:

2018-11-24

The first release candidate for version 3.6.0 is now available!

Warning! 3.6 is our first significantly backward-incompatible upgrade. Please ensure that you have the time to review your installation and configuration scripts before updating.

Here’s a (possibly incomplete still) list of the changes you want to be aware of if you’re upgrading:

  1. Installation is somewhat different and the userspace tools have new dependency libxtables.
  2. You can no longer create a default instance while modprobing. (Sorry. It was very misleading as to what a modprobe is supposed to represent.) Please issue modprobes and instance adds separately.
  3. Jool instances now have names. Instances that share stateness and namespace must have unique names.
  4. Many userspace application arguments have lost their -- prefix, and some degree of order is now enforced.
  5. pool6 is now a global configuration field, not a database. It can now be defined during instance adds. NAT64 Jool no longer allows you to change it afterwards. See here for more details.
  6. pool6791 also became a global configuration field, to mirror its IPv6 counterpart.
  7. --count is gone. (See stats.)
  8. Minor global variable specific quirks:
  9. The manpages are horribly outdated. (I will rewrite them over the course of the week; use this site’s documentation instead.)
  10. All userspace client commands that require kernel cooperation (ie. all off them, except for --help, --usage and such) now require admin privileges.

These are the new features:

  1. iptables mode
  2. Instance naming
  3. stats
  4. Support for kernels 4.17 and 4.18. (4.19 compiles too, but I haven’t fully tested it.)
  5. Bash autocompletion for the jool and jool_siit userspace application clients. (You might need to restart your terminal after installing to see the effects. I’m not actually sure; it’s a little non-deterministic in my experience.)

And these are the bugfixes:

  1. Fix low performance on virtual interfaces. (And perhaps other problems related to offloading.)
    Offload disabling might no longer be necessary. (Hoping for some feedback on this.)
  2. Patch incorrect fragment handling on newer kernels.

2018-05-04

Version 3.5.7 has been released!

The updates are

  • #247: Fix unlikely kernel panic.
  • #260 and #263: Add support for kernels 4.15 and 4.16.

2018-01-16

Version 3.5.6 has been released!

The main update is a change of license. Originally released under the GPLv3+, Jool 3.5.6 and onwards will now operate under the General Public License version 2. This change was prompted due to GPLv3’s incompatibilities with the Linux kernel’s own license.

Because of this issue, though the remaining patches might be of little interest to you, you are strongly encouraged to update to the newer version. There will be no further official development nor support for older versions.

Other changes include:

  • #255: Improved parsing of configuration from JSON files.
  • #256: Added support for kernels 4.13 and 4.14.
  • Fit the --pool4 --display table in 80-column terminals for ease of view.

2017-11-23

Version 3.5.5 has been released.

Bugfixes:

  1. #249: Fix missing entries from --eamt --display output.
  2. #253: Fix namespace code for usage of Jool in a container.
  3. Fix random broken connections due to mischosen masking ports.
  4. --pool4 --add and --pool4 --remove weren’t validating that the given prefix didn’t contain suffix bits active. They reacted in different ways no this situation, both of which were wrong.

Performance patches:

  1. Improve mask selection algorithm’s performance. Please read this. The default value of Max Iterations is not backwards compatible!

Also, just a heads up: If you monitored the logging message

I ran out of pool4 addresses.

Then you probably want to know that it changed slightly:

I'm running out of pool4 addresses for mark <mark>.

If the relevant Max Iterations is infinity, then the message triggers when pool4 is exhausted (as it used to). If it isn’t, it triggers whenever pool4 failed to find a suitable mark. (Though the message rate-limits itself.)

Misc tweaks:

  1. The userspace app now displays assumed mode and operation on most errors.

This should help users troubleshoot problems, particularly when these fields are implicit:

# jool --pool4 --tcp 192.0.2.1/30
Jool Error: '192.0.2.1/30' seems to have a suffix; please fix.
(Error code: 22)
(Note: Assuming configuration mode '--pool4' and operation '--add'.)

2017-07-25

Version 3.5.4 has been released. The improvements are

  1. Added support for kernels 4.11 and 4.12.
  2. Fixed compilation on debugging-enabled kernels.
  3. Improved make clean slightly.
  4. Added error handling for #247. (The core problem hasn’t been found yet, but what used to be a kernel crash has been upgraded to a packet drop and debugging messages.)

2017-03-09

Version 3.5.3 has been released.

  1. Bugfix: --logging-bib and --logging-session weren’t logging UDP and ICMP traffic.
  2. Added support for Linux 4.9 and 4.10.
  3. Fixed build errors on some platforms.

2016-12-06

Version 3.4.6 has been released.

3.4.6 simply mirrors the #232 fix (already in 3.5.2) into the 3.4 series. You don’t need to downgrade if you’re using Jool 3.5.

2016-12-02

Version 3.5.2 has been released.

  1. Fixed a kernel panic. (Both SIIT and NAT64.)
  2. Improved the build system: #233 and #234
  3. Fixed the RFC6791 pool.

2016-10-07

Version 3.5.1 has been released. Both apply to NAT64:

  1. Fixed two memory leaks.
  2. Silenced fragmentation warning.

2016-09-26

Version 3.5.0 has been released! The new features are

Some functionality was dropped:

2016-09-19

Jool 3.4.5 was released.

  1. Added support for kernels 4.6 and 4.7.
  2. Deleted constant warning due to an empty pool6.
  3. Improved the implicit blacklist:
    • Blacklisted directed broadcast.
    • Applied the implicit blacklist to EAMT-based translation.
      (Among other things, this prevents an overly-intrusive EAMT from hogging packets intended for the translator.)
  4. jool and jool_siit can now be modprobed in the same namespace without suffering a Netlink socket collision.

2016-07-11

Version 3.4.4 released. One bug was found:

  1. NAT64 Jool’s implementation of empty pool4 used to mistake point-to-point interface addresses, leading to packet drops.

2016-04-21

Version 3.4.3 released.

  1. Added support for a wider range of kernels. Support is now from Linux 3.2 to 4.4, and also RHEL 7.0 to 7.2.
  2. New configuration flag for NAT64: --f-args
  3. New configuration flag for NAT64: --handle-rst-during-fin-rcv

2015-11-20

Version 3.4.2 released. There are three bugfixes:

  1. Bogus pointers and memory leaks caused by --flush and termination of pool6791 and blacklist (SIIT Jool).
  2. --bib --display and --session --display now require network admin privileges (NAT64 Jool).
  3. Needlessly purged some compilation warnings in old gcc versions (NAT64 Jool).

Careful with #2! You might need to update scripts.

2015-11-11

Version 3.4.1 released. There are three bugfixes:

  1. Kernel panic due to incorrect namespace API handling.
  2. Fixed compilation for kernels 4.1 and above.
  3. The userspace applications used to return success after errors found by the module.

2015-11-04

Version 3.4.0 released. This is a fat one.

  1. Refactors to pool4 add mark-dependent sourcing and port ranges (which in turn removes the need for a second IPv4 address), and fixes the excessive memory usage.
  2. The EAMT now implements Hairpinning and overlapping entries, which are newer updates to the EAM draft.
  3. Minimal namespace features, which allow Host-Based Edge Translation (now called Node-Based Translation) and (subjectively) better filtering.
  4. The userspace application now prints the friendlier error messages that used to be dumped in the kernel log only.
  5. Removed reliance on dead code deletion, which used to prevent compilation on some systems.
  6. Two bugfixes.
  7. A spanish version of this site.
  8. --csv can now be used on all configuration targets.

Warning If you want to upgrade, please keep in mind pool4 is not completely backwards-compatible. In Jool 3.3, any packet would be masked using any available pool4 entry. In Jool 3.4, every pool4 entry only masks packets wielding specific marks (which defaults to zero). See --mark for more details.

2015-10-15

Version 3.3.5 released.

Three bugfixes:

  1. A connection could be masked using port zero (NAT64 Jool).
  2. Incorrect routing when pool6791 was empty (SIIT Jool).
  3. Memory leak on --eamt --flush (SIIT Jool).

2015-09-21

Version 3.3.4 released.

The most important fix is (theoretically) a Path MTU Discovery breaker. There’s also the now automatic blacklisting of IPv4 multicast and the better handling of the IPv6 header’s hop limit.

Also, it has been noticed SIIT Jool installations in kernels 3.5 and below need IPv4 forwarding active. In other words, add

sudo sysctl -w net.ipv4.conf.all.forwarding=1

to the modprobe procedure.

2015-08-17

Critical bug detected!

In addition, version 3.3.3 contains the following:

  1. Added support for the DKMS framework!
  2. Userspace application quirks fixed: #150, #151.

2015-04-14

Version 3.3.2 released.

This is the summary:

Also, unrelated to the code, we now have two mailing lists:

  • jool-news@nic.mx is intended to spread news. Since we currently don’t have other major events, the plan is to only use it to announce new releases coming out. Click here to start listening.
  • jool-list@nic.mx can be used for public discussion (help, proposals, whatever). I will also drop the news here so people doesn’t have to subscribe to both at a time. Click here to register.

jool@nic.mx can still be used to reach us developers only.

We’d also like to apologize for the certificate hiccup we had recently. Though they are being generated, the mailing list archives are also not available yet, and this is in our admins’ TODO list.

2015-03-11

Important bug discovered!

We just released Jool 3.3.1.

2015-03-09

Jool 3.3.0 is finished.

Filtering couldn’t make it into the milestone, but Stateless IP/ICMP Translation (SIIT) is now supported.

See the updated SIIT/NAT64 introduction for an improved picture of the SIIT paradigm. Here’s the tutorial. Also keep an eye on 464XLAT.

We also refactored the userspace app somewhat; please review your scripts:

We also released Jool 3.2.3, which is bugfixes since 3.2.2. One of the bugs is a DoS vulnerability, so upgrading to at least 3.2.3 is highly recommended.

2014-10-24

An important bug was discovered, and version 3.2.2 is out.

2014-10-17

The documentation of --plateaus proved to be lacking, so there’s now a full article dedicated to it. The original definition also received improvements.

It has come to our attention that we are also lacking an explanation of IP literals, so there should be another codeless update like this in the near future.

2014-10-08

Version 3.2.1 released. The 3.2 series is now considered more mature than 3.1.

The important changes are

  1. Jool used to always attempt to mask packets using the first prefix of the pool. This meant that Jool was unable to handle more than one prefix.
  2. The memory leak in the core has been purged.

The less noticeable ones are

  1. log_martians is no longer a step in modprobing Jool (though it doesn’t bite if you keep it).
  2. The SNMP stat updates returned. See nstat and netstat -s.
  3. Corner-case packets now get checksums updated correctly.

2014-09-01

It took it a really long time to overcome testing, but version 3.2.0 is finally released.

We changed the minor version number this time, because the userspace application has a slightly different interface; the single-value configuration parameters have been joined: --general replaced --filtering, --translate and --fragmentation. The application also has three new features:

  1. The ability to flush the pools.
  2. The addition of --quick.
  3. The addition of --svg, in BIB and session.

The second main novelty is the finally correct implementation of Simultaneous Open of TCP Connections. The translation pipeline should now be completely quirkless.

A little confusion also revealed that the path to libnl used to be hardcoded in the configuration script. If you used to have trouble compiling the userspace application, you might want to try again using the new version.

The more unnoticeable stuff includes a complement to the old issue #65 and a healthier code-to-comment ratio :). The user documentation, on the other hand, received a significant refactor, so looking at the diff might not be overly productive this time.

One thing we did not complete was the fragmentation refactor. This is in fact the reason why this milestone dragged. We appear to really need to reconcile the kernel’s defragmenter and the RFC in order to implement filtering policies however, so it’s still considered an active issue.

We also released 3.1.6, which is small fixes from 3.1.5, in case somebody has a reason to continue using the 3.1.x series.

2014-06-26

By the way:

If you can read Markdown and Github’s diffs, you can find the documentation changes for version 3.1.5 here, here and here.

2014-06-18

Version 3.1.5 released.

Our most important fix is issue #92. Incorrect ICMP errors used to confuse IPv4 nodes, which lowered the reliability of 4-to-6 traffic.

Aside from that, the userspace application has been tightened. It doesn’t crash silly anymore when it has to output large BIB or session tables, and works a lot harder to keep the database free from trashy leftover records.

Then we have a couple of performance optimizations. In particular (and more or less as a side effect), by aligning log priorities to those from the rest of the kernel, more care has been taken to keep the log cleaner.

If you care about performance, you might want to read the as-of-now-missing documentation of --minMTU6, a configuration parameter that helps you avoid fragmentation.

If people doesn’t find critical bugs in this version, this appears to be the end of the 3.1.x series. We’ll go back to aim for 100% RFC compliance in the next update.

2014-04-25

Version 3.1.4 released. Fixes:

  1. Two kernel crashes.
  2. The userspace application now resolves names.
  3. Added support for Linux 3.13+.

Also, we no longer recommend usage of Jool in kernel 3.12.

2014-03-26

Version 3.1.3 released. Fixes:

  1. An incorrect implementation used to ban configuration on certain systems.
  2. A bug used to prevent Jool from sending certain ICMP errors.
  3. A memory leak.
  4. Slightly optimized the packet translation algorithm by replacing some spinlocks with RCUs.

2014-03-04

Website released. This website!

And with it comes a new release. 3.1.2 fixes:

  1. 21-centuried the userspace-app’s installation procedure.
  2. Jool is now more explicit regarding the suffix of prefixes.
  3. Jool no longer wrecks itself when modprobed with invalid arguments.

2014-02-21

Version 3.1.1 released.

It contains two bugfixes:

  1. Added permission checking to the admin-related userspace requests.
  2. Fixed compatibility issues with ~3.1 kernels.

2014-01-15

Version 3.1.0 released. Jool finally handles fragments!

Other important fixes:

  • Major optimizations on both the BIB and session databases. The module should scale a lot more gracefully as clients demand more traffic.
  • Jool no longer requires a separate IPv4 address.
  • Kernel panic during removal of the module fixed.
  • And More stuff.