shorewall_code/docs/netmap.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article>
  <!--$Id$-->

  <articleinfo>
    <title>Network Mapping</title>

    <authorgroup>
      <author>
        <firstname>Tom</firstname>

        <surname>Eastep</surname>
      </author>
    </authorgroup>

    <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>

    <copyright>
      <year>2004-2005</year>

      <year>2007</year>

      <year>2011</year>

      <holder>Thomas M. Eastep</holder>
    </copyright>

    <legalnotice>
      <para>Permission is granted to copy, distribute and/or modify this
      document under the terms of the GNU Free Documentation License, Version
      1.2 or any later version published by the Free Software Foundation; with
      no Invariant Sections, with no Front-Cover, and with no Back-Cover
      Texts. A copy of the license is included in the section entitled
      <quote><ulink url="GnuCopyright.htm">GNU Free Documentation
      License</ulink></quote>.</para>
    </legalnotice>
  </articleinfo>

  <section id="Why">
    <title>Why use Network Mapping</title>

    <para>Network Mapping is most often used to resolve IP address conflicts.
    Suppose that two organizations, A and B, need to be linked and that both
    organizations have allocated the 192.168.1.0/24 subnetwork. There is a
    need to connect the two networks so that all systems in A can access the
    192.168.1.0/24 network in B and vice versa without any
    re-addressing.</para>
  </section>

  <section id="Solution">
    <title>Solution</title>

    <para>Shorewall NETMAP support is designed to supply a solution. The basic
    situation is as shown in the following diagram.<graphic
    fileref="images/netmap.png"/></para>

    <para>While the link between the two firewalls is shown here as a VPN, it
    could be any type of interconnection that allows routing of <ulink
    url="shorewall_setup_guide.htm#RFC1918">RFC 1918</ulink> traffic.</para>

    <para>The systems in the top cloud will access the 192.168.1.0/24 subnet
    in the lower cloud using addresses in another unused /24. Similarly, the
    systems in the bottom cloud will access the 192.168.1.0/24 subnet in the
    upper cloud using a second unused /24.</para>

    <para>In order to apply this solution:</para>

    <itemizedlist>
      <listitem>
        <para>You must be running Shorewall 2.0.1 Beta 2 or later.</para>
      </listitem>

      <listitem>
        <para>Your kernel must have NETMAP support. 2.6 Kernels have NETMAP
        support without patching while 2.4 kernels must be patched using
        Patch-O-Matic from <ulink
        url="http://www.netfilter.org">netfilter.org</ulink>.</para>
      </listitem>

      <listitem>
        <para>NETMAP support must be enabled in your kernel
        (CONFIG_IP_NF_TARGET_NETMAP=m or CONFIG_IP_NF_TARGET_NETMAP=y).</para>
      </listitem>

      <listitem>
        <para>Your iptables must have NETMAP support. NETMAP support is
        available in iptables 1.2.9 and later.</para>
      </listitem>
    </itemizedlist>

    <para>Network mapping is defined using the
    <filename>/etc/shorewall/netmap</filename> file. Columns in this file
    are:</para>

    <variablelist>
      <varlistentry>
        <term>TYPE</term>

        <listitem>
          <para>Must be DNAT or SNAT.</para>

          <para>If DNAT, traffic entering INTERFACE and addressed to NET1 has
          its destination address rewritten to the corresponding address in
          NET2.</para>

          <para>If SNAT, traffic leaving INTERFACE with a source address in
          NET1 has its source address rewritten to the corresponding address
          in NET2.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>NET1</term>

        <listitem>
          <para>Must be expressed in CIDR format (e.g., 192.168.1.0/24).
          Beginning with Shorewall 4.4.24, <ulink
          url="manpages/shorewall-exclusion.html">exclusion</ulink> is
          supported.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>INTERFACE</term>

        <listitem>
          <para>A firewall interface. This interface must have been defined in
          <ulink
          url="manpages/shorewall-interfaces.html"><filename>/etc/shorewall/interfaces</filename></ulink>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>NET2</term>

        <listitem>
          <para>A second network expressed in CIDR format.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><emphasis role="bold">NET3 (Optional)</emphasis> -
        <emphasis>network-address</emphasis></term>

        <listitem>
          <para>Added in Shorewall 4.4.11. If specified, qualifies INTERFACE.
          It specifies a SOURCE network for DNAT rules and a DESTINATON
          network for SNAT rules.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><emphasis role="bold">PROTO (Optional - Added in Shorewall
        4.4.23.2)</emphasis> -
        <emphasis>protocol-number-or-name</emphasis></term>

        <listitem>
          <para>Only packets specifying this protocol will have their IP
          header modified.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><emphasis role="bold">DPORT (Optional - Added in Shorewall
        4.4.23.2)</emphasis> -
        <emphasis>port-number-or-name-list</emphasis></term>

        <listitem>
          <para>Destination Ports. A comma-separated list of Port names (from
          services(5)), <emphasis>port number</emphasis>s or <emphasis>port
          range</emphasis>s; if the protocol is <emphasis
          role="bold">icmp</emphasis>, this column is interpreted as the
          destination icmp-type(s). ICMP types may be specified as a numeric
          type, a numberic type and code separated by a slash (e.g., 3/4), or
          a typename. See <ulink
          url="https://shorewall.org/configuration_file_basics.htm#ICMP">https://shorewall.org/configuration_file_basics.htm#ICMP</ulink>.</para>

          <para>If the protocol is <emphasis role="bold">ipp2p</emphasis>,
          this column is interpreted as an ipp2p option without the leading
          "--" (example <emphasis role="bold">bit</emphasis> for bit-torrent).
          If no PORT is given, <emphasis role="bold">ipp2p</emphasis> is
          assumed.</para>

          <para>An entry in this field requires that the PROTO column specify
          icmp (1), tcp (6), udp (17), sctp (132) or udplite (136). Use '-' if
          any of the following field is supplied.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><emphasis role="bold">SPORT (Optional - Added in Shorewall
        4.4.23.2)</emphasis> -
        <emphasis>port-number-or-name-list</emphasis></term>

        <listitem>
          <para>Source port(s). If omitted, any source port is acceptable.
          Specified as a comma-separated list of port names, port numbers or
          port ranges.</para>

          <para>An entry in this field requires that the PROTO column specify
          tcp (6), udp (17), sctp (132) or udplite (136). Use '-' if any of
          the following fields is supplied.</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Referring to the figure above, lets suppose that systems in the top
    cloud are going to access the 192.168.1.0/24 network in the bottom cloud
    using addresses in 10.10.10.0/24 and that systems in the bottom could will
    access 192.168.1.0/24 in the top could using addresses in
    10.10.11.0.<important>
        <para>You must arrange for routing as follows:</para>

        <itemizedlist>
          <listitem>
            <para>Traffic from the top cloud to 10.10.10.0/24 must be routed
            to eth0 on firewall 1.</para>
          </listitem>

          <listitem>
            <para>Firewall 1 must route traffic to 10.10.10.0/24 through
            firewall 2.</para>
          </listitem>

          <listitem>
            <para>Traffic from the bottom cloud to 10.10.11.0/24 must be
            routed to eth0 on firewall 2.</para>
          </listitem>

          <listitem>
            <para>Firewall 2 must route traffic to 10.10.11.0/24 through
            firewall 1.</para>
          </listitem>
        </itemizedlist>
      </important></para>

    <section>
      <title>If you are running Shorewall 4.4.22 or Earlier</title>

      <para>The entries in
      <filename><filename>/etc/shorewall/netmap</filename></filename> in
      firewall1 would be as follows:</para>

      <programlisting>#TYPE NET1           INTERFACE        NET2
