shorewall_code/docs/Shorewall-4.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>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>

      <year>2009</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.0 represented a substantial shift in direction
    for Shorewall. Up until then</para>

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

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

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

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

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

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

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

      <listitem>
        <para>did a much more thorough job of checking the configuration to
        avoid run-time errors.</para>
      </listitem>

      <listitem>
        <para>supported creating either Ipv4 or Ipv6 firewalls (Shorewall
        4.2.4 and later).</para>
      </listitem>
    </itemizedlist>

    <para><ulink url="Shorewall-perl.html#Install">Both compilers could be
    installed on your system</ulink> and you could <ulink
    url="Shorewall-perl.html#CompilerSelection">use whichever one suited you
    in a particular case</ulink>.</para>
  </section>

  <section id="Install">
    <title>Shorewall 4.4</title>

    <para>Shorewall 4.4 discontinues the availability of the legacy
    shell-based compiler. All users must migrate to the perl-based compiler
    before or during an upgrade to Shorewall version 4.4. We highly recommend
    that current users of the shell-based compiler migrate before upgrading to
    4.4 so that both compilers are available during the migration.</para>

    <para>Shorewall 4.4 contains five packages:</para>

    <itemizedlist>
      <listitem>
        <para><emphasis role="bold">Shorewall</emphasis> - Everything needed
        to create an IPv4 firewall.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">Shorewall-lite</emphasis>- Can run scripts
        generated by Shorewall on another system.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">Shorewall6</emphasis> - The utilities for
        creating and operating an Ipv6 firewall. Requires Shorewall.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">Shorewall6-lite</emphasis> - Ipv6
        equivalent of Shorewall Lite. Can run scripts generated by Shoreall on
        another system.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">Shorewall-init</emphasis> - An add-on
        package for any of the other packages which can:</para>

        <orderedlist>
          <listitem>
            <para>Secure the firewall(s) prior to bringing up the interfaces
            (does not work with systems running Upstart)</para>
          </listitem>

          <listitem>
            <para>React to ifup/ifdown events and restart the firewall(s) if
            needed</para>
          </listitem>
        </orderedlist>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Shorewall 4.5/4.6</title>

    <para>Shorewall 4.5 added an additional <emphasis
    role="bold">Shorewall-core</emphasis> package. This package contains the
    core Shorewall shell libraries that are required by the other
    packages.</para>
  </section>

  <section id="Prereqs">
    <title>Prerequisites for using the Shorewall Version 4.2/4.4/4.5/4.6
    Perl-based Compiler</title>

    <itemizedlist>
      <listitem>
        <para>Perl (I use Perl 5.8.10 but other 5.8 versions should work
        fine). <note>
            <para>If you want to be able to use DNS names in your Shorewall6
            configuration files, then Perl 5.10 is required together with the
            Perl <emphasis role="bold">Socket6</emphasis> module.</para>
          </note></para>
      </listitem>

      <listitem>
        <para>Perl <emphasis role="bold">Cwd</emphasis> Module</para>
      </listitem>

      <listitem>
        <para>Perl <emphasis role="bold">File::Basename</emphasis>
        Module</para>
      </listitem>

      <listitem>
        <para>Perl <emphasis role="bold">File::Temp</emphasis> Module</para>
      </listitem>

      <listitem>
        <para>Perl <emphasis role="bold">Getopt::Long</emphasis> Module</para>
      </listitem>

      <listitem>
        <para>Perl <emphasis role="bold">Carp</emphasis> Module</para>
      </listitem>

      <listitem>
        <para>Perl <emphasis role="bold">FindBin</emphasis> Module</para>
      </listitem>

      <listitem>
        <para>Perl <emphasis role="bold">Scalar::Util </emphasis>Module</para>
      </listitem>

      <listitem>
        <para>Perl <emphasis role="bold">Digest::SHA1</emphasis> Module
        (Shorewall 4.5 only)</para>
      </listitem>
    </itemizedlist>

    <para>Please note that there are <ulink url="IPv6Support.html">additional
    requirements</ulink> if you plan to install and use Shorewall6.</para>
  </section>

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

    <para>The Shorewall Perl-based compiler is not 100% compatible with the
    Shorewall shell-based version. See <ulink url="Shorewall-perl.html">this
    document</ulink> for details.</para>
  </section>
</article>