holm/shorewall_code
1
0
Fork 0
forked from extern/shorewall_code
Code Pull Requests 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
Show Stats 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>

9
manpages/shorewall-masq.xml
View File

@ -119,10 +119,11 @@
<listitem>
<para>Set of hosts that you wish to masquerade. You can specify this
as an <emphasis>address</emphasis> (net or host) or as an
<emphasis>interface</emphasis>. If you give the name of an
interface, the interface must be up before you start the firewall
(Shorewall will use your main routing table to determine the
appropriate addresses to masquerade).</para>
<emphasis>interface</emphasis> (use of an interface is deprecated).
If you give the name of an interface, the interface must be up
before you start the firewall and the Shorewall rules compiler will
warn you of that fact. (Shorewall will use your main routing table
to determine the appropriate addresses to masquerade).</para>
<para>In order to exclude a address of the specified SOURCE, you may
append an <emphasis>exclusion</emphasis> ("!" and a comma-separated