SNAT  192.168.1.0/24 vpn              10.10.11.0/24        #RULE 1A
DNAT  10.10.11.0/24  vpn              192.168.1.0/24       #RULE 1B</programlisting>

      <para>The entry in <filename>/etc/shorewall/netmap</filename> in
      firewall2 would be:</para>

      <programlisting>#TYPE NET1           INTERFACE        NET2
DNAT  10.10.10.0/24  vpn              192.168.1.0/24       #RULE 2A
SNAT  192.168.1.0/24 vpn              10.10.10.0/24        #RULE 2B</programlisting>

      <example id="Example1">
        <title>192.168.1.4 in the top cloud connects to 192.168.1.27 in the
        bottom cloud</title>

        <para>In order to make this connection, the client attempts a
        connection to 10.10.10.27. The following table shows how the source
        and destination IP addresses are modified as requests are sent and
        replies are returned. The RULE column refers to the above
        <filename>/etc/shorewall/netmap</filename> entries and gives the rule
        which transforms the source and destination IP addresses to those
        shown on the next line. <informaltable>
            <tgroup cols="5">
              <thead>
                <row>
                  <entry>FROM</entry>

                  <entry>TO</entry>

                  <entry>SOURCE IP ADDRESS</entry>

                  <entry>DESTINATION IP ADDRESS</entry>

                  <entry>RULE</entry>
                </row>
              </thead>

              <tbody>
                <row>
                  <entry>192.168.1.4 in upper cloud</entry>

                  <entry>Firewall 1</entry>

                  <entry>192.168.1.4</entry>

                  <entry>10.10.10.27</entry>

                  <entry>1A</entry>
                </row>

                <row>
                  <entry>Firewall 1</entry>

                  <entry>Firewall 2</entry>

                  <entry>10.10.11.4</entry>

                  <entry>10.10.10.27</entry>

                  <entry>2A</entry>
                </row>

                <row>
                  <entry>Firewall 2</entry>

                  <entry>192.168.1.27 in lower cloud</entry>

                  <entry>10.10.11.4</entry>

                  <entry>192.168.1.27</entry>

                  <entry/>
                </row>

                <row>
                  <entry>192.168.1.27 in the lower cloud</entry>

                  <entry>Firewall 2</entry>

                  <entry>192.168.1.27</entry>

                  <entry>10.10.11.4</entry>

                  <entry>2B</entry>
                </row>

                <row>
                  <entry>Firewall 2</entry>

                  <entry>Firewall 1</entry>

                  <entry>10.10.10.27</entry>

                  <entry>10.10.11.4</entry>

                  <entry>1B</entry>
                </row>

                <row>
                  <entry>Firewall 1</entry>

                  <entry>192.168.1.4 in upper cloud</entry>

                  <entry>10.10.10.27</entry>

                  <entry>192.168.1.4</entry>

                  <entry/>
                </row>
              </tbody>
            </tgroup>
          </informaltable></para>

        <para>See the<ulink url="OPENVPN.html"> OpenVPN documentation</ulink>
        for a solution contributed by Nicola Moretti for resolving duplicate
        networks in a roadwarrior VPN environment.</para>
      </example>
    </section>

    <section>
      <title>If you are running Shorewall 4.4.23 or Later</title>

      <para>Beginning with Shorewall 4.4.23, you <emphasis>can</emphasis>
      bridge two duplicate networks with one router, provided that your kernel
      and iptables include <emphasis>Rawpost Table Support</emphasis>. That
      support is used to implement Stateless NAT which allows for performing
      DNAT in the rawpost table POSTROUTING and OUTPUT chains and for
      performing SNAT in the raw table PREROUTING chain. Using this support,
      only firewall1 requires <filename>/etc/shorewall/netmap</filename>. Two
      additional entries are added.</para>

      <programlisting>#TYPE NET1            INTERFACE        NET2
