extern/shorewall_code
1
0
Fork 1
mirror of https://gitlab.com/shorewall/code.git synced 2024-11-21 23:23:13 +01:00
Code Issues Packages Projects Releases Wiki Activity

Documentation update for Shorewall 4.3

Browse Source 
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@9561 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
This commit is contained in:
teastep 2009-02-28 03:45:43 +00:00
parent 5b5f7dc10e
commit c31f899749
35 changed files with 1051 additions and 2503 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
docs/Actions.xml
View File

@ -41,9 +41,10 @@
</articleinfo>
<caution>
<para>This article applies to Shorewall 4.0 and later. If you are running
a version of Shorewall earlier than Shorewall 4.0.0 then please see the
documentation for that release.</para>
<para><emphasis role="bold">This article applies to Shorewall 4.3 and
later. If you are running a version of Shorewall earlier than Shorewall
4.3.5 then please see the documentation for that
release.</emphasis></para>
</caution>
<section id="Intro">
@ -104,9 +105,8 @@ ACCEPT - - tcp 135,139,445
file to <filename class="directory">/etc/shorewall</filename> (or
somewhere else on your CONFIG_PATH) and modify the copy.</para>
<para>Standard Actions were largely replaced by <ulink
url="Macros.html">macros</ulink> in Shorewall 3.0 and later major
versions.</para>
<para>Standard Actions have been largely replaced by <ulink
url="Macros.html">macros</ulink> .</para>
</listitem>
<listitem>
@ -121,19 +121,6 @@ ACCEPT - - tcp 135,139,445
</orderedlist>
</section>
<section id="Enabling">
<title>Enabling the Use of Actions</title>
<para>In Shorewall version 3.4 and later, to make use of any of the three
types of actions you must set the USE_ACTIONS option to Yes in
<filename>/etc/shorewall/shorewall.conf</filename>.</para>
<note>
<para>Shorewall-perl will complain if USE_ACTIONS=No since that compiler
always includes the capability to use actions.</para>
</note>
</section>
<section id="Default">
<title>Default Actions (Formerly Common Actions)</title>
@ -185,10 +172,9 @@ ACCEPT - - tcp 135,139,445
<section id="Limit">
<title>Limiting Per-IP Connection Rate</title>
<para>Beginning with Shorewall 3.0.4, Shorewall has a <quote>Limit</quote>
<ulink url="Actions.html">action</ulink>. Limit is invoked with a
comma-separated list in place of a logging tag. The list has three
elements:</para>
<para>Shorewall supports a <quote>Limit</quote> <ulink
url="Actions.html">action</ulink>. Limit is invoked with a comma-separated
list in place of a logging tag. The list has three elements:</para>
<orderedlist>
<listitem>
@ -251,45 +237,8 @@ Limit:info:SSHA,3,60 net $FW tcp 22</programl
<section id="LimitImp">
<title>How Limit is Implemented</title>
<para>For those who are curious, the Limit action is implemented in
Shorewall 3.0 and Shorewall 3.2 as follows:</para>
<itemizedlist>
<listitem>
<para>The file <filename>/usr/share/shorewall/action</filename>.
Limit is empty.</para>
</listitem>
<listitem>
<para>The file <filename>/usr/share/shorewall/Limit</filename> is as
follows:</para>
<programlisting>set -- $(separate_list $TAG)
[ $# -eq 3 ] || fatal_error "Rule must include &lt;set name&gt;,&lt;max connections&gt;,&lt;interval&gt; as the log tag"
run_iptables -A $CHAIN -m recent --name $1 --set
if [ -n "$LEVEL" ]; then
run_iptables -N $CHAIN%
log_rule_limit $LEVEL $CHAIN% $1 DROP "" "" -A
run_iptables -A $CHAIN% -j DROP
run_iptables -A $CHAIN -m recent --name $1 --update --seconds $3 --hitcount $(( $2 + 1 )) -j $CHAIN%
else
run_iptables -A $CHAIN -m recent --update --name $1 --seconds $3 --hitcount $(( $2 + 1 )) -j DROP
fi
run_iptables -A $CHAIN -j ACCEPT</programlisting>
</listitem>
</itemizedlist>
<para>In Shorewall 3.3, Limit is made into a built-in action; basically
that means that the above code now lives inside of Shorewall rather than
in a separate file.</para>
<para>For completeness, here's the above
<filename>/usr/share/shorewall/Limit</filename> for use with
Shorewall-perl:</para>
<para>For those who are curious, the Limit action is implemented as
follows:</para>
<programlisting>my @tag = split /,/, $tag;
@ -537,7 +486,7 @@ add_rule $chainref, '-j ACCEPT';
</listitem>
<listitem>
<para>MARK (Added in Shorewall 3.4.4)</para>
<para>MARK</para>
<para><simplelist>
<member>[!]&lt;<emphasis>value</emphasis>&gt;[/&lt;<emphasis>mask</emphasis>&gt;][:C]</member>
@ -743,20 +692,12 @@ acton:info:test $FW net</programlisting>
<para>/etc/shorewall/actions<programlisting>DropBcasts</programlisting></para>
<para>/etc/shorewall/action.DropBcasts<programlisting># This file is empty</programlisting>When
using Shorewall-shell:</para>
<para><blockquote>
<para>/etc/shorewall/DropBcasts<programlisting>[ -n "$LEVEL" ] &amp;&amp; log_rule_limit $LEVEL $CHAIN DropBcasts DROP "" "$TAG" -A
run_iptables -A DropBcasts -m pkttype --pkttype broadcast -j DROP</programlisting></para>
</blockquote>When using Shorewall-Perl:<blockquote>
<para>/etc/shorewall/DropBcasts<programlisting>use Shorewall::Chains;
<para>/etc/shorewall/action.DropBcasts<programlisting># This file is empty</programlisting>/etc/shorewall/DropBcasts<programlisting>use Shorewall::Chains;
log_rule_limit( $level, $chainref, 'DropBcasts', 'DROP', '', $tag, 'add', '' ) if $level ne '';
add_rule( $chainref, '-m pkttype --pkttype broadcast -j DROP' );
1;</programlisting></para>
</blockquote></para>
</example>
<para>For a richer example, see <ulink url="PortKnocking.html">this

477
docs/Anatomy.xml
View File

@ -5,7 +5,7 @@
<!--$Id$-->
<articleinfo>
<title>Anatomy of Shorewall 4.0</title>
<title>Anatomy of Shorewall 4.3</title>
<authorgroup>
<author>
@ -20,6 +20,8 @@
<copyright>
<year>2007</year>
<year>2009</year>
<holder>Thomas M. Eastep</holder>
</copyright>
@ -37,47 +39,46 @@
<section id="Products">
<title>Products</title>
<para>Shorewall 4.0 consists of four packages.</para>
<para>Shorewall 4.3 consists of four packages.</para>
<orderedlist>
<listitem>
<para><emphasis role="bold">Shorewall-common</emphasis>. This package
must be installed on at least one system in your network. That system
must also have Shorewall-shell and/or Shorewall-perl installed.</para>
<para><emphasis role="bold">Shorewall</emphasis>. This package must be
installed on at least one system in your network. It contains
everything needed to create an IPv4 firewall.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Shorewall-shell</emphasis>. This package
includes the legacy Shorewall configuration compiler written in Bourne
Shell. This compiler is very portable but suffers from performance
problems and has become hard to maintain.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Shorewall-perl</emphasis>. An alternative
to Shorewall-shell written in the Perl language. This compiler is
highly portable to those Unix-like platforms that support Perl
(including Cygwin) and is the compiler of choice for new Shorewall
installations.</para>
<para><emphasis role="bold">Shorewall6</emphasis>. This package
requires the Shorewall package and adds those components needed to
create an IPv6 fireawall. </para>
</listitem>
<listitem>
<para><emphasis role="bold">Shorewall-lite</emphasis>. Shorewall
allows for central administration of multiple firewalls through use of
Shorewall lite. The full Shorewall product (including Shorewall-common
with Shorewall-shell and/or Shorewall-perl) is installed on a central
administrative system where compiled Shorewall scripts are generated.
These scripts are copied to the firewall systems where they run under
the control of Shorewall-lite.</para>
allows for central administration of multiple IPv4 firewalls through
use of Shorewall lite. The full Shorewall product is installed on a
central administrative system where compiled Shorewall scripts are
generated. These scripts are copied to the firewall systems where they
run under the control of Shorewall-lite.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Shorewall6-lite</emphasis>. Shorewall
allows for central administration of multiple IPv4 firewalls through
use of Shorewall lite. The full Shorewall product is installed on a
central administrative system where compiled Shorewall scripts are
generated. These scripts are copied to the firewall systems where they
run under the control of Shorewall-lite.</para>
</listitem>
</orderedlist>
</section>
<section id="Shorewall">
<title>Shorewall-common</title>
<title>Shorewall</title>
<para>The Shorewall-common package includes a large number of files which
are installed in <filename class="directory">/sbin</filename>, <filename
<para>The Shorewall package includes a large number of files which are
installed in <filename class="directory">/sbin</filename>, <filename
class="directory">/usr/share/shorewall</filename>, <filename
class="directory">/etc/shorewall</filename>,
<filename>/etc/init.d</filename> and <filename
@ -113,6 +114,11 @@
actions.</para>
</listitem>
<listitem>
<para><filename>compiler.pl</filename> - The configuration compiler
perl program.</para>
</listitem>
<listitem>
<para><filename class="directory">configfiles</filename> - A
directory containing configuration files to copy to create a <ulink
@ -162,6 +168,16 @@
<filename>/etc/shorewall/modules</filename>.</para>
</listitem>
<listitem>
<para><filename>prog.*</filename> - Shell program fragments used as
input to the compiler.</para>
</listitem>
<listitem>
<para><filename class="directory">Shorewall</filename> - Directory
containing the Shorewall Perl modules used by the compiler.</para>
</listitem>
<listitem>
<para><filename>version</filename> - A file containing the currently
install version of Shorewall.</para>
@ -178,7 +194,7 @@
<section id="shorewall">
<title>/etc/shorewall</title>
<para>This is where the modifiable configuration files are
<para>This is where the modifiable IPv4 configuration files are
installed.</para>
</section>
@ -199,14 +215,6 @@
url="manpages/shorewall-vardir.html">shorewall-vardir</ulink>(5).</para>
<itemizedlist>
<listitem>
<para><filename>chains</filename> - If DYNAMIC_ZONES=Yes in <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink>(5), this
file contains information used by the <command>add</command> and
<command>delete</command> commands (see <ulink
url="manpages/shorewall.html">shorewall</ulink>(8)).</para>
</listitem>
<listitem>
<para><filename>.iptables-restore-input</filename> - The file passed
as input to the iptables-restore program to initialize the firewall
@ -290,69 +298,175 @@
</section>
</section>
<section id="Shorewall-shell">
<title>Shorewall-shell</title>
<para>The Shorewall-shell product installs all of its files in
/usr/share/<filename class="directory">shorewall-shell</filename>.</para>
<itemizedlist>
<listitem>
<para><filename>compiler</filename> - The configuration compiler shell
program.</para>
</listitem>
<listitem>
<para><filename>lib.*</filename> - Shell function libraries used by
the compiler. On embedded systems, only a sub-set of the available
libraries may be installed as a space-saving measure.</para>
</listitem>
<listitem>
<para><filename>prog.*</filename> - Shell program fragments used as
input to the compiler.</para>
</listitem>
<listitem>
<para><filename>version</filename> - A file containing the currently
install version of Shorewall-shell.</para>
</listitem>
</itemizedlist>
</section>
<section id="Shorewall-perl">
<title>Shorewall-perl</title>
<title>Shorewall6</title>
<para>The Shorewall-perl product installs all of its files in
/usr/share/<filename class="directory">shorewall-perl</filename>.</para>
<para>Shorewall6 installs its files in a number of directories:</para>
<itemizedlist>
<listitem>
<para><filename>buildports.pl</filename> - A Perl program that builds
the Shorewall/Ports.pm module during installation (This program is
removed in Shorewall 4.0.5 and later releases)</para>
</listitem>
<section id="sbin6">
<title>/sbin</title>
<listitem>
<para><filename>compiler.pl</filename> - The configuration compiler
perl program.</para>
</listitem>
<para>The <filename>/sbin/shorewall6</filename> shell program is used to
interact with Shorewall6. See <ulink
url="manpages6/shorewall6.html">shorewall6</ulink>(8).</para>
</section>
<listitem>
<para><filename>prog.*</filename> - Shell program fragments used as
input to the compiler.</para>
</listitem>
<section id="share-shorewall6">
<title>/usr/share/shorewall6</title>
<listitem>
<para><filename class="directory">Shorewall</filename> - Directory
containing the Shorewall Perl modules used by the compiler.</para>
</listitem>
<para>The bulk of Shorewall6 is installed here.</para>
<listitem>
<para><filename>version</filename> - A file containing the currently
install version of Shorewall-shell.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para><filename>action.template</filename> - template file for
creating <ulink url="Actions.html">actions</ulink>.</para>
</listitem>
<listitem>
<para><filename>action.*</filename> - standard Shorewall
actions.</para>
</listitem>
<listitem>
<para><filename>actions.std</filename> - file listing the standard
actions.</para>
</listitem>
<listitem>
<para><filename class="directory">configfiles</filename> - A
directory containing configuration files to copy to create a <ulink
url="CompiledPrograms.html#Lite">Shorewall6-lite export
directory.</ulink></para>
</listitem>
<listitem>
<para><filename><filename>configpath</filename></filename> - A file
containing distribution-specific path assignments.</para>
</listitem>
<listitem>
<para><filename>firewall</filename> - A shell program that handles
the <command>add</command> and <command>delete</command> commands
(see <ulink url="manpages/shorewall.html">shorewall</ulink>(8)). It
also handles the <command>stop</command> and
<command>clear</command> commands when there is no current compiled
firewall script on the system.</para>
</listitem>
<listitem>
<para><filename class="symlink">functions</filename> - A symbolic
link to <filename>lib.base</filename> that provides for
compatibility with older versions of Shorewall.</para>
</listitem>
<listitem>
<para><filename>lib.*</filename> - Shell function libraries used by
the other shell programs.</para>
</listitem>
<listitem>
<para><filename>modules</filename> - File that drives the loading of
Netfilter kernel modules. May be overridden by
<filename>/etc/shorewall/modules</filename>.</para>
</listitem>
<listitem>
<para><filename>version</filename> - A file containing the currently
install version of Shorewall.</para>
</listitem>
<listitem>
<para><filename>wait4ifup</filename> - A shell program that <ulink
url="shorewall_extension_scripts.htm">extension scripts</ulink> can
use to delay until a network interface is available.</para>
</listitem>
</itemizedlist>
</section>
<section id="etc-shorewall6">
<title>/etc/shorewall6</title>
<para>This is where the modifiable IPv6 configuration files are
installed.</para>
</section>
<section id="var-shorewall6">
<title>/var/lib/shorewall6</title>
<para>Shorewall6 doesn't install any files in this directory but rather
uses the directory for storing state information. This directory may be
relocated using <ulink
url="manpages/shorewall-vardir.html">shorewall-vardir</ulink>(5).</para>
<itemizedlist>
<listitem>
<para><filename>.ip6tables-restore-input</filename> - The file
passed as input to the ip6tables-restore program to initialize the
firewall during the last <command>start</command> or
<command>restart</command> command (see <ulink
url="manpages6/shorewall6.html">shorewall6</ulink>(8)).</para>
</listitem>
<listitem>
<para><filename>.modules</filename> - The contents of the modules
file used during the last <command>start</command> or
<command>restart</command> command (see <ulink
url="manpages6/shorewall6.html">shorewall</ulink>(8) for command
information).</para>
</listitem>
<listitem>
<para><filename>.modulesdir</filename> - The MODULESDIR setting
(<ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink>(5)) at the
last <command>start</command> or <command>restart</command>.</para>
</listitem>
<listitem>
<para><filename>.refresh</filename> - The shell program that
performed the last successful <command>refresh</command>
command.</para>
</listitem>
<listitem>
<para><filename>.restart</filename> - The shell program that
performed the last successful <command>restart</command>
command.</para>
</listitem>
<listitem>
<para><filename>restore</filename> - The default shell program used
to execute <command>restore</command> commands.</para>
</listitem>
<listitem>
<para><filename>.restore</filename> - The shell program that
performed the last successful <command>refresh, restart</command> or
<command>start</command> command.</para>
</listitem>
<listitem>
<para><filename>save</filename> - File created by the
<command>save</command> command and used to restore the dynamic
blacklist during <command>start/restart</command>.</para>
</listitem>
<listitem>
<para><filename>.start</filename> - The shell program that performed
the last successful <command>start</command> command.</para>
</listitem>
<listitem>
<para><filename>state</filename> - Records the current firewall
state.</para>
</listitem>
<listitem>
<para><filename>zones</filename> - Records the current zone
contents.</para>
</listitem>
</itemizedlist>
</section>
</section>
<section id="Shorewall-lite">
@ -363,8 +477,8 @@
class="directory">/usr/share/shorewall-lite</filename>, <filename
class="directory">/etc/shorewall-lite</filename>,
<filename>/etc/init.d</filename> and <filename
class="directory">/var/lib/shorewall/</filename>. These are described in
the sub-sections that follow.</para>
class="directory">/var/lib/shorewall-lite/</filename>. These are described
in the sub-sections that follow.</para>
<section id="sbin-lite">
<title>/sbin</title>
@ -544,4 +658,181 @@
</itemizedlist>
</section>
</section>
<section id="Shorewall6-lite">
<title>Shorewall6-lite</title>
<para>The Shorewall6-lite product includes files installed in <filename
class="directory">/sbin</filename>, <filename
class="directory">/usr/share/shorewall6-lite</filename>, <filename
class="directory">/etc/shorewall6-lite</filename>,
<filename>/etc/init.d</filename> and <filename
class="directory">/var/lib/shorewall6-lite/</filename>. These are
described in the sub-sections that follow.</para>
<section id="sbin-lite6">
<title>/sbin</title>
<para>The <filename>/sbin/shorewall6-lite</filename> shell program is
use to interact with Shorewall lite. See <ulink
url="manpages6/shorewall6-lite.html">shorewall6-lite</ulink>(8).</para>
</section>
<section id="init-lite6">
<title>/etc/init.d or /etc/rc.d (depends on distribution)</title>
<para>An init script is installed here. Depending on the distribution,
it is named <filename>shorewall6-lite</filename> or
<filename>rc.firewall</filename>.</para>
</section>
<section id="etc-shorewall6-lite">
<title>/etc/shorewall6-lite</title>
<para>This is where the modifiable configuration files are
installed.</para>
</section>
<section id="share-lite6">
<title>/usr/share/shorewall6-lite</title>
<para>The bulk of Shorewall-lite is installed here.</para>
<itemizedlist>
<listitem>
<para><filename><filename>configpath</filename></filename> - A file
containing distribution-specific path assignments.</para>
</listitem>
<listitem>
<para><filename class="symlink">functions</filename> - A symbolic
link to <filename>lib.base</filename> that provides for
compatibility with older versions of Shorewall.</para>
</listitem>
<listitem>
<para><filename>lib.*</filename> - Shell function libraries used by
the other shell programs. These are copies of the corresponding
libraries in the Shorewall product.</para>
</listitem>
<listitem>
<para><filename>modules</filename> - File that drives the loading of
Netfilter kernel modules. May be overridden by
<filename>/etc/shorewall-lite/modules</filename>.</para>
</listitem>
<listitem>
<para><filename>shorecap</filename> - A shell program used for
generating capabilities files. See the <ulink
url="CompiledPrograms.html#Lite">Shorewall-lite
documentation</ulink>.</para>
</listitem>
<listitem>
<para><filename>version</filename> - A file containing the currently
install version of Shorewall.</para>
</listitem>
<listitem>
<para><filename>wait4ifup</filename> - A shell program that <ulink
url="shorewall_extension_scripts.htm">extension scripts</ulink> can
use to delay until a network interface is available.</para>
</listitem>
</itemizedlist>
</section>
<section id="var-lite6">
<title>/var/lib/shorewall6-lite</title>
<para>Shorewall6-lite doesn't install any files in this directory but
rather uses the directory for storing state information. This directory
may be relocated using <ulink
url="manpages/shorewall-lite-vardir.html">shorewall-lite-vardir</ulink>(5).</para>
<itemizedlist>
<listitem>
<para><filename>firewall</filename> - Compiled shell script
installed by running the load or reload command on the
administrative system (see <ulink
url="manpages/shorewall.html">shorewall6</ulink>(8)).</para>
</listitem>
<listitem>
<para><filename>firewall.conf</filename> - Digest of the
shorewall.conf file used to compile the firewall script on the
administrative system.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para><filename>.ip6tables-restore-input</filename> - The file
passed as input to the ip6tables-restore program to initialize the
firewall during the last <command>start</command> or
<command>restart</command> command (see <ulink
url="manpages/shorewall-lite.html">shorewall-lite</ulink>(8)).</para>
</listitem>
<listitem>
<para><filename>.modules</filename> - The contents of the modules
file used during the last <command>start</command> or
<command>restart</command> command (see <ulink
url="manpages/shorewall-lite.html">shorewall-lite</ulink>(8) for
command information).</para>
</listitem>
<listitem>
<para><filename>.modulesdir</filename> - The MODULESDIR setting
(<ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink>(5)) at the
last <command>start</command> or <command>restart.</command></para>
</listitem>
<listitem>
<para><filename>.refresh</filename> - The shell program that
performed the last successful <command>refresh</command>
command.</para>
</listitem>
<listitem>
<para><filename>.restart</filename> - The shell program that
performed the last successful <command>restart</command>
command.</para>
</listitem>
<listitem>
<para><filename>restore</filename> - The default shell program used
to execute <command>restore</command> commands.</para>
</listitem>
<listitem>
<para><filename>.restore</filename> - The shell program that
performed the last successful <command>refresh, restart</command> or
<command>start</command> command.</para>
</listitem>
<listitem>
<para><filename>save</filename> - File created by the
<command>save</command> command and used to restore the dynamic
blacklist during <command>start/restart</command>.</para>
</listitem>
<listitem>
<para><filename>.start</filename> - The shell program that performed
the last successful <command>start</command> command.</para>
</listitem>
<listitem>
<para><filename>state</filename> - Records the current firewall
state.</para>
</listitem>
<listitem>
<para><filename>zones</filename> - Records the current zone
contents.</para>
</listitem>
</itemizedlist>
</section>
</section>
</article>

87
docs/CompiledPrograms.xml
View File

@ -35,20 +35,20 @@
</articleinfo>
<caution>
<para><emphasis role="bold">This article applies to Shorewall 4.0 and
<para><emphasis role="bold">This article applies to Shorewall 4.3 and
later. If you are running a version of Shorewall earlier than Shorewall
4.0.0 then please see the documentation appropriate for your
4.3.5 then please see the documentation appropriate for your
version.</emphasis></para>
</caution>
<section id="Overview">
<title>Overview</title>
<para>Beginning with Shorewall version 3.1, Shorewall has the capability
to compile a Shorewall configuration and produce a runnable firewall
program script. The script is a complete program which can be placed on a
system with <emphasis>Shorewall Lite</emphasis> installed and can serve as
the firewall creation script for that system.</para>
<para>Shorewall has the capability to compile a Shorewall configuration
and produce a runnable firewall program script. The script is a complete
program which can be placed on a system with <emphasis>Shorewall
Lite</emphasis> installed and can serve as the firewall creation script
for that system.</para>
<section id="Restrictions">
<title>Restrictions</title>
@ -63,16 +63,11 @@
option is not supported.</para>
</listitem>
<listitem>
<para>DYNAMIC_ZONES=Yes in <filename>shorewall.conf</filename> is
not supported.</para>
</listitem>
<listitem>
<para>All extension scripts used are copied into the program (with
the exception of <ulink url="shorewall_extension_scripts.htm">those
executed at compile-time by Shorewall-perl</ulink>). The
ramifications of this are:</para>
executed at compile-time by the compiler</ulink>). The ramifications
of this are:</para>
<itemizedlist>
<listitem>
@ -81,9 +76,8 @@
</listitem>
<listitem>
<para>Beginning with Shorewall 3.2.9 and 3.4.0 RC2, the
<filename>params</filename> file is only processed at compile
time if you set EXPORTPARAMS=No in
<para>The <filename>params</filename> file is only processed at
compile time if you set EXPORTPARAMS=No in
<filename>shorewall.conf</filename>. For run-time setting of
shell variables, use the <filename>init</filename> extension
script. Although the default setting is EXPORTPARAMS=Yes for
@ -121,8 +115,8 @@
command:</para>
<blockquote>
<para><command>shorewall compile [ -e ] [ C {perl|shell} ] [
&lt;directory name&gt; ] &lt;path name&gt;</command></para>
<para><command>shorewall compile [ -e ] [ &lt;directory name&gt; ]
&lt;path name&gt;</command></para>
</blockquote>
<para>where</para>
@ -147,16 +141,6 @@
</listitem>
</varlistentry>
<varlistentry>
<term>-C {perl|shell}</term>
<listitem>
<para>Specifies the compiler to use. Overrides the
SHOREWALL_COMPILER setting in <filename><ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink></filename>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>&lt;directory name&gt;</term>
@ -223,19 +207,10 @@
<listitem>
<para>The <filename>/etc/shorewall/shorewall.conf</filename> file is
used to determine several settings during the compilation process,
even though there is a shorewall.conf file in the export directory.
<filename>/sbin/shorewall</filename> uses the SHOREWALL_COMPILER
setting from <filename>/etc/shorewall/shorewall.conf</filename> to
determine which compiler to launch. If the compiler is
shorewall-shell, then the SHOREWALL_SHELL setting from
<filename>/etc/shorewall/shorewall.conf</filename> determines the
shell to use. <filename>/sbin/shorewall</filename> also uses the
VERBOSITY setting from
<filename>/etc/shorewall/shorewall.conf</filename> for determining how
much output the compiler generates. All other settings are taken from
the <filename>shorewall.conf </filename>file in the remote systems
export directory.</para>
used to determine the VERBOSITY setting which determines how much
output the compiler generates. All other settings are taken from the
<filename>shorewall.conf </filename>file in the remote systems export
directory.</para>
<caution>
<para>If you want to be able to allow non-root users to manage
@ -321,7 +296,7 @@
<para><command>/sbin/shorewall load -c gateway</command><note>
<para>Although scp and ssh are used by default, you can use
other utilities by setting RSH_COMMAND and RCP_COMMAND in
<filename>/etc/shorewall/shorewall.conf</filename>. </para>
<filename>/etc/shorewall/shorewall.conf</filename>.</para>
</note></para>
</listitem>
</orderedlist>
@ -339,9 +314,9 @@
command compiles a firewall script from the configuration files in the
current working directory (using <command>shorewall compile
-e</command>), copies that file to the remote system via scp and
restarts Shorewall Lite on the remote system via ssh. Note: In
Shorewall 3.2.6 and later, the <emphasis role="bold">reload</emphasis>
command also supports the '-c' option.</para>
restarts Shorewall Lite on the remote system via ssh. The <emphasis
role="bold">reload</emphasis> command also supports the '-c'
option.</para>
<para>I personally place a <filename>Makefile</filename> in each
export directory as follows:</para>
@ -594,11 +569,11 @@ clean:
<para>If you set variables in the params file, there are a couple of
issues:</para>
<para>Beginning with Shorewall 3.2.9 and 3.4.0 RC2, the
<filename>params</filename> file is only processed at compile time
if you set EXPORTPARAMS=No in <filename>shorewall.conf</filename>.
For run-time setting of shell variables, use the
<filename>init</filename> extension script.</para>
<para>The <filename>params</filename> file is not processed at run
time if you set EXPORTPARAMS=No in
<filename>shorewall.conf</filename>. For run-time setting of shell
variables, use the <filename>init</filename> extension
script.</para>
<para>If the <filename>params</filename> file needs to set shell
variables based on the configuration of the firewall system, you can
@ -658,8 +633,7 @@ clean:
<programlisting><command>/usr/share/shorewall-lite/shorecap &gt; capabilities</command>
<command>scp capabilities &lt;admin system&gt;:&lt;this system's config dir&gt;</command></programlisting>
<para>Or, if you are running Shorewall 3.2.6 or later, simply use
the -c option the next time that you use the
<para>Or simply use the -c option the next time that you use the
<command>reload</command> command.</para>
</listitem>
</orderedlist>
@ -738,9 +712,8 @@ CAPVERSION=40190</programlisting>
system with Shorewall installed and used when compiling firewall programs
to run on the remote system.</para>
<para>Beginning with Shorewall Lite version 3.2.2, the
<filename>capabilities</filename> file may also be creating using
<filename>/sbin/shorewall-lite</filename>:<blockquote>
<para>The <filename>capabilities</filename> file may also be creating
using <filename>/sbin/shorewall-lite</filename>:<blockquote>
<para><command>shorewall-lite show -f capabilities &gt;
capabilities</command></para>
</blockquote></para>
@ -790,4 +763,4 @@ CAPVERSION=40190</programlisting>
is the level specified in the <filename>shorewall.conf</filename> file
used when the program was compiled.</para>
</section>
</article>
</article>

