shorewall_code/docs/Shorewall-4.xml

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

  <articleinfo>
    <title>Shorewall Version 4</title>

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

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

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

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

    <para>Shorewall version 4 is currently in development and is available for
    testing as the 3.9.x series.</para>

    <para>Shorewall version 4 represents a substantial shift in direction for
    Shorewall. Up to now</para>

    <itemizedlist>
      <listitem>
        <para>Shorewall has been written entirely in Bourne Shell.</para>
      </listitem>

      <listitem>
        <para>Shorewall ran the <command>iptables</command> utility to add
        each Netfilter rule.</para>
      </listitem>
    </itemizedlist>

    <para> Shorewall version 4 offers you a choice. You can continue to use
    the existing shell-based implementation or you can use a new
    implementation of the Shorewall compiler written in the Perl programming
    language. The new compiler:</para>

    <itemizedlist>
      <listitem>
        <para>has a small disk footprint</para>
      </listitem>

      <listitem>
        <para>is very fast.</para>
      </listitem>

      <listitem>
        <para>generates a firewall script that uses
        <command>iptables-restore</command>; so the script is very
        fast.</para>
      </listitem>
    </itemizedlist>

    <para>Both compilers may be installed on your system and you can use
    whichever one suits you in a particular case.</para>
  </section>

  <section>
    <title>Installing Shorewall Version 4</title>

    <para>You can download the development version of Shorewall Version 4 from
    any of the download sites with the exception of SourceForge. It is
    contained in the <filename
    class="directory">/pub/shorewall/development/3.9/</filename>
    directory.</para>

    <para>Shorewall 4 contains four packages:</para>

    <itemizedlist>
      <listitem>
        <para>Shorewall-shell - the old shell-based compiler and related
        components.</para>
      </listitem>

      <listitem>
        <para>Shorewall-perl - the new Perl-based compiler. May be installed
        under Shorewall 3.4.2 or 3.9.x.</para>
      </listitem>

      <listitem>
        <para>Shorewall - the part of Shorewall common to both
        compilers.</para>
      </listitem>

      <listitem>
        <para>Shorewall-lite- same as the 3.4 version of Shorewall Lite. Can
        run scripts generated by either Shorewall-perl or
        Shorewall-shell.</para>
      </listitem>
    </itemizedlist>

    <para>If you upgrade to Shorewall Version 4, you must install
    Shorewall-shell and/or Shorewall-perl; in fact, if you are using the
    tarball for your installation, you must install Shorewall-shell and/or
    Shorewall-perl <emphasis role="bold">before</emphasis> you upgrade
    Shorewall.</para>
  </section>

  <section>
    <title>Prerequisites for using the Shorewall Version 4 Perl-based
    Compiler</title>

    <itemizedlist>
      <listitem>
        <para>Perl (I use Perl 5.8.8 but other versions should work
        fine)</para>
      </listitem>

      <listitem>
        <para>Perl Cwd Module</para>
      </listitem>

      <listitem>
        <para>Perl File::Basename Module</para>
      </listitem>

      <listitem>
        <para>Perl File::Temp Module</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Incompatibilities Introduced in the Shorewall Version 4 Perl-based
    Compiler</title>

    <para>The Shorewall-perl compiler is not 100% compatible with the
    Shorewall-shell version.</para>

    <orderedlist>
      <listitem>
        <para>The Perl-based compiler requires the following capabilities in
        your kernel and iptables.</para>

        <itemizedlist>
          <listitem>
            <para>addrtype match (may be relaxed later)</para>
          </listitem>

          <listitem>
            <para>multiport match (will not be relaxed)</para>
          </listitem>
        </itemizedlist>

        <para>These capabilities are in current distributions.</para>
      </listitem>

      <listitem>
        <para>Now that Netfilter has features to deal reasonably with port
        lists, I see no reason to duplicate those features in Shorewall. The
        Shorewall-shell compiler goes to great pain (in some cases) to break
        very long port lists ( &gt; 15 where port ranges in lists count as two
        ports) into individual rules. In the new compiler, I'm avoiding the
        ugliness required to do that. The new compiler just generates an error
        if your list is too long. It will also produce an error if you insert
        a port range into a port list and you don't have extended multiport
        support.</para>
      </listitem>

      <listitem>
        <para>BRIDGING=Yes is not supported. The kernel code necessary to
        support this option was removed in Linux kernel 2.6.20.</para>
      </listitem>

      <listitem>
        <para>The BROADCAST column in the interfaces file is essentially
        unused; if you enter anything in this column but '-' or 'detect', you
        will receive a warning. This will be relaxed if and when the addrtype
        match requirement is relaxed.</para>
      </listitem>

      <listitem>
        <para>Because the compiler is now written in Perl, your compile-time
        extension scripts from earlier versions will no longer work. For now,
        if you want to use extension scripts, you will need to read the Perl
        code to see how the compiler operates internally. I will produce
        documentation before the first official release. Compile-time
        extension scripts are executed using the Perl 'do FILE'
        mechanism.</para>
      </listitem>

      <listitem>
        <para>The 'refresh' command is now synonymous with 'restart'.</para>
      </listitem>

      <listitem>
        <para> Because the compiler is now written in Perl, your compile-time
        extension scripts from earlier versions will no longer work.
        Compile-time extension scripts are executed using the Perl 'eval `cat
        &lt;file&gt;`' mechanism. Be sure that each script returns a 'true'
        value; otherwise, the compiler will assume that the script failed and
        will abort the compilation.</para>

        <para>When a script is invoked, the $chainref scalar variable will
        hold a reference to a chain table entry.</para>

        <simplelist>
          <member>$chainref-&gt;{name} contains the name of the chain</member>

          <member>$chainref-&gt;{table} holds the table name</member>
        </simplelist>

        <para>To add a rule to the chain:</para>

        <simplelist>
          <member>add_rule $chainref, &lt;<replaceable>the
          rule</replaceable>&gt;</member>
        </simplelist>

        <para>Where</para>

        <simplelist>
          <member>&lt;<replaceable>the rule</replaceable>&gt; is a scalar
          argument holding the rule text. Do not include "-A
          &lt;<replaceable>chain name</replaceable>&gt;"</member>
        </simplelist>

        <para>Example:</para>

        <simplelist>
          <member>add_rule $chainref, '-j ACCEPT';</member>
        </simplelist>

        <para>To insert a rule into the chain:</para>

        <simplelist>
          <member>insert_rule $chainref,
          &lt;<replaceable>rulenum</replaceable>&gt;, &lt;<replaceable>the
          rule</replaceable>&gt;</member>
        </simplelist>

        <para>The log_rule_limit function works like it does in the shell
        compiler with two exceptions:</para>

        <itemizedlist>
          <listitem>
            <para>You pass the chain reference rather than the name of the
            chain.</para>
          </listitem>

          <listitem>
            <para>The commands are 'add' and 'insert' rather than '-A' and
            '-I'.</para>
          </listitem>

          <listitem>
            <para>There is only a single "pass as-is to iptables" argument (so
            you must quote that par</para>
          </listitem>
        </itemizedlist>

        <para>Example:</para>

        <programlisting>    log_rule_limit
              'info' , 
              $chainref , 
              $chainref-&gt;{name},
              'DROP' , 
              '',    #Limit
              '' ,   #Log tag
              'add';         </programlisting>
      </listitem>

      <listitem>
        <para>The <filename>/etc/shorewall/tos</filename> file now has
        zone-independent SOURCE and DEST columns as do all other files except
        the rules and policy files.</para>

        <para>The SOURCE column may be one of the following:</para>

        <simplelist>
          <member>[<command>all</command>:]&lt;<replaceable>address</replaceable>&gt;[,...]</member>

          <member>[<command>all</command>:]&lt;<replaceable>interface</replaceable>&gt;[:&lt;<replaceable>address</replaceable>&gt;[,...]]</member>

          <member><command>$FW</command>[:&lt;<replaceable>address</replaceable>&gt;[,...]]</member>
        </simplelist>

        <para>The DEST column may be one of the following:</para>

        <simplelist>
          <member>[<command>all</command>:]&lt;<replaceable>address</replaceable>&gt;[,...]</member>

          <member>[<command>all</command>:]&lt;<replaceable>interface</replaceable>&gt;[:&lt;<replaceable>address</replaceable>&gt;[,...]]</member>
        </simplelist>

        <para>This is a permanent change. The old zone-based rules have never
        worked right and this is a good time to replace them. I've tried to
        make the new syntax cover the most common cases without requiring
        change to existing files. In particular, it will handle the tos file
        released with Shorewall 1.4 and earlier.</para>
      </listitem>

      <listitem>
        <para>Currently, support for ipsets is untested. That will change with
        future pre-releases but one thing is certain -- Shorewall is now out
        of the ipset load/reload business. With scripts generated by the
        Perl-based Compiler, the Netfilter ruleset is never cleared. That
        means that there is no opportunity for Shorewall to load/reload your
        ipsets since that cannot be done while there are any current rules
        using ipsets.</para>

        <para>So:</para>

        <orderedlist numeration="upperroman">
          <listitem>
            <para>Your ipsets must be loaded before Shorewall starts. You are
            free to try to do that with the following code in
            <filename>/etc/shorewall/start</filename>:</para>

            <programlisting>if [ "$COMMAND" = start ]; then
    ipset -U :all: :all:
    ipset -F
    ipset -X
    ipset -R &lt; /etc/shorewall/ipsets
fi</programlisting>

            <para>The file <filename>/etc/shorewall/ipsets</filename> will
            normally be produced using the <command>ipset -S</command>
            command.</para>

            <para>The above will work most of the time but will fail in a
            <command>shorewall stop</command> - <command>shorewall
            start</command> sequence if you use ipsets in your routestopped
            file (see below).</para>
          </listitem>

          <listitem>
            <para>Your ipsets may not be reloaded until Shorewall is stopped
            or cleared.</para>
          </listitem>

          <listitem>
            <para>If you specify ipsets in your routestopped file then
            Shorewall must be cleared in order to reload your ipsets.</para>
          </listitem>
        </orderedlist>

        <para>As a consequence, scripts generated by the Perl-based compiler
        will ignore <filename>/etc/shorewall/ipsets</filename> and will issue
        a warning if you set SAVE_IPSETS=Yes in
        <filename>shorewall.conf</filename>.</para>
      </listitem>

      <listitem>
        <para>Because the configuration files (with the exception of
        <filename>/etc/shorewall/params</filename>) are now processed by the
        Shorewall-perl compiler rather than by the shell, only the basic forms
        of Shell expansion ($variable and ${variable}) are supported. The more
        exotic forms such as ${variable:=default} are not supported. Both
        variables defined in /etc/shorewall/params and environmental variables
        (exported by the shell) can be used in configuration files.</para>
      </listitem>

      <listitem>
        <para>USE_ACTIONS=No is not supported. That option is intended to
        minimize Shorewall's footprint in embedded applications. As a
        consequence, Default Macros are not supported.</para>
      </listitem>

      <listitem>
        <para>DELAYBLACKLISTLOAD=Yes is not supported. The entire ruleset is
        atomically loaded with one execution of
        <command>iptables-restore</command>.</para>
      </listitem>

      <listitem>
        <para>MAPOLDACTIONS=Yes is not supported. People should have converted
        to using macros by now.</para>
      </listitem>

      <listitem>
        <para>The pre Shorewall-3.0 format of the zones file is not supported;
        neither is the <filename>/etc/shorewall/ipsec</filename> file.</para>
      </listitem>
    </orderedlist>
  </section>

  <section>
    <title>Compiler Selection</title>

    <para>If you only install one compiler, then that compiler will be
    used.</para>

    <para>If you install both compilers, then the compiler actually used
    depends on the SHOREWALL_COMPILER setting in
    <filename>shorewall.conf</filename>. The value of this new option can be
    either 'perl' or 'shell'.</para>

    <para>If you add 'SHOREWALL_COMPILER=shell' to
    <filename>/etc/shorewall/shorewall.conf</filename> then by default, the
    new compiler will be used on the system. If you add it to
    <filename>shorewall.conf</filename> in a separate directory (such as a
    Shorewall-lite export directory) then the new compiler will only be used
    when you compile from that directory. If you only install one compiler, it
    is suggested that you do not set SHOREWALL_COMPILER. Regardless of the
    setting of SHOREWALL_COMPILER, there is one change in Shorewall operation
    that is triggered simply by installing shorewall-perl. Your
    <filename>params</filename> file will be processed during compilation with
    the shell's '-a' option which causes any variables that you set or create
    in that file to be automatically exported. Since the params file is
    processed before <filename>shorewall.conf</filename>, using -a insures
    that the settings of your params variables are available to the new
    compiler should it's use be specified in
    <filename>shorewall.conf</filename>.</para>
  </section>
</article>