SNAT   192.168.1.0/24 vpn              10.10.11.0/24
DNAT   10.10.11.0/24  vpn              192.168.1.0/24
<emphasis role="bold">SNAT:P 192.168.1.0/24 vpn              10.10.10.0/24
DNAT:T 10.10.10.0/24  vpn              192.168.1.0/24</emphasis></programlisting>

      <para>The last two entries define <firstterm>Stateless NAT</firstterm>
      by specifying a chain designator (:P for PREROUTING and :T for
      POSTROUTING respectively). See <ulink
      url="manpages/shorewall-netmap.html">shorewall-netmap</ulink> (5) for
      details.</para>
    </section>
  </section>

  <section>
    <title>IPv6</title>

    <para>Beginning with Shorewall6 4.4.24, IPv6 support for Netmap is
    included. This provides a way to use private IPv6 addresses internally and
    still have access to the IPv6 internet.</para>

    <warning>
      <para>IPv6 netmap is <firstterm>stateless</firstterm> which means that
      there are no Netfilter helpers for applications that need them. As a
      consequence, applications that require a helper (FTP, IRC, etc.) may
      experience issues.</para>
    </warning>

    <para>For IPv6, the chain designator (:P for PREROUTING or :T for
    POSTROUTING) is required in the TYPE column. Normally SNAT rules are
    placed in the POSTROUTING chain while DNAT rules are placed in
    PREROUTING.</para>

    <para>To use IPv6 Netmap, your kernel and iptables must include
    <emphasis>Rawpost Table Support</emphasis>.</para>

    <para>IPv6 Netmap has been verified at shorewall.net using the
    configuration shown below.</para>

    <graphic align="center" fileref="images/Network2011b.png"/>

    <para>IPv6 support is supplied from Hurricane Electric; the IPv6 address
    block is 2001:470:b:227::/64.</para>

    <para>Because of the limitations of IPv6 NETMAP (no Netfilter helpers),
    the servers in the DMZ have public addresses in the block
    2001:470:b:227::/112. The local LAN uses the private network
    fd00:470:b:227::/64 with the hosts autoconfigured using radvd. This block
    is allocated from the range (fc00::/7) reserved for<firstterm> <ulink
    url="http://en.wikipedia.org/wiki/Unique_local_address">Unique Local
    Addresses</ulink></firstterm>.</para>

    <para>The /etc/shorewall6/netmap file is as follows:</para>

    <programlisting>#TYPE	NET1			INTERFACE	NET2		NET3		PROTO	DEST	SOURCE