20
docs/Documentation_Index.xml
View File

@ -57,11 +57,10 @@
<row>
<entry><ulink url="6to4.htm">6to4 Tunnels</ulink></entry>
<entry><ulink url="Actions.html#Limit">Limiting per-IPaddress
Connection Rate</ulink></entry>
<entry><ulink url="KVM.html">KVM (Kernel-mode Virtual
Machine)</ulink></entry>
<entry><ulink url="CompiledPrograms.html#Lite">Shorewall
Lite</ulink></entry>
<entry></entry>
</row>
<row>
@ -69,8 +68,7 @@
<entry><ulink url="shorewall_logging.html">Logging</ulink></entry>
<entry><ulink url="Modularization.html">Shorewall
Modularization</ulink></entry>
<entry></entry>
</row>
<row>
@ -78,8 +76,8 @@
<entry><ulink url="Macros.html">Macros</ulink></entry>
<entry><ulink url="Shorewall-4.html">Shorewall 4.x</ulink> --
What's new</entry>
<entry> <ulink url="CompiledPrograms.html#Lite">Shorewall
Lite</ulink></entry>
</row>
<row>
@ -351,11 +349,9 @@
</row>
<row>
<entry><ulink url="KVM.html">KVM (Kernel-mode Virtual
Machine)</ulink></entry>
<entry></entry>
<entry><ulink url="ScalabilityAndPerformance.html">Scalability and
Performance</ulink></entry>
<entry></entry>
<entry></entry>
</row>

174
docs/FAQ.xml
View File

@ -37,9 +37,9 @@
</articleinfo>
<caution>
<para><emphasis role="bold">This article applies to Shorewall 3.0 and
<para><emphasis role="bold">This article applies to Shorewall 4.3 and
later. If you are running a version of Shorewall earlier than Shorewall
3.0.0 then please see the documentation for that
4.3.0 then please see the documentation for that
release.</emphasis></para>
</caution>
@ -83,12 +83,9 @@
<title>(FAQ 37a) I just installed Shorewall on Debian and I can't find
the sample configurations.</title>
<para><emphasis role="bold">Answer:</emphasis> With Shorewall 3.x, the
samples are included in the shorewall documentation package and are
<para><emphasis role="bold">Answer:</emphasis> Beginning with
Shorewall 4.0, the samples are in the shorewall-common package and are
installed in <filename
class="directory">/usr/share/doc/shorewall/examples/</filename>.
Beginning with Shorewall 4.0, the samples are in the shorewall-common
package and are installed in <filename
class="directory">/usr/share/doc/shorewall-common/examples/</filename>.</para>
</section>
</section>
@ -606,14 +603,7 @@ DNAT loc loc:192.168.1.5 tcp www - <emph
<para>Using this technique, you will want to configure your
DHCP/PPPoE/PPTP/… client to automatically restart Shorewall each
time that you get a new IP address.<note>
<para>If you are running Shorewall 3.2.6 on a Debian-based
system, the call to
<command>find_first_interface_address</command> in
<filename>/etc/shorewall/params</filename> must be preceded with
a load of the Shorewall function library:<programlisting><command>. /usr/share/shorewall/functions</command>
<command>ETH0_IP=`find_first_interface_address eth0`</command></programlisting></para>
</note></para>
time that you get a new IP address.</para>
</listitem>
</itemizedlist>
@ -733,14 +723,6 @@ DNAT loc dmz:192.168.2.4 tcp 80 - <emph
save</command> and <command>shorewall[-lite]
restore</command></ulink>.</para>
</warning>
<note>
<para>If you are running Shorewall 3.2.6 on a Debian-based system,
the call to <command>find_first_interface_address</command> in
<filename>/etc/shorewall/params</filename> must be preceded with a
load of the Shorewall function library:<programlisting><command>. /usr/share/shorewall/functions</command>
<command>ETH0_IP=`find_first_interface_address eth0`</command></programlisting></para>
</note>
</section>
<section id="faq2c">
@ -1026,13 +1008,10 @@ to debug/develop the newnat interface.</programlisting></para>
non-bridged traffic is not supported anymore.</programlisting>
<para>This kernel change, while necessary, means that Shorewall zones
may no longer be defined in terms of bridge ports. See <ulink
url="bridge-Shorewall-perl.html">the new Shorewall-shell bridging
documentation</ulink> for information about configuring a
bridge/firewall under kernel 2.6.20 and later with Shorewall shell or
the<ulink url="bridge-Shorewall-perl.html"> Shorewall-perl bridging
documentation</ulink> if you use Shorewall-perl
(highly-recommended).<note>
may no longer be defined in terms of bridge ports. See the<ulink
url="bridge-Shorewall-perl.html"> Shorewall-perl bridging
documentation</ulink> for information about how to configure
bridge/firewalls.<note>
<para>Following the instructions in the new bridging documentation
will not prevent the above message from being issued.</para>
</note></para>
@ -1312,11 +1291,11 @@ teastep@ursa:~$ </programlisting>The first number determines the maximum log
<ulink url="manpages/shorewall-rules.html">rule</ulink> to that
effect.</para>
<para>Beginning with Shorewall 3.3.3, packets logged out of these
chains may have a source and/or destination that is not in any
defined zone (see the output of <command>shorewall[-lite] show
zones</command>). Remember that zone membership involves both a
firewall interface and an ip address.</para>
<para>Packets logged out of these chains may have a source and/or
destination that is not in any defined zone (see the output of
<command>shorewall[-lite] show zones</command>). Remember that
zone membership involves both a firewall interface and an ip
address.</para>
</listitem>
</varlistentry>
@ -1392,10 +1371,10 @@ teastep@ursa:~$ </programlisting>The first number determines the maximum log
or you've done something silly like define a default route out of
an internal interface.</filename></para>
<para>In Shorewall 3.3.3 and later versions with OPTIMIZE=1 in
<ulink url="manpages/shorewall.conf.html">shorewall.conf</ulink>,
such packets may also be logged out of a &lt;zone&gt;2all chain or
the all2all chain.</para>
<para>With OPTIMIZE=1 in <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink>, such
packets may also be logged out of a &lt;zone&gt;2all chain or the
all2all chain.</para>
</listitem>
</varlistentry>
@ -1407,10 +1386,10 @@ teastep@ursa:~$ </programlisting>The first number determines the maximum log
your defined zones(<command>shorewall[-lite] show zones</command>
and look at the printed zone definitions).</para>
<para>In Shorewall 3.3.3 and later versions with OPTIMIZE=1 in
<ulink url="manpages/shorewall.conf.html">shorewall.conf</ulink>,
such packets may also be logged out of the fw2all chain or the
all2all chain.</para>
<para>With OPTIMIZE=1 in <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink>, such
packets may also be logged out of the fw2all chain or the all2all
chain.</para>
</listitem>
</varlistentry>
@ -1770,21 +1749,6 @@ Creating input Chains...
at the -I (--insert) command.</para>
</section>
<section id="faq34">
<title>(FAQ 34) How can I speed up Shorewall start (restart)?</title>
<para><emphasis role="bold">Answer:</emphasis> Switch to using <ulink
url="Shorewall-perl.html">Shorewall-perl</ulink>.</para>
</section>
<section id="faq69">
<title>(FAQ 69) When I restart Shorewall, new connections are blocked
for a long time. Is there a way to avoid that?</title>
<para><emphasis role="bold">Answer:</emphasis> Switch to using <ulink
url="Shorewall-perl.html">Shorewall-perl</ulink>.</para>
</section>
<section id="faq43">
<title>(FAQ 43) I just installed the Shorewall RPM and Shorewall doesn't
start at boot time.</title>
@ -1864,12 +1828,11 @@ iptables: Invalid argument
</itemizedlist>
<note>
<para>Beginning with Shorewall 3.4.0, Shorewall no longer attempts to
use policy match if you have no IPSEC zones and you have not specified
the <option>ipsec</option> option on any entry in
<filename>/etc/shorewall/hosts</filename>. The subject message will
still appear in your kernel log each time that Shorewall determines
the capabilities of your kernel/iptables.</para>
<para>Shorewall does not attempt to use policy match if you have no
IPSEC zones and you have not specified the <option>ipsec</option>
option on any entry in <filename>/etc/shorewall/hosts</filename>. The
subject message will still appear in your kernel log each time that
Shorewall determines the capabilities of your kernel/iptables.</para>
</note>
</section>
@ -2072,8 +2035,8 @@ We have an error talking to the kernel
<section id="faq12">
<title>(FAQ 12) Is there a GUI?</title>
<para><emphasis role="bold">Answer:</emphasis> Yes! Shorewall 3.x
support is available in Webmin 1.300. See <ulink
<para><emphasis role="bold">Answer:</emphasis> Yes! Shorewall support is
available in Webmin. See <ulink
url="http://www.webmin.com">http://www.webmin.com</ulink></para>
</section>
@ -2106,16 +2069,6 @@ We have an error talking to the kernel
type:</para>
<programlisting><command>/sbin/shorewall[-lite] version</command> </programlisting>
<section id="faq25a">
<title>(FAQ 25a) How do I tell which version of Shorewall-perl and
Shorewall-shell that I have installed?</title>
<para><emphasis role="bold">Answer:</emphasis> At the shell prompt,
type:</para>
<programlisting><command>/sbin/shorewall version -a</command> </programlisting>
</section>
</section>
<section id="faq31">
@ -2211,8 +2164,8 @@ We have an error talking to the kernel
with kernel 2.6.25. So that is what we developed IPv6 support on and
that's all that it has been tested on. If you are running 2.6.20 or
later, you can <emphasis role="bold">try</emphasis> to run Shorewall6
by hacking<filename> /usr/share/shorewall-perl/prog.footer6</filename>
and changing the kernel version test to check for your kernel version
by hacking<filename> /usr/share/shorewall/prog.footer6</filename> and
changing the kernel version test to check for your kernel version
rather than 2.6.25 (20625). But after that, you are on your
own.</para>
@ -2399,69 +2352,8 @@ eth0 eth1 # eth1 = interface to local netwo
<title>(FAQ 60) What are the compatibility restrictions between
Shorewall and Shorewall Lite</title>
<para><emphasis role="bold">Answer:</emphasis> Beginning with version
3.2.3, there are no compatibility constraints between Shorewall and
Shorewall-lite.</para>
</section>
</section>
<section id="Perl">
<title>Shorewall-Perl</title>
<section id="faq70">
<title>(FAQ 70) What is Shorewall-Perl?</title>
<para><emphasis role="bold">Answer:</emphasis> Shorewall-perl is a
re-implementation of the Shorewall configuration compiler written in
Perl.</para>
</section>
<section id="faq71">
<title>(FAQ 71) What are the advantages of using Shorewall-perl?</title>
<para><emphasis role="bold">Answer:</emphasis></para>
<itemizedlist>
<listitem>
<para>The Shorewall-perl compiler is much faster than the
Shorewall-shell compiler.</para>
</listitem>
<listitem>
<para>The script generated by the Shorewall-perl compiler uses
<command>iptables-restore</command> to instantiate the Netfilter
configuration. So it runs much faster than the script generated by
the Shorewall-shell compiler and doesn't disable new connections
during rule set installation.</para>
</listitem>
<listitem>
<para>The Shorewall-perl compiler does more thorough checking of the
configuration than the Shorewall-shell compiler does.</para>
</listitem>
<listitem>
<para>The error messages produced by the Shorewall-perl compiler are
better, more consistent and always include the file name and line
number where the error was detected.</para>
</listitem>
<listitem>
<para>Going forward, the Shorewall-perl compiler will get all
enhancements; the Shorewall-shell compiler will only get those
enhancements that are easy to retrofit.</para>
</listitem>
</itemizedlist>
</section>
<section id="faq72">
<title>(FAQ 72) Can I switch to using Shorewall-perl without changing my
Shorewall configuration?</title>
<para><emphasis role="bold">Answer:</emphasis> Maybe yes, maybe no. See
the <ulink url="Shorewall-perl.html">Shorewall Perl article</ulink> for
a list of the incompatibilities between Shorewall-shell and
Shorewall-perl.</para>
<para><emphasis role="bold">Answer:</emphasis> There are no
compatibility constraints between Shorewall and Shorewall-lite.</para>
</section>
</section>

44
docs/IPP2P.xml
View File

@ -41,26 +41,22 @@
</articleinfo>
<caution>
<para><emphasis role="bold">This article applies to Shorewall 3.0 and
<para><emphasis role="bold">This article applies to Shorewall 4.3 and
later. If you are running a version of Shorewall earlier than Shorewall
3.0.0 then please see the documentation for that
4.3.5 then please see the documentation for that
release.</emphasis></para>
<para><emphasis role="bold">If you are running the xtables-addons version
of IPP2P, you are strongly advised to use Shorewall-perl 4.2.5 or
later.</emphasis></para>
</caution>
<section id="Intro">
<title>Introduction</title>
<para>Shorewall versions 2.2.0 and later include support for the ipp2p
match facility. This is a departure from my usual policy in that the ipp2p
match facility is included in xtables-addons and is unlikely to ever be
included in the kernel.org source tree. Questions about how to install
xtables-addons or how to build your kernel and/or iptables should not be
posted on the Shorewall mailing lists but should rather be referred to the
Netfilter Mailing List.</para>
<para>Shorewall includes support for the ipp2p match facility. This is a
departure from my usual policy in that the ipp2p match facility is
included in xtables-addons and is unlikely to ever be included in the
kernel.org source tree. Questions about how to install xtables-addons or
how to build your kernel and/or iptables should not be posted on the
Shorewall mailing lists but should rather be referred to the Netfilter
Mailing List.</para>
</section>
<section id="Scope">
@ -91,25 +87,11 @@
<programlisting><command>iptables -m ipp2p --help</command></programlisting>
<para>You must not include the leading "--" on the option(s); Shorewall
will supply those characters for you. If you do not include an option
then:</para>
will supply those characters for you. If you do not include an option then
Shorewall will assume "edk,kazaa,gnu,dc".</para>
<itemizedlist>
<listitem>
<para>Shorewall-shell and Shorewall-perl up through 4.2.4 will assume
"ipp2p". Note that the xtables-addons version of IPP2P no longer
supports that option.</para>
</listitem>
<listitem>
<para>Shorewall-perl 4.2.5 and later will assume "ipp2p" if that
option is supported by the installed iptables/Netfilter. Otherwise,
Shorewall-perl will assume "edk,kazaa,gnu,dc"</para>
</listitem>
</itemizedlist>
<para>If 'ipp2p' is specified, Shorewall-perl 4.2.5 and later will
substitute "edk,kazaa,gnu,dc".</para>
<para>If 'ipp2p' is specified, Shorewall will substitute
"edk,kazaa,gnu,dc".</para>
</section>
<section id="Example">

6
docs/IPSEC-2.6.xml
View File

@ -51,9 +51,9 @@
</articleinfo>
<caution>
<para><emphasis role="bold">This article applies to Shorewall 3.0 and
<para><emphasis role="bold">This article applies to Shorewall 4.3 and
later. If you are running a version of Shorewall earlier than Shorewall
3.0.0 then please see the documentation for that
4.3.5 then please see the documentation for that
release.</emphasis></para>
</caution>
@ -83,7 +83,7 @@
</warning>
<section id="Overview">
<title>Shorewall 3.0 and Kernel 2.6 IPSEC</title>
<title>Shorwall and Kernel 2.6 IPSEC</title>
<para>This is <emphasis role="bold">not</emphasis> a HOWTO for Kernel 2.6
IPSEC -- for that, please see <ulink

