Protocolary updates for release 4.0.6

NICMx · Oct 24, 2019 · 98c56b4 · 98c56b4
1 parent 5367a68
commit 98c56b4
Show file tree

Hide file tree

Showing 18 changed files with 281 additions and 60 deletions.
diff --git a/configure.ac b/configure.ac
@@ -2,7 +2,7 @@
 # Process this file with autoconf to produce a configure script.
 
 AC_PREREQ([2.68])
-AC_INIT([Jool], [4.0.5], [[email protected]])
+AC_INIT([Jool], [4.0.6], [[email protected]])
 AC_CONFIG_SRCDIR([src/common/xlat.h])
 AM_INIT_AUTOMAKE([subdir-objects])
 

diff --git a/docs/_config.yml b/docs/_config.yml
@@ -3,7 +3,7 @@ baseurl: /Jool
 repository-url: https://github.com/NICMx/Jool
 downloads-url: https://github.com/NICMx/releases/raw/master/Jool
 downloads-url-2: https://github.com/NICMx/Jool/releases/download
-latest-version: 4.0.1
+latest-version: 4.0.6
 
 rfc-siit: https://tools.ietf.org/html/rfc7915
 draft-siit-eam: https://tools.ietf.org/html/rfc7757

diff --git a/docs/en/debian.md b/docs/en/debian.md
@@ -9,12 +9,69 @@ title: Debian
 
 # Jool in Debian and its derivatives
 
+<!--
 The Debian package is maintained by the Jool team. It should always be up-to-date.
 
 ## Installation
 
 {% highlight bash %}
 $ sudo apt install jool-dkms jool-tools
 {% endhighlight %}
