summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--README.dbk273
-rw-r--r--README.txt2
2 files changed, 171 insertions, 104 deletions
diff --git a/README.dbk b/README.dbk
index 80887ab..153d50a 100644
--- a/README.dbk
+++ b/README.dbk
@@ -18,12 +18,15 @@
<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 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 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>
@@ -31,37 +34,47 @@
<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>
+ <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 below <filename>/usr/src</filename>, change to the new sub-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 below <filename>/usr/src</filename>,
+ change to the new 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>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>
+ <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
@@ -77,37 +90,53 @@ 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 outgoing packets and
- changes their IPv6 source address. The second rule matches incoming packets and reverts 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>
+ <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 reverts 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. If 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 requires 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>
+ <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. If 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 requires 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
+ <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
@@ -131,10 +160,13 @@ 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 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
+ <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
@@ -150,26 +182,35 @@ 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 interface addresses. 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>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 interface addresses. 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>
+ <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>
+ <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>
@@ -177,37 +218,48 @@ ip6tables -t mangle -A FORWARD -p tcp --tcp-flags SYN,RST SYN -j TCPMSS --clamp-
<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>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>
+ <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>
+ <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
+ <quote>precedence</quote> lines compare destination 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
+ <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>
+ <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>
+ <para>Re-add the hash character to the line stating <quote>#label
+ fc00::/7 6</quote>.</para>
</step>
<step>
@@ -215,53 +267,68 @@ ip6tables -t mangle -A FORWARD -p tcp --tcp-flags SYN,RST SYN -j TCPMSS --clamp-
</step>
<step>
- <para>Restart your browser and re-try to browse to a multi-homed web site.</para>
+ <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>
+ <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>
+ <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 <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 (keep it
- simple stupid).</para>
-
- <para>Using private IP addresses on the mesh nodes has a drawback: mesh node software updates e.g. a download via HTTP 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>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 (keep it simple stupid).</para>
+
+ <para>Using private IP addresses on the mesh nodes has a drawback: mesh
+ node software updates e.g. a download via HTTP 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>
diff --git a/README.txt b/README.txt
index f2af2d4..4e53698 100644
--- a/README.txt
+++ b/README.txt
@@ -206,7 +206,7 @@ scope4 type entries. If the /etc/gai.conf 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 “label” lines compare source
-addresses, the precedence lines compare “destination” addresses.
+addresses, the “precedence” lines compare destination addresses.
Procedure 1. Change IPv6 Precedence