Jool is an Open Source SIIT and NAT64 for Linux.
As far as we know, Jool is a compliant SIIT and Stateful NAT64.
Its most mature version is 4.0.6.
Jool 4.0.6 has been released.
Development since 4.0.1 has been generally focused on Debian packaging and systemd scripts. To make sure the build was sane I was planning to wait until Debian approved it before announcing a new version, but since it’s been queued for more than two months I guess it’s time to force ourselves out of the “transitional phase.”
In particular, I had to revert the single
make && make install installation hack from #163. Kernel modules and userspace applications need to be installed separately again. I also removed Kbuild from the documentation because it induces too many user headaches; Please use DKMS instead.
The following additional changes have been applied since 4.0.1:
- Add support for kernels 5.1, 5.2, 5.3, 5.4, RHEL7.7 and RHEL8.0.
.debpackages are now available in Downloads. (See Debian.)
- #297: Mirror Netfilter packet return mechanism on iptables mode. (By the way: This means that you’re no longer required to include matches in iptables rules. See the tutorials.)
The OpenWRT version has also been updated.
Jool 4.0.1 has been released.
It patches two bugs:
Version 3.5.8 has also been released. It fixes
- Compilation error on newer Ubuntu (Debian?) kernels.
(Incidentally, this also adds support for kernels 4.17 and 4.18.)
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.)
Jool 4.0.0 has been released.
Since the fifth release candidate:
- Update the manpages.
- Patch validation of pool6 during
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
$DESTDIRon 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,
commenttags 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.
- Duplicate and unknown tags are no longer allowed on any object contexts. (To make up for this,
- See here for more details.
The third release candidate for version 3.6.0 is now available.
It patches several (Json) file reading bugs:
The second release candidate for version 3.6.0 is now available.
It has two fixes:
- Patch reliable panic in certain kernels.
- Improve bash autocompletion by being more prediction-happy. (Autocomplete
default, file names, etc.)
The first release candidate for version 3.6.0 is now available!
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:
- Installation is somewhat different and the userspace tools have new dependency
- You can no longer create a default instance while modprobing. (Sorry. It was very misleading as to what a
modprobeis supposed to represent.) Please issue
instance adds separately.
- Jool instances now have names. Instances that share stateness and namespace must have unique names.
- Many userspace application arguments have lost their
--prefix, and some degree of order is now enforced.
pool6is 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.
pool6791also became a global configuration field, to mirror its IPv6 counterpart.
--countis gone. (See
globalvariable specific quirks:
source-icmpv6-errors-betternow defaults to
eam-hairpin-modeis a string now.
logging-sessionformats now have the instance name attached to them.
- The timeouts now follow the
--fragment-arrival-timeoutis gone. (Because the fragment database is gone.)
- The manpages are horribly outdated. (I will rewrite them over the course of the week; use this site’s documentation instead.)
- All userspace client commands that require kernel cooperation (ie. all off them, except for
--usageand such) now require admin privileges.
These are the new features:
- Instance naming
- Support for kernels 4.17 and 4.18. (4.19 compiles too, but I haven’t fully tested it.)
- Bash autocompletion for the
jool_siituserspace 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:
- 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.)
- Patch incorrect fragment handling on newer kernels.
Version 3.5.7 has been released!
The updates are
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 --displaytable in 80-column terminals for ease of view.
Version 3.5.5 has been released.
- #249: Fix missing entries from
- #253: Fix namespace code for usage of Jool in a container.
- Fix random broken connections due to mischosen masking ports.
--pool4 --removeweren’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.
- 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.)
- 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'.)
Version 3.5.4 has been released. The improvements are
- Added support for kernels 4.11 and 4.12.
- Fixed compilation on debugging-enabled kernels.
- 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.)
Version 3.5.3 has been released.
--logging-sessionweren’t logging UDP and ICMP traffic.
- Added support for Linux 4.9 and 4.10.
- Fixed build errors on some platforms.
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.
Version 3.5.2 has been released.
- Fixed a kernel panic. (Both SIIT and NAT64.)
- Improved the build system: #233 and #234
- Fixed the RFC6791 pool.
Version 3.5.1 has been released. Both apply to NAT64:
Version 3.5.0 has been released! The new features are
- Atomic Configuration
- Session Synchronization
- Namespace Instances
- A v6 RFC6791 prefix
- Documented Testing Framework (unit and graybox)
Some functionality was dropped:
Jool 3.4.5 was released.
- Added support for kernels 4.6 and 4.7.
- Deleted constant warning due to an empty pool6.
- 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.)
jool_siitcan now be modprobed in the same namespace without suffering a Netlink socket collision.
Version 3.4.4 released. One bug was found:
- NAT64 Jool’s implementation of empty pool4 used to mistake point-to-point interface addresses, leading to packet drops.
Version 3.4.3 released.
- 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.
- New configuration flag for NAT64:
- New configuration flag for NAT64:
Version 3.4.2 released. There are three bugfixes:
- Bogus pointers and memory leaks caused by
--flushand termination of pool6791 and blacklist (SIIT Jool).
--session --displaynow require network admin privileges (NAT64 Jool).
- Needlessly purged some compilation warnings in old gcc versions (NAT64 Jool).
Careful with #2! You might need to update scripts.
Version 3.4.1 released. There are three bugfixes:
- Kernel panic due to incorrect namespace API handling.
- Fixed compilation for kernels 4.1 and above.
- The userspace applications used to return success after errors found by the module.
Version 3.4.0 released. This is a fat one.
- 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.
- The EAMT now implements Hairpinning and overlapping entries, which are newer updates to the EAM draft.
- Minimal namespace features, which allow Host-Based Edge Translation (now called Node-Based Translation) and (subjectively) better filtering.
- The userspace application now prints the friendlier error messages that used to be dumped in the kernel log only.
- Removed reliance on dead code deletion, which used to prevent compilation on some systems.
- Two bugfixes.
- A spanish version of this site.
--csvcan now be used on all configuration targets.
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
--markfor more details.
Version 3.3.5 released.
- A connection could be masked using port zero (NAT64 Jool).
- Incorrect routing when pool6791 was empty (SIIT Jool).
- Memory leak on
--eamt --flush(SIIT Jool).
Version 3.3.4 released.
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.
In addition, version 3.3.3 contains the following:
Version 3.3.2 released.
This is the summary:
- There are new configuration flags:
- The userspace app was misbehaving in several ways. While all of its bugs had workarounds, it was a pain to use.
Also, unrelated to the code, we now have two mailing lists:
- email@example.com 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.
- firstname.lastname@example.org 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.
email@example.com 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.
Important bug discovered!
We just released Jool 3.3.1.
Jool 3.3.0 is finished.
Filtering couldn’t make it into the milestone, but Stateless IP/ICMP Translation (SIIT) is now supported.
We also refactored the userspace app somewhat; please review your scripts:
- The kernel’s per-interface MTU setting replaced
--bib6were deprecated because they’re considered redundant. See
- Three global flags were also deprecated for different reasons.
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.
An important bug was discovered, and version 3.2.2 is out.
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.
Version 3.2.1 released. The 3.2 series is now considered more mature than 3.1.
The important changes are
- 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.
- The memory leak in the core has been purged.
The less noticeable ones are
log_martiansis no longer a step in modprobing Jool (though it doesn’t bite if you keep it).
- The SNMP stat updates returned. See
- Corner-case packets now get checksums updated correctly.
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:
--fragmentation. The application also has three new features:
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.
By the way:
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 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.
Version 3.1.4 released. Fixes:
Version 3.1.3 released. Fixes:
- An incorrect implementation used to ban configuration on certain systems.
- A bug used to prevent Jool from sending certain ICMP errors.
- A memory leak.
- Slightly optimized the packet translation algorithm by replacing some spinlocks with RCUs.
Website released. This website!
And with it comes a new release. 3.1.2 fixes:
- 21-centuried the userspace-app’s installation procedure.
- Jool is now more explicit regarding the suffix of prefixes.
- Jool no longer wrecks itself when modprobed with invalid arguments.
Version 3.1.1 released.
It contains two bugfixes:
- Added permission checking to the admin-related userspace requests.
- Fixed compatibility issues with ~3.1 kernels.
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.