shorewall_code/docs/Helpers.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>Netfilter Helpers</title>

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

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

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

    <copyright>
      <year>2012</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>
    <title>Helpers - Introduction</title>

    <para>There are a number of applications that create connections
    dynamically between a client and server. These connections use temporary
    TCP or UDP ports, so static configuration of firewall rules to allow those
    connections would require a very lax firewall configuration. To deal with
    these problem applications, Netfilter supports the concept of a
    <firstterm>helper</firstterm>. Each helper monitors traffic to/from the
    default primary port used by the application and opens the firewall to
    accept temporary connections created by the primary session.</para>

    <para>There are helpers for the following applications; default ports
    monitored by each helper are listed in parentheses:</para>

    <itemizedlist>
      <listitem>
        <para>Amanda (UDP 10080)</para>
      </listitem>

      <listitem>
        <para>FTP (TCP 21)</para>
      </listitem>

      <listitem>
        <para>H323 (UDP 1719, TCP 1720)</para>
      </listitem>

      <listitem>
        <para>IRC (TCP 6667)</para>
      </listitem>

      <listitem>
        <para>Netbios-NS (UDP 137)</para>
      </listitem>

      <listitem>
        <para>PPTP (TCP 1729)</para>
      </listitem>

      <listitem>
        <para>SANE (TCP 6566)</para>
      </listitem>

      <listitem>
        <para>SIP (UDP 5060)</para>
      </listitem>

      <listitem>
        <para>SNMP (UDP 161)</para>
      </listitem>

      <listitem>
        <para>TFTP (UDP 69)</para>
      </listitem>
    </itemizedlist>

    <section>
      <title>Helper Module Loading</title>

      <para>In a modular kernel, each helper is typically packaged as two
      kernel modules. One module handles connection tracking where NAT isn't
      involved and the other module handles NAT. For example, the FTP helper
      consists of these two modules (kernels 2.6.20 and later):</para>

      <itemizedlist>
        <listitem>
          <para>nf_conntrack_ftp</para>
        </listitem>

        <listitem>
          <para>nf_nat_ftp</para>
        </listitem>
      </itemizedlist>

      <para>Note that the naming convention is
      nf_conntrack_<replaceable>application</replaceable> and
      nf_nat_<replaceable>application</replaceable>; more about that
      below.</para>

      <para>Prior to Shorewall 4.5.7, helper modules were not auto-loaded and
      must be loaded explicitly using the <command>modprob</command> or
      <command>insmod</command> utilities. Beginning with Shorewall 4.5.7,
      these modules are loaded when Shorewall is determining the capabilities
      of your system.</para>

      <para>Many of the modules allow parameters to be specified when the
      module is loaded. Among the common parameters is the ports parameter
      that lists one or more ports that the module is to monitor. This allows
      running the application on a non-standard port.</para>
    </section>

    <section>
      <title>Iptables and Helpers</title>

      <para>Iptables supports two ways of interacting with modules:</para>

      <variablelist>
        <varlistentry>
          <term>Helper Match</term>

          <listitem>
            <para>This match (-m helper --helper
            <replaceable>name</replaceable>) allows selection of packets from
            connections monitored or created by the named helper.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>CT Target</term>

          <listitem>
            <para>This target (-j CT --helper <replaceable>name</replaceable>
            ...) , introduced in the 3.4 kernels, allows for explicit
            association of a helper with a connection.</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>It is important to note that the name used in iptables is not
      always the same as the name in the kernel module. Names used in iptables
      are shown in the following table:</para>

      <informaltable>
        <tgroup cols="2">
          <tbody>
            <row>
              <entry>Name of kernel module</entry>

              <entry>Name recognized by iptables</entry>
            </row>

            <row>
              <entry>nf_conntrack_amanda</entry>

              <entry>amanda</entry>
            </row>

            <row>
              <entry>nf_conntrack_ftp</entry>

              <entry>ftp</entry>
            </row>

            <row>
              <entry>nf_conntrack_h323</entry>

              <entry><emphasis role="bold">RAS (udp 1719), Q.931 (tcp
              1720)</emphasis></entry>
            </row>

            <row>
              <entry>nf_conntrack_irc</entry>

              <entry>irc</entry>
            </row>

            <row>
              <entry>nf_conntrack_netbios_ns</entry>

              <entry><emphasis role="bold">netbios-ns</emphasis></entry>
            </row>

            <row>
              <entry>nf_conntrack_pptp</entry>

              <entry>pptp</entry>
            </row>

            <row>
              <entry>nf_conntrack_sane</entry>

              <entry>sane</entry>
            </row>

            <row>
              <entry>nf_conntrack_sip</entry>

              <entry>sip</entry>
            </row>

            <row>
              <entry>nf_conntrack_snmp</entry>

              <entry>snmp</entry>
            </row>

            <row>
              <entry>nf_conntrack_tftp</entry>

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

      <para>Netfilter helpers present an opportunity for attackers to attempt
      to breach your firewall by IP address spoofing; See <ulink
      url="https://home.regit.org/netfilter-en/secure-use-of-helpers/">https://home.regit.org/netfilter-en/secure-use-of-helpers/</ulink>
      for a description of the Netfilter facilities available to meet these
      attacks.</para>
    </section>
  </section>

  <section>
    <title>Shorewall Support for Helpers</title>

    <para>Shorewall includes support for helpers is several areas. These areas
    are covered in the sections below.</para>

    <section>
      <title>Module Loading</title>

      <para>Shorewall includes support for loading the helper modules as part
      of its support for loading kernel modules in general. There are several
      options in shorewall.conf (5) that deal with kernel module
      loading:</para>

      <variablelist>
        <varlistentry>
          <term>MODULESDIR</term>

          <listitem>
            <para>This option specifies a comma-separated list of directories
            where Shorewall will look for kernel modules to load.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>MODULE_SUFFIX</term>

          <listitem>
            <para>Lists the possible suffixes for module names.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>LOAD_HELPERS_ONLY</term>

          <listitem>
            <para>Controls whether Shorewall should load only the helpers and
            leave the other modules to the auto-loader. This option
            dramatically reduces the time to process a <command>shorewall
            start</command> or <command>shorewall restart</command>
            command.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>DONT_LOAD</term>

          <listitem>
            <para>This is a comma-separated list of modules that you
            specifically don't want Shorewall to load.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>HELPERS</term>

          <listitem>
            <para>This option was added in Shorewall 4.5.7 and lists the
            modules to be enabled for association with connections
            (comma-separated). This option is fully functional only on systems
            running kernel 3.5 or later.</para>

            <para>The module names allowed in this list are <emphasis
            role="bold">amanda</emphasis>, <emphasis
            role="bold">ftp</emphasis>, <emphasis role="bold">h323</emphasis>,
            <emphasis role="bold">irc</emphasis>, <emphasis
            role="bold">netbios-ns</emphasis>, <emphasis
            role="bold">pptp</emphasis>, <emphasis
            role="bold">sane</emphasis>, <emphasis role="bold">sip</emphasis>,
            <emphasis role="bold">snmp</emphasis> and <emphasis
            role="bold">tftp</emphasis>. If you don't want a particular helper
            module loaded, then:</para>

            <itemizedlist>
              <listitem>
                <para>List it in the DONT_LOAD option; and</para>
              </listitem>

              <listitem>
                <para>Explicitly list those helpers that you do want in
                HELPERS.</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term>AUTOHELPERS</term>

          <listitem>
            <para>This option was also added in Shorewall 4.5.7. When enabled
            on systems that support the CT Target capability, it provides
            automatic association of helpers to connections in the same manner
            as in pre-3.5 kernels (and with the same vulnerabilities).</para>
          </listitem>
        </varlistentry>
      </variablelist>

      <para>The helper modules to be loaded are listed in the file
      <filename>/usr/share/shorewall/helpers</filename>. If you wish to
      customize that file to load only a subset of the helpers or to specify
      module parameters, then copy the file to <filename>/etc/shorewall/
      </filename>and modify the copy. That way, your changes won't be
      overwritten the next time that Shorewall is updated on your
      system.</para>

      <para>On systems running a a kernel earlier than 3.5, not all of the
      helpers can be totally disabled. The following modules can be disabled
      by using the parameter <emphasis role="bold">ports=0</emphasis> in
      /etc/shorewall/helpers:</para>

      <itemizedlist>
        <listitem>
          <para>ftp</para>
        </listitem>

        <listitem>
          <para>irc</para>
        </listitem>

        <listitem>
          <para>sane</para>
        </listitem>

        <listitem>
          <para>sip</para>
        </listitem>

        <listitem>
          <para>tftp</para>
        </listitem>
      </itemizedlist>

      <para>After disabling one or more helpers using this method, you
      must:</para>

      <itemizedlist>
        <listitem>
          <para>Unload the related module(s).</para>
        </listitem>

        <listitem>
          <para>Restart Shorewall (use the -c option (e.g., <command>shorewall
          restart -c</command>) if you have AUTOMAKE=Yes in <ulink
          url="manpages/shorewall.conf.html">shorewall.conf</ulink>
          (5))..</para>
        </listitem>
      </itemizedlist>

      <para>Note that if you choose to reboot your system to unload the
      modules, then if you have CT:helper entries in <ulink
      url="manpages/shorewall-conntrack.html">shorewall-conntrack</ulink> (5)
      that refer to the module(s) and you have AUTOMAKE=Yes in <ulink
      url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5), then
      Shorewall will fail to start at boot time.</para>
    </section>

    <section>
      <title>Iptables</title>

      <para>The iptables helper match is supported by Shorewall in the form of
      the HELPER column in <ulink
      url="manpages/shorewall-mangle.html">shorewall-mangle </ulink>(5) and
      <ulink url="manpages/shorewall-tcrules.html">shorewall-tcrules</ulink>
      (5).</para>

      <para>The CT target is supported directly in <ulink
      url="manpages/shorewall-conntrack.html">shorewall-conntrack</ulink>
      (5).</para>

      <para>In these files, Shorewall supports the same module names as
      iptables; see the table above.</para>

      <para>Beginning with Shorewall 4.5.7, there is a HELPER column in <ulink
      url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5). In the
      NEW section, this column allows the explicit association of a helper
      with connections allowed by a given rules. The column may contain any of
      the helper names recognized by iptables (see the table above). In the
      RELATED section, the rule will only match the packet if the related
      connection has the named helper attached.</para>

      <para>Also added in Shorewall 4.5.7 is the HELPER action in <ulink
      url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5). HELPER
      rules associate the helper listed in the HELPER column with connections
      that match the rule. A destination zone should not be specified in
      HELPER rules.</para>
    </section>

    <section>
      <title>Capabilities</title>

      <para>The output of <command>shorewall show capabilities</command> has
      two entries for each of the helpers listed above that can be disabled by
      adding<emphasis role="bold"> ports=0</emphasis> in
      /etc/shorewall/helpers.</para>

      <programlisting>shorewall show capabilities
   Amanda Helper: Available
   <emphasis role="bold">FTP Helper: Not available
   FTP-0 Helper: Available</emphasis>
