more doc

git-svn-id: https://map66.svn.sourceforge.net/svnroot/map66@6 3484d885-4da6-438d-b19d-107d078dd756

1 files changed, 154 insertions, 37 deletions

diff --git a/README.dbk b/README.dbk
index 2a50e00..1241b1b 100644
--- a/README.dbk
+++ b/README.dbk
@@ -25,7 +25,7 @@
   address of incoming packets. This allows you to map an internal IPv6 address
   range to a second, externally used IPv6 address range. IPv6 address mapping
   is not very similar to IPv4 network address translation, but one can
-  describe it as some sort of stateless NAT. The implmementation is based on
+  describe it as some sort of stateless NAT. The implementation is based on
   the expired the IETF discussion paper published here:</para>
 
   <para><ulink
@@ -55,27 +55,27 @@
       Linux-2.6 or <filename>ip6t_MAP66.o</filename> for Linux-2.4) is not
       automatically installed nor loaded into the kernel. You can copy the
       kernel module file manually, e.g. with <userinput>sudo cp ip6t_MAP66.ko
-      /lib/modules/$(uname -r)/</userinput>. </para>
+      /lib/modules/$(uname -r)/</userinput>.</para>
     </note>
   </section>
 
   <section>
-    <title>DKMS integration</title>
+    <title>DKMS Integration</title>
 
     <para>If the next system update needs to install a new kernel version, you
     also need to re-compile/re-install the MAP66 kernel module. With
     Debian/(EKU)buntu, this can be automated with the Dynamic Kernel Module
-    Support Framework (DKMS). For this, the dkms.conf file is included with
-    the MAP66 source file package. Install DKMS with the following
-    command:</para>
+    Support Framework (DKMS). For this, the <filename>dkms.conf</filename>
+    file is included with the MAP66 source file package. Install DKMS with the
+    following command:</para>
 
     <programlisting>sudo apt-get install dkms</programlisting>
 
     <para>Move/unpack the MAP66 source files below /usr/src and adapt the
     directory name to the version mentioned in the dkms.conf file. For
-    example, issue "mkdir /usr/src/ip6t_MAP66-0.3" and "cp *
-    /usr/src/ip6t_MAP66-0.3/". To register the MAP66 source to DKMS and
-    compile/install, issue these commands:</para>
+    example, issue <userinput>mkdir /usr/src/ip6t_MAP66-0.3</userinput> and
+    <userinput>cp * /usr/src/ip6t_MAP66-0.3/</userinput>. To register the
+    MAP66 source to DKMS and compile/install, issue these commands:</para>
 
     <programlisting>sudo dkms add -m ip6t_MAP66 -v 0.3
 sudo dkms build -m ip6t_MAP66 -v 0.3
@@ -88,39 +88,156 @@ sudo dkms install -m ip6t_MAP66 -v 0.3</programlisting>
   <section>
     <title>Configuration</title>
 
