extern/shorewall_code
1
0
Fork 1
mirror of https://gitlab.com/shorewall/code.git synced 2025-08-18 04:35:33 +02:00
Code Issues Packages Projects Releases Wiki Activity

More documentation updates

Browse Source
This commit is contained in:
Tom Eastep
2009-06-17 11:21:58 -07:00
parent fe1978b864
commit 08cfa6d19a
3 changed files with 296 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

182
docs/Shorewall-4.xml Normal file
View File

@@ -0,0 +1,182 @@
<?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>Both compilers could be installed on your system 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</para>
<para>Shorewall 4.4 contains four 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>
</itemizedlist>
</section>
<section id="Prereqs">
<title>Prerequisites for using the Shorewall Version 4.4 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>
</itemizedlist>
</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>

113
docs/Shorewall-perl.xml
View File

@@ -108,9 +108,10 @@
</listitem>
<listitem>
<para>DYNAMIC_ZONES=Yes is not supported. <ulink
url="ipsets.html#Dynamic">Use an ipset </ulink>to define your
dytnamic zones.</para>
<para>DYNAMIC_ZONES=Yes is not supported in Shorewall-perl 4.2.
<ulink url="ipsets.html#Dynamic">Use an ipset </ulink>to define your
dytnamic zones. In Shorewall 4.4, dynamic zone support based on
ipsets was added to Shorewall.</para>
</listitem>
<listitem>
@@ -534,6 +535,20 @@ DNAT- net loc:192.168.1.3 tcp 21</programl
<para>you instead want:<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
DNAT- net 192.168.1.3 tcp 21</programlisting></para>
</listitem>
<listitem>
<para>Supplying an interface name in the SOURCE column of
/etc/shorewall/masq is deprecated as of Shorewall 4.4. Entering the
name of an interface there will result in a compile-time
warning:</para>
<para>WARNING: Using an interface as the masq SOURCE requires the
interface to be up and configured when Shorewall
starts/restarts</para>
<para>To avoid this warning, replace interface names by the
corresponding network addresses (e.g., 192.168.144.0/24).</para>
</listitem>
</orderedlist>
</section>
@@ -545,10 +560,100 @@ DNAT- net 192.168.1.3 tcp 21</programl
environment. The best way to work around this limitation is to install
Shorewall-perl on an administrative system and employ Shorewall-lite on
your embedded systems. Shorewall-perl will run on Windows under <ulink
url="http://www.cygwin.com/">Cygwin</ulink>.</para>
url="http://www.cygwin.com/">Cygwin</ulink>. Install using the
install.sh script.</para>
</section>
</section>
<section id="Install">
<title>Installing Shorewall Version 4.0 or 4.2</title>
<para>Shorewall 4.2 contains six packages, four of which are also included
in Shorewall 4.0:</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Shorewall-shell</emphasis> - the old
shell-based compiler and related components.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Shorewall-perl</emphasis> - the new
Perl-based compiler.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Shorewall-common</emphasis> - the part of
Shorewall common to both compilers.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Shorewall-lite</emphasis>- same as the 3.4
version of Shorewall Lite. Can run scripts generated by either
Shorewall-perl or Shorewall-shell.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Shorewall6</emphasis> - The utilities for
creating and operating an Ipv6 firewall. Requires Shorewall-perl and
Shorewall-common. Introduced in Shorewall 4.2.4.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Shorewall6-lite</emphasis> - Ipv6
equivalent of Shorewall Lite. Can run scripts generated by
Shoreall-perl 4.2.4 and later.</para>
</listitem>
</itemizedlist>
<para>If you upgrade to Shorewall Version 4.0 or 4.2, 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="CompilerSelection">
<title>Compiler Selection (Shorewall 4.0-4.2)</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 for
IPv4 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>If both compilers are installed, 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 shell
<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>
<section id="Modules">
<title>The Shorewall Perl Modules</title>