30
docs/IPv6Support.xml
View File

@ -20,6 +20,8 @@
<copyright>
<year>2008</year>
<year>2009</year>
<holder>Thomas M. Eastep</holder>
</copyright>
@ -34,6 +36,13 @@
</legalnotice>
</articleinfo>
<caution>
<para><emphasis role="bold">This article applies to Shorewall 4.3 and
later. If you are running a version of Shorewall earlier than Shorewall
4.3.5 then please see the documentation for that
release.</emphasis></para>
</caution>
<section>
<title>Overview</title>
@ -77,9 +86,8 @@
of <filename>/sbin/shorewall</filename>.
<filename>/sbin/shorewall</filename> only handles IPv4 while
<filename>/sbin/shorewall6</filename> handles only IPv6.. Shorewall6
depends on both Shorewall-common and on Shorewall-perl. The
Shorewall6 configuration is stored in <filename
class="directory">/etc/shorewall6</filename>.</para>
depends on Shorewall. The Shorewall6 configuration is stored in
<filename class="directory">/etc/shorewall6</filename>.</para>
</listitem>
<listitem>
@ -476,11 +484,7 @@ ACCEPT net:wlan0:&lt;2002:ce7c:92b4::3&gt; tcp
</listitem>
</itemizedlist>
<para>Also, please note that since Shorewall6 is based on
Shorewall-perl, dynamic zones are not supported. Hence the add and
delete commands are not supported by
<filename>/sbin/shorewall6</filename> and
<filename>/sbin/shorewall6-lite</filename>.</para>
<para></para>
</listitem>
</varlistentry>
@ -505,19 +509,15 @@ ACCEPT net:wlan0:&lt;2002:ce7c:92b4::3&gt; tcp
<itemizedlist>
<listitem>
<para>Shorewall-common 4.2.4 or later.</para>
<para>Shorewall 4.3.5 or later.</para>
</listitem>
<listitem>
<para>Shorewall-perl 4.2.4 or later.</para>
</listitem>
<listitem>
<para>Shorewall6 4.2.4 or later.</para>
<para>Shorewall6 4.3.5 or later.</para>
</listitem>
</itemizedlist>
<para>You may also with to install Shorewall6-lite 4.3.4 or later on your
<para>You may also with to install Shorewall6-lite 4.3.5 or later on your
remote firewalls to allow for central IPv6 firewall administration.</para>
</section>

303
docs/Install.xml
View File

@ -22,6 +22,8 @@
<year>2006</year>
<year>2009</year>
<holder>Thomas M. Eastep</holder>
</copyright>
@ -37,9 +39,9 @@
</articleinfo>
<caution>
<para><emphasis role="bold">This article applies to Shorewall 3.0 and
<para><emphasis role="bold">This article applies to Shorewall 4.3 and
later. If you are installing or upgrading to a version of Shorewall
earlier than Shorewall 3.0.0 then please see the documentation for that
earlier than Shorewall 4.3.5 then please see the documentation for that
release.</emphasis></para>
</caution>
@ -47,7 +49,9 @@
<para>Before attempting installation, I strongly urge you to read and
print a copy of the <ulink url="shorewall_quickstart_guide.htm">Shorewall
QuickStart</ulink> Guide for the configuration that most closely matches
your own.</para>
your own. This article only tells you how to install the product on your
system. The QuickStart Guides describe how to configure the
product.</para>
</important>
<important>
@ -91,27 +95,13 @@
page</ulink>.</para>
<para>If you try to install the wrong package, it probably won't
work.<note>
<para>If you are installing Shorewall 4.0.0 or later then you need
to install at least two packages.<itemizedlist>
<listitem>
<para>Either Shorewall-shell (the classic shell-based
configuration compiler) and/or Shorewall-perl (the newer and
faster compiler written in Perl).</para>
</listitem>
<listitem>
<para>Shorewall-common</para>
</listitem>
</itemizedlist>If you are installing Shorewall for the first
time, we strongly suggest that you install Shorewall-perl.</para>
</note></para>
work.</para>
</listitem>
<listitem>
<para>Install the RPMs</para>
<programlisting><command>rpm -ivh &lt;compiler rpm&gt; ... &lt;shorewall-common rpm&gt;</command></programlisting>
<programlisting><command>rpm -ivh &lt;shorewall rpm&gt;</command></programlisting>
<caution>
<para>Some users are in the habit of using the <command>rpm
@ -123,15 +113,6 @@
links.</para>
</caution>
<note>
<para>Some <trademark>SUSE</trademark> users have encountered a
problem whereby rpm reports a conflict with kernel &lt;= 2.2 even
though a 2.4 kernel is installed. If this happens, simply use the
--nodeps option to rpm.</para>
<programlisting><filename><command>rpm -ivh --nodeps &lt;rpms&gt;</command></filename></programlisting>
</note>
<note>
<para>Shorewall is dependent on the iproute package. Unfortunately,
some distributions call this package iproute2 which will cause the
@ -146,39 +127,7 @@
<programlisting><command>rpm -ivh --nodeps &lt;rpms&gt;</command></programlisting>
</note>
<para>Example:<programlisting><command>rpm -ivh shorewall-perl-4.0.0-1.noarch.rpm shorewall-common-4.0.0-1.noarch.rpm</command></programlisting><important>
<para>Simon Matter names his '<emphasis>common</emphasis>' rpm
'<emphasis>shorewall</emphasis>' rather than
'<emphasis>shorewall-common</emphasis>'. So if you are installing
his RPMs, the command would be:<programlisting><command>rpm -ivh shorewall-perl-4.0.0-1.noarch.rpm shorewall-4.0.0-1.noarch.rpm</command></programlisting></para>
</important></para>
</listitem>
<listitem>
<para>Edit the <link linkend="Config_Files">configuration files</link>
to match your configuration.</para>
<warning>
<para>YOU CAN <emphasis role="bold">NOT</emphasis> SIMPLY INSTALL
THE RPM AND ISSUE A <quote>shorewall start</quote> COMMAND. SOME
CONFIGURATION IS REQUIRED BEFORE THE FIREWALL WILL START. IF YOU
ISSUE A <quote>start</quote> COMMAND AND THE FIREWALL FAILS TO
START, YOUR SYSTEM WILL NO LONGER ACCEPT ANY NETWORK TRAFFIC. IF
THIS HAPPENS, ISSUE A <quote>shorewall clear</quote> COMMAND TO
RESTORE NETWORK CONNECTIVITY.</para>
</warning>
</listitem>
<listitem>
<para>Enable startup by editing
/<filename>etc/shorewall/shorewall.conf</filename> and set
STARTUP_ENABLED to Yes).</para>
</listitem>
<listitem>
<para>Start the firewall by typing</para>
<programlisting><command>shorewall start</command></programlisting>
<para>Example:<programlisting><command>rpm -ivh shorewall-4.3.5-0base.noarch.rpm</command></programlisting></para>
</listitem>
</orderedlist>
</section>
@ -186,35 +135,16 @@
<section id="Install_Tarball">
<title>Install using tarball</title>
<note>
<para>If you are installing Shorewall 4.0.0 or later then you need to
install at least two packages.<itemizedlist>
<listitem>
<para>Either Shorewall-shell (the classic shell-based
configuration compiler) and/or Shorewall-perl (the newer and
faster compiler written in Perl).</para>
</listitem>
<listitem>
<para>Shorewall-common</para>
</listitem>
</itemizedlist>If you are installing Shorewall for the first time, we
strongly suggest that you install Shorewall-perl.</para>
</note>
<para>To install Shorewall-perl and Shorewall-common using the tarball and
install scripts:</para>
<para>To install Shorewall using the tarball and install script:</para>
<orderedlist>
<listitem>
<para>unpack the tarballs:<programlisting><command>tar -jxf shorewall-common-4.0.0.tar.bz2</command>
<command>tar -jxf shorewall-perl-4.0.0.tar.bz2
</command></programlisting></para>
<para>unpack the tarballs:<programlisting><command>tar -jxf shorewall-4.3.5.tar.bz2</command></programlisting></para>
</listitem>
<listitem>
<para>cd to the shorewall-perl directory (the version is encoded in
the directory name as in <quote>shorewall-perl-4.0.0</quote>).</para>
<para>cd to the shorewall directory (the version is encoded in the
directory name as in <quote>shorewall-4.3.5</quote>).</para>
</listitem>
<listitem>
@ -223,34 +153,6 @@
<programlisting><command>./install.sh</command></programlisting>
</listitem>
<listitem>
<para>cd to the shorewall-common directory (the version is encoded in
the directory name as in <quote>shorewall-common-4.0.0</quote>)</para>
</listitem>
<listitem>
<para>Type:</para>
<programlisting><command>./install.sh</command></programlisting>
</listitem>
<listitem>
<para>Edit the <link linkend="Config_Files">configuration files</link>
to match your configuration.</para>
</listitem>
<listitem>
<para>Enable Startup by editing
<filename>/etc/shorewall/shorewall.conf</filename> and set
STARTUP_ENABLED=Yes.</para>
</listitem>
<listitem>
<para>Start the firewall by typing</para>
<programlisting><command>shorewall start</command></programlisting>
</listitem>
<listitem>
<para>If the install script was unable to configure Shorewall to be
started automatically at boot, see <ulink
@ -280,11 +182,7 @@
Shorewall, please modify your
<filename>/etc/apt/preferences:</filename></para>
<para><programlisting>Package: shorewall-common
Pin: release o=Debian,a=testing
Pin-Priority: 700
Package: shorewall-perl
<para><programlisting>Package: shorewall
Pin: release o=Debian,a=testing
Pin-Priority: 700
@ -292,7 +190,7 @@ Package: shorewall-doc
Pin: release o=Debian,a=testing
Pin-Priority: 700</programlisting><emphasis role="bold"><emphasis>Then
run:</emphasis></emphasis><programlisting># apt-get update
# apt-get install shorewall-common shorewall-perl</programlisting></para>
# apt-get install shorewall</programlisting></para>
<para><emphasis><emphasis role="bold">Once you have completed configuring
Shorewall, you can enable startup at boot time by setting startup=1 in
@ -365,16 +263,7 @@ Pin-Priority: 700</programlisting><emphasis role="bold"><emphasis>Then
<listitem>
<para>Upgrade the RPM</para>
<programlisting><command>rpm -Uvh &lt;compiler rpm file&gt; ... &lt;shorewall-common rpm file&gt; </command></programlisting>
<note>
<para>Some <trademark>SUSE</trademark> users have encountered a
problem whereby rpm reports a conflict with kernel &lt;= 2.2 even
though a 2.4 kernel is installed. If this happens, simply use the
--nodeps option to rpm.</para>
<programlisting><command>rpm -Uvh --nodeps &lt;shorewall-common rpm&gt; &lt;compiler rpm&gt; ...</command></programlisting>
</note>
<programlisting><command>rpm -Uvh &lt;shorewall rpm file&gt; </command></programlisting>
<note>
<para>Shorewall is dependent on the iproute package. Unfortunately,
@ -386,7 +275,7 @@ Pin-Priority: 700</programlisting><emphasis role="bold"><emphasis>Then
<para>This may be worked around by using the --nodeps option of
rpm.</para>
<programlisting><command>rpm -Uvh --nodeps &lt;shorewall rpm&gt; &lt;compiler-rpm&gt; ...</command></programlisting>
<programlisting><command>rpm -Uvh --nodeps &lt;shorewall rpm&gt; ...</command></programlisting>
</note>
</listitem>
@ -420,30 +309,12 @@ Pin-Priority: 700</programlisting><emphasis role="bold"><emphasis>Then
<orderedlist>
<listitem>
<para>unpack the tarballs:<programlisting><command>tar -jxf shorewall-common-4.0.0.tar.bz2</command>
<command>tar -jxf shorewall-perl-4.0.0.tar.bz2
tar -jxf shorewall-shell-4.0.0.tar.bz2</command> (if you use this compiler)</programlisting></para>
<para>unpack the tarball:<programlisting><command>tar -jxf shorewall-4.3.5.tar.bz2</command></programlisting></para>
</listitem>
<listitem>
<para>cd to the shorewall-perl directory (the version is encoded in
the directory name as in <quote>shorewall-perl-4.0.0</quote>).</para>
</listitem>
<listitem>
<para>Type:</para>
<programlisting><command>./install.sh</command></programlisting>
</listitem>
<listitem>
<para>Perform the above two steps for the shorewall-shell directory if
you use that compiler.</para>
</listitem>
<listitem>
<para>cd to the shorewall-common directory (the version is encoded in
the directory name as in <quote>shorewall-perl-4.0.0</quote>)</para>
the directory name as in <quote>shorewall-4.3.5</quote>).</para>
</listitem>
<listitem>
@ -485,140 +356,6 @@ tar -jxf shorewall-shell-4.0.0.tar.bz2</command> (if you use this compiler)</pro
</warning>
</section>
<section id="LRP_Upgrade">
<title>Upgrade the .lrp</title>
<para>The following was contributed by Charles Steinkuehler on the Leaf
mailing list:</para>
<blockquote>
<para>It's *VERY* simple...just put in a new CD and reboot!  :-)
Actually, I'm only slightly kidding...that's exactly how I upgrade my
production firewalls.  The partial backup feature I added to Dachstein
allows configuration data to be stored separately from the rest of the
package.</para>
<para>Once the config data is separated from the rest of the package,
it's an easy matter to upgrade the package while keeping your current
configuration (in my case, just inserting a new CD and
re-booting).</para>
<para>Users who aren't running with multiple package paths and using
partial backups can still upgrade a package, it just takes a bit of
extra work.  The general idea is to use a partial backup to save your
configuration, replace the package, and restore your old configuration
files. Step-by-step instructions for one way to do this (assuming a
conventional single-floppy LEAF system) would be:</para>
<itemizedlist>
<listitem>
<para>Make a backup copy of your firewall disk ('NEW').  This is the
disk you will add the upgraded package(s) to.</para>
</listitem>
<listitem>
<para>Format a floppy to use as a temporary location for your
configuration file(s) ('XFER').  This disk should have the same
format as your firewall disk (and could simply be another backup
copy of your current firewall).</para>
</listitem>
<listitem>
<para>Make sure you have a working copy of your existing firewall
('OLD') in a safe place, that you *DO NOT* use during this process.
That way, if anything goes wrong you can simply reboot off the OLD
disk to get back to a working configuration.</para>
</listitem>
<listitem>
<para>Remove your current firewall configuration disk and replace it
with the XFER disk.</para>
</listitem>
<listitem>
<para>Use the lrcfg backup menu to make a partial backup of the
package(s) you want to upgrade, being sure to backup the files to
the XFER disk.  From the backup menu:</para>
<programlisting>t e &lt;enter&gt; p &lt;enter&gt;
b &lt;package1&gt; &lt;enter&gt;
b &lt;package2&gt; &lt;enter&gt;
...</programlisting>
</listitem>
<listitem>
<para>Download and copy the package(s) you want to upgrade onto the
NEW disk.</para>
</listitem>
<listitem>
<para>Reboot your firewall using the NEW disk...at this point your
upgraded packages will have their default configuration.</para>
</listitem>
<listitem>
<para>Mount the XFER disk (mount -t msdos /dev/fd0u1680 /mnt)</para>
</listitem>
<listitem>
<para>CD to the root directory (cd /)</para>
</listitem>
<listitem>
<para>Manually extract configuration data for each package you
upgraded:</para>
<programlisting>tar -xzvf /mnt/package1.lrp
tar -xzvf /mnt/package2.lrp
...</programlisting>
</listitem>
<listitem>
<para>Unmount (umount /mnt) and remove the XFER disk</para>
</listitem>
<listitem>
<para>Using lrcfg, do *FULL* backups of your upgraded
packages.</para>
</listitem>
<listitem>
<para>Reboot, verifying the firewall works as expected.  Some
configuration files may need to be 'tweaked' to work properly with
the upgraded package binaries.</para>
</listitem>
</itemizedlist>
<important>
<para>The new package file &lt;package&gt;.local can be used to
fine-tune which files are included (and excluded) from the partial
backup (see the Dachstein-CD README for details).  If this file
doesn't exist, the backup scripts assume anything from the
&lt;package&gt;.list file that resides in /etc or /var/lib/lrpkg is
part of the configuration data and is used to create the partial
backup.  If shorewall puts anything in /etc that isn't a user modified
configuration file, a proper shorewall.local file should be created
prior to making the partial backup [<emphasis role="bold">Editor's
note</emphasis>: Shorewall places only user-modifiable files in
/etc].</para>
</important>
<note>
<para>It's obviously possible to do the above 'in-place', without
using multiple disks, and even without making a partial backup (ie:
copy current config files to /tmp, manually extract new package on top
of current running firewall, then copy or merge config data from /tmp
and backup...or similar), but anyone capable of that level of command
line gymnastics is probably doing it already, without needing detailed
instructions! :-)</para>
</note>
</blockquote>
<para>For information on other LEAF/Bering upgrade tools, check out <ulink
url="http://leaf.cvs.sourceforge.net/*checkout*/leaf/devel/alexrh/lck/README.html">this
article by Alex Rhomberg</ulink>.</para>
</section>
<section id="Config_Files">
<title>Configuring Shorewall</title>

70
docs/Introduction.xml
View File

@ -16,7 +16,7 @@
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
<copyright>
<year>2003-2007</year>
<year>2003-2009</year>
<holder>Thomas M. Eastep</holder>
</copyright>
@ -35,8 +35,8 @@
<section id="Intro">
<title>Introduction</title>
<para>The information in this document applies only to 4.x releases of
Shorewall.</para>
<para>The information in this document applies only to 4.3 and later
releases of Shorewall.</para>
<section id="Glossary">
<title>Glossary</title>
@ -337,12 +337,11 @@ ACCEPT net $FW tcp 22</programlisting>
<section id="Compile">
<title>Compile then Execute</title>
<para>Shorewall versions beginning with 3.2.0 use a "compile" then
"execute" approach. The Shorewall configuration compiler reads the
configuration files and generates a shell script. Errors in the
compilation step cause the script to be discarded and the command to be
aborted. If the compilation step doesn't find any errors then the shell
script is executed.</para>
<para>Shorewall uses a "compile" then "execute" approach. The Shorewall
configuration compiler reads the configuration files and generates a shell
script. Errors in the compilation step cause the script to be discarded
and the command to be aborted. If the compilation step doesn't find any
errors then the shell script is executed.</para>
<para>The 'compiled' scripts are placed in the directory <filename
class="directory">/var/lib/shorewall</filename> and are named to
@ -355,54 +354,37 @@ ACCEPT net $FW tcp 22</programlisting>
<section id="Packages">
<title>Shorewall Packages</title>
<para>Shorewall 4.0 consists of four packages.</para>
<para>Shorewall 4.3 and later consists of four packages.</para>
<orderedlist>
<listitem>
<para><emphasis role="bold">Shorewall-common</emphasis>. This package
must be installed on at least one system in your network. That system
must also have Shorewall-shell and/or Shorewall-perl installed.</para>
<para><emphasis role="bold">Shorewall</emphasis>. This package must be
installed on at least one system in your network. It contains
everything needed to create an IPv4 firewall.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Shorewall-shell</emphasis>. This package
includes the legacy Shorewall configuration compiler written in Bourne
Shell. This compiler is very portable but suffers from performance
problems and has become hard to maintain.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Shorewall-perl</emphasis>. An alternative
to Shorewall-shell written in the Perl language. This compiler is
highly portable to those Unix-like platforms that support Perl
(including Cygwin) and is the compiler of choice for new Shorewall
installations. Scripts created using Shorewall-perl use
iptables-restore to install the generated Netfilter rule set.</para>
<para><emphasis role="bold">Shorewall6</emphasis>. This package
requires the Shorewall package and adds those components needed to
create an IPv6 fireawall.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Shorewall-lite</emphasis>. Shorewall
allows for central administration of multiple firewalls through use of
Shorewall lite. The full Shorewall product (along with Shorewall-shell
and/or Shorewall-perl) are installed on a central administrative
system where compiled Shorewall scripts are generated. These scripts
are copied to the firewall systems where they run under the control of
Shorewall-lite.</para>
</listitem>
</orderedlist>
<para>In Shorewall 4.2.4, two additional packages were added:</para>
<orderedlist>
<listitem>
<para><emphasis role="bold">Shorewall6</emphasis> - The utilities
necessary to <ulink url="IPv6Support.html">control and configure an
IPv6 firewall</ulink>.</para>
allows for central administration of multiple IPv4 firewalls through
use of Shorewall lite. The full Shorewall product is installed on a
central administrative system where compiled Shorewall scripts are
generated. These scripts are copied to the firewall systems where they
run under the control of Shorewall-lite.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Shorewall6-lite</emphasis> - The IPv6
equivalent of Shorewall-lite.</para>
<para><emphasis role="bold">Shorewall6-lite</emphasis>. Shorewall
allows for central administration of multiple IPv4 firewalls through
use of Shorewall lite. The full Shorewall product is installed on a
central administrative system where compiled Shorewall scripts are
generated. These scripts are copied to the firewall systems where they
run under the control of Shorewall-lite.</para>
</listitem>
</orderedlist>
</section>

26
docs/MAC_Validation.xml
View File