-    <para>Note for me: svn propedit svn:ignore.</para>
-
-    <para>Note: on ubuntu, you need to enable prefer-family in /etc/wgetrc.
-    after this e.g. "wget -O /dev/null http://ftp.se.debian.org" should
-    connect to the IPv6 addrs of that server.</para>
-
-    <para>/etc/gai.conf</para>
+    <section>
+      <title>Brief Version</title>
+
+      <para>You always need to add two ip6tables-rules to your netfilter
+      configuration. One rule matches the outgoing packet and changes the IPv6
+      source address. The second rule matches the incoming packet and revert
+      the address change by altering the IPv6 destination address. To
+      following commands correspond to the <quote>Address Mapping
+      Example</quote> given in the IETF discussion paper:</para>
+
+      <programlisting>ip6tables -t mangle -I POSTROUTING -o eth0 -s FD01:0203:0405::/48 -j MAP66 --to 2001:0DB8:0001::/48
+ip6tables -t mangle -I PREROUTING  -i eth0 -d 2001:0DB8:0001::/48 -j MAP66 --to FD01:0203:0405::/48</programlisting>
+
+      <para>This example is also printed to the screen if you issue
+      <userinput>ip6tables -j MAP66 --help</userinput>. By design, you cannot
+      use an arbitrary prefix length. Only /112, /96 .. /16 are supported.
+      </para>
+
+      <para>For each packet, the Linux kernel module also compares the
+      packet's source address to all IPv6 addresses assigned to the outgoing
+      interface. It a match is found, the packet's source address is not
+      mapped. The same comparison happens on the incoming packet's destination
+      address. The comparison require some CPU resources, especially if the
+      interface has a large number of assigned IPv6 addresses. If you are
+      sure, that the mapping cannot match the IPv6 address of the interface
+      (e.g. the mapping rule defines a mapping prefix that cannot match the
+      interface address) you can switch off the comparison. Add the
+      <userinput>--nocheck</userinput> parameter to the ip6tables command for
+      this. </para>
+    </section>
+
+    <section>
+      <title>Detailed Version</title>
+
+      <para>The following explanation details a living example from the
+      wireless mesh network that is mentioned under <xref
+      endterm="motivation-title" linkend="motivation" /> (see below). The mesh
+      network uses a private IP range, the ULA prefix fdca:ffee:babe::/64. All
+      mesh nodes derive their IPv6 interface addresses by correlating the ULA
+      prefix with the EUI48 (<quote>MAC address</quote>) of the respective
+      network adapter. </para>
+
+      <para>There is a Debian based virtual machine that should act as one
+      Internet gateway for the mesh. You can reach this virtual machine's web
+      service via IPv4 under <ulink
+      url="http://bbb-vpn.freifunk.net">http://bbb-vpn.freifunk.net</ulink>.
+      To experiment with IPv6, a <ulink
+      url="http://www.sixxs.net/">SIXXS</ulink> static tunnel setup has been
+      added and there is also an experimental 6-to-4 configuration. The
+      following <filename>/etc/network/interfaces</filename> file provides the
+      configuration for IPv6:</para>
+
+      <programlisting>auto sixxs
+iface sixxs inet6 v4tunnel
+        address  2001:4dd0:ff00:2ee::2
+        netmask 64
+        local 77.87.48.7
+        endpoint 78.35.24.124
+        ttl 64
+        up ip link set mtu 1280 dev $IFACE
+        up ip route add default via  2001:4dd0:ff00:2ee::1 dev $IFACE
+        up ip addr add 2001:4dd0:fe77::1/48 dev $IFACE
+
+#auto tun6to4
+iface tun6to4 inet6 v4tunnel
+        # ipv6calc --quiet --action conv6to4 77.87.48.7
+        address 2002:4d57:3007::1
+        netmask 16
+        local 77.87.48.7
+        endpoint any
+        ttl 64
+        gateway ::192.88.99.1</programlisting>
+
+      <para>As you can see, the virtual machine has an IPv6 prefix of
+      2001:4dd0:fe77::/48 and is reachable via <ulink
+      url="http://[2001:4dd0:fe77::1]/">http://[2001:4dd0:fe77::1]/</ulink>.
+      For experimental reasons, the 6-to-4 tunnel can be activated by issuing
+      <userinput>ifup tun6to4</userinput>. The netfilter setup of this machine
+      includes the following command sequence to ensure mapping from the
+      private fdca:ffee:babe::/64 prefix to the globally valid IPv6
+      address:</para>
+
+      <programlisting>ip6tables -t mangle -F POSTROUTING
+ip6tables -t mangle -F PREROUTING
+ip6tables -t mangle -F FORWARD
+
+grep -q ^ip6t_MAP66 /proc/modules &amp;&amp; rmmod ip6t_MAP66
+insmod /usr/src/map66/ip6t_MAP66.ko
+
+ip6tables -t mangle -A POSTROUTING -o sixxs -s fdca:ffee:babe::/64 -j MAP66 --to 2001:4dd0:fe77:1::/64 --nocheck
+ip6tables -t mangle -A PREROUTING  -i sixxs -d 2001:4dd0:fe77:1::/64 -j MAP66 --to fdca:ffee:babe::/64 --nocheck
+ip6tables -t mangle -A POSTROUTING -o tun6to4 -s fdca:ffee:babe::/64 -j MAP66 --to 2002:4d57:3007:1::/64 --nocheck
+ip6tables -t mangle -A PREROUTING  -i tun6to4 -d 2002:4d57:3007:1::/64 -j MAP66 --to fdca:ffee:babe::/64 --nocheck
+ip6tables -t mangle -A FORWARD -p tcp --tcp-flags SYN,RST SYN -j TCPMSS --clamp-mss-to-pmtu</programlisting>
+
+      <para>Because for both IPv6 networks the external prefix length is
+      smaller than the internal prefix length, we can make sure that the
+      mapped addresses cannot match the interfaces address. For example:
+      2001:4dd0:fe77:1::/64 cannot match 2001:4dd0:fe77:0::1/128. For this
+      reason, we can use the <userinput>--nocheck</userinput> speedup flag
+      here.</para>
+
+      <para>You may stumble over the MSS-clamping rule. While IPv6 defines,
+      that path MTU detection via ICMPv6 must be supported by any host,
+      sometimes path MTU detection does not work. The SIXXS tunnel uses an MTU
+      of 1280 byte. To get the following command working, I needed to add the
+      above MSS-clamping rule on the gateway: </para>
+
+      <programlisting>wget --prefer-family=IPv6 -O - http://6to4.nro.net/</programlisting>
+
+      <note>
+        <para>The tun6to4 tunnel interface is disabled normally, because of
+        the implicit 2002::/16 network route configured for that interface.
+        This network route ensures, that traffic between one 2002::/16 to
+        another 2002::/16 travels directly between the IPv4 hosts. Without
+        this network route, any IPv6 traffic will be routed via the 6-to-4
+        gateways which may not work and place a higher load on those
+        gateways.</para>
+
+        <para>However, if you ping the SIXXS IP address from another host that
+        has a 6-to-4 address, you will get the answer packet back via 6-to-4.
+        If the above network mapping is configured, you ping one IPv6 address
+        and get the answer from another IPv6 address...</para>
+      </note>
+    </section>
+  </section>
 
