shorewall_code/docs/Shorewall-4.xml
2008-10-05 21:45:05 +00:00

371 lines
11 KiB
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>
<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 5.8 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 FindBin 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.3</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.3</entry>
<entry>Shorewall-perl 4.0.0 - 4.0.1</entry>
</row>
<row>
<entry valign="middle">Shorewall-common 4.0.2<footnote>
<para>Shorewall-common/lib.base should have
patch-common-4.0.2-1.diff applied.</para>
</footnote></entry>
<entry>Shorewall-shell 4.0.0 - 4.0.3</entry>
<entry>Shorewall-perl 4.0.0 - 4.0.2</entry>
</row>
<row>
<entry valign="middle">Shorewall-common 4.0.3</entry>
<entry>Shorewall-shell 4.0.0 - 4.0.3</entry>
<entry>Shorewall-perl 4.0.0 - 4.0.3<footnote>
<para>Shorewall-perl 4.0.3 requires Shorewall-common 4.0.3 if
capabilities files are to be used. Shorewall-perl 4.0.3 also
requires Shorewall-lite 4.0.3.</para>
</footnote></entry>
</row>
<row>
<entry valign="middle">Shorewall-common 4.0.4</entry>
<entry>Shorewall-shell 4.0.0 - 4.0.4</entry>
<entry>Shorewall-perl 4.0.0 - 4.0.4<footnote>
<para>Shorewall-perl 4.0.4 requires Shorewall-common 4.0.3 or
later if capabilities files are to be used. Shorewall-perl
4.0.4 also requires Shorewall-lite 4.0.3 or later.</para>
</footnote></entry>
</row>
<row>
<entry valign="middle">Shorewall-common 4.0.5</entry>
<entry>Shorewall-shell 4.0.5</entry>
<entry>Shorewall-perl 4.0.5<footnote>
<para>Shorewall-perl 4.0.5 also requires Shorewall-lite
4.0.5.</para>
</footnote></entry>
</row>
<row>
<entry valign="middle">Shorewall-common 4.0.6</entry>
<entry>Shorewall-shell 4.0.5 - 4.0.6</entry>
<entry>Shorewall-perl 4.0.5 - 4.0.6<footnote>
<para>Shorewall-perl 4.0.6 also requires Shorewall-lite
4.0.6.</para>
</footnote></entry>
</row>
<row>
<entry valign="middle">Shorewall-common 4.0.7</entry>
<entry>Shorewall-shell 4.0.5 - 4.0.9</entry>
<entry>Shorewall-perl 4.0.5 - 4.0.9<footnote>
<para>Shorewall-perl 4.0.6 and later require Shorewall-lite
4.0.6 or later</para>
</footnote></entry>
</row>
<row>
<entry valign="middle">Shorewall-common 4.0.8</entry>
<entry>Shorewall-shell 4.0.5 - 4.0.9</entry>
<entry>Shorewall-perl 4.0.5 - 4.0.9<footnote>
<para>Shorewall-perl 4.0.6 and later require Shorewall-lite
4.0.6 or later</para>
</footnote></entry>
</row>
<row>
<entry valign="middle">Shorewall-common 4.0.9-4.0.14</entry>
<entry>Shorewall-shell 4.0.5 - 4.0.14</entry>
<entry>Shorewall-perl 4.0.5 - 4.0.14<footnote>
<para>Shorewall-perl 4.0.6 and later require Shorewall-lite
4.0.6 or later</para>
</footnote></entry>
</row>
<row>
<entry valign="middle">Shorewall-common 4.2.0</entry>
<entry>Shorewall-shell 4.2.0</entry>
<entry>Shorewall-perl 4.2.0</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>