@ -86,9 +86,9 @@
<listitem>
<para>The <emphasis role="bold">maclist</emphasis> option in <ulink
url="manpages/shorewall-hosts.html">/etc/shorewall/hosts</ulink>. When this
option is specified for a subnet, all new connection requests from
that subnet are subject to MAC verification.</para>
url="manpages/shorewall-hosts.html">/etc/shorewall/hosts</ulink>. When
this option is specified for a subnet, all new connection requests
from that subnet are subject to MAC verification.</para>
</listitem>
<listitem>
@ -110,10 +110,9 @@
</listitem>
<listitem>
<para>Beginning with Shorewall 2.2.3, the <emphasis
role="bold">MACLIST_TTL</emphasis> variable in <ulink
url="???">/etc/shorewall/shorewall.conf</ulink>. The performance of
configurations with a large numbers of entries in
<para>The <emphasis role="bold">MACLIST_TTL</emphasis> variable in
<ulink url="???">/etc/shorewall/shorewall.conf</ulink>. The
performance of configurations with a large numbers of entries in
/etc/shorewall/maclist can be improved by setting the MACLIST_TTL
variable.</para>
@ -138,9 +137,8 @@
</listitem>
<listitem>
<para>Beginning with Shorewall 2.4.6, the <emphasis
role="bold">MACLIST_TABLE</emphasis> variable in <ulink
url="???">/etc/shorewall/shorewall.conf</ulink>. Normally, MAC
<para>The <emphasis role="bold">MACLIST_TABLE</emphasis> variable in
<ulink url="???">/etc/shorewall/shorewall.conf</ulink>. Normally, MAC
verification occurs in the filter table (INPUT and FORWARD) chains.
When forwarding a packet from an interface with MAC verification to a
bridge interface, that doesn't work.</para>
@ -161,7 +159,7 @@
<variablelist>
<varlistentry>
<term>DISPOSITION (Added in Shorewall version 3.1)</term>
<term>DISPOSITION</term>
<listitem>
<para>Must be ACCEPT, DROP or REJECT (REJECT may not be specified if
@ -186,9 +184,9 @@
<listitem>
<para>The MAC address of a device on the Ethernet segment connected
by INTERFACE. It is not necessary to use the Shorewall MAC format in
this column although you may use that format if you so choose.
Beginning with Shorewall 3.1, you may specify "-" here if you enter
an IP address in the next column.</para>
this column although you may use that format if you so choose. You
may specify "-" here if you enter an IP address in the next
column.</para>
</listitem>
</varlistentry>

79
docs/Macros.xml
View File

@ -41,9 +41,9 @@
</articleinfo>
<caution>
<para><emphasis role="bold">This article applies to Shorewall 3.0 and
<para><emphasis role="bold">This article applies to Shorewall 4.3 and
later. If you are running a version of Shorewall earlier than Shorewall
3.0.0 then please see the documentation for that
4.3.5 then please see the documentation for that
release.</emphasis></para>
</caution>
@ -112,33 +112,9 @@ PARAM - - tcp 135,139,445
when you invoke the macro. The SMB macro shown above is parameterized
(note PARAM in the TARGET column).</para>
<para><emphasis role="bold">Shorewall versions prior to 4.2.0:</emphasis>
When invoking a parameterized macro, you follow the name of the macro with
a slash ("/") and the action that you want to substitute for PARAM.</para>
<para>Example:</para>
<blockquote>
<para>/etc/shorewall/rules:</para>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
SMB/ACCEPT loc fw </programlisting>
<para>The above is equivalent to coding the following series of
rules:</para>
<programlisting>#TARGET SOURCE DEST PROTO DEST PORT(s)
ACCEPT loc fw udp 135,445
ACCEPT loc fw udp 137:139
ACCEPT loc fw udp 1024: 137
ACCEPT loc fw tcp 135,139,445</programlisting>
</blockquote>
<para><emphasis role="bold">Shorewall-perl versions 4.2.0 and
later:</emphasis> When invoking a parameterized macro, you follow the name
of the macro with the action that you want to substitute for PARAM
enclosed in parentheses. The older syntax described above is still
supported but is deprecated.</para>
<para>When invoking a parameterized macro, you follow the name of the
macro with the action that you want to substitute for PARAM enclosed in
parentheses. </para>
<para>Example:</para>
@ -168,11 +144,10 @@ ACCEPT loc fw tcp 135,139,445</programlisting>
<listitem>
<para>If a value other than "-" appears in both the macro body and
in the invocation of the macro, then the value in the invocation is
examined and the appropriate action is taken (you will want to be
running Shorewall 3.0.1 or later). If the value in the invocation
appears to be an address (IP or MAC) or the name of an ipset, then
it is placed after the value in the macro body. Otherwise, it is
placed before the value in the macro body.</para>
examined and the appropriate action is taken. If the value in the
invocation appears to be an address (IP or MAC) or the name of an
ipset, then it is placed after the value in the macro body.
Otherwise, it is placed before the value in the macro body.</para>
<para>Example 1:</para>
@ -224,16 +199,16 @@ SMTP(DNAT):info net loc</programlisting>
DNAT:info net loc:192.168.1.5 tcp 25</programlisting>
</blockquote>
<para>Beginning with Shorewall 3.1, you may also specify SOURCE or
DEST in the SOURCE and DEST columns. This allows you to define
macros that work in both directions.</para>
<para>You may also specify SOURCE or DEST in the SOURCE and DEST
columns. This allows you to define macros that work in both
directions.</para>
<para>Example 3:</para>
<blockquote>
<para><filename>/etc/shorewall/macro.SMBBI</filename> (Note: there
is already a macro like this released as part of Shorewall 3.1 and
later):</para>
is already a standard macro like this released as part of
Shorewall):</para>
<programlisting>#ACTION SOURCE DEST PROTO DEST SOURCE ORIGINAL RATE USER/
# PORT PORT(S) DEST LIMIT GROUP
@ -287,32 +262,6 @@ ACCEPT fw loc tcp 135,139,445</programlisting>
from actions cannot themselves invoke other actions.</para>
</section>
<section id="Default">
<title>Default Macros</title>
<para>Beginning with Shorewall release 3.4, Shorewall supports
<firstterm>default macros</firstterm>; default macros perform the same
function as <ulink url="???">default actions</ulink>. The DEFAULT_ACCEPT,
DEFAULT_REJECT, DEFAULT_DROP and DEFAULT_QUEUE options in
<filename>/etc/shorewall/shorewall.conf</filename> may specify the name of
a macro. In that case, the rules in the macro will be traversed before the
associated policy is applied.</para>
<para>The value of the …_DEFAULT settings is interpreted as follows. If
USE_ACTIONS=Yes in shorewall.conf, then the value is treated like the name
of an action -- if that action is not found, then the value is treated
like the name of a macro. If USE_ACTIONS=No, then the value is treated
like the name of a macro. The special value "none" is always interpreted
as "no default rules should be applied".</para>
<para>Shorewall versions 3.4 and later include standard 'Reject' and
'Drop' macros that are equivalent to the 'Reject' and 'Drop'
actions.</para>
<para><emphasis>Default Macros are not supported by
Shorewall-perl.</emphasis></para>
</section>
<section id="Defining">
<title>Defining your own Macros</title>

12
docs/ManualChains.xml
View File

@ -18,7 +18,9 @@
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
<copyright>
<year>2007</year>
<year>2008</year>
<year>2009</year>
<holder>Thomas M. Eastep</holder>
</copyright>
@ -37,10 +39,10 @@
<section id="Intro">
<title>Introduction</title>
<para>Manual chains were introduced in Shorewall-perl 4.0.6; for Perl
programmers, manual chains provide an alternative to Actions with
extension scripts. Manual chains are chains which you create and populate
yourself using the low-level functions in Shorewall::Chains.</para>
<para>For Perl programmers, manual chains provide an alternative to
Actions with extension scripts. Manual chains are chains which you create
and populate yourself using the low-level functions in
Shorewall::Chains.</para>
<para>Manual chains work in conjunction with the
<firstterm>compile</firstterm> <ulink

241
docs/Modularization.xml
View File

@ -1,241 +0,0 @@
<?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 Modularization</title>
<authorgroup>
<author>
<firstname>Tom</firstname>
<surname>Eastep</surname>
</author>
</authorgroup>
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
<copyright>
<year>2006</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>One of the major changes in Shorewall version 3.4 involved breaking
much of the code into <firstterm>libraries</firstterm>. This
modularization is expected to be used primarily by embedded distributions
that wish to minimize the Shorewall disk and RAM footprint.</para>
<para>Shorewall libraries are Bourne shell source files that contain
nothing but function declarations. Shorewall libraries may be loaded into
a running shell program using the shell's "." operator. The library files
have names which begin with "lib." and are installed in <filename
class="directory">/usr/share/shorewall/</filename>.</para>
<para>Individual libraries are of one of two classes. The first class of
libraries are <firstterm>required libraries</firstterm> which, as their
name implies, must be included in any Shorewall installation. The other
libraries are <firstterm>optional libraries</firstterm> that implement a
particular function. Each optional library may be included or omitted
based on the requirements of the individual installation.</para>
</section>
<section id="Required">
<title>Required Libraries</title>
<para>Shorewall 3.4 includes the following required libraries.</para>
<itemizedlist>
<listitem>
<para>lib.base — includes functions needed by all Shorewall
programs.</para>
</listitem>
<listitem>
<para>lib.cli — includes functions common to both
<filename>/sbin/shorewall</filename> and
<filename>/sbin/shorewall-lite</filename>.</para>
</listitem>
<listitem>
<para>lib.config — contains functions common to both
<filename>/sbin/shorewall</filename> and
<filename>/usr/share/shorewall/firewall</filename>.</para>
</listitem>
</itemizedlist>
<para>lib.base and lib.cli are installed in /usr/share/shorewall-lite/ on
Shorewall Lite systems.</para>
</section>
<section id="Optional">
<title>Optional Libraries</title>
<para>Optional libraries are loaded upon demand based on the user's
configuration.</para>
<para>In Shorewall 3.4, the optional libraries are as follows.</para>
<itemizedlist>
<listitem>
<para>lib.accounting — required if the
<filename>/etc/shorewall/accounting</filename> file is
non-empty.</para>
</listitem>
<listitem>
<para>lib.actions — required if USE_ACTIONS=Yes in
<filename>/etc/shorewall/shorewall.conf</filename>.</para>
</listitem>
<listitem>
<para>lib.dynamiczones — required if DYNAMIC_ZONES=Yes in
<filename>/etc/shorewall/shorewall.conf</filename>.</para>
</listitem>
<listitem>
<para>lib.maclist — required if the maclist option is specified in any
entry in <filename>/etc/shorewall/interfaces</filename> or
<filename>/etc/shorewall/hosts</filename>.</para>
</listitem>
<listitem>
<para>lib.nat — required if the
<filename>/etc/shorewall/masq</filename>,
<filename>/etc/shorewall/nat</filename> or
<filename>/etc/shorewall/netmap</filename> files are non-empty or if
DNAT[-] rules are present in
<filename>/etc/shorewall/rules</filename>.</para>
</listitem>
<listitem>
<para>lib.providers — required if the
<filename>/etc/shorewall/providers</filename> file is
non-empty.</para>
</listitem>
<listitem>
<para>lib.proxyarp — required if the
<filename>/etc/shorewall/proxyarp</filename> file is non-empty or if
the <emphasis role="bold">proxyarp</emphasis> option is specified in
an entry in <filename>/etc/shorewall/interfaces</filename>.</para>
</listitem>
<listitem>
<para>lib.tc — required if the
<filename>/etc/shorewall/tcdevices</filename> or
<filename>/etc/shorewall/tcclasses</filename> file is
non-empty.</para>
</listitem>
<listitem>
<para>lib.tcrules — required if the
<filename>/etc/shorewall/tcrules</filename> file is non-empty.</para>
</listitem>
<listitem>
<para>lib.tunnels — required if the
<firstterm>/etc/shorewall/tunnels</firstterm> file is
non-empty.</para>
</listitem>
</itemizedlist>
<para>As described, many of the libraries are required when one or more
configuration files are non-empty and embedded distribution providers are
encouraged to package each optional library together with its associated
configuration files.</para>
<informaltable>
<tgroup cols="2">
<colspec align="left" />
<tbody>
<row>
<entry><emphasis role="bold">Library</emphasis></entry>
<entry><emphasis role="bold">Files</emphasis></entry>
</row>
<row>
<entry>lib.accounting</entry>
<entry><filename>/etc/shorewall/accounting</filename></entry>
</row>
<row>
<entry>lib.actions</entry>
<entry><filename>/etc/shorewall/actions</filename></entry>
</row>
<row>
<entry>lib.maclist</entry>
<entry><filename>/etc/shorewall/maclist</filename></entry>
</row>
<row>
<entry>lib.nat</entry>
<entry><filename>/etc/shorewall/masq, /etc/shorewall/nat,
/etc/shorewall/netmap</filename></entry>
</row>
<row>
<entry>lib.providers</entry>
<entry><filename>/etc/shorewall/route_rules,
/etc/shorewall/providers</filename></entry>
</row>
<row>
<entry>lib.proxyarp</entry>
<entry><filename>/etc/shorewall/proxyarp</filename></entry>
</row>
<row>
<entry>lib.tc</entry>
<entry><filename>/etc/shorewall/tcclasses,
/etc/shorewall/tcdevices</filename></entry>
</row>
<row>
<entry>lib.tcrules</entry>
<entry><filename>/etc/shorewall/tcrules</filename></entry>
</row>
<row>
<entry>lib.tunnels</entry>
<entry><filename>/etc/shorewall/tunnels</filename></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>Note that in Shorewall 4, the optional libraries (with the exception
of <filename>lib.dynamiczones</filename>) are included in the
Shorewall-shell package while the required libraries and
<filename>lib.dynamiczones</filename> are included in the Shorewall-common
package.</para>
</section>
</article>

92
docs/MultiISP.xml
View File

@ -43,9 +43,9 @@
</articleinfo>
<warning>
<para>This document describes the Multi-ISP facility in Shorewall 4.0 and
later. If you are running an earlier release, please see the documentation
for that release.</para>
<para>This document describes the Multi-ISP facility in Shorewall 4.3.5
and later. If you are running an earlier release, please see the
documentation for that release.</para>
</warning>
<warning>
@ -76,14 +76,13 @@
<section id="Support">
<title>Multiple Internet Connection Support</title>
<para>Beginning with Shorewall 2.3.2, limited support is included for
multiple Internet connections. Limitations of this support are as
follows:</para>
<para>Shorewall includes limited support for multiple Internet
connections. Limitations of this support are as follows:</para>
<itemizedlist>
<listitem>
<para>It utilizes static routing configuration. As such, there is no
provision for reacting to the failure of any of the uplinks.</para>
<para>It utilizes static routing configuration. If there is a change
in the routing topopogy, Shorewall must be restarted.</para>
</listitem>
<listitem>
@ -94,13 +93,6 @@
filter should have no effect on routing.</para>
</listitem>
<listitem>
<para>Prior to Shorewall 3.4.0, the routes and route rules added by
this support were not completely removed during <command>shorewall
stop</command>, <command>shorewall clear</command> or
<command>shorewall restart</command>.</para>
</listitem>
<listitem>
<para>For most routing applications, <ulink
url="http://www.quagga.net/">Quagga</ulink> is a better solution
@ -226,8 +218,7 @@
value and will restore the packet mark in the PREROUTING CHAIN.
Mark values must be in the range 1-255.</para>
<para>Beginning with Shorewall version 3.2.0 Beta 6, you may use
may set HIGH_ROUTE_MARKS=Yes in
<para>Alternatively, you may set HIGH_ROUTE_MARKS=Yes in
<filename>/etc/shorewall/shorewall.conf</filename>. This allows
you to:</para>
@ -417,7 +408,7 @@
</varlistentry>
<varlistentry>
<term>optional (added in Shorewall 3.2.2)</term>
<term>optional</term>
<listitem>
<para>Shorewall will determine of this interface is up and
@ -432,8 +423,7 @@
without error doesn't mean that traffic can actually be
sent through the interface.</para>
<para>Beginning with Shorewall-perl 4.0.3, you can supply
an 'isusable' <ulink
<para>You can supply an 'isusable' <ulink
url="shorewall_extension_scripts.htm">extension
script</ulink> to extend Shorewall's interface state
detection.</para>
@ -442,8 +432,7 @@
</varlistentry>
<varlistentry>
<term>src=<replaceable>source-address</replaceable> (Added in
Shorewall-perl 4.1.5)</term>
<term>src=<replaceable>source-address</replaceable></term>
<listitem>
<para>Specifies the source address to use when routing to
@ -457,8 +446,7 @@
</varlistentry>
<varlistentry>
<term>mtu=<replaceable>number</replaceable> (Added in
Shorewall-perl 4.1.5)</term>
<term>mtu=<replaceable>number</replaceable></term>
<listitem>
<para>Specifies the MTU when forwarding through this
@ -469,8 +457,7 @@
<varlistentry>
<term><emphasis
role="bold">fallback[=<replaceable>weight</replaceable>]
(Added in Shorewall-perl 4.2.5)</emphasis></term>
role="bold">fallback[=<replaceable>weight</replaceable>]</emphasis></term>
<listitem>
<para>Indicates that a default route through the provider
@ -764,10 +751,7 @@ eth1 eth2 130.252.99.27</programlisting>
<para>Now suppose that you want to route all outgoing SMTP traffic from
your local network through ISP 2. You would make this entry in <ulink
url="traffic_shaping.htm">/etc/shorewall/tcrules</ulink> (and if you are
running a version of Shorewall earlier than 3.0.0, you would set
TC_ENABLED=Yes in <ulink
url="???">/etc/shorewall/shorewall.conf</ulink>).</para>
url="traffic_shaping.htm">/etc/shorewall/tcrules</ulink> </para>
<programlisting>#MARK SOURCE DEST PROTO PORT(S) CLIENT USER TEST
# PORT(S)
@ -863,12 +847,11 @@ eth3 eth2 16.105.78.4</programlisting></para>
<section id="route_rules">
<title>/etc/shorewall/route_rules</title>
<para>The <filename>/etc/shorewall/route_rules</filename> file was added
in Shorewall version 3.2.0. The <filename>route_rules</filename> file
allows assigning certain traffic to a particular provider just as
entries in the <filename>tcrules</filename> file. The difference between
the two files is that entries in <filename>route_rules</filename> are
independent of Netfilter.</para>
<para>The <filename>route_rules</filename> file allows assigning certain
traffic to a particular provider just as entries in the
<filename>tcrules</filename> file. The difference between the two files
is that entries in <filename>route_rules</filename> are independent of
Netfilter.</para>
<section id="Routing_rules">
<title>Routing Rules</title>
@ -995,8 +978,7 @@ gateway:~ #</programlisting>Note that because we used a priority of 1000, the
<section id="USE_DEFAULT_RT">
<title>USE_DEFAULT_RT</title>
<para>Beginning with Shorewall 4.2.0 Beta3, Shorewall-perl has supported
a USE_DEFAULT_RT option in <ulink
<para>USE_DEFAULT_RT is an option in <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5).</para>
<para>One of the drawbacks of the Multi-ISP support as described in the
@ -1041,10 +1023,9 @@ gateway:~ #</programlisting>Note that because we used a priority of 1000, the
<para>All provider gateways must be specified explicitly in the
GATEWAY column. 'detect' may not be specified. Note that for ppp
interfaces, the GATEWAY may remain unspecified ("-").<note>
<para>Beginning with Shorewall 4.2.6, 'detect' may be specified
for interfaces whose configuration is managed by dhcpcd.
Shorewall will use dhcpcd's database to determine the gateway IP
address.</para>
<para>'detect' may be specified for interfaces whose
configuration is managed by dhcpcd. Shorewall will use dhcpcd's
database to determine the gateway IP address.</para>
</note></para>
</listitem>
@ -1084,19 +1065,15 @@ shorewall 2 2 - eth0 192.168.1.254 track,balance=2,optional<
<section id="swping">
<title>SWPING</title>
<para>Beginning with Shorewall 4.2.6, Shorewall includes a sample
monitoring script <filename>swping</filename>. The
<filename>swping</filename> file is available in the main directory
contained in the Shorewall-common tarball and is included in the
Shorewall-common documentation directory on the Shorewall-common RPM.
The script is inspired by Angsuman Chakraborty's <ulink
<para>Shorewall includes a sample monitoring script
<filename>swping</filename>. The <filename>swping</filename> file is
available in the main directory contained in the Shorewall-common
tarball and is included in the Shorewall-common documentation
directory on the Shorewall-common RPM. The script is inspired by
Angsuman Chakraborty's <ulink
url="http://blog.taragana.com/index.php/archive/how-to-load-balancing-failover-with-dual-multi-wan-adsl-cable-connections-on-linux/">gwping</ulink>
script.</para>
<para>For those not on 4.2.6 yet, the script may be downloaded from
<ulink
url="http://www.shorewall.net/pub/shorewall/contrib/MultiISP-failover/">http://www.shorewall.net/pub/shorewall/contrib/MultiISP-failover/</ulink>.</para>
<important>
<para>These samples are offered <emphasis>as is</emphasis> — they
work for me but I don't make any claim that they will work for
@ -1411,8 +1388,7 @@ exit 0;
<section id="Shared">
<title>Two Providers Sharing an Interface</title>
<para>Shared interface support is available only in Shorewall-perl 4.2.0
and later.</para>
<para>Shared interface support has the following characteristics"</para>
<orderedlist numeration="loweralpha">
<listitem>
@ -1685,10 +1661,10 @@ wlan0 192.168.0.0/24</programlisting><note>
<programlisting>ROUTE_FILTER=No
RESTORE_DEFAULT_ROUTE=No</programlisting>
<para>The RESTORE_DEFAULT_ROUTE option was added in Shorewall-perl 4.2.6
and causes the default route in the main table to be deleted when the
Comcast link is unavailable. That way, the default route in the default
table will be used until Comcast is available again.</para>
<para>RESTORE_DEFAULT_ROUTE=No causes the default route in the main table
to be deleted when the Comcast link is unavailable. That way, the default
route in the default table will be used until Comcast is available
again.</para>
<para><filename>/etc/shorewall/providers</filename>:</para>

4
docs/Multiple_Zones.xml
View File

@ -35,9 +35,9 @@
</articleinfo>
<caution>
<para><emphasis role="bold">This article applies to Shorewall 3.0 and
<para><emphasis role="bold">This article applies to Shorewall 4.3 and
later. If you are running a version of Shorewall earlier than Shorewall
3.0.0 then please see the documentation for that
4.3.5 then please see the documentation for that
release.</emphasis></para>
</caution>

11
docs/NAT.xml
View File