#												PORT(S)	PORT(S)
SNAT:T	fd00:470:b:227::/64	HE_IF		2001:470:b:227::/64
DNAT:P  2001:470:b:227::/64!2001:470:b:227::/112\
				HE_IF		fd00:470:b:227::/64
</programlisting>

    <para>HE_IF is the logical name for interface sit1. On output, the private
    address block is mapped to the public block. Because autoconfiguration is
    used, none of the local addresses falls into the range
    fd00:470:b:227::/112. That range can therefore be excluded from
    DNAT.</para>

    <note>
      <para>While the site local network that was used is very similar to the
      public network (only the first word is different), that isn't a
      requirement. We could have just as well used
      fd00:bad:dead:beef::/64</para>
    </note>

    <note>
      <para>The MacBook Pro running OS X Lion refused to autoconfigure when
      radvd advertised a <ulink
      url="http://tools.ietf.org/html/rfc3513">site-local</ulink> network
      (fec0:470:b:227/64) but worked fine with the unique-local network
      (fd00:470:b:227::/64). Note that site-local addresses were deprecated in
      <ulink url="http://tools.ietf.org/html/rfc3879">RFC3879</ulink>.</para>
    </note>

    <note>
      <para>This whole scheme isn't quite as useful as it might appear. Many
      IPv6-enabled applications (web browsers, for example) are smart enough
      to recognize unique local addresses and will only use IPv6 to
      communicate with other such local addresses.</para>
    </note>
  </section>
</article>