-    <para>for wget --prefer-family=IPv6 -O - http://6to4.nro.net/ one needs
-    ip6tables -t mangle -A FORWARD -p tcp --tcp-flags SYN,RST SYN -j TCPMSS
-    --clamp-mss-to-pmtu </para>
+  <section>
+    <title>Hints (Chapter is To-do)</title>
 
-    <para>Mention --nocheck for speedup (if you do not expect the outer iface
-    in the mapping range) </para>
+    <para>Note for me: svn propedit svn:ignore.</para>
 
-    <para>Fieses zeugs: ein sixxs und ein 6to4. Kommt rein via sixxs, geht
-    raus ueber 6to4 wenn ping von einem anderen 6to4-rechner (route hat
-    2002::/16)! Ping geht, ssh aber nicht == boinks kann evnt. mit TOS
-    markiert werden und mit einer policyroute aussortiert. Brrr. </para>
+    <para>Note on ubuntu. One needs to enable prefer-family in /etc/wgetrc.
+    after this e.g. "wget -O /dev/null http://ftp.se.debian.org" should
+    connect to the IPv6 addrs of that server. Alternative: change presedence
+    of ULAs in /etc/gai.conf </para>
 
     <para>Idea to think about: --salt 3b5b91c5a2 XOR client addresses for some
-    more privacy </para>
+    more privacy</para>
   </section>
 
-  <section>
-    <title>Motivation</title>
+  <section id="motivation">
+    <title id="motivation-title">Motivation</title>
 
-    <para>My internet access at home is realized by a wireless community mesh
+    <para>My Internet access at home is realized by a wireless community mesh
     network not owned by me. The mesh is operated with small embedded devices
     (nodes aka. WLAN routers) that are interconnected via radio links (WLAN
     IBSS / AdHoc). Routing is done with a specialized protocol such as Batman
     or OLSR. The routing protocol selects the nearest out of a dozen Internet
-    gateways and configures a default route or an ipip tunnel accordingly.
+    gateways and configures a default route or an IPIP tunnel accordingly.
     Each Internet gateway is connected to a different ISP and provides the
     service with the help of IPv4 network address translation (NAT). Using NAT
     has the following effects:</para>
@@ -137,33 +254,33 @@ sudo dkms install -m ip6t_MAP66 -v 0.3</programlisting>
       </listitem>
 
       <listitem>
-        <para>ISP independance - no reverse routing, no
+        <para>ISP independence - no reverse routing, no
         "buy-a-number-range"</para>
       </listitem>
     </itemizedlist>
 
     <para>The last point _is_ mission critical. One can use a provider
-    independant IPv6 address range, but you need the cooperation of an ISP to
+    independent IPv6 address range, but you need the cooperation of an ISP to
     use that address range for Internet connectivity. If you e.g. move to
     another ISP you need that address range to be re-routed to your new
     location.</para>
 
-    <para>ISP independance is also possible with some tunneling technique,
+    <para>ISP independence is also possible with some tunneling technique,
     such as VPN or mobile IP. Tunneling can be implemented on client PCs and
     Internet gateways/servers one day. But there is no need to implement the
     same tunneling technique on every mesh node. Why? Because the mesh nodes
-    can use private IP adresses (or "ULA") to transport the tunnel data
+    can use private IP addresses (or "ULA") to transport the tunnel data
     between the client PC and the gateway/server. Each tunneling technique
     typically needs a single instance (the "server") which forms a single
     point of failure. Rule-of-thumb1: avoid a SPOF for the infrastructure.
     Rule-of-thumb2: KISS.</para>
 
     <para>Using private IP addresses on the mesh nodes has a drawback: mesh
-    node software updates e.g. via http downloads from an Internet server is
+    node software updates e.g. via HTTP downloads from an Internet server is
     not possible. This is where I start to think: "hey, some kind of address
-    mapping may be nice to have". While opening pandoras NAT66 box, I
+    mapping may be nice to have". While opening Pandora's NAT66 box, I
     discovered that IPv6 nerds do not like the acronym. It is always a good
-    tactic in infowars to rename, hence the name "MAP66".</para>
+    tactic in info wars to rename, hence the name "MAP66".</para>
 
     <para>// Sven-Ola</para>
   </section>