@ -35,9 +35,9 @@
</articleinfo>
<caution>
<para><emphasis role="bold">This article applies to Shorewall 3.0 and
<para><emphasis role="bold">This article applies to Shorewall 4.3 and
later. If you are running a version of Shorewall earlier than Shorewall
3.0.0 then please see the documentation for that
4.3.5 then please see the documentation for that
release.</emphasis></para>
</caution>
@ -48,7 +48,8 @@
<para><emphasis role="bold">If all you want to do is forward ports to
servers behind your firewall, you do NOT want to use one-to-one NAT.
Port forwarding can be accomplished with simple entries in the <ulink
url="manpages/shorewall-rules.html">rules file</ulink>.</emphasis></para>
url="manpages/shorewall-rules.html">rules
file</ulink>.</emphasis></para>
</important>
<para>One-to-one NAT is a way to make systems behind a firewall and
@ -114,8 +115,8 @@
<quote>yes</quote> or <quote>Yes</quote> (and the ALL INTERFACES COLUMN
also contains <quote>Yes</quote> or <quote>yes</quote>) then such
packets are redirected; otherwise, such packets are not redirected. This
feature requires kernel 2.4.19 or later and iptables 1.2.6a or later and
you must have enabled CONFIG_IP_NF_NAT_LOCAL in your kernel.</para>
feature requires that you enabled CONFIG_IP_NF_NAT_LOCAL in your
kernel.</para>
</note>
<para>Entries in <filename>/etc/shorewall/nat</filename> only arrange for

22
docs/PortKnocking.xml
View File

@ -89,20 +89,7 @@
<listitem>
<para>Create /etc/shorewall/SSHKnock with the following
contents.</para>
<para>If using Shorewall-shell:</para>
<programlisting>if [ -n "$LEVEL" ]; then
log_rule_limit $LEVEL $CHAIN SSHKnock ACCEPT "" "$TAG" -A -p tcp --dport 22 -m recent --rcheck --name SSH
log_rule_limit $LEVEL $CHAIN SSHKnock DROP "" "$TAG" -A -p tcp --dport ! 22
fi
run_iptables -A $CHAIN -p tcp --dport 22 -m recent --rcheck --seconds 60 --name SSH -j ACCEPT
run_iptables -A $CHAIN -p tcp --dport 1599 -m recent --name SSH --remove -j DROP
run_iptables -A $CHAIN -p tcp --dport 1600 -m recent --name SSH --set -j DROP
run_iptables -A $CHAIN -p tcp --dport 1601 -m recent --name SSH --remove -j DROP</programlisting>
<para>If using Shorewall-perl:<programlisting>use Shorewall::Chains;
contents.<programlisting>use Shorewall::Chains;
if ( $level ) {
log_rule_limit( $level,
@ -148,10 +135,9 @@ SSHKnock:info net $FW tcp 22,1599,1600,1601<
</listitem>
<listitem>
<para>If you wish to use SSHKnock with a forwarded connection, you
must be using Shorewall 2.3.1 or later for fullest protection. Assume
that you forward port 22 from external IP address 206.124.146.178 to
internal system 192.168.1.5. In /etc/shorewall/rules:</para>
<para>Assume that you forward port 22 from external IP address
206.124.146.178 to internal system 192.168.1.5. In
/etc/shorewall/rules:</para>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S) SOURCE ORIGINAL
# PORT(S) DEST

212
docs/ScalabilityAndPerformance.xml
View File

@ -1,212 +0,0 @@
<?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>Scalability and Performance</title>
<authorgroup>
<author>
<firstname>Tom</firstname>
<surname>Eastep</surname>
</author>
</authorgroup>
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
<copyright>
<year>2006</year>
<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>The performance of the <emphasis role="bold">shorewall
start</emphasis> and <emphasis role="bold">shorewall restart</emphasis>
commands when using Shorewall-shell is a frequent topic of questions. This
article attempts to explain the scalability issues involved and to offer
some tips for reducing the time required to compile a Shorewall
configuration and to execute the compiled script.</para>
<para>Ultimately, the solution to these performance problems is to migrate
to the use of Shorewall-perl if at all possible.</para>
</section>
<section id="Groups">
<title>Host Groups</title>
<para>In this article, we will use the term <firstterm>host
group</firstterm> to refer to a set of IP addresses accessed through a
particular interface. In a Shorewall configuration, there is one host
group for:</para>
<itemizedlist>
<listitem>
<para>Each entry in <filename>/etc/shorewall/interfaces</filename>
that contains the name of a zone in the first column.</para>
</listitem>
<listitem>
<para>Each entry in <filename>/etc/shorewall/hosts</filename>.</para>
</listitem>
</itemizedlist>
<para>As you can see, each host group is associated with a single
<firstterm>zone</firstterm>.</para>
</section>
<section id="GroupScale">
<title>Scaling by Host Groups</title>
<para>For each host group, it is possible to attempt connections to every
other host group; and if the host group has the <emphasis
role="bold">routeback</emphasis> option, then it is possible for
connections to be attempted from the host group to itself. So if there are
<emphasis role="bold">H</emphasis> host groups defined in a Shorewall
configuration, then the number of unique pairs of (<emphasis>source host
group</emphasis>, <emphasis>destination host group</emphasis>) is
<emphasis role="bold">H</emphasis>*<emphasis role="bold">H</emphasis> or
<emphasis role="bold">H</emphasis><superscript>2</superscript>. In other
words, the number of combinations is the square of the number of host
groups and increasing the number of groups from <emphasis
role="bold">H</emphasis> to <emphasis role="bold">H</emphasis>+1 adds
<emphasis role="bold">H</emphasis> + <emphasis role="bold">H</emphasis> +
1 = 2<emphasis role="bold">H</emphasis> + 1 additional
combinations.</para>
</section>
<section id="ZoneScale">
<title>Scaling by Zones</title>
<para>A similar scaling issue applies to Shorewall zones. If there are
<emphasis role="bold">Z</emphasis> zones, then connections may be
attempted from a given zone <emphasis
role="bold">Z</emphasis><subscript>n</subscript> to all of the other zones
(including to <emphasis role="bold">Z</emphasis><subscript>n</subscript>
itself). Hence, the number of combinations is the square of the number of
zones or <emphasis
role="bold">Z</emphasis><superscript>2</superscript>.</para>
</section>
<section id="Shorewall">
<title>Scaling within the Shorewall Code</title>
<para>Shorewall-shell is written entirely in Bourne Shell. While this
allows Shorewall to run on a wide range of distributions (included
embedded ones), the shell programming environment is not ideal for writing
the compiler portion of Shorewall. As a consequence, the code must
repeatedly perform sequential searches of lists. If a list has <emphasis
role="bold">N</emphasis> elements and a sequential search is made for each
of those elements, then the number of comparisons is 1 + 2 + 3 + .... +
<emphasis role="bold">N</emphasis> = <emphasis role="bold">N</emphasis> *
(<emphasis role="bold">N</emphasis> + 1 ) / 2. So again, we see order
<emphasis role="bold">N</emphasis><superscript>2</superscript>
scaling.</para>
</section>
<section id="Improving">
<title>Improving Performance</title>
<para>Achieving good performance boils down to three things:</para>
<itemizedlist>
<listitem>
<para>Use a light-weight shell and fast hardware. Especially in the
compiler, a light-weight shell such as <command>ash</command> or
<command>dash</command> can provide considerable improvement over
<command>bash</command>.</para>
</listitem>
<listitem>
<para>With all of the order <emphasis
role="bold">N</emphasis><superscript>2</superscript> scaling that is
implicit in the problem being solved, it is vital to keep <emphasis
role="bold">N</emphasis> small.</para>
<itemizedlist>
<listitem>
<para>If you have a large number of interfaces, use wild-cards
("+") in <filename>/etc/shorewall/interfaces</filename> and
<filename>/etc/shorewall/hosts</filename> to reduce the number of
host groups.</para>
</listitem>
<listitem>
<para>Combine host groups with similar firewall requirements into
a single zone.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>Use NONE policies wherever appropriate. This helps especially in
the rules activation phase of both script compilation and
execution.</para>
</listitem>
</itemizedlist>
<para>So while it is tempting to create lots of zones through entries in
<filename>/etc/shorewall/hosts</filename>, such configurations
<emphasis>always</emphasis> perform badly. In these cases, it is much
better to have more rules than more zones because the performance scales
linearly with the number of rules whereas it scales geometrically with the
number of zones.</para>
<para>Another tip worth noting has to do with the use of shell
variables.</para>
<para>Suppose that the following appears in
<filename>/etc/shorewall/params</filename>:</para>
<programlisting>HOSTS=&lt;ip1&gt;,&lt;ip2&gt;,&lt;ip3&gt;,...&lt;ipN&gt;</programlisting>
<para>and suppose that $HOSTS appears in the SOURCE column of <emphasis
role="bold">M</emphasis> ACCEPT rules. That would generate a total of
<emphasis role="bold">N</emphasis> * <emphasis role="bold">M</emphasis>
iptables ACCEPT rules.</para>
<para>The number of rules can be reduced significantly by using an <ulink
url="Actions.html">action</ulink>. Consider the following:</para>
<blockquote>
<para><filename>/etc/shorewall/actions</filename>:</para>
<programlisting>AcceptHosts</programlisting>
<para><filename>/etc/shorewall/action.AcceptHosts</filename>:</para>
<programlisting>#TARGET SOURCE DEST PROTO DEST SOURCE ORIGINAL RATE
# PORT PORT(S) DEST LIMIT
ACCEPT $HOSTS </programlisting>
</blockquote>
<para>If the <emphasis role="bold">M</emphasis> ACCEPT rules are now
replaced with <emphasis role="bold">M</emphasis> AcceptHosts rules, the
total number of rules will be <emphasis role="bold">N</emphasis> +
<emphasis role="bold">M</emphasis>.</para>
<para>Example (Accept net-&gt;fw SSH from $HOSTS):</para>
<programlisting>#ACTION SOURCE DEST PROTO DEST SOURCE ORIGINAL RATE USER/
# PORT PORT(S) DEST LIMIT GROUP
AcceptHosts net $FW tcp 22 </programlisting>
</section>
</article>

238
docs/Shorewall-4.xml
View File

@ -1,238 +0,0 @@
<?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 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>
<listitem>
<para>supports creating either Ipv4 or Ipv6 firewalls (Shorewall 4.2.4
and later).</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 six packages:</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.</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, 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).
<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 (Shorewall
4.0.3 and later)</para>
</listitem>
<listitem>
<para>Perl <emphasis role="bold">Scalar::Util </emphasis>Module
(Shorewall 4.0.6 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="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 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>
</article>

142
docs/Shorewall-perl.xml
View File

@ -20,6 +20,8 @@
<copyright>
<year>2007</year>
<year>2009</year>
<holder>Thomas M. Eastep</holder>
</copyright>
@ -37,43 +39,47 @@
<section id="What">
<title>Shorewall-perl - What is it?</title>
<para>Shorewall-perl is a companion product to Shorewall.</para>
<para>Shorewall-perl was released as a companion product to Shorewall in
Shorewall 4.0.0.</para>
<para>Shorewall-perl contains a re-implementation of the Shorewall
<para>Shorewall-perl contained a re-implementation of the Shorewall
compiler written in Perl. The advantages of using Shorewall-perl over
Shorewall-shell (the shell-based compiler included in earlier Shorewall
3.x releases) are:</para>
3.x releases) were:</para>
<itemizedlist>
<listitem>
<para>The Shorewall-perl compiler is much faster.</para>
<para>The Shorewall-perl compiler was much faster.</para>
</listitem>
<listitem>
<para>The script generated by the compiler uses
<para>The script generated by the compiler used
<command>iptables-restore</command> to instantiate the Netfilter
configuration. So it runs much faster than the script generated by the
Shorewall-shell compiler and doesn't stop new connections during
configuration. So it ran much faster than the script generated by the
Shorewall-shell compiler and did not stop new connections during
<command>shorewall restart</command>.</para>
</listitem>
<listitem>
<para>The Shorewall-perl compiler does more thorough checking of the
configuration than the Shorewall-shell compiler does.</para>
<para>The Shorewall-perl compiler did more thorough checking of the
configuration than the Shorewall-shell compiler did.</para>
</listitem>
<listitem>
<para>The error messages produced by the compiler are better, more
consistent and always include the file name and line number where the
<para>The error messages produced by the compiler were better, more
consistent and always included the file name and line number where the
error was detected.</para>
</listitem>
<listitem>
<para>Going forward, the Shorewall-perl compiler will get all
enhancements; the Shorewall-shell compiler will only get those
enhancements that are easy to retrofit.</para>
<para>Going forward, the Shorewall-perl compiler got all enhancements;
the Shorewall-shell compilerl only got those enhancements that were
easy to retrofit.</para>
</listitem>
</itemizedlist>
<para>Beginning with Shorewall 4.3.5, Shorewall-perl is an integral part
of Shorewall and support for Shorewall-shell has been discontinued.</para>
</section>
<section id="DownSide">
@ -555,112 +561,14 @@ DNAT- net 192.168.1.3 tcp 21</programl
<section id="PerlDep">
<title>Dependence on Perl</title>
<para>Shorewall-perl is dependent on Perl (see the next section) which
has a large disk footprint. This makes Shorewall-perl less desirable in
an embedded 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.</para>
<para>Shorewall-perl is dependent on Perl which has a large disk
footprint. This makes Shorewall-perl less desirable in an embedded
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.</para>
</section>
</section>
<section id="Prerequisites">
<title>Shorewall-perl - Prerequisites</title>
<itemizedlist>
<listitem>
<para>Perl (I use Perl 5.8.8 but other 5.8 or later versions should
work fine)</para>
<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 Socket6 module.</para>
</note>
</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>
<listitem>
<para>Perl Scalar::Util Module (Shorewall 4.0.6 and later)</para>
</listitem>
</itemizedlist>
</section>
<section id="Install">
<title>Shorewall-perl - Installation</title>
<para>Either</para>
<programlisting><command>tar -jxf shorewall-perl-4.0.x.tar.bz2</command>
<command>cd shorewall-perl-4.0.x</command>
<command>./install.sh</command></programlisting>
<para>or</para>
<programlisting><command>rpm -ivh shorewall-perl-4.0.x.noarch.rpm</command></programlisting>
</section>
<section id="Using">
<title>Using Shorewall-perl</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>. The value of this 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 may also 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 twice, the second time 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>
<section id="Modules">
<title>The Shorewall Perl Modules</title>

26
docs/Shorewall_and_Aliased_Interfaces.xml
View File

@ -18,7 +18,7 @@
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
<copyright>
<year>2001-2007</year>
<year>2001-2009</year>
<holder>Thomas M. Eastep</holder>
</copyright>
@ -35,9 +35,9 @@
</articleinfo>
<caution>
<para><emphasis role="bold">This article applies to Shorewall 3.0 and
<para><emphasis role="bold">This article applies to Shorewall 4.3 and
later. If you are running a version of Shorewall earlier than Shorewall
3.0.0 then please see the documentation for that
4.3.5 then please see the documentation for that
release.</emphasis></para>
</caution>
@ -198,11 +198,10 @@ eth0 eth1 206.124.146.178</programlisting>
connections using those addresses may be severed.</para>
</warning>
<para>Beginning with Shorewall 1.3.14, Shorewall can actually create the
<quote>label</quote> (virtual interface) so that you can see the created
address using ifconfig. In addition to setting ADD_SNAT_ALIASES=Yes, you
specify the virtual interface name in the INTERFACE column as
follows.</para>
<para>Shorewall can create the <quote>label</quote> (virtual interface)
so that you can see the created address using ifconfig. In addition to
setting ADD_SNAT_ALIASES=Yes, you specify the virtual interface name in
the INTERFACE column as follows.</para>
<para><filename>/etc/shorewall/masq</filename><programlisting>#INTERFACE SUBNET ADDRESS
eth0:0 eth1 206.124.146.178</programlisting></para>
@ -243,11 +242,10 @@ eth0:2 = 206.124.146.180</programlisting>
connections using those addresses may be severed.</para>
</warning>
<para>Beginning with Shorewall 1.3.14, Shorewall can actually create the
<quote>label</quote> (virtual interface) so that you can see the created
address using ifconfig. In addition to setting ADD_IP_ALIASES=Yes, you
specify the virtual interface name in the INTERFACE column as
follows.</para>
<para>Shorewall can create the <quote>label</quote> (virtual interface)
so that you can see the created address using ifconfig. In addition to
setting ADD_IP_ALIASES=Yes, you specify the virtual interface name in
the INTERFACE column as follows.</para>
<para><filename>/etc/shorewall/nat</filename><programlisting>#EXTERNAL INTERFACE INTERNAL ALL INTERFACES LOCAL
206.124.146.178 eth0:0 192.168.1.3 no no</programlisting></para>
@ -284,8 +282,6 @@ ACCEPT net loc:192.168.1.3 tcp 22</programlisting></para>
eth1:0 is 192.168.20.254. You simply want your firewall to route
between these two subnetworks.</title>
<para>This example applies to Shorewall 1.4.2 and later.</para>
<para>In <filename>/etc/shorewall/zones</filename>:</para>
<programlisting>#ZONE TYPE OPTIONS

4
docs/UPnP.xml
View File

