small doc changes

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

1 files changed, 88 insertions, 147 deletions

diff --git a/README.dbk b/README.dbk
index 1241b1b..7fc6aff 100644
--- a/README.dbk
+++ b/README.dbk
@@ -8,7 +8,7 @@
     <author>
       <firstname>Sven-Ola</firstname>
 
-      <surname>Tücke</surname>
+      <surname>Tuecke</surname>
 
       <affiliation>
         <orgname>Freifunk</orgname>
@@ -18,15 +18,12 @@
     <pubdate>06-OCT-2010</pubdate>
   </articleinfo>
 
-  <para>These files implement a Linux netfilter target to change the IPv6
-  address of packets. The address change is done checksum neutral, thus no
-  checksum re-calculation for the IPv6 packet is necessary. You can change the
-  IPv6 source address of outgoing packets as well as the IPv6 destination
-  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 implementation is based on
-  the expired the IETF discussion paper published here:</para>
+  <para>These files implement a Linux netfilter target that changes the IPv6 address of packets. The address change is done
+  checksum neutral, thus no checksum re-calculation for the packet is necessary. You can change the IPv6 source address of
+  outgoing packets as well as the IPv6 destination 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 implementation is based on the expired the IETF
+  discussion paper published here:</para>
 
   <para><ulink
   url="http://tools.ietf.org/html/draft-mrw-behave-nat66-02">http://tools.ietf.org/html/draft-mrw-behave-nat66-02</ulink></para>
@@ -34,48 +31,37 @@
   <section>
     <title>Installation</title>
 
-    <para>MAP66 implements two pieces of software: a shared library that
-    extends the ip6tables command and a Linux kernel module. The shared
-    library file adds the '-j MAP66' target to the ip6tables command. To build
-    and install, you need ip6tables installed as well as the necessary
-    headers. The Linux kernel module requires the Linux source file tree and
-    Linux configuration files to compile. On a Debian/(EKU)buntu, the
-    following command prepares the build environment:</para>
+    <para>MAP66 implements two pieces of software: a shared library that extends the ip6tables command and a Linux kernel
+    module. The shared library file adds the '-j MAP66' target to the ip6tables command. To build and install, you need
+    ip6tables installed as well as the necessary headers. The Linux kernel module requires the Linux source file tree and kernel
+    configuration files to compile. On a Debian/(EKU)buntu, the following command prepares the build environment:</para>
 
     <programlisting>sudo apt-get install build-essential linux-headers iptables-dev</programlisting>
 
-    <para>Unpack the source tgz archive, change to the directory and issue
-    "make" to build. If this compiles without errors, install the ip6tables
-    extension with the following command:</para>
+    <para>Unpack the source tgz archive to <filename>/usr/src</filename>, change to the archive's sub-directory and issue "make"
+    to build. If this compiles without errors, install the ip6tables extension with the following command:</para>
 
     <programlisting>sudo make install</programlisting>
 
     <note>
-      <para>The kernel module (<filename>ip6t_MAP66.ko</filename> for
-      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>
+      <para>The kernel module (<filename>ip6t_MAP66.ko</filename> for 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>
     </note>
   </section>
 
   <section>
     <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 <filename>dkms.conf</filename>
-    file is included with the MAP66 source file package. Install DKMS with the
+    <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 <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 <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>
+    <para>If not already in place, move/unpack the MAP66 source file archive below <filename>/usr/src/</filename>. 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
@@ -91,53 +77,37 @@ sudo dkms install -m ip6t_MAP66 -v 0.3</programlisting>
     <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>
+      <para>You always need to add two ip6tables-rules to your netfilter configuration. One rule matches outgoing packets and
+      changes their IPv6 source address. The second rule matches incoming packets and revert the address change by altering
+      their 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>
+      <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 result in 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
+      <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). Throughout the mesh network, a private IP address range is
+      used. The ULA prefix is 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 IPv6 Internet gateway for the mesh. You can reach the
+      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
@@ -161,14 +131,11 @@ iface tun6to4 inet6 v4tunnel
         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>
+      <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 purposes, 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 realize mapping from the private fdca:ffee:babe::/64 prefix to the globally valid IPv6
+      addresses:</para>
 
       <programlisting>ip6tables -t mangle -F POSTROUTING
 ip6tables -t mangle -F PREROUTING
@@ -183,34 +150,26 @@ ip6tables -t mangle -A POSTROUTING -o tun6to4 -s fdca:ffee:babe::/64 -j MAP66 --
 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
+      <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 be converted
+      to 2001:4dd0:fe77:0::1/128 in this context. For this reason, we can use the <userinput>--nocheck</userinput> speedup
       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>
+      <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 on my PC, 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>
+        <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 6-to-4 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 the 6-to-4 interface. If the above address mapping is configured, you ping one IPv6 address and get the
+        answer from another IPv6 address...</para>
       </note>
     </section>
   </section>
@@ -218,68 +177,50 @@ ip6tables -t mangle -A FORWARD -p tcp --tcp-flags SYN,RST SYN -j TCPMSS --clamp-
   <section>
     <title>Hints (Chapter is To-do)</title>
 
-    <para>Note for me: svn propedit svn:ignore.</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>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>
+    <para>Idea to think about: --salt 3b5b91c5a2 XOR client addresses for some more privacy</para>
   </section>
 
   <section id="motivation">
     <title id="motivation-title">Motivation</title>
 
-    <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.
-    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>
+    <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. 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>
 
     <itemizedlist>
       <listitem>
-        <para>Address amplification - something not necessary with IPv6 any
-        more</para>
+        <para>Address amplification - something not necessary with IPv6 any more</para>
       </listitem>
 
       <listitem>
-        <para>Anonymization - nice to have as an option but not mission
-        critical</para>
+        <para>Anonymization - nice to have as an option but not mission critical</para>
       </listitem>
 
       <listitem>
-        <para>ISP independence - no reverse routing, no
-        "buy-a-number-range"</para>
+        <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
-    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 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 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
-    not possible. This is where I start to think: "hey, some kind of address
-    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
+    <para>The last point <emphasis role="bold">is</emphasis> mission critical. One can obtain a provider 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 your address range to be re-routed to your new location.</para>
+
+    <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 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 not possible. This is where I start to think: <quote>hey, some kind of address mapping may be nice to
+    have</quote>. While opening Pandora's NAT66 box, I discovered that IPv6 nerds do not like the acronym. It is always a good
     tactic in info wars to rename, hence the name "MAP66".</para>
 
     <para>// Sven-Ola</para>