summaryrefslogtreecommitdiffstats
path: root/README.dbk
blob: 37cd8d4312f012dbf3a23193071d835236cd0528 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
<?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" [
<!ENTITY VERSION "0.6">
]>
<article>
  <articleinfo>
    <title>NPTv6 (IPv6-to-IPv6 Network Prefix Translation) for Linux</title>

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

      <surname>Tuecke</surname>

      <affiliation>
        <orgname>Freifunk</orgname>
      </affiliation>
    </author>
    <author>
      <firstname>Matthias</firstname>

      <surname>Schiffer</surname>

      <affiliation>
        <orgname>Freifunk L├╝beck</orgname>
      </affiliation>
    </author>

    <pubdate>10-NOV-2011</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 RFC 6296 published
  here:</para>

  <para><ulink
  url="https://tools.ietf.org/html/rfc6296">https://tools.ietf.org/html/rfc6296</ulink></para>

  <warning>
    <para>Using NPTv6 rules together with connection tracking rules such as
    <userinput>--ctstate</userinput> is currently untested and may not work or
    may cause dysfunctions.</para>
  </warning>

  <section id="install">
    <title id="install-title">Installation</title>

    <para>NPTv6 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 SNPTV6' target (for source address translation)
    and the '-j DNPTV6' target (for destination address translation) 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 ip6tabless extension by copying
    libip6t_SNPTV6.so and libip6t_DNPTV6.so to the iptables module directory,
    which is probably located under <filename>/lib/xtables</filename> or
    <filename>/usr/lib/iptables</filename>.</para>

    <note>
      <para>The kernel modules (<filename>ip6t_SNPTV6.ko</filename> and
      <filename>ip6t_DNPTV6.ko</filename>) is not automatically installed nor loaded
      into the kernel. You can copy the kernel module file manually, e.g. with
      <userinput>sudo cp ip6t_SNPTV6.ko ip6t_DNPTV6.ko /lib/modules/$(uname -r)/</userinput>.</para>
    </note>
  </section>

  <section id="dkms">
    <title id="dkms-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 NPTv6 kernel modules. 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 NPTv6 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 NPTv6 source file archive
    below <filename>/usr/src/</filename>. To register the NPTv6 source to DKMS
    and compile/install, issue these commands:</para>

    <programlisting>sudo dkms add -m ip6t_NPTV6 -v &VERSION;
sudo dkms build -m ip6t_NPTV6 -v &VERSION;
sudo dkms install -m ip6t_NPTV6 -v &VERSION;</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 id="config">
    <title id="config-title">Configuration</title>

    <section id="config-brief">
      <title id="config-brief-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>/48 Prefix Mapping Example</quote> given
      in RFC6296:</para>

      <programlisting>ip6tables -t mangle -A PREROUTING  -i eth0 -d 2001:0DB8:0001::/48 -j DNPTV6 --to-destination FD01:0203:0405::/48
ip6tables -t mangle -A POSTROUTING -o eth0 -s FD01:0203:0405::/48 -j SNPTV6 --to-source 2001:0DB8:0001::/48</programlisting>

      <para>This example is also printed to the screen if you issue
      <userinput>ip6tables -j SNPTV6 --help</userinput>. By design, you cannot
      use prefix lengths longer than 64.</para>
    </section>

    <section id="config-nat-behaviour">
      <title id="config-nat-behaviour-title">NAT Behavioral Requirements</title>

      <para>RFC 6296 states that NPTv6 translators must support hairpinning behaviour.
      This means that when an NPTv6 Translator receives a datagram on the
      internal interface that has a destination address that matches the
      site's external prefix, it will translate the datagram and forward it
      internally. While it is possible that the network works correctly
      without this depending on the configuration of the external router, it
      is desirable to have hairpinning behaviour. The following iptables rules
      will enable this:</para>

      <programlisting>ip6tables -t mangle -A PREROUTING -d 2001:0DB8:0001::/48 -j MARK --set-mark 42
ip6tables -t mangle -A PREROUTING -d 2001:0DB8:0001::/48 -j DNPTV6 --to-destination FD01:0203:0405::/48
ip6tables -t mangle -A POSTROUTING -m mark --mark 42 -s FD01:0203:0405::/48 -j SNPTV6 --to-source 2001:0DB8:0001::/48
ip6tables -t mangle -A POSTROUTING -o eth0 -s FD01:0203:0405::/48 -j SNPTV6 --to-source 2001:0DB8:0001::/48</programlisting>
    </section>
  </section>

  <section id="precedence">
    <title id="precedence-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> (see <xref
    endterm="precedence-gai-title" linkend="precedence-gai" />).</para>

    <section id="precedence-gai">
      <title id="precedence-gai-title">Change gai.conf</title>

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

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