Permalink
Browse files

Most (if not all) the substancial documentation updates for version 3…

….2.0.
  • Loading branch information...
ydahhrk committed Aug 1, 2014
1 parent 4c66bc4 commit 752ed2584534e6bf6bd481d7f4d4ababb6424efe
View
@@ -33,22 +33,24 @@ Alternatively, you might want to upload bugs and pull requests to the [issue tra
### ITESM students
-* [Juan Antonio Osorio](https://github.com/JAORMX) <jaosorior@gmail.com>
-* [Luis Fernando Hinojosa](https://github.com/luion) <lf.hinojosa@gmail.com>
-* [David Valenzuela](https://github.com/davidvrdz) <david.valenzuela.88@gmail.com>
-* Jose Vicente Ramirez <pepermz@gmail.com>
-* Mario Gerardo Trevinho <mario_tc88@hotmail.com>
-* [Roberto Aceves](https://github.com/robertoaceves) <roberto.aceves@gmail.com>
-* [Miguel Alejandro González](https://github.com/magg) <maggonzz@gmail.com>
-* [Ramiro Nava](https://github.com/ramironava) <ramironava@gmail.com>
-* [Adrian González](https://github.com/Adrian2112) <bernardogzzf@gmail.com>
-* Manuel Aude <dormam@gmail.com>
-* [Gabriel Chavez](https://github.com/chavezgu) <gabrielchavez02@gmail.com>
-* Alan Villela López <avillop@gmail.com>
-* [Angel Cazares](https://github.com/legionAngel) <angel.cazares@live.com>
-* [Abraham Baez](https://github.com/basuam) <basuam@gmail.com>
-* Ing. Elvia Patricia Barrón Cano <epatybarron@gmail.com>
+* [Abraham Baez](https://github.com/basuam) - basuam@gmail.com
+* [Adrian González](https://github.com/Adrian2112) - bernardogzzf@gmail.com
+* Alan Villela López - avillop@gmail.com
+* [Angel Cazares](https://github.com/legionAngel) - angel.cazares@live.com
+* [David Valenzuela](https://github.com/davidvrdz) - david.valenzuela.88@gmail.com
+* Ing. Elvia Patricia Barrón Cano - epatybarron@gmail.com
+* [Gabriel Chavez](https://github.com/chavezgu) - gabrielchavez02@gmail.com
+* Jose Vicente Ramirez - pepermz@gmail.com
+* [Juan Antonio Osorio](https://github.com/JAORMX) - jaosorior@gmail.com
+* [Juan Francisco Barragán Cantú]() - p.cantu12@gmail.com
+* [Luis Fernando Hinojosa](https://github.com/luion) - lf.hinojosa@gmail.com
+* Manuel Aude - dormam@gmail.com
+* Mario Gerardo Trevinho - mario_tc88@hotmail.com
+* [Miguel Alejandro González](https://github.com/magg) - maggonzz@gmail.com
* [Nixa Jayu Gpe Rodríguez Dagnino](https://github.com/NixaDagnino)
+* [Ramiro Nava](https://github.com/ramironava) - ramironava@gmail.com
+* [Roberto Aceves](https://github.com/robertoaceves) - roberto.aceves@gmail.com
+* [Roberto Martínez Beltrán]() - robmabe.92@gmail.com
### Special Thanks (contributing users)
View
@@ -6,23 +6,9 @@ This folder contains **source** files you can use to generate the project's docu
If you're a user, you should just follow that link and don't bother generating these files. But if you disagree, you're supposed to compile them using [Jekyll](http://jekyllrb.com/).
-First install Jekyll by following the steps outlined at https://help.github.com/articles/using-jekyll-with-pages:
-
-```bash
-$ # YMMV
-$ ruby --version
-ruby 1.9.3p194 (2012-04-20 revision 35410) [x86_64-linux]
-# gem install bundler
-$ echo "source 'https://rubygems.org'" > Gemfile
-$ echo "gem 'github-pages'" >> Gemfile
-# bundle install
-```
-
-Then generate using the `jekyll` command:
-
```bash
$ cd usr
-$ jekyll
+$ jekyll build
```
Have a look at your generated files in the newly-generated usr/_site folder.
@@ -31,15 +17,6 @@ Have a look at your generated files in the newly-generated usr/_site folder.
`dev/` contains a file you're supposed to run using [Doxygen](http://www.stack.nl/~dimitri/doxygen/). It is documentation indended for developers; Doxygen will extract the header comments from the code and summarize them in HTML form (by default).
-Installation:
-
-```bash
-$ # YMMV
-# apt-get install doxygen
-```
-
-Doc generation:
-
```bash
$ cd dev
$ doxygen
View
@@ -276,6 +276,10 @@ code {
padding-right: 0.3em;
}
+.bash .c {
+ color: #058;
+}
+
table {
display: block;
background-color: #f8f8f8;
View
@@ -7,32 +7,29 @@ title: Documentation - Index
Welcome to Jool's documentation site.
-## Quick links
+## Introduction
-If you're completely lost, first [click here for an introduction to NAT64](intro.html).
+1. [What is NAT64?](intro.html)
+2. [What is Jool?](intro.html#jool)
-If you just want to run Jool, [click here to get started](tutorial1.html).
-
-## Formal index
-
-### Tutorials
+## Kernel module
1. [Compilation and Installation](tutorial1.html)
-2. [Basic Runs](tutorial2.html)
-3. [A Bigger IPv4 Pool](tutorial3.html)
-4. [DNS64](tutorial4.html)
+2. [Tutorial - Basic Runs](tutorial2.html)
-### Miscellaneous
+## Userspace application
-1. [Introduction to NAT64](intro.html)
-2. [Static Bindings](static-bindings.html)
-3. [The problem with Offloading](offloading.html)
+1. [Compilation and Installation](userspace-app-install.html)
+2. [Flags](userspace-app-flags.html)
-### Reference material
+## Further operation
-1. [Userspace Application](userspace-app.html)
+1. [Static Bindings](static-bindings.html)
+2. [A Bigger IPv4 Pool](tutorial3.html)
+3. [DNS64](tutorial4.html)
-### Quirks
+## Miscellaneous
-1. [Quirk list](quirks.html)
+1. [The problem with Offloading](offloading.html)
+2. [Jool's thievish nature](quirk-thieve.html)
@@ -7,12 +7,13 @@ title: Download
Latest version:
-[Jool v3.1.5](https://www.jool.mx/download/Jool-3.1.5.zip) - [SHA256](https://www.jool.mx/download/Jool-3.1.5.sha), [MD5](https://www.jool.mx/download/Jool-3.1.5.md5)
+[Jool v3.2.0](https://www.jool.mx/download/Jool-3.2.0.zip) - [SHA256](https://www.jool.mx/download/Jool-3.2.0.sha), [MD5](https://www.jool.mx/download/Jool-3.2.0.md5)
You can also use the <a href="https://github.com/NICMx/NAT64" target="_blank">git repository</a> if you want.
Usage of previous versions is never recommended, but here you go, just in case:
+- [Jool v3.1.5](https://www.jool.mx/download/Jool-3.1.5.zip) - [SHA256](https://www.jool.mx/download/Jool-3.1.5.sha), [MD5](https://www.jool.mx/download/Jool-3.1.5.md5)
- [Jool v3.1.4](https://www.jool.mx/download/Jool-3.1.4.zip) - [SHA256](https://www.jool.mx/download/Jool-3.1.4.sha), [MD5](https://www.jool.mx/download/Jool-3.1.4.md5)
- [Jool v3.1.3](https://www.jool.mx/download/Jool-3.1.3.zip) - [SHA256](https://www.jool.mx/download/Jool-3.1.3.sha), [MD5](https://www.jool.mx/download/Jool-3.1.3.md5)
- [Jool v3.1.2](https://www.jool.mx/download/Jool-3.1.2.zip) - [SHA256](https://www.jool.mx/download/Jool-3.1.2.sha), [MD5](https://www.jool.mx/download/Jool-3.1.2.md5)
View
@@ -22,19 +22,28 @@ If you want to know what the development team is currently tweaking, you should
But just to make things clear, this is the status of the project as of now:
-Jool is still a couple of features away from being 100% RFC 6146 compliant:
+Jool is still <a href="https://github.com/NICMx/NAT64/issues/41" target="_blank">one feature away</a> from being 100% RFC 6146 compliant. That doesn't stop the IPv6-IPv4 translation mechanism from being functional, however.
-1. <a href="https://github.com/NICMx/NAT64/issues/41" target="_blank">Filtering policies</a>
-2. <a href="https://github.com/NICMx/NAT64/issues/58" target="_blank">Simultaneous open of TCP connections</a>
-
-That doesn't stop the IPv6-IPv4 translation mechanism from being functional, however.
-
-Our next target is **Simultaneous open of TCP connections**. Now cooking version 3.2.0...
+Out last release is version <a href="https://github.com/NICMx/NAT64/milestones/3.2.0" target="_blank">3.2.0</a>. Now cooking 3.3.0...
-------------------
## News
+### 2014-07-X (TODO)
+
+Version 3.2.0 released.
+
+<a href="https://github.com/NICMx/NAT64/issues/58" target="_blank">Simultaneous Open of TCP Connections</a> is now correctly implemented. The translation pipeline should now be completely quirkless.
+
+The userspace application has a couple of new features: The <a href="https://github.com/NICMx/NAT64/pull/97" target="_blank">ability to flush the pools</a> and the addition of `--quick` (TODO). On the other hand, the single-value configuration parameters have been joined: `--general` (TODO) replaced `--filtering` and `--translate`, and `--fragmentation` has been dropped (since you now configure the kernel's defragmenter, not Jool's).
+
+A <a href="https://github.com/NICMx/NAT64/issues/103" target="_blank">little confusion</a> also revealed that the path to libnl <a href="https://github.com/NICMx/NAT64/commit/6455ffd898bae996ce3cab37b2fb6a3459ae096b" target="_blank">used to be hardcoded in the configuration script</a>. 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 major <a href="https://github.com/NICMx/NAT64/issues/104" target="_blank">refactor to the fragmentation code</a>, a <a href="https://github.com/NICMx/NAT64/issues/100" target="_blank">complement to the old issue #65</a>, and a <a href="https://github.com/NICMx/NAT64/issues/56" target="_blank">healthier code-to-comment ratio</a> :).
+
+These are the changes to the documentation: TODO.
+
### 2014-06-26
By the way:
View
@@ -106,23 +106,28 @@ Stateful NAT64 is defined by <a href="http://tools.ietf.org/html/rfc6146" target
## Jool
-Jool is an Open Source implementation of a Stateful NAT64 on Linux. It is intended to comply perfectly with the RFC. As of now (2014-01-13), we're two features away from the goal:
+Jool is an Open Source implementation of a Stateful NAT64 on Linux. It is intended to comply perfectly with the RFC. As of now (2014-07-30), we're one feature away from the goal:
-1. <a href="https://github.com/NICMx/NAT64/issues/58" target="_blank">Simultaneous open of TCP connections</a> (being worked on <a href="https://github.com/NICMx/NAT64/tree/tcp_store_packet" target="_blank">here</a>).
-2. <a href="https://github.com/NICMx/NAT64/issues/41" target="_blank">Filtering policies</a> (not quite on the map yet).
+1. <a href="https://github.com/NICMx/NAT64/issues/41" target="_blank">Filtering policies</a>.
-We're supposed to support Linux kernels 3.0.0 and up, but we don't have the resources to test every variation.
+We're supposed to support Linux kernels 3.0.0 and up. While most of the development time has been spent experimenting on Ubuntu 12.04 using kernel 3.2.0-63-generic-pae, we've performed a healthy amount of formal testing on Jool 3.1.5 in the following variants:
-Specifically, we have formally tested the system in the following kernels:
-
-* 3.2.0
-* 3.5.0
-* 3.8.0
-* 3.11.5
+| Distribution | Kernels |
+| -------------|---------|
+| CentOS | 3.10 |
+| Debian 7 | 3.2 |
+| Red Hat | 3.10 |
+| SuSE | 3.0.101-0.35-default |
+| Ubuntu 12.04 | 3.1.10-030110-generic, 3.2.60-030260-generic |
+| Ubuntu 12.10 | 3.3.8-030308-generic, 3.4.94-030494-generic, 3.5.7-03050733-generic |
+| Ubuntu 13.04 | 3.6.11-030611-generic, 3.7.10-030710-generic, 3.8.13-03081323-generic |
+| Ubuntu 13.10 | 3.9.11-030911-generic, 3.10.44-031044-generic, 3.11.10-03111011-generic |
+| Ubuntu 14.04 | 3.12.22-031222-generic, 3.13.11-03131103-generic |
+| Ubuntu 14.10 | 3.14.8-031408-generic, 3.15.1-031501-generic |
### Considerations
-Our second missing feature (see above) means that you cannot firewall your packets being translated. If you need to filter, you're better off placing another node next to the NAT64 to do the task.
+Our missing feature (see above) means that you cannot firewall your packets being translated. If you need to filter, you're better off placing another node next to the NAT64 to do the task.
Here's a [list of oddities](quirks.html) regarding Jool's design that people might want to debate.
@@ -46,7 +46,7 @@ This is all fine and dandy, but you start running into trouble when the system i
In step 1 the aggregation happens, which makes step 2 very fast, but then because the assembled packet of the blue stream is too big for the outgoing interface (size 1800 > max 1500), the packet gets fragmented in step 3, which is inefficient.
-More importantly, if the emitter performed <a href="http://en.wikipedia.org/wiki/Path_MTU_Discovery" target="_blank">path MTU discovery</a>, then the optimum MTU computed will be lost in step 1 (because it is not stored in the packet; it is indicated by its size, which step 1 mangles). If the Don't Fragment flag of the IPv4 header is _not_ set, then this will encourage further re-fragmentation. But if the flag IS set, then the packet will be eventually and irremediably dropped as soon as it reaches a lower MTU. Hence, we just created a black hole.
+More importantly, if the emitter performed <a href="http://en.wikipedia.org/wiki/Path_MTU_Discovery" target="_blank">path MTU discovery</a>, then the optimum MTU computed will be lost in step 1 (because it is not stored in the packet; it is indicated by its size, which step 1 mangles). Because the packet's Don't Fragment flag is going to be ON, then the packet will be eventually and irremediably dropped as soon as it reaches a lower MTU. Hence, we just created a black hole.
(Well, not completely. A number of conditions are required for the NIC to run offloading. These conditions might rarely and randomly not be met, so certain packets will occasionally not be aggregated, and as such will slip past the hole. If your transport protocol retries enough, instead of having a complete denial of service, you get an extremely - **EXTREMELY** - slow network.)
@@ -1,91 +0,0 @@
----
-layout: documentation
-title: Documentation - Quirk-iptables
----
-
-# Quirk: The iptables Conundrum
-
-> **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
-
-1. [Theory](#theory)
- 1. [IPv4 defrag](#ipv4-defrag)
- 2. [defrag and the IPv6 world](#defrag-and-the-ipv6-world)
-2. [The current status](#the-current-status)
-
-## Theory
-
-I need to clear something up first: Netfilter is not the same as iptables. Netfilter is a really low level packet manipulation framework (just hooks really) where anything goes, whereas iptables is a more specific one where Linux implements filtering, mangling and NAT. iptables sits on top of Netfilter. It has more tools to develop with, but also more constraints.
-
-(Despite this, both terms are usually used as synonyms because there is usually pretty much one thing sitting on top of Netfilter, and that one thing is iptables.)
-
-Seeing that traditional NAT is implemented on top of iptables, it would seem natural that a NAT64 implementation would do the same. So why is Jool sitting on Netfilter instead?
-
-Because of a corner-case scenario. In order to get to it, I have to backtrack a little:
-
-### IPv4 defrag
-
-In the **IPv4** pipeline, there exists an iptables module normally hooked up to Netfilter, whose name I believe is "<a href="http://lxr.free-electrons.com/source/net/ipv4/netfilter/nf_defrag_ipv4.c?v=3.5" target="_blank">defrag</a>". It is normally the very first step in the chain (as can be seen in the <a href="http://lxr.free-electrons.com/source/include/linux/netfilter_ipv4.h?v=3.5#L57" target="_blank">priority list</a>) and is a life-saver for most of Linux's Network Stack. As its name might imply, its purpose is to assemble incoming fragments so the rest of the code can enjoy relieving privileges such as guaranteed transport headers and the irrelevance of a number of fields in the IP ones.
-
-It is to the point that Linux machines feature the perhaps odd idiosyncrasy of outputting different IPv4 fragments than the ones received, since defrag is normally active even while forwarding. One might argue that this is inefficient since fragmented packets have to first be copied to a single larger buffer and then sliced back, but in reality the end result is probably faster since one gets better "MTU utilization", which is probably more critical than CPU (Also, there's the concept of paged packets, but I'm not sure if it's being used to handle fragments. Anyway, I digress).
-
-The presence of this potential size fluctuation of packets while forwarding in IPv4 is usually painless:
-
-* If an incoming packet's DF flag is off, then who cares if it is sliced back and forth along the way, as long as it is correctly reassembled at the destination.
-* If the DF flag is on, then the packet will never be a fragment, so there will be nothing to reassemble. Its size will not change.
-
-NAT depends on conntrack, and conntrack depends on defrag. There's nothing wrong with this; fragments do not affect the major hack which is NAT.
-
-### defrag and the IPv6 world
-
-The problem is that NAT64's nature (specifically, the inclusion of IPv6) stretches NAT's hack a little further. I'm sorry that this will sound very similar to the [offload fiasco](offloading.html), but here it goes:
-
-There is no "IPv6 defrag" module for a reason: There is no "Don't Fragment" (DF) flag in the IPv6 Fragment Header. This means that no IPv6 packets are meant to be fragmented or assembled by routers (i.e. as if DF was always on). I understand there's this assumption in the IPv4 protocol that if a packet with no DF flag arrives, then a packet with no DF flag departs. But what if the forwarder is translating to IPv6? One thing that can happen is:
-
-![Fig.1 - NAT64 with defrag](images/iptc-defrag.svg)
-
-1. Node A (IPv4) sends fragmentable (DF off) fragments.
-2. (defrag assembles fragments and) NAT64 translates the packet.
-3. Packet doesn't fit the MTU, so router B sends back the ICMPv6 error "<a href="http://tools.ietf.org/html/rfc4443#section-3.2" target="_blank">Packet too big</a>".
-4. NAT64 translates the error into the spiritually equivalent ICMPv4 error "<a href="http://tools.ietf.org/html/rfc792" target="_blank">fragmentation needed (and DF set)</a>".
-5. Node A says "What are you talking about? DF WAS NOT SET!!!"
-6. Perhaps Node A creates smaller fragments.
-7. Node A again receives the ICMP error, since defrag is still assembling in the NAT64 step.
-8. Keep trying, keep failing.
-
-The problem exists here because NAT64 was _forced_ into Linux's infrastructure. Pure NAT64 as explained by RFC 6146 assumes no defrag module; fragments are supposed to be _correlated_, never _assembled_. The correct way to do it can be exemplified as follows:
-
-![Fig.2 - NAT64 without defrag](images/iptc-nodefrag.svg)
-
-1. Node A (IPv4) sends fragmentable (DF off) fragments.
-2. The NAT64 translates each fragment separately.
-3a. This time each fragment is not a behemoth, so the router forwards.
-3b. Alternatively, the fragments are still too big so Node A retries with smaller fragments. This time the fragments fit and the router forwards. Or Node A surrenders, but at least it wasn't Jool's fault.
-
-The fact that iptables depends on defrag pretty much means that Jool has to _replace_ iptables if it wants to be as reliable as it can be.
-
-## The current status
-
-Jool has handled fragmentation correctly since version 3.1.0, but you might still come up with a couple of questions:
-
-### I haven't rmmoded iptables. Why does everything seem to work?
-
-While Jool (or stateful NAT64 for that matter) is incompatible with iptables, Netfilter is versatile enough that you don't have to kill iptables in order to deploy Jool.
-
-That is because Netfilter queues modules and has packets visit them in a developer-defined order. The order is normally something in the lines of defrag -> conntrack -> firewall/NAT. Jool currently hooks itself to the beginning of the line, so it _steals_ packets directed to its pools and the rest of the chain doesn't get to see them.
-
-(You might think this _robbery_ is a hack, but preventing the packets from reaching defrag [is neither the only nor the main reason why we did it](quirk-thieve.html).)
-
-Note that packets that aren't meant to be translated (i.e. not headed towards the pools) are _not_ stolen by Jool, which means you can benefit from having them visit iptables for purposes such as local firewalling.
-
-### What if I want to filter translated packets?
-
-Yes, we have this problem. iptables is your usual firewall, and if Jool prevents it from touching your packets, you can't filter them.
-
-But you see, the RFC dictates that stateful NAT64 implementations are supposed to provide a way for you to define filtering rules. We just <a href="https://github.com/NICMx/NAT64/issues/41" target="_blank">haven't implemented them yet</a>.
-
-While we're at it, you can work around it by placing a firewall adjacent to the NAT64 machine to do your filtering.
-
Oops, something went wrong.

0 comments on commit 752ed25

Please sign in to comment.