path: root/README.dbk

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<article>
  <articleinfo>
    <title>MAP66 (NAT from IPv6 to IPv6, NAT66) for Linux</title>

    <author>
      <firstname>Sven-Ola</firstname>

      <surname>Tuecke</surname>

      <affiliation>
        <orgname>Freifunk</orgname>
      </affiliation>
    </author>

    <pubdate>06-OCT-2010</pubdate>
  </articleinfo>

  <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>

  <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 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 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>
    </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
    following command:</para>

    <programlisting>sudo apt-get install dkms</programlisting>

    <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
sudo dkms install -m ip6t_MAP66 -v 0.3</programlisting>

    <para>Read DKMS details here: <ulink
    url="Read DKMS details here: https://wiki.kubuntu.org/Kernel/Dev/DKMSPackaging">https://wiki.kubuntu.org/Kernel/Dev/DKMSPackaging</ulink></para>
  </section>

  <section>
    <title>Configuration</title>

    <section>
      <title>Brief Version</title>

      <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 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). 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
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 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
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 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 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 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>

  <section>
    <title>IPv6/IPv4 Precedence</title>

    <para>With (EKU)buntu and eventually with RedHat, you will notice that your browser does not show the IPv6 version of a web
    site that is multi-homed when using ULA addresses for your IPv6 Internet connection. The reason for this is an add on to the
    RFC 3484 rules that is compiled into the (EKU)buntu libc. The pre-installed <filename>/etc/gai.conf</filename> file will
    give you a hint on this.</para>

    <para>In short: the getaddrinfo() library function rates a private IPv4 address higher than the ULA IPv6 address when
    choosing the transport protocol for a new Internet connection if this add on to the RFC 3484 rules is compiled in. For this
    reason, you may want to change the precedence rules within <filename>/etc/gai.conf</filename>.</para>

    <note>
      <para>The getaddrinfo() library function manages lists of label, precedence, and scope4 type entries. If the
      <filename>/etc/gai.conf</filename> file does not provide a single entry for a particular type, the compiled-in list is
      used. For this reason, you cannot uncomment a single entry to overwrite the default. You need to uncomment all entries of
      a particular type for this. The <quote>label</quote> lines compare source addresses, the precedence lines compare
      <quote>destination</quote> addresses.</para>
    </note>

    <procedure>
      <title>Change IPv6 Precedence</title>

      <step>
        <para>Open the <filename>/etc/gai.conf</filename> file as root user, e.g. by executing <userinput>sudo nano
        /etc/gai.conf</userinput>.</para>
      </step>

      <step>
        <para>Remove the leading hash character from the 8 lines starting with <quote>#label</quote>.</para>
      </step>

      <step>
        <para>Re-add the hash character to the line stating <quote>#label fc00::/7 6</quote>.</para>
      </step>

      <step>
        <para>Save the file.</para>
      </step>

      <step>
        <para>Restart your browser and re-try to browse to a multi-homed web site.</para>
      </step>
    </procedure>

    <para>The above procedure removes the difference between standard IPv6 source addresses and ULA type private IPv6 source
    addresses. Anything else is unchanged.</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>

    <itemizedlist>
      <listitem>
        <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>
      </listitem>

      <listitem>
        <para>ISP independence - no reverse routing, no "buy-a-number-range"</para>
      </listitem>
    </itemizedlist>

    <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>
  </section>
</article>