@ -37,8 +37,8 @@
<section id="UPnP">
<title>UPnP</title>
<para>In Shorewall 2.2.4, support was added for UPnP (Universal Plug and
Play) using linux-igd (<ulink
<para>Shorewall includes support for UPnP (Universal Plug and Play) using
linux-igd (<ulink
url="http://linux-igd.sourceforge.net">http://linux-igd.sourceforge.net</ulink>).
UPnP is required by a number of popular applications including MSN
IM.</para>

11
docs/blacklisting_support.xml
View File

@ -43,9 +43,9 @@
<orderedlist>
<listitem>
<para>BLACKLISTNEWONLY=No -- All incoming packets are checked
against the blacklist. New blacklist entries can be used to terminate
existing connections.</para>
<para>BLACKLISTNEWONLY=No -- All incoming packets are checked against
the blacklist. New blacklist entries can be used to terminate existing
connections.</para>
</listitem>
<listitem>
@ -189,12 +189,7 @@ ipset -B Blacklist 206.124.146.177 -b SMTP</programlisting>
<para>show dynamic - displays the dynamic blacklisting
configuration.</para>
</listitem>
</itemizedlist>
<para>If you are running Shorewall 3.2.0 Beta2 or later, there are two
additional commands:</para>
<itemizedlist>
<listitem>
<para>logdrop <emphasis>&lt;ip address list&gt;</emphasis> - causes
packets from the listed IP addresses to be dropped and logged by the

8
docs/bridge-Shorewall-perl.xml
View File

@ -20,6 +20,8 @@
<copyright>
<year>2007</year>
<year>2009</year>
<holder>Thomas M. Eastep</holder>
</copyright>
@ -35,10 +37,8 @@
</articleinfo>
<caution>
<para><emphasis role="bold">This article applies to Shorewall-perl 4.0 and
later. If you are running a version of Shorewall earlier than Shorewall
4.0.0-Beta4 or you are not running Shorewall-perl then please see <ulink
url="3.0/NewBridge.html">this article</ulink>.</emphasis></para>
<para><emphasis role="bold">This article applies to Shorewall-perl 4.3 and
later.</emphasis></para>
</caution>
<section id="Background">

157
docs/configuration_file_basics.xml
View File

@ -35,10 +35,9 @@
</articleinfo>
<caution>
<para><emphasis role="bold">This article applies to Shorewall 3.0 and
<para><emphasis role="bold">This article applies to Shorewall 4.3 and
later. If you are running a version of Shorewall earlier than Shorewall
3.0.0 then please see the documentation for that
release.</emphasis></para>
4.3.5then please see the documentation for that release.</emphasis></para>
</caution>
<caution>
@ -183,17 +182,16 @@
</listitem>
<listitem>
<para><filename>/etc/shorewall/route_rules</filename> (Added in
Shorewall 3.2.0) - Defines routing rules to be used in conjunction
with the routing tables defined in
<filename>/etc/shorewall/providers</filename>.</para>
<para><filename>/etc/shorewall/route_rules</filename> - Defines
routing rules to be used in conjunction with the routing tables
defined in <filename>/etc/shorewall/providers</filename>.</para>
</listitem>
<listitem>
<para><filename>/etc/shorewall/tcdevices</filename>,
<filename>/etc/shorewall/tcclasses</filename>,
<filename>/etc/shorewall/tcfilters</filename> (tcfilters added in
Shorewall 4.2.0) - Define traffic shaping.</para>
<filename>/etc/shorewall/tcfilters</filename> - Define traffic
shaping.</para>
</listitem>
<listitem>
@ -202,9 +200,8 @@
</listitem>
<listitem>
<para><filename>/etc/shorewall/vardir</filename> - (Added in
Shorewall 4.0.0-RC2) - Determines the directory where Shorewall
maintains its state.</para>
<para><filename>/etc/shorewall/vardir</filename> - Determines the
directory where Shorewall maintains its state.</para>
</listitem>
<listitem>
@ -236,9 +233,9 @@
<section id="Manpages">
<title>Man Pages</title>
<para>Beginning with Shorewall version 3.4, man pages are provided in
section 5 for each of the Shorewall configuration files. The name of the
page is formed by prefixing the file name with "shorewall-".</para>
<para>Man pages are provided in section 5 for each of the Shorewall
configuration files. The name of the page is formed by prefixing the file
name with "shorewall-".</para>
<para>Example — To view the manual page for
<filename>/etc/shorewall/interfaces</filename>:</para>
@ -270,10 +267,10 @@ ACCEPT net $FW tcp www #This is an end-of-line comment</progra
<section id="COMMENT">
<title>Attach Comment to Netfilter Rules</title>
<para>Beginning with Shorewall version 3.3.3, if you kernel and iptables
contain comment match support (see the output of <command>shorewall show
capabilities</command>), then you can attach comments to Netfilter rules.
This feature is available in the following files:</para>
<para>If you kernel and iptables contain comment match support (see the
output of <command>shorewall show capabilities</command>), then you can
attach comments to Netfilter rules. This feature is available in the
following files:</para>
<itemizedlist>
<listitem>
@ -298,9 +295,7 @@ ACCEPT net $FW tcp www #This is an end-of-line comment</progra
</listitem>
<listitem>
<para>Macro definition files (/etc/shorewall/macro.*) — Added in
Shorewall-perl 4.2.0. They are ignored by Shorewall-shell 4.1 and
later.</para>
<para>Macro definition files (/etc/shorewall/macro.*)</para>
</listitem>
</itemizedlist>
@ -330,7 +325,7 @@ COMMENT</programlisting>
<filename>/sbin/shorewall-lite</filename>:</para>
<programlisting>gateway:~ # <command>shorewall-lite show loc2net</command>
Shorewall Lite 3.3.3 Chains loc2net at gateway - Mon Oct 16 15:04:52 PDT 2006
Shorewall Lite 4.3.3 Chains loc2net at gateway - Mon Oct 16 15:04:52 PDT 2008
Counters reset Mon Oct 16 14:52:17 PDT 2006
@ -411,16 +406,16 @@ smtp,www,pop3,imap #Services running on the firewall</programlisting>
<caution>
<para>If you are using <ulink
url="CompiledPrograms.html%23Lite">Shorewall Lite</ulink> and are
running a version of Shorewall earlier than 3.2.9, it is not advisable
to use INCLUDE in the <filename>params</filename> file in an export
directory. If you do that, you must ensure that the included file is
also present on the firewall system's <filename
url="CompiledPrograms.html%23Lite">Shorewall Lite</ulink> , it is not
advisable to use INCLUDE in the <filename>params</filename> file in an
export directory. If you do that, you must ensure that the included file
is also present on the firewall system's <filename
class="directory">/etc/shorewall-lite/</filename> directory.</para>
<para>Beginning with Shorewall version 3.2.9 (3.4.0 RC2), you can set
EXPORTPARAMS=No in <filename>shorewall.conf</filename>. That prevents
the <filename>params</filename> file from being copied into the compiled
<para>If you only need the <filename>params</filename> file at compile
time, you can set EXPORTPARAMS=No in
<filename>shorewall.conf</filename>. That prevents the
<filename>params</filename> file from being copied into the compiled
script. With EXPORTPARAMS=No, it is perfectly okay to use INCLUDE in the
<filename>params</filename> file.</para>
</caution>
@ -470,9 +465,8 @@ smtp,www,pop3,imap #Services running on the firewall</programlisting>
   ----- end rules -----</programlisting>
<para>Users of Shorewall-perl 4.0.6 and later may include multiple files
in one command using an <link linkend="Embedded">embedded shell
command</link>.</para>
<para>You may include multiple files in one command using an <link
linkend="Embedded">embedded shell command</link>.</para>
<para>Example (include all of the files ending in ".rules" in a
directory:):<programlisting>gateway:/etc/shorewall # ls rules.d
@ -516,9 +510,9 @@ SHELL cat /etc/shorewall/rules.d/*.rules</programlisting></para>
<para>Variables may be used anywhere in the other configuration
files.<note>
<para>Shorewall-perl users: If you use "$FW" on the right side of
assignments in the <filename>/etc/shorewall/params</filename> file,
you must also set the FW variable in that file.</para>
<para>If you use "$FW" on the right side of assignments in the
<filename>/etc/shorewall/params</filename> file, you must also set the
FW variable in that file.</para>
<para>Example:<programlisting>/etc/shorewall/zones:
@ -587,35 +581,22 @@ SHELL cat /etc/shorewall/rules.d/*.rules</programlisting></para>
</listitem>
</orderedlist>
<para>When expanding a variable, the acceptable forms of expansion depend
on whether you are using Shorewall-shell or Shorewall-perl.</para>
<itemizedlist>
<listitem>
<para>Shorewall-shell and all Shorewall versions prior to 4.0 can use
any form of expansion supported by the shell ($VAR, ${VAR},
${VAR:=val}, ...).</para>
</listitem>
<listitem>
<para>Shorewall-perl only supports the $VAR and ${VAR} forms.</para>
</listitem>
</itemizedlist>
<note>
<para>Only the $VAR and ${VAR} forms of variable expansion are
supported. You may not use the more exotic forms supported by the shell
($VAR, ${VAR}, ${VAR:=val}, ...)</para>
</note>
</section>
<section id="Embedded">
<title>Embedded Shell and Perl</title>
<para>This feature was added in Shorewall-perl 4.0.6. To use it, you must
be running 4.0.6 or later and must be using Shorewall-perl
(SHOREWALL_COMPILER=perl in shorewall.conf).</para>
<para>Earlier versions of Shorewall offered <ulink
url="shorewall_extension_scripts.htm">extension scripts</ulink> to allow
users to extend Shorewall's functionality. Extension scripts were designed
to work under the limitations of the Bourne Shell. With Shorewall-perl,
<firstterm>Embedded scripts</firstterm> offer a richer and more flexible
extension capability.</para>
to work under the limitations of the Bourne Shell. With the current
Perl-based compiler, <firstterm>Embedded scripts</firstterm> offer a
richer and more flexible extension capability.</para>
<para>While inline scripts scripts may be written in either Shell or Perl,
those written in Perl have a lot more power.</para>
@ -654,7 +635,7 @@ ACCEPT dmz fw tcp 22</programlisting></para>
<programlisting>package Shorewall::User;
use Shorewall::Config qw/shorewall/;</programlisting>
<para>As part of the change that added embedded scripts:</para>
<para>A couple of more points should be mentioned:</para>
<orderedlist>
<listitem>
@ -663,16 +644,17 @@ use Shorewall::Config qw/shorewall/;</programlisting>
</listitem>
<listitem>
<para>A <emphasis role="bold">compile</emphasis> extension script was
added for use by Shorewall-perl. That script is run early in the
compilation process and allows users to load additional modules and to
define data and functions for use in subsequent embedded scripts and
extension scripts.</para>
<para>A <emphasis role="bold">compile</emphasis> extension script is
supported. That script is run early in the compilation process and
allows users to load additional modules and to define data and
functions for use in subsequent embedded scripts and extension
scripts.</para>
</listitem>
<listitem>
<para>A <ulink url="ManualChains.html">Manual Chain</ulink> facility
was added.</para>
<para><ulink url="ManualChains.html">Manual Chains</ulink> may be
added in the <emphasis role="bold">compile</emphasis> extension
script..</para>
</listitem>
</orderedlist>
@ -866,8 +848,7 @@ POP/ACCEPT loc net:pop.gmail.com</programlisting>
<section id="Exclusion">
<title>Exclusion Lists</title>
<para>Shorewall 3.0 differs from earlier versions in that in most contexts
where a comma-separated list of addresses is accepted, an
<para>Where a comma-separated list of addresses is accepted, an
<firstterm>exclusion list</firstterm> may also be included. An exclusion
list is a comma-separated list of addresses that begins with "!".</para>
@ -922,30 +903,13 @@ Shorewall has detected the following iptables/netfilter capabilities:
<filename>/etc/protocols</filename>. Similarly, when giving a port number
you can use either an integer or a service name from
<filename>/etc/services</filename>.<note>
<para>Shorewall-perl translates protocol names to protocol numbers and
service names to port numbers itself.</para>
<para>In Shorewall versions 4.0.0 - 4.0.4, the mapping that it uses is
contained in the Perl module
<filename>/usr/share/shorewall-perl/Shorewall/Ports.pm</filename>.
That module is built when Shorewall is installed or upgraded using the
current <filename>/etc/protocols</filename> and
<filename>/etc/services</filename> files as input (if the build
program fails, a fallback version of the module is installed).</para>
<para>To generate a new Ports.pm module:<programlisting>cp /usr/share/shorewall-perl/Shorewall/Ports.pm /usr/share/shorewall-perl/Shorewall/Ports.pm.backup
/usr/share/shorewall/buildports.pm &gt; /usr/share/shorewall-perl/Shorewall/Ports.pm</programlisting></para>
<para>Beginning with Shorewall version 4.0.5, the
<filename>/usr/share/shorewall-perl/Shorewall/Ports.pm</filename> has
been eliminated and the Shorewall-perl compiler uses Perl's interfaces
to getprotobyname(3posix) and getservbyname(3posix).</para>
<para>The rules compiler translates protocol names to protocol numbers
and service names to port numbers itself.</para>
</note></para>
<para>Also, unless otherwise documented, a protocol number/name can be
preceded by '!' to specify "All protocols except this one" (e.g., "!tcp").
Shorewall-perl support for that feature was added in Shorewall
4.2.6.</para>
preceded by '!' to specify "All protocols except this one" (e.g.,
"!tcp").</para>
</section>
<section id="Ranges">
@ -964,8 +928,7 @@ DNAT net loc:192.168.1.3 tcp 4000:4100</programlisting>
<para>Also, unless otherwise documented, a port range can be preceded by
'!' to specify "All ports except those in this range" (e.g.,
"!4000:4100"). Shorewall-perl support for that feature was added in
Shorewall 4.2.6.</para>
"!4000:4100").</para>
</section>
<section id="Portlists">
@ -995,18 +958,8 @@ DNAT net loc:192.168.1.3 tcp 4000:4100</programlisting>
</listitem>
</orderedlist>
<note>
<para>Shorewall-perl requires <emphasis role="bold">multiport</emphasis>
match in order to accept port lists in Shorewall configuration files. It
further requires Extended <emphasis role="bold">multiport</emphasis>
match in order to accept port ranges in port lists. Shorewall-perl
versions earlier than 4.0.5 will never break a list longer than 15 ports
(with each range counting as two ports) into smaller lists.</para>
</note>
<para>Also, unless otherwise documented, a port list can be preceded by
'!' to specify "All ports except these" (e.g., "!80,443"). Shorewall-perl
support for that feature was added in Shorewall 4.2.6.</para>
'!' to specify "All ports except these" (e.g., "!80,443").</para>
</section>
<section id="MAC">

37
docs/fallback.xml
View File

@ -18,7 +18,7 @@
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
<copyright>
<year>2001-2005</year>
<year>2001-2009</year>
<holder>Thomas M. Eastep</holder>
</copyright>
@ -44,22 +44,13 @@
<itemizedlist>
<listitem>
<para>cd to the distribution directory for the version of Shoreline
Firewall that you are currently running (NOT the version that you want
to fall back to).</para>
Firewall that you want to fall back to.</para>
</listitem>
<listitem>
<para>Type <quote>./fallback.sh</quote></para>
<para>Type <quote>./install.sh</quote></para>
</listitem>
</itemizedlist>
<caution>
<para>The fallback script will replace /etc/shorewall[-lite]/*,
/var/lib/shorewall[-lite]/*, /etc/init.d/shorewall[-lilte]] (or
equivalent), and /sbin/shorewall[-lite] with the version of these files
from before the current version was installed. Any changes to any of
these files made since the installation will be lost.</para>
</caution>
</section>
<section id="RPM">
@ -91,26 +82,4 @@
<para>If you installed using an rpm, at a root shell prompt type
<quote>rpm -e shorewall</quote>.</para>
</section>
<section id="Shell-Perl">
<title>Shorewall-shell and Shorewall-perl</title>
<para>Shorewall-shell and Shorewall-perl have no configuration files and
all of their released files are installed in a single directory. To
fallback to a prior release of one of these products using the tarballs,
simple re-install the older version.</para>
<para>To uninstall these products when they have been installed using the
tarballs:</para>
<itemizedlist>
<listitem>
<para>rm -rf /usr/share/shorewall-shell</para>
</listitem>
<listitem>
<para>rm -rf /usr/share/shorewall-perl</para>
</listitem>
</itemizedlist>
</section>
</article>

123
docs/ipsets.xml
View File

@ -78,7 +78,7 @@
<para>Example: "+Mirrors"</para>
<para>When using Shorewall-perl, the names of ipsets are restricted as
<para>When using Shorewall, the names of ipsets are restricted as
follows:</para>
<itemizedlist>
@ -130,76 +130,21 @@
<para><filename>/etc/shorewall/rules</filename><programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
ACCEPT +sshok $FW tcp 22</programlisting></para>
<para>If you are running Shorewall-shell:</para>
<para>Shorewall is not in the ipset load/reload business because the
Netfilter rule set is never cleared. That means that there is no
opportunity for Shorewall to load/reload your ipsets since that cannot be
done while there are any current rules using ipsets.</para>
<blockquote>
<para>Shorewall can automatically manage the contents of your ipsets for
you. If you specify SAVE_IPSETS=Yes in /etc/shorewall/shorewall.conf
then "shorewall save" will save the contents of your ipsets. The file
where the sets are saved is formed by taking the name where the
Shorewall configuration is stored and appending "-ipsets". So if you
enter the command "shorewall save standard" then Shorewall will save the
file as /var/lib/shorewall/standard-ipsets</para>
<para>So:</para>
<para>Regardless of the setting of SAVE_IPSETS, the <command>shorewall
-f start</command> and <command>shorewall restore</command> commands
will restore the ipset contents corresponding to the Shorewall
configuration restored provided that the saved Shorewall configuration
specified exists.</para>
<orderedlist numeration="upperroman">
<listitem>
<para>Your ipsets must be loaded before Shorewall starts. You are free
to try to do that with the following code in
<filename>/etc/shorewall/init (it works for me; your mileage may
vary)</filename>:</para>
<para>For example, <command>shorewall restore standard</command> would
restore the ipset contents from
<filename>/var/lib/shorewall/standard-ipsets</filename> provided that
<filename>/var/lib/shorewall/standard</filename> exists and is
executable and that
<filename>/var/lib/shorewall/standard-ipsets</filename> exists and is
executable.</para>
<para>Also regardless of the setting of SAVE_IPSETS, the
<command>shorewall forget</command> command will purge the saved ipset
information (if any) associated with the saved shorewall configuration
being removed.</para>
<para>You can also associate ipset contents with Shorewall configuration
directories using the following command:</para>
<programlisting><command>ipset -S &gt; &lt;config directory&gt;/ipsets</command></programlisting>
<para>Example:</para>
<programlisting><command>ipset -S &gt; /etc/shorewall/ipsets</command></programlisting>
<para>When you start or restart Shorewall (including using the
<command>try</command> command) from the configuration directory, your
ipsets will be configured from the saved ipsets file. Once again, this
behavior is independent of the setting of SAVE_IPSETS.</para>
<para>As mentioned above, ipsets are well suited for large blacklists.
You can maintain your blacklist using the 'ipset' utility without ever
having to restart or refresh Shorewall. If you use the SAVE_IPSETS=Yes
feature just be sure to "shorewall save" after altering the blacklist
ipset(s).</para>
</blockquote>
<para>If you are running Shorewall-perl:</para>
<blockquote>
<para>Shorewall is now out of the ipset load/reload business. With
scripts generated by the Perl-based Compiler, the Netfilter rule set is
never cleared. That means that there is no opportunity for Shorewall to
load/reload your ipsets since that cannot be done while there are any
current rules using ipsets.</para>
<para>So:</para>
<orderedlist numeration="upperroman">
<listitem>
<para>Your ipsets must be loaded before Shorewall starts. You are
free to try to do that with the following code in
<filename>/etc/shorewall/init (it works for me; your mileage may
vary)</filename>:</para>
<programlisting>if [ "$COMMAND" = start ]; then
<programlisting>if [ "$COMMAND" = start ]; then
ipset -U :all: :all:
ipset -U :all: :default:
ipset -F
@ -207,32 +152,30 @@ ACCEPT +sshok $FW tcp 22</programlisting></para>
ipset -R &lt; /etc/shorewall/ipsets
fi</programlisting>
<para>The file <filename>/etc/shorewall/ipsets</filename> will
normally be produced using the <command>ipset -S</command>
command.</para>
<para>The file <filename>/etc/shorewall/ipsets</filename> will
normally be produced using the <command>ipset -S</command>
command.</para>
<para>The above will work most of the time but will fail in a
<command>shorewall stop</command> - <command>shorewall
start</command> sequence if you use ipsets in your routestopped file
(see below).</para>
</listitem>
<para>The above will work most of the time but will fail in a
<command>shorewall stop</command> - <command>shorewall start</command>
sequence if you use ipsets in your routestopped file (see
below).</para>
</listitem>
<listitem>
<para>Your ipsets may not be reloaded until Shorewall is stopped or
cleared.</para>
</listitem>
<listitem>
<para>Your ipsets may not be reloaded until Shorewall is stopped or
cleared.</para>
</listitem>
<listitem>
<para>If you specify ipsets in your routestopped file then Shorewall
must be cleared in order to reload your ipsets.</para>
</listitem>
</orderedlist>
<listitem>
<para>If you specify ipsets in your routestopped file then Shorewall
must be cleared in order to reload your ipsets.</para>
</listitem>
</orderedlist>
<para>As a consequence, scripts generated by the Perl-based compiler
will ignore <filename>/etc/shorewall/ipsets</filename> and will issue a
warning if you set SAVE_IPSETS=Yes in
<filename>shorewall.conf</filename>.</para>
</blockquote>
<para>As a consequence, scripts generated by the Perl-based compiler will
ignore <filename>/etc/shorewall/ipsets</filename> and will issue a warning
if you set SAVE_IPSETS=Yes in <filename>shorewall.conf</filename></para>
<para>Example (Note -- this example is applicable to ipset versions up to
and including 2.4. In 2.5, the binding feature of ipsets is scheduled for

188
docs/shorewall_extension_scripts.xml
View File

@ -35,9 +35,10 @@
</articleinfo>
<caution>
<para>This article applies to Shorewall 4.0 and later. If you are running
a version of Shorewall earlier than Shorewall 4.0.0 then please see the
documentation for that release.</para>
<para><emphasis role="bold">This article applies to Shorewall 4.3 and
later. If you are running a version of Shorewall earlier than Shorewall
4.3.5 then please see the documentation for that
release.</emphasis></para>
</caution>
<section id="Scripts">
@ -69,9 +70,8 @@
<itemizedlist>
<listitem>
<para><filename>compile</filename> -- (Added in Shorewall-perl version
4.0.6). Invoked by the Shorewall-perl compiler early in the
compilation process. Must be written in Perl.</para>
<para><filename>compile</filename> -- Invoked by the rules compiler
early in the compilation process. Must be written in Perl.</para>
</listitem>
<listitem>
@ -87,14 +87,12 @@
<listitem>
<para><filename>start</filename> -- invoked after the firewall has
been started or restarted. The script is also invoked by
Shorewall-shell after a successful 'restore'.</para>
been started or restarted.</para>
</listitem>
<listitem>
<para><filename>started</filename> -- invoked after the firewall has
been marked as 'running'. The script is also invoked by
Shorewall-shell after a successful 'restore'.</para>
been marked as 'running'.</para>
</listitem>
<listitem>
@ -147,11 +145,11 @@
</listitem>
<listitem>
<para><filename>isusable</filename> -- (Added in Shorewall-perl
version 4.0.3) invoked when Shorewall is trying to determine the
usability of the network interface associated with an optional entry
in <filename>/etc/shorewall/providers</filename>. $1 is the name of
the interface which will have been determined to be up and configured
<para><filename>isusable</filename> -- invoked when Shorewall is
trying to determine the usability of the network interface associated
with an optional entry in
<filename>/etc/shorewall/providers</filename>. $1 is the name of the
interface which will have been determined to be up and configured
before the script is invoked. The return value from the script
indicates whether or not the interface is usable (0 = usable, other =
unusable).</para>
@ -185,16 +183,14 @@ esac</programlisting><caution>
</listitem>
<listitem>
<para><filename>save</filename> -- (Added in Shorewall version 4.2.0
Beta2). This script is invoked during execution of the
<command>shorewall save</command> and <command>shorewall-lite
save</command> commands.</para>
<para><filename>save</filename> -- This script is invoked during
execution of the <command>shorewall save</command> and
<command>shorewall-lite save</command> commands.</para>
</listitem>
<listitem>
<para><filename>restored</filename> -- (Added in Shorewall-perl
version 4.2.6). This script is invoked at the completion of a
successful <command>shorewall restore</command> and
<para><filename>restored</filename> -- This script is invoked at the
completion of a successful <command>shorewall restore</command> and
<command>shorewall-lite restore</command>.</para>
</listitem>
</itemizedlist>
@ -210,29 +206,23 @@ esac</programlisting><caution>
scripts.</para>
<informaltable frame="none" rowheader="firstcol">
<tgroup cols="3">
<tgroup cols="2">
<tbody>
<row>
<entry><emphasis role="bold">script</emphasis></entry>
<entry><emphasis role="bold">Shorewall-shell</emphasis></entry>
<entry><emphasis role="bold">Shorewall-perl</emphasis></entry>
<entry><emphasis role="bold">Commands</emphasis></entry>
</row>
<row>
<entry>clear</entry>
<entry>clear</entry>
<entry>clear</entry>
</row>
<row>
<entry>compile</entry>
<entry>-</entry>
<entry>check, compile, export, load, refresh, reload, restart,
restore,start</entry>
</row>
@ -240,24 +230,18 @@ esac</programlisting><caution>
<row>
<entry>continue</entry>
<entry>load, refresh, reload, restart, restore, start</entry>
<entry></entry>
</row>
<row>
<entry>init</entry>
<entry>load, refresh, reload, restart, restore, start</entry>
<entry>load, refresh, reload, restart restore, start</entry>
</row>
<row>
<entry>initdone</entry>
<entry>refresh, restart, restore, start</entry>
<entry>check, compile, export, refresh, restart, start</entry>
</row>
@ -265,15 +249,11 @@ esac</programlisting><caution>
<entry>isusable</entry>
<entry>refresh, restart, restore, start</entry>
<entry>refresh, restart, restore, start</entry>
</row>
<row>
<entry>maclog</entry>
<entry>load, refresh, reload, restart, restore, start</entry>
<entry>check, compile, export, refresh, restart, start</entry>
</row>
@ -281,23 +261,17 @@ esac</programlisting><caution>
<entry>refresh</entry>
<entry>refresh</entry>
<entry>refresh</entry>
</row>
<row>
<entry>refreshed</entry>
<entry>refresh</entry>
<entry>refresh</entry>
</row>
<row>
<entry>restored</entry>
<entry>-</entry>
<entry>restore</entry>
</row>
@ -305,23 +279,17 @@ esac</programlisting><caution>
<entry>save</entry>
<entry>save</entry>
<entry>save</entry>
</row>
<row>
<entry>start</entry>
<entry>load, reload, restart, restore, start</entry>
<entry>load, reload, restart, start</entry>
</row>
<row>
<entry>started</entry>
<entry>load, reload, restart, restore, start</entry>
<entry>load, reload, restart, start</entry>
</row>
@ -329,24 +297,18 @@ esac</programlisting><caution>
<entry>stop</entry>
<entry>stop, clear</entry>
<entry>stop, clear</entry>
</row>
<row>
<entry>stopped</entry>
<entry>stop, clear</entry>
<entry>stop, clear</entry>
</row>
<row>
<entry>tcclear</entry>
<entry>load, reload, restart, restore, start</entry>
<entry>load, reload, restart, restore, start</entry>
</row>
</tbody>
</tgroup>
@ -362,12 +324,10 @@ esac</programlisting><caution>
<command>run_iptables</command> will run the iptables utility passing
the arguments to <command>run_iptables</command> and if the command
fails, the firewall will be stopped (or restored from the last
<command>save</command> command, if any). Note that when
Shorewall-shell invokes this script during <command>restore</command>,
The <command>run_iptables</command> function does nothing; calls to
that function are effectively ignored. <command>run_iptables</command>
should not be called from the <filename>started</filename> or
<filename>restored</filename> scripts.</para>
<command>save</command> command, if any).
<command>run_iptables</command> should not be called from the
<filename>started</filename> or <filename>restored</filename>
scripts.</para>
</listitem>
<listitem>
@ -428,99 +388,38 @@ esac</programlisting><caution>
<para></para>
<section id="v3.2.9">
<title>Shorewall-shell</title>
<para>When compiling your firewall configuration, Shorewall copies most
extension scripts directly into the "compiled" program where they are
executed in-line during processing of the start, restart and restore
commands. When copying a script, Shorewall indents the script to match
the surrounding code; if you have 'awk' installed on the system where
the configuration is being compiled, Shorewall can correctly handle line
continuation in your script ("\" as the last character on a line). If
you do not have awk, you may not use line continuation in your scripts.
Also beware that quoted strings continued from one line to another will
have extra whitespace inserted as a result of indentation.</para>
<note>
<para>The <filename>/etc/shorewall/params</filename> script is
processed only during compilation if EXPORTPARAMS=No in
<filename>shorewall.conf</filename>. So shell variables set in that
file may be used in Shorewall configuration files only. Any variables
that your extension scripts require at run-time on the firewall system
should be set in the <filename>init</filename> extension script (if
you need variable values in the <filename>stop</filename> or
<filename>stopped</filename> scripts, you will need to set their value
in <filename>stop</filename> since <filename>init</filename> is not
invoked when processing the <command>stop</command> and
<command>clear</command> commands).</para>
<para>When EXPORTPARAMS=Yes (the default), the
<filename>/etc/shorewall/params</filename> script is processed during
compilation <emphasis role="bold">and</emphasis> copied into the
compiled script as described above. So shell variables set during
compilation may be used in Shorewall configuration files while those
set at run-time are available to your other extension scripts.Note
that if you assign dynamic values to variables, there is no guarantee
that the value calculated at compile time will be the same as what is
calculated at run time. This is particularly true if you use the
<command>shorewall compile</command> command to compile a program then
run that program at a later time or if you use Shorewall Lite.</para>
</note>
<note>
<para>Extension scripts associated with a particular chain or action
are not copied into the compiled script; they are rather processed
directly by the compiler using the Bourne shell "." command. For
example, if A is an action then if <filename
class="directory">/etc/shorewall/A</filename> exists then it will be
processed by the compiler rather than copied into the compiled
script.</para>
</note>
</section>
<section id="Perl">
<title>Shorewall-perl</title>
<title>Compile-time vs Run-time Scripts</title>
<para>Because the compiler is written in Perl, some of your extension
scripts from earlier versions will no longer work because Shorewall-perl
runs those extension scripts at compile-time rather than at
run-time.</para>
<para>Shorewall runs some extension scripts at compile-time rather than
at run-time.</para>
<para>The following table summarizes when the various extension scripts
are run:<informaltable frame="all">
<tgroup cols="3">
<tgroup cols="2">
<tbody>
<row>
<entry><emphasis role="bold">Compile-time</emphasis></entry>
<entry><emphasis role="bold">Run-time</emphasis></entry>
<entry><emphasis role="bold">Eliminated</emphasis></entry>
</row>
<row>
<entry>compile</entry>
<entry>clear</entry>
<entry>continue</entry>
</row>
<row>
<entry>initdone</entry>
<entry>init</entry>
<entry></entry>
</row>
<row>
<entry>maclog</entry>
<entry>isusable</entry>
<entry></entry>
</row>
<row>
@ -528,32 +427,24 @@ esac</programlisting><caution>
actions)</entry>
<entry>start</entry>
<entry></entry>
</row>
<row>
<entry></entry>
<entry>started</entry>
<entry></entry>
</row>
<row>
<entry></entry>
<entry>stop</entry>
<entry></entry>
</row>
<row>
<entry></entry>
<entry>stopped</entry>
<entry></entry>
</row>
<row>
@ -588,8 +479,7 @@ esac</programlisting><caution>
script returns a 'true' value; otherwise, the compiler will assume that
the script failed and will abort the compilation.</para>
<para>Beginning with Shorewall version 4.0.6, each compile-time script
is implicitly prefaced with:</para>
<para>Each compile-time script is implicitly prefaced with:</para>
<programlisting>package Shorewall::User;</programlisting>
@ -597,7 +487,7 @@ esac</programlisting><caution>
line:<programlisting>use Shorewall::Chains;</programlisting>For more
complex scripts, you may need to 'use' other Shorewall Perl modules --
browse <filename
class="directory">/usr/share/shorewall-perl/Shorewall/</filename> to see
class="directory">/usr/share/shorewall/Shorewall/</filename> to see
what's available.</para>
<para>When a script is invoked, the <emphasis
@ -616,12 +506,12 @@ esac</programlisting><caution>
name</emphasis>&gt;"</member>
</simplelist>Example:<programlisting>add_rule( $chainref, '-j ACCEPT' );</programlisting></para>
<para>Beginning with Shorewall 4.0.5, add_rule() accepts an optional
third argument; If that argument evaluates to true and the passed rule
contains a <emphasis role="bold">--dports</emphasis> list with more than
15 ports (a port range counts as two ports), the rule will be split into
multiple rules where each resulting rule has 15 or fewer ports in its
<emphasis role="bold">--dports</emphasis> list.</para>
<para>The add_rule() function accepts an optional third argument; If
that argument evaluates to true and the passed rule contains a <emphasis
role="bold">--dports</emphasis> list with more than 15 ports (a port
range counts as two ports), the rule will be split into multiple rules
where each resulting rule has 15 or fewer ports in its <emphasis
role="bold">--dports</emphasis> list.</para>
<para>To insert a rule into the chain:<programlisting> insert_rule( $chainref, &lt;<emphasis>rulenum</emphasis>&gt;, &lt;<emphasis>the rule</emphasis>&gt; );</programlisting>The
<emphasis role="bold">log_rule_limit()</emphasis> function works like it
@ -662,12 +552,6 @@ esac</programlisting><caution>
<para>Example:</para>
<programlisting>my $chainref = $filter_table-&gt;{INPUT}; #Same as above with a few less keystrokes; runs faster too</programlisting>
<para>The 'continue' script has been eliminated because it no longer
make any sense under Shorewall-perl. That script was designed to allow
you to add special temporary rules during [re]start. Shorewall-perl
doesn't need such rules since the rule set is instantiated atomically by
table.</para>
</section>
</section>
</article>

27
docs/shorewall_logging.xml
View File

@ -18,7 +18,7 @@
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
<copyright>
<year>2001 - 2007</year>
<year>2001 - 2009</year>
<holder>Thomas M. Eastep</holder>
</copyright>
@ -35,9 +35,9 @@
</articleinfo>
<caution>
<para><emphasis role="bold">This article applies to Shorewall 3.0 and
<para><emphasis role="bold">This article applies to Shorewall 4.3 and
later. If you are running a version of Shorewall earlier than Shorewall
3.0.0 then please see the documentation for that
4.3.5 then please see the documentation for that
release.</emphasis></para>
</caution>
@ -184,13 +184,12 @@
</listitem>
</orderedlist>
<para>Beginning with Shorewall version 1.3.12, if your kernel has ULOG
target support (and most vendor-supplied kernels do), you may also
specify a log level of ULOG (must be all caps). When ULOG is used,
Shorewall will direct Netfilter to log the related messages via the ULOG
target which will send them to a process called <quote>ulogd</quote>.
The ulogd program is included in most distributions and is also
available from <ulink
<para>If your kernel has ULOG target support (and most vendor-supplied
kernels do), you may also specify a log level of ULOG (must be all
caps). When ULOG is used, Shorewall will direct Netfilter to log the
related messages via the ULOG target which will send them to a process
called <quote>ulogd</quote>. The ulogd program is included in most
distributions and is also available from <ulink
url="http://www.netfilter.org/projects/ulogd/index.html">http://www.netfilter.org/projects/ulogd/index.html</ulink>.
Ulogd can be configured to log all Shorewall messages to their own log
file.</para>
@ -233,12 +232,8 @@ gateway:/etc/shorewall# </programl
<quote><command>logwatch</command></quote> and
<quote><command>dump</command></quote> commands.</para>
<para>Beginning in Shorewall-perl 4.1, the NFLOG target is
supported.</para>
<para>NFLOG is a successor to ULOG. When using <ulink
url="Shorewall-perl.html">Shorewall-perl</ulink> 4.1 or later, both ULOG
and NFLOG may be followed by a list of up to three numbers in
<para>The NFLOG target, a successor to ULOG, is supported shorewall.
Both ULOG and NFLOG may be followed by a list of up to three numbers in
parentheses.</para>
<itemizedlist>

56
docs/shorewall_prerequisites.xml
View File

@ -33,9 +33,9 @@
</articleinfo>
<caution>
<para><emphasis role="bold">This article applies to Shorewall 3.0 and
<para><emphasis role="bold">This article applies to Shorewall 4.3 and
later. If you are running a version of Shorewall earlier than Shorewall
3.0.0 then please see the documentation for that
4.3.5 then please see the documentation for that
release.</emphasis></para>
</caution>
@ -90,17 +90,47 @@
<para>The firewall monitoring display is greatly improved if you have
awk (gawk) installed.</para>
</listitem>
<listitem>
<para>On the system where the Shorewall package itself is installed,
you must have Perl installed (preferably Perl 5.8.10):</para>
<itemizedlist>
<listitem>
<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 Socket6 module. </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</para>
</listitem>
<listitem>
<para>Perl Scalar::Util Module</para>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</section>
<section id="Perl">
<title>Shorewall-perl Requirements</title>
<para><ulink url="Shorewall-perl.html">Shorewall-perl</ulink> is a
re-implementation of the Shorewall configuration compiler written in Perl.
It is much faster than the classic Shorewall-shell compiler and produces a
firewall script that runs much faster. It's prerequisites are described in
<ulink url="Shorewall-perl.html#Prerequisites">the Shorewall-perl
article</ulink>.</para>
</section>
</article>

42
docs/starting_and_stopping_shorewall.xml
View File

@ -41,9 +41,9 @@
</articleinfo>
<caution>
<para><emphasis role="bold">This article applies to Shorewall 3.0 and
<para><emphasis role="bold">This article applies to Shorewall 4.3 and
later. If you are running a version of Shorewall earlier than Shorewall
3.0.0 then please see the documentation for that
4.3.5 then please see the documentation for that
release</emphasis>.</para>
</caution>
@ -133,12 +133,12 @@
executed.</para>
<important>
<para>Beginning with Shorewall 3.1, <command>shorewall
start</command> is implemented as a <firstterm>compile and
go</firstterm>; that is, the configuration is compiled and if there
are no compilation errors then the resulting compiled script is
executed. If there are compilation errors, the command is aborted
and the state of the firewall is not altered.</para>
<para><command>shorewall start</command> is implemented as a
<firstterm>compile and go</firstterm>; that is, the configuration is
compiled and if there are no compilation errors then the resulting
compiled script is executed. If there are compilation errors, the
command is aborted and the state of the firewall is not
altered.</para>
</important>
</listitem>
@ -207,15 +207,14 @@
<para>To trace the execution of <command>shorewall start</command> and
write the trace to the file <filename>/tmp/trace</filename>, you would
enter:<programlisting><command>shorewall trace start 2&gt; /tmp/trace</command></programlisting><note>
<para>If you are running Shorewall-perl, the <emphasis
role="bold">trace</emphasis> keyword does not result in a trace of
the execution of the Shorewall-perl compiler. It rather causes
additional diagnostic information to be included in warning and
error messages generated by the compiler.</para>
<para>The <emphasis role="bold">trace</emphasis> keyword does not
result in a trace of the execution of the Shorewall rules compiler.
It rather causes additional diagnostic information to be included in
warning and error messages generated by the compiler.</para>
</note></para>
<para>Beginning with Shorewall 4.0.5, you may also include the word
<emphasis role="bold">debug</emphasis> as the first argument to the
<para>You may also include the word <emphasis
role="bold">debug</emphasis> as the first argument to the
<filename>/sbin/shorewall</filename> and
<filename>/sbin/shorewall-lite</filename> commands.<programlisting><command>shorewall debug restart</command></programlisting>In
most cases, <emphasis role="bold">debug</emphasis> is a synonym for
@ -346,17 +345,12 @@
running <command>iptables</command> dozens or even hundreds of
times.</para>
<para><filename>Under Shorewall versions &lt; 4.0.0,
/etc/init.d/shorewall</filename>
(<filename>/etc/rc.d/rc.firewall</filename>) uses the -f option when
it is processing a request to start Shorewall. Beginning with
Shorewall 4.0.0, the default is to not use -f. If you wish to change
the default, you must set the OPTIONS shell variable in either
<para>The default is to not use -f. If you wish to change the default,
you must set the OPTIONS shell variable in either
<filename>/etc/default/shorewall</filename> or
<filename>/etc/sysconfig/shorewall</filename> (if your distribution
provides neither of these files, you must create one or the other).
For example, to continue to use -f under Shorewall 4.0.0 and later,
you would have:<programlisting>OPTIONS="-f"</programlisting></para>
</para>
</listitem>
<listitem>
@ -515,7 +509,7 @@
<section id="Commands">
<title>Commands</title>
<para>The general form of a command in Shorewall 4.0 is:</para>
<para>The general form of a command is:</para>
<blockquote>
<para><command>shorewall [ &lt;options&gt; ] &lt;command&gt; [

202
docs/traffic_shaping.xml
View File

@ -134,65 +134,17 @@
classes (and their bandwidth limits), and it uses SFQ inside these classes
to make sure, that different data streams are handled equally.</para>
<para><emphasis role="bold">If you are running Shorewall-shell or if you
are running Shorewall-perl 4.1.5 or earlier:</emphasis><blockquote>
<para><emphasis role="bold">You can only shape outgoing traffic. The
reason for this is simple, the packets were already received by your
network card before you can decide what to do with them</emphasis>. So
the only choice would be to drop them which normally makes no sense
(since you received the packet already, it went through the possible
bottleneck (the incoming connection). The next possible bottleneck
might come if the packet leaves on another interface, so this will be
the place where queuing might occur. So, defining queues for incoming
packets is not very useful, you just want to have it forwarded to the
outgoing interface as fast as possible.</para>
<para>You can shape incoming traffic through use of an
<firstterm>Intermediate Frame Block</firstterm> (IFB) device. <link
linkend="IFB">See below</link>. <emphasis role="bold">But beware: using an
IFB can result in queues building up both at your ISPs router and at your
own.</emphasis></para>
<para>There is one exception, though. Limiting incoming traffic to a
value a bit slower than your actual line speed will avoid queuing on
the other end of that connection. This is mostly useful if you don't
have access to traffic control on the other side and if this other
side has a faster network connection than you do (the line speed
between the systems is the bottleneck, e.g. a DSL or Cable Modem
connection to your provider's router, the router itself is normally
connected to a much faster backbone). So, if you drop packets that are
coming in too fast, the underlying protocol might recognize this and
slow down the connection. TCP has a builtin mechanism for this, UDP
has not (but the protocol over UDP might recognize it , if there is
any).</para>
<para>The reason why queuing is bad in these cases is, that you might
have packets which need to be prioritized over others, e.g. VoIP or
ssh. For this type of connections it is important that packets arrive
in a certain amount of time. For others like HTTP downloads, it does
not really matter if it takes a few seconds more.</para>
<para>If you have a large queue on the other side and the router there
does not care about QoS or the QoS bits are not set properly, your
important packets will go into the same queue as your less time
critical download packets which will result in a large delay.</para>
</blockquote></para>
<para><emphasis role="bold">If you are running Shorewall-perl 4.1.6 or
later:</emphasis><blockquote>
<para>You can shape incoming traffic through use of an
<firstterm>Intermediate Frame Block</firstterm> (IFB) device. <link
linkend="IFB">See below</link>. <emphasis role="bold">But beware:
using an IFB can result in queues building up both at your ISPs router
and at your own.</emphasis></para>
</blockquote></para>
<para><emphasis role="bold">This is not to say that you cannot shape
download traffic, regardless of which Shorewall release you are
running</emphasis>.</para>
<blockquote>
<para>If you wish to shape downloads, you can always configure traffic
shaping on your firewall's local interface. An example appears <link
linkend="Downloads">below</link>.</para>
<para>Again, however, <emphasis role="bold">this can result in queues
building up both at your ISPs router and at your own</emphasis>.</para>
</blockquote>
<para>If you wish to shape downloads, you can also configure traffic
shaping on your firewall's local interface. An example appears <link
linkend="Downloads">below</link>. Again, however, <emphasis
role="bold">this can result in queues building up both at your ISPs router
and at your own</emphasis>.</para>
<para>You shape and control outgoing traffic by assigning the traffic to
<firstterm>classes</firstterm>. Each class is associated with exactly one
@ -371,13 +323,10 @@
only once in this file. You may NOT specify the name of an alias
(e.g., eth0:0) here; see <ulink url="FAQ.htm#faq18">FAQ #18</ulink>.
You man NOT specify wildcards here, e.g. if you have multiple ppp
interfaces, you need to put them all in here! With Shorewall
versions prior to 3.0.8 and 3.2.0 Beta 8, the device named in this
column must exist at the time that Shorewall is started, restarted
or refreshed. Beginning with Shorewall 3.0.8 and 3.2.0 Beta 8,
Shorewall will determine if the device exists and will only
configure the device if it does exist. If it doesn't exist, the
following warning is issued:</para>
interfaces, you need to put them all in here! Shorewall will
determine if the device exists and will only configure the device if
it does exist. If it doesn't exist, the following warning is
issued:</para>
<para><emphasis role="bold">WARNING: Device &lt;device name&gt; not
found -- traffic-shaping configuration skipped</emphasis></para>
@ -385,10 +334,9 @@
<para>Shorewall assigns a sequential <firstterm>interface
number</firstterm> to each interface (the first entry in
<filename>/etc/shorewall/tcdevices</filename> is interface 1, the
second is interface 2 and so on) Beginning with Shorewall-perl
4.1.6, you can explicitly specify the interface number by prefixing
the interface name with the number and a colon (":"). Example:
1:eth0.</para>
second is interface 2 and so on) You can also explicitly specify the
interface number by prefixing the interface name with the number and
a colon (":"). Example: 1:eth0.</para>
</listitem>
<listitem>
@ -400,8 +348,8 @@
exceeded, the excess packets are dropped. You want this mainly if
you have a DSL or Cable Connection to avoid queuing at your
providers side. If you don't want any traffic to be dropped set this
to a value faster than your interface maximum rate (or to 0 (zero),
if you are running Shorewall 3.2.6 or later).</para>
to a value faster than your interface maximum rate (or to 0
(zero).</para>
<para>To determine the optimum value for this setting, we recommend
that you start by setting it significantly below your measured
@ -420,8 +368,8 @@
</listitem>
<listitem>
<para>OPTIONS (Added in Shorewall-perl 4.1.4) — A comma-separated
list of options from the following list:</para>
<para>OPTIONS — A comma-separated list of options from the following
list:</para>
<variablelist>
<varlistentry>
@ -439,14 +387,13 @@
</listitem>
<listitem>
<para>REDIRECTED INTERFACES (Added in Shorewall-perl 4.1.6) —
Entries are appropriate in this column only if the device in the
INTERFACE column names a <link linkend="IFB">Intermediate Frame
Block (IFB)</link>. It lists the physical interfaces that will have
their input shaped using classes defined on the IFB. Neither the IFB
nor any of the interfaces listed in this column may have an
IN-BANDWIDTH specified. You may specify zero (0) or a dash ("-:) in
the IN-BANDWIDTH column.</para>
<para>REDIRECTED INTERFACES — Entries are appropriate in this column
only if the device in the INTERFACE column names a <link
linkend="IFB">Intermediate Frame Block (IFB)</link>. It lists the
physical interfaces that will have their input shaped using classes
defined on the IFB. Neither the IFB nor any of the interfaces listed
in this column may have an IN-BANDWIDTH specified. You may specify
zero (0) or a dash ("-:) in the IN-BANDWIDTH column.</para>
<para>IFB devices automatically get the <emphasis
role="bold">classify</emphasis> option.</para>
@ -473,15 +420,14 @@ ppp0 6000kbit 500kbit</programlisting>
<itemizedlist>
<listitem>
<para>INTERFACE - Name of interface. Users of Shorewall-perl 4.1.6
or later may also specify the interface number. Must match the name
(or number) of an interface with an entry in
<filename>/etc/shorewall/tcdevices</filename>. If the interface has
the <emphasis role="bold">classify</emphasis> option in
<filename>/etc/shorewall/tcdevices</filename>, then the interface
name or number must be followed by a colon and a <firstterm>class
number</firstterm>. Examples: eth0:1, 4:9. Class numbers must be
unique for a given interface.</para>
<para>INTERFACE - Name of interface. Users may also specify the
interface number. Must match the name (or number) of an interface
with an entry in <filename>/etc/shorewall/tcdevices</filename>. If
the interface has the <emphasis role="bold">classify</emphasis>
option in <filename>/etc/shorewall/tcdevices</filename>, then the
interface name or number must be followed by a colon and a
<firstterm>class number</firstterm>. Examples: eth0:1, 4:9. Class
numbers must be unique for a given interface.</para>
</listitem>
<listitem>
@ -685,11 +631,10 @@ ppp0 6000kbit 500kbit</programlisting>
</itemizedlist>
<note>
<para>The "T" qualifier was added in Shorewall version 3.3.6 and
is not available in earlier versions. <emphasis role="bold">Use
this qualifier if you want the rule to apply equally to traffic
being routed through the firewall and to traffic originating on
the firewall itself.</emphasis></para>
<para> <emphasis role="bold">Use the 'T' qualifier if you want the
rule to apply equally to traffic being routed through the firewall
and to traffic originating on the firewall
itself.</emphasis></para>
</note>
<para>Normally, the mark is applied to the packet. If you follow the
@ -735,12 +680,11 @@ ppp0 6000kbit 500kbit</programlisting>
</listitem>
<listitem>
<para><emphasis role="bold">COMMENT</emphasis> (Added in
Shorewall version 3.3.3) -- the rest of the line will be
attached as a comment to the Netfilter rule(s) generated by the
following entries. The comment will appear delimited by "/* ...
*/" in the output of <command>shorewall show
mangle</command></para>
<para><emphasis role="bold">COMMENT</emphasis> -- the rest of
the line will be attached as a comment to the Netfilter rule(s)
generated by the following entries. The comment will appear
delimited by "/* ... */" in the output of <command>shorewall
show mangle</command></para>
<para>To stop the comment from being attached to further rules,
simply include COMMENT on a line by itself.</para>
@ -767,9 +711,7 @@ ppp0 6000kbit 500kbit</programlisting>
<member>prio</member>
</simplelist>
<para>With Shorewall versions prior to 3.2.3, classify rules are
always placed in the POSTROUTING chain. Beginning with Shorewall
3.2.3, classification occurs in the POSTROUTING chain <emphasis
<para>Classification occurs in the POSTROUTING chain <emphasis
role="bold">except</emphasis> when the SOURCE contains
$FW[:&lt;<emphasis>address</emphasis>&gt;] in which case, the
classify action takes place in the OUTPUT chain. When used with the
@ -783,7 +725,7 @@ ppp0 6000kbit 500kbit</programlisting>
</listitem>
<listitem>
<para>SOURCE - Source of the packet. </para>
<para>SOURCE - Source of the packet.</para>
<para>May be:</para>
@ -835,7 +777,7 @@ ppp0 6000kbit 500kbit</programlisting>
</listitem>
<listitem>
<para>DEST - Destination of the packet. </para>
<para>DEST - Destination of the packet.</para>
<para>May be:</para>
@ -873,12 +815,8 @@ ppp0 6000kbit 500kbit</programlisting>
ipp2p option without the leading "--" (example "bit" for
bit-torrent). If no PORT is given, "ipp2p" is assumed. Note that the
xtables-addons version of IPP2P does not support the "ipp2p" option;
to use that version of IPP2P with Shorewall-shell or with
Shorewall-perl 4.2.4 or earlier, you must specify an option other
than "ipp2p". Shorewall-perl 4.2.5 and later support a
comma-separated list of IPP2P options in this column; if the column
is empty or contains "ipp2p", then those versions of Shorewall-perl
will substitute "edk,kazaa,gnu,dc".</para>
if the column is empty or contains "ipp2p" when using that version
of IPP2P, Shorewall will substitute "edk,kazaa,gnu,dc".</para>
<para>This column is ignored if PROTOCOL = all but must be entered
if any of the following field is supplied. In that case, it is
@ -893,11 +831,10 @@ ppp0 6000kbit 500kbit</programlisting>
</listitem>
<listitem>
<para>USER/GROUP (Added in Shorewall version 1.4.10) - (Optional)
This column may only be non-empty if the SOURCE is the firewall
itself. When this column is non-empty, the rule applies only if the
program generating the output is running under the effective user
and/or group. It may contain :</para>
<para>USER/GROUP (Optional) This column may only be non-empty if the
SOURCE is the firewall itself. When this column is non-empty, the
rule applies only if the program generating the output is running
under the effective user and/or group. It may contain :</para>
<para>[!][&lt;user name or number&gt;]:[&lt;group name or
number&gt;][+&lt;program name&gt;]</para>
@ -913,9 +850,9 @@ ppp0 6000kbit 500kbit</programlisting>
</listitem>
<listitem>
<para>TEST - Defines a test on the existing packet or connection
mark. The rule will match only if the test returns true. Tests have
the format [!]&lt;value&gt;[/&lt;mask&gt;][:C]</para>
<para>TEST (Optional) Defines a test on the existing packet or
connection mark. The rule will match only if the test returns true.
Tests have the format [!]&lt;value&gt;[/&lt;mask&gt;][:C]</para>
<para>Where:</para>
@ -934,11 +871,10 @@ ppp0 6000kbit 500kbit</programlisting>
</listitem>
<listitem>
<para>LENGTH (Optional, added in Shorewall version 3.2.0) Packet
Length - This field, if present, allows you to match the length of a
packet against a specific value or range of values. A range is
specified in the form &lt;min&gt;:&lt;max&gt; where either
&lt;min&gt; or &lt;max&gt; (but not both) may be omitted. If
<para>LENGTH (Optional) This field, if present, allows you to match
the length of a packet against a specific value or range of values.
A range is specified in the form &lt;min&gt;:&lt;max&gt; where
either &lt;min&gt; or &lt;max&gt; (but not both) may be omitted. If
&lt;min&gt; is omitted, then 0 is assumed; if &lt;max&gt; is
omitted, than any packet that is &lt;min&gt; or longer will
match.</para>
@ -951,9 +887,8 @@ ppp0 6000kbit 500kbit</programlisting>
</listitem>
<listitem>
<para>TOS (Optional, added in Shorewall version 3.2.0 Beta 6) Type
of Service. Either a standard name, or a numeric value to
match.</para>
<para>TOS (Optional) Type of Service. Either a standard name, or a
numeric value to match.</para>
<blockquote>
<simplelist>
@ -971,9 +906,8 @@ ppp0 6000kbit 500kbit</programlisting>
</listitem>
<listitem>
<para>HELPER (Optional, added in Shorewall version 4.2.0 Beta 2).
Names one of the Netfilter protocol helper modules such as
<emphasis>ftp</emphasis>, <emphasis>sip</emphasis>,
<para>HELPER (Optional). Names one of the Netfilter protocol helper
modules such as <emphasis>ftp</emphasis>, <emphasis>sip</emphasis>,
<emphasis>amanda</emphasis>, etc.</para>
</listitem>
</itemizedlist>
@ -1063,8 +997,7 @@ SAVE 0.0.0.0/0 0.0.0.0/0 all - - -
<para>Mark all forwarded VOIP connections with connection mark 1 and
ensure that all VOIP packets also receive that mark (assumes that
nf_conntrack_sip is loaded and that Shorewall-perl 4.2.0 or later is
being used).</para>
nf_conntrack_sip is loaded).</para>
<programlisting>#MARK SOURCE DESTINATION PROTOCOL PORT(S) CLIENT USER/ TEST CONNBYTES TOS HELPER
# PORT(S) GROUP
@ -1328,8 +1261,7 @@ eth0 4 94mbit full default #for local traff
<section id="IFB">
<title>Intermediate Frame Block (IFB) Devices</title>
<para>Beginning with Shorewall 4.1.6, Shorewall-perl includes support for
IFBs. The principles behind an IFB is fairly simple:</para>
<para>The principles behind an IFB is fairly simple:</para>
<itemizedlist>
<listitem>

280
docs/troubleshoot.xml
View File

@ -36,25 +36,109 @@
<title><quote>shorewall start</quote> and <quote>shorewall restart</quote>
Errors</title>
<section id="Start-shell">
<title>Shorewall-shell</title>
<para>If the error is detected by the Shorewall compiler, it should be
fairly obvious where the problem was found. Each error message includes
the configuration file name and line number where the error was detected
and often gives the particular item in error. The item is either enclosed
in parentheses or is at the end following a colon (":").</para>
<para>If you use the Shorewall-shell compiler and you receive an error
message when starting or restarting the firewall and you can't determine
the cause. First, if your VERBOSITY setting in shorewall.conf is less
than 2, then try running with a higher verbosity level by using the "-v"
option:</para>
<para>Example:<programlisting>gateway:~/test # shorewall restart .
Compiling...
ERROR: Invalid ICMP Type (0/400) : /root/test/rules (line 19)
gateway:~/test # </programlisting>In this case, line 19 in the rules file
specified an invalid ICMP Type (0/400).</para>
<blockquote>
<programlisting><command>shorewall -vv [re]start</command></programlisting>
</blockquote>
<para>Additional information about the error can be obtained using the
'debug' keyword:<programlisting>gateway:~/test # shorewall debug restart .
Compiling...
ERROR: Invalid ICMP Type (0/400) : /root/test/rules (line 19) at /usr/share/shorewall/Shorewall/Config.pm line 338
Shorewall::Config::fatal_error('Invalid ICMP Type (0/400)') called at /usr/share/shorewall/Shorewall/Chains.pm line 885
Shorewall::Chains::validate_icmp('0/400') called at /usr/share/shorewall/Shorewall/Chains.pm line 949
Shorewall::Chains::do_proto('icmp', '0/400', '-') called at /usr/share/shorewall/Shorewall/Rules.pm line 1055
Shorewall::Rules::process_rule1('ACCEPT', 'loc', 'net', 'icmp', '0/400', '-', '-', '-', '-', ...) called at /usr/share/shorewall/Shorewall/Rules.pm line 1290
Shorewall::Rules::process_rule('ACCEPT', 'loc', 'net', 'icmp', '0/400', '-', '-', '-', '-', ...) called at /usr/share/shorewall/Shorewall/Rules.pm line 1336
Shorewall::Rules::process_rules() called at /usr/share/shorewall/Shorewall/Compiler.pm line 799
Shorewall::Compiler::compiler('/var/lib/shorewall/.restart', '/root/test', 0, 4) called at /usr/share/shorewall/compiler.pl line 86
gateway:~/test # </programlisting>This information is useful to Shorewall
support if you need to <ulink url="support.html">file a problem
report</ulink>.</para>
<para>That will give you additional progress messages that may make it
clear which entry in which file is generating the error.</para>
<para>The end of the compile phase is signaled by a message such as the
following:<programlisting>Shorewall configuration compiled to /var/lib/shorewall/.restart</programlisting>Errors
occurring past that point are said to occur at
<firstterm>run-time</firstterm> because they occur during the running of
the compiled firewall script (/var/lib/shorewall/.restart in the case of
the above message).</para>
<para>If that didn't help, then do the following:</para>
<para>One common run-time failure is that the iptables-restore program
encounters an error. This will produce an error such as the
following:<programlisting>...
Restarting Shorewall....
iptables-restore v1.3.6: No chain/target/match by that name
Error occurred at line: 83
Try `iptables-restore -h' or 'iptables-restore --help' for more information.
ERROR: iptables-restore Failed. Input is in /var/lib/shorewall/.iptables-restore-input
Restoring Shorewall...
Shorewall restored from /var/lib/shorewall/restore
Terminated
gateway:~/test # </programlisting>A look at /var/lib/shorewall/restore at line
83 might show something like the following:<programlisting>-A reject -p tcp -j REJECT --reject-with tcp-reset</programlisting>In
this case, the user had compiled his own kernel and had forgotten to
include REJECT target support (see <ulink
url="kernel.htm">kernel.htm</ulink>).</para>
<itemizedlist>
<para>You may also include the word <emphasis role="bold">debug</emphasis>
as the first argument to the <filename>/sbin/shorewall</filename> and
<filename>/sbin/shorewall-lite</filename> commands.<programlisting><command>shorewall debug restart</command></programlisting>In
most cases, <emphasis role="bold">debug</emphasis> is a synonym for
<emphasis role="bold">trace</emphasis>. The exceptions are:</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">debug</emphasis> is ignored by the
Shorewall compiler.</para>
</listitem>
<listitem>
<para><emphasis role="bold">debug</emphasis> causes altered behavior
of generated scripts. These scripts normally use<command>
iptables-restore</command> to install the Netfilter ruleset but with
<emphasis role="bold">debug</emphasis>, the commands normally passed
to <command>iptables-restore</command> in its input file are passed
individually to <command>iptables</command>. This is a diagnostic aid
which allows identifying the individual command that is causing
<command>iptables-restore</command> to fail; it should be used when
iptables-restore fails when executing a <command>COMMIT</command>
command.</para>
</listitem>
</itemizedlist>
<warning>
<para>The <emphasis role="bold">debug</emphasis> feature is strictly for
problem analysis. When <emphasis role="bold">debug</emphasis> is
used:</para>
<orderedlist>
<listitem>
<para>The firewall is made 'wide open' before the rules are
applied.</para>
</listitem>
<listitem>
<para>The <filename>routestopped</filename> file is not
consulted.</para>
</listitem>
<listitem>
<para>The rules are applied in the canonical
<command>iptables-restore</command> order. So if you need critical
hosts to be always available during start/restart, you may not be
able to use <emphasis role="bold">debug</emphasis>.</para>
</listitem>
</orderedlist>
</warning>
<para>In other run-time failure cases:<itemizedlist>
<listitem>
<para>Make a note of the error message that you see.</para>
</listitem>
@ -67,177 +151,15 @@
<listitem>
<para>Look at the <filename>/tmp/trace</filename> file and see if
that helps you determine what the problem is. Be sure you find the
place in the log where the error message you saw is generated -- If
you are using Shorewall 1.4.0 or later, you should find the message
near the end of the log.</para>
place in the log where the error message you saw is generated -- you
should find the message near the end of the log.</para>
</listitem>
<listitem>
<para>If you still can't determine what's wrong then see the <ulink
url="support.htm">support page</ulink>.</para>
</listitem>
</itemizedlist>
<example id="Example1">
<title>Startup Error</title>
<para>During startup, a user sees the following:</para>
<programlisting>Adding Common Rules
iptables: No chain/target/match by that name
Terminated</programlisting>
<para>A search through the trace for <quote>No chain/target/match by
that name</quote> turned up the following:</para>
<programlisting>+ echo 'Adding Common Rules'
+ add_common_rules
+ run_iptables -A reject -p tcp -j REJECT --reject-with tcp-reset
++ echo -A reject -p tcp -j REJECT --reject-with tcp-reset
++ sed 's/!/! /g'
+ iptables -A reject -p tcp -j REJECT --reject-with tcp-reset
iptables: No chain/target/match by that name
</programlisting>
<para>The command that failed was: <quote><command>iptables -A reject
-p tcp -j REJECT --reject-with tcp-reset</command></quote>. In this
case, the user had compiled his own kernel and had forgotten to
include REJECT target support (see <ulink
url="kernel.htm">kernel.htm</ulink>)</para>
</example>
</section>
<section id="Start-perl">
<title>Shorewall-perl</title>
<para>If the error is detected by the Shorewall-perl compiler, it should
be fairly obvious where the problem was found. Each error message
includes the configuration file name and line number where the error was
detected and often gives the particular item in error. The item is
either enclosed in parentheses or is at the end following a colon
(":").</para>
<para>Example:<programlisting>gateway:~/test # shorewall restart .
Compiling...
ERROR: Invalid ICMP Type (0/400) : /root/test/rules (line 19)
gateway:~/test # </programlisting>In this case, line 19 in the rules file
specified an invalid ICMP Type (0/400).</para>
<para>Additional information about the error can be obtained using the
'debug' keyword:<programlisting>gateway:~/test # shorewall debug restart .
Compiling...
ERROR: Invalid ICMP Type (0/400) : /root/test/rules (line 19) at /usr/share/shorewall-perl/Shorewall/Config.pm line 338
Shorewall::Config::fatal_error('Invalid ICMP Type (0/400)') called at /usr/share/shorewall-perl/Shorewall/Chains.pm line 885
Shorewall::Chains::validate_icmp('0/400') called at /usr/share/shorewall-perl/Shorewall/Chains.pm line 949
Shorewall::Chains::do_proto('icmp', '0/400', '-') called at /usr/share/shorewall-perl/Shorewall/Rules.pm line 1055
Shorewall::Rules::process_rule1('ACCEPT', 'loc', 'net', 'icmp', '0/400', '-', '-', '-', '-', ...) called at /usr/share/shorewall-perl/Shorewall/Rules.pm line 1290
Shorewall::Rules::process_rule('ACCEPT', 'loc', 'net', 'icmp', '0/400', '-', '-', '-', '-', ...) called at /usr/share/shorewall-perl/Shorewall/Rules.pm line 1336
Shorewall::Rules::process_rules() called at /usr/share/shorewall-perl/Shorewall/Compiler.pm line 799
Shorewall::Compiler::compiler('/var/lib/shorewall/.restart', '/root/test', 0, 4) called at /usr/share/shorewall-perl/compiler.pl line 86
gateway:~/test # </programlisting>This information is useful to Shorewall
support if you need to <ulink url="support.html">file a problem
report</ulink>.</para>
<para>The end of the compile phase is signaled by a message such as the
following:<programlisting>Shorewall configuration compiled to /var/lib/shorewall/.restart</programlisting>Errors
occurring past that point are said to occur at
<firstterm>run-time</firstterm> because they occur during the running of
the compiled firewall script (/var/lib/shorewall/.restart in the case of
the above message).</para>
<para>One common run-time failure is that the iptables-restore program
encounters an error. This will produce an error such as the
following:<programlisting>...
Restarting Shorewall....
iptables-restore v1.3.6: No chain/target/match by that name
Error occurred at line: 83
Try `iptables-restore -h' or 'iptables-restore --help' for more information.
ERROR: iptables-restore Failed. Input is in /var/lib/shorewall/.iptables-restore-input
Restoring Shorewall...
Shorewall restored from /var/lib/shorewall/restore
Terminated
gateway:~/test # </programlisting>A look at /var/lib/shorewall/restore at line
83 might show something like the following:<programlisting>-A reject -p tcp -j REJECT --reject-with tcp-reset</programlisting>In
this case, the user had compiled his own kernel and had forgotten to
include REJECT target support (see <ulink
url="kernel.htm">kernel.htm</ulink>).</para>
<para>f you are running Shorewall-perl 4.0.5 or later, you may also
include the word <emphasis role="bold">debug</emphasis> as the first
argument to the <filename>/sbin/shorewall</filename> and
<filename>/sbin/shorewall-lite</filename> commands.<programlisting><command>shorewall debug restart</command></programlisting>In
most cases, <emphasis role="bold">debug</emphasis> is a synonym for
<emphasis role="bold">trace</emphasis>. The exceptions are:</para>
<itemizedlist>
<listitem>
<para><emphasis role="bold">debug</emphasis> is ignored by the
Shorewall-perl compiler.</para>
</listitem>
<listitem>
<para><emphasis role="bold">debug</emphasis> causes altered behavior
of scripts generated by the Shorewall-perl compiler. These scripts
normally use<command> iptables-restore</command> to install the
Netfilter ruleset but with <emphasis role="bold">debug</emphasis>,
the commands normally passed to <command>iptables-restore</command>
in its input file are passed individually to
<command>iptables</command>. This is a diagnostic aid which allows
identifying the individual command that is causing
<command>iptables-restore</command> to fail; it should be used when
iptables-restore fails when executing a <command>COMMIT</command>
command.</para>
</listitem>
</itemizedlist>
<warning>
<para> The <emphasis role="bold">debug</emphasis> feature is strictly
for problem analysis. When <emphasis role="bold">debug</emphasis> is
used:</para>
<orderedlist>
<listitem>
<para>The firewall is made 'wide open' before the rules are
applied.</para>
</listitem>
<listitem>
<para>The <filename>routestopped</filename> file is not
consulted.</para>
</listitem>
<listitem>
<para>The rules are applied in the canonical
<command>iptables-restore</command> order. So if you need critical
hosts to be always available during start/restart, you may not be
able to use <emphasis role="bold">debug</emphasis>.</para>
</listitem>
</orderedlist>
</warning>
<para>In other run-time failure cases:<itemizedlist>
<listitem>
<para>Make a note of the error message that you see.</para>
</listitem>
<listitem>
<para><command>shorewall debug start 2&gt;
/tmp/trace</command></para>
</listitem>
<listitem>
<para>Look at the <filename>/tmp/trace</filename> file and see if
that helps you determine what the problem is. Be sure you find the
place in the log where the error message you saw is generated --
you should find the message near the end of the log.</para>
</listitem>
<listitem>
<para>If you still can't determine what's wrong then see the
<ulink url="support.htm">support page</ulink>.</para>
</listitem>
</itemizedlist></para>
</section>
</itemizedlist></para>
</section>
<section id="Network">

18
docs/upgrade_issues.xml
View File

@ -29,6 +29,8 @@
<year>2008</year>
<year>2009</year>
<holder>Thomas M. Eastep</holder>
<holder></holder>
@ -71,12 +73,22 @@
command to see the groups associated with each of your zones.</para>
</section>
<section>
<title>Versions &gt;= 4.3.5</title>
<para>If you are using Shorewall-perl, there are no additional upgrade
issues. If you are using Shorewall-shell or are upgrading from a Shorewall
version earlier than 4.0.0 then you will need to <ulink
url="Shorewall-perl.html">migrate to Shorewall-perl</ulink>.
Shorewall-4.3.5 and later only use the perl-based compiler.</para>
</section>
<section>
<title>Versions &gt;= 4.2.0</title>
<orderedlist>
<listitem>
<para> Previously, when HIGH_ROUTE_MARKS=Yes, Shorewall allowed
<para>Previously, when HIGH_ROUTE_MARKS=Yes, Shorewall allowed
non-zero mark values &lt; 256 to be assigned in the OUTPUT chain. This
has been changed so that only high mark values may be assigned there.
Packet marking rules for traffic shaping of packets originating on the
@ -158,7 +170,7 @@
<listitem>
<para>The value of IMPLICIT_CONTINUE in shorewall.conf (and samples)
has been changed from Yes to No. </para>
has been changed from Yes to No.</para>
</listitem>
<listitem>
@ -169,7 +181,7 @@
<listitem>
<para>DYNAMIC_ZONES=Yes is no longer supported by Shorewall-perl. Use
ipset-based zones instead. </para>
ipset-based zones instead.</para>
</listitem>
</orderedlist>
</section>