<emphasis role="bold">   IRC Helper: Not available
   IRC-0 Helper: Available
</emphasis>   Netbios_ns Helper: Available
   H323 Helper: Not available
   PPTP Helper: Available
<emphasis role="bold">   SANE Helper: Not available
   SANE-0 Helper: Available
</emphasis>   SNMP Helper: Available
<emphasis role="bold">   TFTP Helper: Not available
   TFTP-0 Helper: Available
</emphasis>   iptables -S (IPTABLES_S): Available
   Basic Filter (BASIC_FILTER): Available
   CT Target (CT_TARGET): Available
   Kernel Version (KERNELVERSION): 30404
   Capabilities Version (CAPVERSION): 40507

</programlisting>

      <para>The above output is produced when this /etc/shorewall/helpers file
      is used on a system running kernel 3.4.4:</para>

      <programlisting>loadmodule nf_conntrack_ftp         ports=0
loadmodule nf_conntrack_irc         ports=0
loadmodule nf_conntrack_netbios_ns
loadmodule nf_conntrack_sip         ports=0
loadmodule nf_conntrack_tftp        ports=0
loadmodule nf_conntrack_sane        ports=0</programlisting>

      <para>The reason for the double capabilities is that when <emphasis
      role="bold">ports=0</emphasis> is specified, the iptables name of the
      helper gets '-0' added to it. So in order for the compiler to generate
      the correct iptables commands, it needs to know if <emphasis
      role="bold">ports=0</emphasis> was specified for each of the helprs that
      support it.</para>

      <para>Notice that most of the other helpers are available, even though
      their modules were not loaded. That's because auto-loading occurs during
      capability detection on those modules whose iptables name matches the
      module name.</para>
    </section>
  </section>

  <section>
    <title>Kernel &gt;= 3.5 and Shorewall &gt;= 4.5.7</title>

    <para>While the AUTOHELPER option described above provides for seamless
    migration to kernel 3.5 and beyond, we recommend setting AUTOHELPER=No at
    the first opportunity after migrating. Additionally, you should:</para>

    <itemizedlist>
      <listitem>
        <para>Use the HELPER action and the HELPER column in <ulink
        url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5) to
        attach helpers to only those connections that you need to
        support.</para>
      </listitem>

      <listitem>
        <para>If you run one or more servers (such as an FTP server) that
        interact with helpers, you should consider adding rules to the RELATED
        section of <ulink
        url="manpages/shorewall-rules.html">shorewall-rules</ulink> (5) to
        limit the scope of the helper. Suppose that your Linux FTP server is
        in zone dmz and has address 70.90.191.123.</para>

        <programlisting>#ACTION               SOURCE                         DEST                      PROTO            DEST           SOURCE
#                                                                                               PORT(S)        PORT(2)
SECTION RELATED
ACCEPT                all                            dmz:70.90.191.123                          32768:               ; helper=ftp   # passive FTP to dmz server; /proc/sys/net/ipv4/ip_local_port_range == 32760:65535
ACCEPT                dmz:70.90.191.123              all                       tcp              1024:          20    ; helper=ftp   # active  FTP to dmz server
ACCEPT                loc,dmz,$FW                    net                       tcp              -              1024: ; helper=ftp   # passive FTP to net
ACCEPT                net                            all                       tcp              1024:          20    ; helper=ftp   # active  FTP from net
DROP:info             all                            all                                                             ; helper=ftp   # 
SECTION NEW
HELPER                all                            net                       tcp              21                   ; helper=ftp
ACCEPT                all                            dmz:70.90.191.123         tcp              21                   ; helper=ftp</programlisting>
      </listitem>
    </itemizedlist>
  </section>
</article>