+-->
+
+## Uninstalling old versions (installed from source)
+
+If you already installed a previous version of Jool from source, know that it will conflict with the userspace clients installed in the next section. To uninstall the old userspace clients, run `make uninstall` in the directory where you compiled them:
+
+```bash
+user@T:~$ cd jool-4.0.5/
+user@T:~# make uninstall
+```
+
+If you no longer have the directory where you compiled it, download it again and do this instead:
+
+<div class="distro-menu">
+	<span class="distro-selector" onclick="showDistro(this);">tarball</span>
+	<span class="distro-selector" onclick="showDistro(this);">git clone</span>
+</div>
+
+<!-- iptables Jool -->
+{% highlight bash %}
+user@T:~$ cd jool-4.0.5/
+user@T:~$
+user@T:~$ ./configure
+user@T:~# make uninstall
+{% endhighlight %}
+
+<!-- Netfilter Jool -->
+{% highlight bash %}
+user@T:~$ cd Jool/
+user@T:~$ ./autogen.sh
+user@T:~$ ./configure
+user@T:~# make uninstall
+{% endhighlight %}
+
+This can be done before or after the commands in the next section. (But if you did it later, restart your terminal.)
+
+You might also want to detach the old running modules while you're at it:
+
+```bash
+user@T:~# modprobe -r jool_siit
+user@T:~# modprobe -r jool
+```
+
+## Installing the Debian packages
+
+The official Debian package is currently [queued for approval into `unstable`](https://github.com/NICMx/Jool/issues/243#issuecomment-517779741). In the meantime, if you're using amd64, you can download standalone `.deb` packages from [Downloads](#downloads.html) and install them like so:
+
+{% highlight bash %}
+user@T:~# apt install ./jool-dkms_{{ site.latest-version }}-1_all.deb ./jool-tools_{{ site.latest-version }}-1_amd64.deb
+{% endhighlight %}
+
+> Sorry; I can't provide packages for other architectures because I don't have any hardware to try them on. If you'd like to help, [contact us](contact.html).
+
+They are tested in Debian 10 and Ubuntu 18.04.
+
+Please note that these packages do not update automatically. This feature will not be available until Jool reaches `unstable`.
 
 Here's a quick link back to the [basic tutorials list](documentation.html#basic-tutorials).
diff --git a/docs/en/documentation.md b/docs/en/documentation.md
@@ -20,18 +20,18 @@ See [RFC 6586](https://tools.ietf.org/html/rfc6586) for deployment experiences u
 
 ## Installation
 
-1. [Installation on OpenWRT](openwrt.html)
-2. [Installation on openSUSE](opensuse.html)
-2. [Installation on most other distros](install.html)
-
-<!-- 2. [Installation on Debian and derivatives](debian.html) -->
+1. [Installation in OpenWRT](openwrt.html)
+2. [Installation in openSUSE](opensuse.html)
+3. [Installation in Debian and its derivatives](debian.html)
+4. [Installation in most other distros](install.html) (Installing from source)
 
 ## Basic Tutorials
 
 1. [SIIT](run-vanilla.html)
 2. [SIIT + EAM](run-eam.html)
 3. [Stateful NAT64](run-nat64.html)
 4. [DNS64](dns64.html)
+5. [Persistence](run-persistent.html)
 
 ## IP/ICMP Translation in Detail
 

diff --git a/docs/en/download.md b/docs/en/download.md
@@ -21,30 +21,24 @@ Results [here](index.html#survey).
 
 Jool 4.0 is a [compliant SIIT and Stateful NAT64](intro-jool.html#compliance).
 
-4.0.1 is the latest version. It is also considered the most mature version of Jool.
-
-| Release Date | Version | .tar.gz | Git commit |
-|--------------|---------|---------|------------|
-| 2019-04-26   | **4.0.1**            | [Download]({{ site.downloads-url-2 }}/v4.0.1/jool_4.0.1.tar.gz) | <a href="{{ site.repository-url }}/tree/v4.0.1" target="_blank">Link</a> |
-| 2019-01-17   | <del>4.0.0</del>     | [Download]({{ site.downloads-url-2 }}/v4.0.0/jool_4.0.0.tar.gz) | <a href="{{ site.repository-url }}/tree/v4.0.0" target="_blank">Link</a> |
-| 2019-01-09   | <del>4.0.0-rc5</del> | [Download]({{ site.downloads-url-2 }}/v4.0.0-rc5/jool_4.0.0-rc5.tar.gz) | <a href="{{ site.repository-url }}/tree/v4.0.0-rc5" target="_blank">Link</a> |
-| 2019-01-04   | <del>3.6.0-rc4</del> | [Download]({{ site.downloads-url-2 }}/v3.6.0-rc4/jool_3.6.0-rc4.tar.gz) | <a href="{{ site.repository-url }}/tree/v3.6.0-rc4" target="_blank">Link</a> |
-| 2018-12-26   | <del>3.6.0-rc3</del> | [Download]({{ site.downloads-url }}/jool_3.6.0-rc3.tar.gz) | <a href="{{ site.repository-url }}/tree/v3.6.0-rc3" target="_blank">Link</a> |
-| 2018-12-14   | <del>3.6.0-rc2</del> | [Download]({{ site.downloads-url }}/jool_3.6.0-rc2.tar.gz) | <a href="{{ site.repository-url }}/tree/v3.6.0-rc2" target="_blank">Link</a> |
-| 2018-11-24   | <del>3.6.0-rc1</del> | [Download]({{ site.downloads-url }}/jool_3.6.0-rc1.tar.gz) | <a href="{{ site.repository-url }}/tree/v3.6.0-rc1" target="_blank">Link</a> |
-
-"rc" stands for "Release Candidate."
-
-Transitional packages:
-
-| Release Date | Version | .tar.gz | Signature | Git commit |
-|--------------|---------|---------|-----------|------------|
-| 2019-08-20   | 4.0.5   | [Download]({{ site.downloads-url-2 }}/v4.0.5/jool-4.0.5.tar.gz) | [Signature]({{ site.downloads-url-2 }}/v4.0.5/jool-4.0.5.tar.gz.asc) | <a href="{{ site.repository-url }}/tree/v4.0.5" target="_blank">Link</a> |
-| 2019-07-31   | 4.0.4   | [Download]({{ site.downloads-url-2 }}/v4.0.4/jool-4.0.4.tar.gz) | [Signature]({{ site.downloads-url-2 }}/v4.0.4/jool-4.0.4.tar.gz.asc) | <a href="{{ site.repository-url }}/tree/v4.0.4" target="_blank">Link</a> |
-| 2019-07-19   | 4.0.3   | [Download]({{ site.downloads-url-2 }}/v4.0.3/jool-4.0.3.tar.gz) | [Signature]({{ site.downloads-url-2 }}/v4.0.3/jool-4.0.3.tar.gz.asc) | <a href="{{ site.repository-url }}/tree/v4.0.3" target="_blank">Link</a> |
-| 2019-07-11   | <del>4.0.2</del>   | [Download]({{ site.downloads-url-2 }}/v4.0.2/jool-4.0.2.tar.gz) | [Signature]({{ site.downloads-url-2 }}/v4.0.2/jool-4.0.2.tar.gz.asc) | <a href="{{ site.repository-url }}/tree/v4.0.2" target="_blank">Link</a> |
-
-[This](http://keys.gnupg.net/pks/lookup?op=get&search=0x72160FD57B242967) is my public key. It is not yet certified, so the Signature column is mostly just theater for now.
+4.0.6 is the latest and most mature version of Jool.
+
+| Release Date | Version | .tar.gz | .tar.gz Signature | Git commit | .deb |
+|--------------|---------|---------|-------------------|------------|------|
+| 2019-10-24   | **4.0.6** | [Download]({{ site.downloads-url-2 }}/v4.0.6/jool-4.0.6.tar.gz) | [Signature]({{ site.downloads-url-2 }}/v4.0.6/jool-4.0.6.tar.gz.asc) | <a href="{{ site.repository-url }}/tree/v4.0.6" target="_blank">Link</a> | [Kernel modules]({{ site.downloads-url-2 }}/v{{ site.latest-version }}/jool-dkms_{{ site.latest-version }}-1_all.deb)<br />[Userspace tools]({{ site.downloads-url-2 }}/v{{ site.latest-version }}/jool-tools_{{ site.latest-version }}-1_amd64.deb) (amd64 only) |
+| 2019-08-20   | 4.0.5 | [Download]({{ site.downloads-url-2 }}/v4.0.5/jool-4.0.5.tar.gz) | [Signature]({{ site.downloads-url-2 }}/v4.0.5/jool-4.0.5.tar.gz.asc) | <a href="{{ site.repository-url }}/tree/v4.0.5" target="_blank">Link</a> | - |
+| 2019-07-31   | <del>4.0.4</del> | [Download]({{ site.downloads-url-2 }}/v4.0.4/jool-4.0.4.tar.gz) | [Signature]({{ site.downloads-url-2 }}/v4.0.4/jool-4.0.4.tar.gz.asc) | <a href="{{ site.repository-url }}/tree/v4.0.4" target="_blank">Link</a> | - |
+| 2019-07-19   | <del>4.0.3</del> | [Download]({{ site.downloads-url-2 }}/v4.0.3/jool-4.0.3.tar.gz) | [Signature]({{ site.downloads-url-2 }}/v4.0.3/jool-4.0.3.tar.gz.asc) | <a href="{{ site.repository-url }}/tree/v4.0.3" target="_blank">Link</a> | - |
+| 2019-07-11   | <del>4.0.2</del> | [Download]({{ site.downloads-url-2 }}/v4.0.2/jool-4.0.2.tar.gz) | [Signature]({{ site.downloads-url-2 }}/v4.0.2/jool-4.0.2.tar.gz.asc) | <a href="{{ site.repository-url }}/tree/v4.0.2" target="_blank">Link</a> | - |
+| 2019-04-26   | 4.0.1                | [Download]({{ site.downloads-url-2 }}/v4.0.1/jool_4.0.1.tar.gz) | - | <a href="{{ site.repository-url }}/tree/v4.0.1" target="_blank">Link</a> | - |
+| 2019-01-17   | <del>4.0.0</del>     | [Download]({{ site.downloads-url-2 }}/v4.0.0/jool_4.0.0.tar.gz) | - | <a href="{{ site.repository-url }}/tree/v4.0.0" target="_blank">Link</a> | - |
+| 2019-01-09   | <del>4.0.0-rc5</del> | [Download]({{ site.downloads-url-2 }}/v4.0.0-rc5/jool_4.0.0-rc5.tar.gz) | - | <a href="{{ site.repository-url }}/tree/v4.0.0-rc5" target="_blank">Link</a> | - |
+| 2019-01-04   | <del>3.6.0-rc4</del> | [Download]({{ site.downloads-url-2 }}/v3.6.0-rc4/jool_3.6.0-rc4.tar.gz) | - | <a href="{{ site.repository-url }}/tree/v3.6.0-rc4" target="_blank">Link</a> | - |
+| 2018-12-26   | <del>3.6.0-rc3</del> | [Download]({{ site.downloads-url }}/jool_3.6.0-rc3.tar.gz) | - | <a href="{{ site.repository-url }}/tree/v3.6.0-rc3" target="_blank">Link</a> | - |
+| 2018-12-14   | <del>3.6.0-rc2</del> | [Download]({{ site.downloads-url }}/jool_3.6.0-rc2.tar.gz) | - | <a href="{{ site.repository-url }}/tree/v3.6.0-rc2" target="_blank">Link</a> | - |
+| 2018-11-24   | <del>3.6.0-rc1</del> | [Download]({{ site.downloads-url }}/jool_3.6.0-rc1.tar.gz) | - | <a href="{{ site.repository-url }}/tree/v3.6.0-rc1" target="_blank">Link</a> | - |
+
+"rc" stands for "Release Candidate." [This](http://keys.gnupg.net/pks/lookup?op=get&search=0x72160FD57B242967) is my public key. It is not yet certified, so the Signature column is mostly just theater for now.
 
 ## 3.5.x
 

diff --git a/docs/en/faq.md b/docs/en/faq.md
@@ -12,7 +12,7 @@ title: FAQ
 ## Index
 
 1. [Why is Jool not doing anything?](#why-is-jool-not-doing-anything)
-2. [Why in my ping not working?](#why-in-my-ping-not-working)
+2. [Why is my ping not working?](#why-is-my-ping-not-working)
 3. [Jool is intermitently unable to translate traffic.](#jool-is-intermitently-unable-to-translate-traffic)
 4. [The throughput is terrible!](#the-throughput-is-terrible)
 
@@ -49,7 +49,7 @@ Given the output above, for example, I'd try looking into the routing table.
 
 If `stats` proves insufficient, you can [enable debug logging](logging.html).
 
-## Why in my ping not working?
+## Why is my ping not working?
 
 Probably because you started the ping on the same machine (or rather, network namespace) your translator instance is attached to.
 

diff --git a/docs/en/index.md b/docs/en/index.md
@@ -22,7 +22,7 @@ Jool is an Open Source [SIIT and NAT64](intro-xlat.html) for Linux.
 
 As far as we know, Jool is a [compliant](intro-jool.html#compliance) SIIT and Stateful NAT64.
 
-Its most mature version is [4.0.1]({{ site.repository-url }}/milestone/43).
+Its most mature version is [4.0.6]({{ site.repository-url }}/milestone/45).
 
 -------------------
 
@@ -34,6 +34,23 @@ Its most mature version is [4.0.1]({{ site.repository-url }}/milestone/43).
 
 ## News
 
+### 2019-10-24
+
+[Jool 4.0.6](download.html) has been released.
+
+Development since 4.0.1 has been generally focused on [Debian packaging](https://github.com/NICMx/Jool/issues/243#issuecomment-517779741) and [systemd scripts](https://github.com/NICMx/Jool/issues/250#issuecomment-517790775). 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](https://ftp-master.debian.org/new.html) 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](https://github.com/NICMx/Jool/issues/163). Kernel modules and userspace applications need to be [installed separately](https://jool.mx/en/install.html#compilation-and-installation) 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:
+
+1. Add support for kernels 5.1, 5.2, 5.3, 5.4, RHEL7.7 and RHEL8.0.
+2. `.deb` packages are now available in [Downloads](download.html). (See [Debian](debian.html).)
+3. [#287](https://github.com/NICMx/Jool/issues/287): [`address query`](usr-flags-address.html)
+4. [#297](https://github.com/NICMx/Jool/issues/297#issuecomment-540080336): 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](run-vanilla.html#jool).)
+
+The OpenWRT version has also been [updated](https://github.com/openwrt/packages/issues/9349).
+
 ### 2019-04-26
 
 [Jool 4.0.1](download.html) has been released.

diff --git a/docs/en/intro-jool.md b/docs/en/intro-jool.md
@@ -15,6 +15,9 @@ title: Introduction to Jool
 2. [Compliance](#compliance)
 3. [Compatibility](#compatibility)
 4. [Design](#design)
+	1. [Netfilter](#netfilter)
+	2. [iptables](#iptables)
+5. [Untranslatable packets](#untranslatable-packets)
 
 ## Overview
 
@@ -46,7 +49,7 @@ Please [let us know]({{ site.repository-url }}/issues) if you find additional co
 | Jool version                        | Supported Linux kernels (mainline)   | Supported Linux kernels (RHEL) |
 |-------------------------------------|--------------------------------------|--------------------------------|
 | [master]({{ site.repository-url }}) | 3.13 - 3.19,<br />4.0 - 4.20,<br />5.0 - 5.4 | RHEL 7.0 - RHEL 7.7,<br />RHEL 8.0 |
-| [4.0.5](download.html#40x)          | 3.13 - 3.19,<br />4.0 - 4.20,<br />5.0 - 5.3 | RHEL 7.0 - RHEL 7.6            |
+| [4.0.6](download.html#40x)          | 3.13 - 3.19,<br />4.0 - 4.20,<br />5.0 - 5.4 | RHEL 7.0 - RHEL 7.7,<br />RHEL 8.0 |
 | [4.0.1](download.html#40x)          | 3.13 - 3.19,<br />4.0 - 4.20,<br />5.0 | RHEL 7.0 - RHEL 7.5            |
 | [3.5.8](download.html#35x)          | 3.2 - 3.19,<br />4.0 - 4.18           | RHEL 7.0 - RHEL 7.4            |
 
@@ -69,7 +72,7 @@ Netfilter Jool instances are simple to configure. However, they are also _greedy
 
 There can only be **one** Netfilter SIIT Jool instance and **one** Netfilter NAT64 instance per network namespace.
 
-Netfilter Jool instances start packet translation as soon as they are created. They drop packets deemed corrupted, translate packets which _can_ be translated (according to their configuration) and return everything else to the kernel.
+Netfilter Jool instances start packet translation as soon as they are created. They drop packets deemed corrupted, translate packets which _can_ be translated (according to their configuration) and return [everything else](#untranslatable-packets) to the kernel.
 
 Netfilter plugins are not allowed to change the network protocol of their packets. Additionally, the kernel API does not export a means to post packets in the `FORWARD` chain. For these reasons, successfully translated packets skip `FORWARD`, going straight to `POSTROUTING`:
 
@@ -101,8 +104,36 @@ adds a _rule_ to iptables's _mangle_ table, which "Jools" all packets headed tow
 
 There can be any number of iptables Jool instances in any namespace, and any number of iptables rules can reference them.
 
-iptables Jool instances sit idle until some iptables rule sends packets to them. (Of course, only packets that [match the rule's conditions](https://www.netfilter.org/documentation/HOWTO/packet-filtering-HOWTO-7.html#ss7.3) are sent.) As of version 4.0.6, iptables instances function the same as Netfilter instances: They drop packets deemed corrupted, translate packets which _can_ be translated (according to their configuration) and return everything else to the kernel. (In this context, "return to the kernel" means that the packet will go back to the iptables chain, right after the Jool rule that matched it.)
+iptables Jool instances sit idle until some iptables rule sends packets to them. (Of course, only packets that [match the rule's conditions](https://www.netfilter.org/documentation/HOWTO/packet-filtering-HOWTO-7.html#ss7.3) are sent.) As of version 4.0.6, iptables instances function the same as Netfilter instances: They drop packets deemed corrupted, translate packets which _can_ be translated (according to their configuration) and return [everything else](#untranslatable-packets) to the kernel. (In this context, "return to the kernel" means that the packet will go back to the iptables chain, right after the Jool rule that matched it.)
 
 iptables Jool has a quirk similar to Netfilter Jool that you should be aware of: iptables rules are also not allowed to change the network protocol of their packets, so iptables Jool rules also send their matched and successfully translated packets straight to `POSTROUTING`. Packets which do not match the rule continue through the chain normally.
 
 iptables Jool first became available in Jool 4.0.0.
+
+## Untranslatable packets
+
+As of version 4.0.6, both Netfilter Jool and iptables Jool return the packet to the kernel if any of these conditions are met:
+
+- An iptables rule's `--instance` parameter does not match any existing iptables instances. (ie. user created the iptables rule but hasn't yet created the instance.)
+- The packet was translated successfully, but the translated packet cannot be routed. (Most of the time, this is because its destination address does not match any entries in the routing table.)
+- The translator is [disabled by configuration](https://jool.mx/en/usr-flags-global.html#manually-enabled).
+
+SIIT Jool also returns the packet to the kernel when at least one of these conditions are met:
+
+- The packet is IPv4 and at least one of its addresses cannot be translated. An IPv4 address cannot be translated when
+	- it's subnet-scoped,
+	- belongs to one of the translator's interfaces,
+	- is [blacklist4ed](https://jool.mx/en/usr-flags-blacklist4.html), or
+	- cannot be translated by any of the populated address translation strategies (EAMT, pool6 and rfc6791).
+- The packet is IPv6 and at least one of its addresses cannot be translated. An IPv6 address cannot be translated when
+	- it cannot be translated by any of the populated address translation strategies (EAMT, pool6 and rfc6791),
+	- its IPv4 counterpart is blacklist4ed,
+	- its IPv4 counterpart is subnet-scoped, or
+	- its IPv4 counterpart belongs to a local interface.
+
+Stateful NAT64 Jool also returns the packet to the kernel when at least one of these conditions are met:
+
+- The packet's transport protocol is unsupported. (NAT64 Jool only supports TCP, UDP and ICMP as of now.)
+- The packet is IPv6 and its destination address does not match pool6. (ie. packet is not meant to be translated.)
+- The packet is IPv4 and its destination transport address (address + port) does not match any BIB entries. (ie. packet lacks IPv6 destination.)
+- Untranslatable/unknown ICMPv4 and ICMPv6 types.