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 id="Intro">
    <title>Introduction</title>

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

      <listitem>
        <para>generates better and more consistent error messages.</para>
      </listitem>

      <listitem>
        <para>does a much more thorough job of checking the configuration to
        avoid run-time errors.</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 id="Install">
    <title>Installing Shorewall Version 4</title>

    <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.</para>
      </listitem>

      <listitem>
        <para>Shorewall-common - 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. See the <ulink url="upgrade_issues.htm">upgrade issues</ulink>
    for details.</para>
  </section>

  <section id="Prereqs">
    <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>

      <listitem>
        <para>Perl Getopt::Long Module</para>
      </listitem>

      <listitem>
        <para>Perl Carp Module</para>
      </listitem>

      <listitem>
        <para>Perl BinFind Module (Shorewall 4.0.3 and later)</para>
      </listitem>
    </itemizedlist>
  </section>

  <section id="Incompatibilities">
    <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. See <ulink url="Shorewall-perl.html">this
    document</ulink> for details.</para>
  </section>

  <section id="Compatibility">
    <title>Package Compatibility Matrix</title>

    <para>The following table indicates which versions of the compilers are
    supported by each version of Shorewall-common.</para>

    <informaltable>
      <tgroup cols="3">
        <colspec colname="_2" colnum="2" />

        <colspec colname="_3" />

        <tbody>
          <row>
            <entry align="center"><emphasis
            role="bold">Package</emphasis></entry>

            <entry align="center" nameend="_3" namest="_2"
            valign="middle"><emphasis role="bold">Compatible
            With</emphasis></entry>
          </row>

          <row>
            <entry>Shorewall-common 4.0.0-RC1</entry>

            <entry>Shorewall-shell 4.0.0-RC1</entry>

            <entry>Shorewall-perl 4.0.0-RC1</entry>
          </row>

          <row>
            <entry morerows="1" valign="middle">Shorewall-common
            4.0.0-RC2</entry>

            <entry>Shorewall-shell 4.0.0-RC1</entry>

            <entry>Shorewall-perl 4.0.0-RC1</entry>
          </row>

          <row>
            <entry>Shorewall-shell 4.0.0-RC2</entry>

            <entry>Shorewall-perl 4.0.0-RC2</entry>
          </row>

          <row>
            <entry valign="middle">Shorewall-common 4.0.0</entry>

            <entry>Shorewall-shell 4.0.0 - 4.0.2</entry>

            <entry>Shorewall-perl 4.0.0 - 4.0.2</entry>
          </row>

          <row>
            <entry valign="middle">Shorewall-common 4.0.1</entry>

            <entry>Shorewall-shell 4.0.0 - 4.0.2</entry>

            <entry>Shorewall-perl 4.0.0 - 4.0.2</entry>
          </row>

          <row>
            <entry valign="middle">Shorewall-common 4.0.2</entry>

            <entry>Shorewall-shell 4.0.0 - 4.0.2</entry>

            <entry>Shorewall-perl 4.0.0 - 4.0.2</entry>
          </row>
        </tbody>
      </tgroup>
    </informaltable>
  </section>

  <section id="CompilerSelection">
    <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>.</para>

    <para>The value of this new option can be either 'perl' or 'shell'.</para>

    <para>If you add 'SHOREWALL_COMPILER=perl' 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.</para>

    <para>If you only install one compiler, it is suggested that you do not
    set SHOREWALL_COMPILER.</para>

    <para>You can select the compiler to use on the command line using the 'C
    option:<simplelist>
        <member>'-C shell' means use the shell compiler</member>

        <member>'-C perl' means use the perl compiler</member>
      </simplelist>The -C option overrides the setting in
    shorewall.conf.</para>

    <para>Example:<programlisting><command>shorewall restart -C perl</command></programlisting></para>

    <para>When the Shorewall-perl compiler has been selected, the
    <filename>params</filename> file is processed using the
    <option>-a</option> option which causes all variables set within the file
    to be exported automatically by the shell. The Shorewall-perl compiler
    uses the current environmental variables to perform variable expansion
    within the other Shorewall configuration files.</para>
  </section>
</article>