Browse files

The documentation now reflects the latest changes.

This includes issue #91.
  • Loading branch information...
ydahhrk committed Jun 19, 2014
1 parent 69a4308 commit 5295b05cf2c380055c3356d48ef56b74c0b828bb
Showing with 62 additions and 4 deletions.
  1. +15 −3 doc/usr/index.markdown
  2. +3 −1 doc/usr/quirk-iptables.markdown
  3. +40 −0 doc/usr/userspace-app.markdown
  4. +4 −0 usr/man/jool.8
@@ -29,14 +29,26 @@ Jool is still a couple of features away from being 100% RFC 6146 compliant:
That doesn't stop the IPv6-IPv4 translation mechanism from being functional, however.
-There are other <a href="" target="_blank">known issues</a>. Because we have perceived users to be more interested in these latter problems, we intend to postpone the missing features.
-Now cooking version 3.1.5...
+Our next target is **Simultaneous open of TCP connections**. Now cooking version 3.2.0...
## News
+### 2014-06-18
+Version 3.1.5 released.
+Our most important fix is <a href="" target="__blank">issue #92</a>. 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 <a href="" target="__blank">output large BIB or session tables</a>, and <a href="" target="__blank">works a lot harder to keep the database free from trashy leftover records</a>.
+Then we have a couple of <a href="" target="__blank">performance</a> <a href="" target="__blank">optimizations</a>. 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 <a href="" target="__blank">as-of-now</a>-missing [documentation of `--minMTU6`](userspace-app.html#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:
@@ -5,7 +5,9 @@ title: Documentation - Quirk-iptables
# Quirk: The iptables Conundrum
-(Please note: This is all based on personal research. The Linux Kernel is a massive behemoth and as such, I might have overlooked some detail. If you know of some feature that trumps the reasoning exposed here, we'd love to hear it - [](
+> **Warning.**
+> Because the RFC wants us to [fragment outgoing IPv6 packets compulsively](userspace-app.html#minmtu6), we now consider this whole reasoning a fallacy. This quirk will probably go away in the next iteration.
## Index
@@ -14,6 +14,7 @@ title: Documentation - Userspace Application
5. [\--session](#session)
6. [\--filtering](#filtering)
7. [\--translate](#translate)
+8. [\--fragment](#fragment)
## Introduction
@@ -462,3 +463,42 @@ Note that if `--boostMTU` is activated, the MTU will still be 1280 if the result
Also, you don't really need to sort the values while you input them. Just saying.
+### \--minMTU6
+- Name: Minimum IPv6 MTU
+- Type: Integer
+- Default: 1280
+- Translation direction: IPv4 to IPv6
+All of your IPv6 networks have MTUs. You should set `--minMTU6` as the smallest of them.
+IPv4 routers fragment, IPv6 routers don't fragment. If Jool receives a fragmentable IPv4 packet (Don't Fragment (DF) bit off), it has to make sure it's small enough to fit into any forthcoming IPv6 links (because the translation to IPv6 turns fragmentable packets into non-fragmentable packets). Otherwise, the smaller IPv6 hop will not let the packet through.
+The way Jool "makes sure it's small enough" is by fragmenting the packet by itself. So, if a fragmentable IPv4 packet gets translated into a IPv6 packet whose length is higher than `--minMTU6`, Jool will fragment it prior to sending it.
+So again, you want `--minMTU6` to be the smallest of your IPv6 MTUs so any of these formerly fragmentable packets will manage to fit into any IPv6 networks.
+This value defaults to 1280 because all IPv6 networks are theoretically guaranteed to support at least 1280 bytes per packet. If all of your IPv6 networks have a higher MTU, you can raise `--minMTU6` to decrease chances of fragmentation.
+- The penalty of `--minMTU6` being too small is performance; you get some unwanted fragmentation.
+- The penalty of `--minMTU6` being too big is reliability; the IPv6 nodes which are behind networks with lesser MTUs will not be able to receive packets from IPv4 whose DF flag os off and which, once translated, are larger than `--minMTU6`.
+IPv6 packets and unfragmentable IPv4 packets don't need any of this because they imply the emitter is the one minding MTUs and packet sizes (via <a href="" target="_blank">Path MTU Discovery</a> or whatever).
+## \--fragment
+Because of [this quirk](quirk-iptables.html), Jool has its own defragmenter, which is built upon different requirements than those from the kernel's.
+> Warning.
+> We've recently found the aforementioned quirk to be a fallacy, and we're <a href="" target="_blank">experimenting on replacing Jool's defragmenter with the kernel's</a>.
+> As a result, this section of the configuration is bound to be replaced by the kernel's <a href="" target="_blank">fragmentation sysctl controls</a> in the future.
+### \--toFrag
+- Name: Defragmentation Timeout
+- Type: Integer (seconds)
+- Default: 2
+Time in seconds to keep an IP fragment in memory.
@@ -110,10 +110,14 @@ Generate IPv4 identification
Decrease MTU failure rate
.IP --plateaus=INT[,INT]*
MTU plateaus
+.IP --minMTU6=INT
+Minimum MTU of all your IPv6 networks.
.SS "--fragmentation's FLAG_KEYs"
.IP --toFrag=INT
Set the fragment reassembly timeout (in seconds).
+.B Note:
+The Fragment Database (and hence this value) is bound to be obsoleted in the next version. If you're using it in your scripts, be prepared to want to tweak them.
Print the IPv6 pool:

0 comments on commit 5295b05

Please sign in to comment.