holm/shorewall_code
1
0
Fork 0
forked from extern/shorewall_code
Code Pull Requests 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> </articleinfo>
<caution> <caution>
<para>This article applies to Shorewall 4.0 and later. If you are running <para><emphasis role="bold">This article applies to Shorewall 4.3 and
a version of Shorewall earlier than Shorewall 4.0.0 then please see the later. If you are running a version of Shorewall earlier than Shorewall
documentation for that release.</para> 4.3.5 then please see the documentation for that
release.</emphasis></para>
</caution> </caution>
<section id="Intro"> <section id="Intro">
@ -104,9 +105,8 @@ ACCEPT - - tcp 135,139,445
file to <filename class="directory">/etc/shorewall</filename> (or file to <filename class="directory">/etc/shorewall</filename> (or
somewhere else on your CONFIG_PATH) and modify the copy.</para> somewhere else on your CONFIG_PATH) and modify the copy.</para>
<para>Standard Actions were largely replaced by <ulink <para>Standard Actions have been largely replaced by <ulink
url="Macros.html">macros</ulink> in Shorewall 3.0 and later major url="Macros.html">macros</ulink> .</para>
versions.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -121,19 +121,6 @@ ACCEPT - - tcp 135,139,445
</orderedlist> </orderedlist>
</section> </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"> <section id="Default">
<title>Default Actions (Formerly Common Actions)</title> <title>Default Actions (Formerly Common Actions)</title>
@ -185,10 +172,9 @@ ACCEPT - - tcp 135,139,445
<section id="Limit"> <section id="Limit">
<title>Limiting Per-IP Connection Rate</title> <title>Limiting Per-IP Connection Rate</title>
<para>Beginning with Shorewall 3.0.4, Shorewall has a <quote>Limit</quote> <para>Shorewall supports a <quote>Limit</quote> <ulink
<ulink url="Actions.html">action</ulink>. Limit is invoked with a url="Actions.html">action</ulink>. Limit is invoked with a comma-separated
comma-separated list in place of a logging tag. The list has three list in place of a logging tag. The list has three elements:</para>
elements:</para>
<orderedlist> <orderedlist>
<listitem> <listitem>
@ -251,45 +237,8 @@ Limit:info:SSHA,3,60 net $FW tcp 22</programl
<section id="LimitImp"> <section id="LimitImp">
<title>How Limit is Implemented</title> <title>How Limit is Implemented</title>
<para>For those who are curious, the Limit action is implemented in <para>For those who are curious, the Limit action is implemented as
Shorewall 3.0 and Shorewall 3.2 as follows:</para> 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>
<programlisting>my @tag = split /,/, $tag; <programlisting>my @tag = split /,/, $tag;
@ -537,7 +486,7 @@ add_rule $chainref, '-j ACCEPT';
</listitem> </listitem>
<listitem> <listitem>
<para>MARK (Added in Shorewall 3.4.4)</para> <para>MARK</para>
<para><simplelist> <para><simplelist>
<member>[!]&lt;<emphasis>value</emphasis>&gt;[/&lt;<emphasis>mask</emphasis>&gt;][:C]</member> <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/actions<programlisting>DropBcasts</programlisting></para>
<para>/etc/shorewall/action.DropBcasts<programlisting># This file is empty</programlisting>When <para>/etc/shorewall/action.DropBcasts<programlisting># This file is empty</programlisting>/etc/shorewall/DropBcasts<programlisting>use Shorewall::Chains;
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;
log_rule_limit( $level, $chainref, 'DropBcasts', 'DROP', '', $tag, 'add', '' ) if $level ne ''; log_rule_limit( $level, $chainref, 'DropBcasts', 'DROP', '', $tag, 'add', '' ) if $level ne '';
add_rule( $chainref, '-m pkttype --pkttype broadcast -j DROP' ); add_rule( $chainref, '-m pkttype --pkttype broadcast -j DROP' );
1;</programlisting></para> 1;</programlisting></para>
</blockquote></para>
</example> </example>
<para>For a richer example, see <ulink url="PortKnocking.html">this <para>For a richer example, see <ulink url="PortKnocking.html">this

477
docs/Anatomy.xml
View File

@ -5,7 +5,7 @@
<!--$Id$--> <!--$Id$-->
<articleinfo> <articleinfo>
<title>Anatomy of Shorewall 4.0</title> <title>Anatomy of Shorewall 4.3</title>
<authorgroup> <authorgroup>
<author> <author>
@ -20,6 +20,8 @@
<copyright> <copyright>
<year>2007</year> <year>2007</year>
<year>2009</year>
<holder>Thomas M. Eastep</holder> <holder>Thomas M. Eastep</holder>
</copyright> </copyright>
@ -37,47 +39,46 @@
<section id="Products"> <section id="Products">
<title>Products</title> <title>Products</title>
<para>Shorewall 4.0 consists of four packages.</para> <para>Shorewall 4.3 consists of four packages.</para>
<orderedlist> <orderedlist>
<listitem> <listitem>
<para><emphasis role="bold">Shorewall-common</emphasis>. This package <para><emphasis role="bold">Shorewall</emphasis>. This package must be
must be installed on at least one system in your network. That system installed on at least one system in your network. It contains
must also have Shorewall-shell and/or Shorewall-perl installed.</para> everything needed to create an IPv4 firewall.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><emphasis role="bold">Shorewall-shell</emphasis>. This package <para><emphasis role="bold">Shorewall6</emphasis>. This package
includes the legacy Shorewall configuration compiler written in Bourne requires the Shorewall package and adds those components needed to
Shell. This compiler is very portable but suffers from performance create an IPv6 fireawall. </para>
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>
</listitem> </listitem>
<listitem> <listitem>
<para><emphasis role="bold">Shorewall-lite</emphasis>. Shorewall <para><emphasis role="bold">Shorewall-lite</emphasis>. Shorewall
allows for central administration of multiple firewalls through use of allows for central administration of multiple IPv4 firewalls through
Shorewall lite. The full Shorewall product (including Shorewall-common use of Shorewall lite. The full Shorewall product is installed on a
with Shorewall-shell and/or Shorewall-perl) is installed on a central central administrative system where compiled Shorewall scripts are
administrative system where compiled Shorewall scripts are generated. generated. These scripts are copied to the firewall systems where they
These scripts are copied to the firewall systems where they run under run under the control of Shorewall-lite.</para>
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> </listitem>
</orderedlist> </orderedlist>
</section> </section>
<section id="Shorewall"> <section id="Shorewall">
<title>Shorewall-common</title> <title>Shorewall</title>
<para>The Shorewall-common package includes a large number of files which <para>The Shorewall package includes a large number of files which are
are installed in <filename class="directory">/sbin</filename>, <filename installed in <filename class="directory">/sbin</filename>, <filename
class="directory">/usr/share/shorewall</filename>, <filename class="directory">/usr/share/shorewall</filename>, <filename
class="directory">/etc/shorewall</filename>, class="directory">/etc/shorewall</filename>,
<filename>/etc/init.d</filename> and <filename <filename>/etc/init.d</filename> and <filename
@ -113,6 +114,11 @@
actions.</para> actions.</para>
</listitem> </listitem>
<listitem>
<para><filename>compiler.pl</filename> - The configuration compiler
perl program.</para>
</listitem>
<listitem> <listitem>
<para><filename class="directory">configfiles</filename> - A <para><filename class="directory">configfiles</filename> - A
directory containing configuration files to copy to create a <ulink directory containing configuration files to copy to create a <ulink
@ -162,6 +168,16 @@
<filename>/etc/shorewall/modules</filename>.</para> <filename>/etc/shorewall/modules</filename>.</para>
</listitem> </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> <listitem>
<para><filename>version</filename> - A file containing the currently <para><filename>version</filename> - A file containing the currently
install version of Shorewall.</para> install version of Shorewall.</para>
@ -178,7 +194,7 @@
<section id="shorewall"> <section id="shorewall">
<title>/etc/shorewall</title> <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> installed.</para>
</section> </section>
@ -199,14 +215,6 @@
url="manpages/shorewall-vardir.html">shorewall-vardir</ulink>(5).</para> url="manpages/shorewall-vardir.html">shorewall-vardir</ulink>(5).</para>
<itemizedlist> <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> <listitem>
<para><filename>.iptables-restore-input</filename> - The file passed <para><filename>.iptables-restore-input</filename> - The file passed
as input to the iptables-restore program to initialize the firewall as input to the iptables-restore program to initialize the firewall
@ -290,69 +298,175 @@
</section> </section>
</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"> <section id="Shorewall-perl">
<title>Shorewall-perl</title> <title>Shorewall6</title>
<para>The Shorewall-perl product installs all of its files in <para>Shorewall6 installs its files in a number of directories:</para>
/usr/share/<filename class="directory">shorewall-perl</filename>.</para>
<itemizedlist> <section id="sbin6">
<listitem> <title>/sbin</title>
<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>
<listitem> <para>The <filename>/sbin/shorewall6</filename> shell program is used to
<para><filename>compiler.pl</filename> - The configuration compiler interact with Shorewall6. See <ulink
perl program.</para> url="manpages6/shorewall6.html">shorewall6</ulink>(8).</para>
</listitem> </section>
<listitem> <section id="share-shorewall6">
<para><filename>prog.*</filename> - Shell program fragments used as <title>/usr/share/shorewall6</title>
input to the compiler.</para>
</listitem>
<listitem> <para>The bulk of Shorewall6 is installed here.</para>
<para><filename class="directory">Shorewall</filename> - Directory
containing the Shorewall Perl modules used by the compiler.</para>
</listitem>
<listitem> <itemizedlist>
<para><filename>version</filename> - A file containing the currently <listitem>
install version of Shorewall-shell.</para> <para><filename>action.template</filename> - template file for
</listitem> creating <ulink url="Actions.html">actions</ulink>.</para>
</itemizedlist> </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>
<section id="Shorewall-lite"> <section id="Shorewall-lite">
@ -363,8 +477,8 @@
class="directory">/usr/share/shorewall-lite</filename>, <filename class="directory">/usr/share/shorewall-lite</filename>, <filename
class="directory">/etc/shorewall-lite</filename>, class="directory">/etc/shorewall-lite</filename>,
<filename>/etc/init.d</filename> and <filename <filename>/etc/init.d</filename> and <filename
class="directory">/var/lib/shorewall/</filename>. These are described in class="directory">/var/lib/shorewall-lite/</filename>. These are described
the sub-sections that follow.</para> in the sub-sections that follow.</para>
<section id="sbin-lite"> <section id="sbin-lite">
<title>/sbin</title> <title>/sbin</title>
@ -544,4 +658,181 @@
</itemizedlist> </itemizedlist>
</section> </section>
</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> </article>

87
docs/CompiledPrograms.xml
View File

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

20
docs/Documentation_Index.xml
View File

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

174
docs/FAQ.xml
View File

@ -37,9 +37,9 @@
</articleinfo> </articleinfo>
<caution> <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 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> release.</emphasis></para>
</caution> </caution>
@ -83,12 +83,9 @@
<title>(FAQ 37a) I just installed Shorewall on Debian and I can't find <title>(FAQ 37a) I just installed Shorewall on Debian and I can't find
the sample configurations.</title> the sample configurations.</title>
<para><emphasis role="bold">Answer:</emphasis> With Shorewall 3.x, the <para><emphasis role="bold">Answer:</emphasis> Beginning with
samples are included in the shorewall documentation package and are Shorewall 4.0, the samples are in the shorewall-common package and are
installed in <filename 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> class="directory">/usr/share/doc/shorewall-common/examples/</filename>.</para>
</section> </section>
</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 <para>Using this technique, you will want to configure your
DHCP/PPPoE/PPTP/… client to automatically restart Shorewall each DHCP/PPPoE/PPTP/… client to automatically restart Shorewall each
time that you get a new IP address.<note> time that you get a new IP address.</para>
<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>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -733,14 +723,6 @@ DNAT loc dmz:192.168.2.4 tcp 80 - <emph
save</command> and <command>shorewall[-lite] save</command> and <command>shorewall[-lite]
restore</command></ulink>.</para> restore</command></ulink>.</para>
</warning> </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>
<section id="faq2c"> <section id="faq2c">
@ -1026,13 +1008,10 @@ to debug/develop the newnat interface.</programlisting></para>
non-bridged traffic is not supported anymore.</programlisting> non-bridged traffic is not supported anymore.</programlisting>
<para>This kernel change, while necessary, means that Shorewall zones <para>This kernel change, while necessary, means that Shorewall zones
may no longer be defined in terms of bridge ports. See <ulink may no longer be defined in terms of bridge ports. See the<ulink
url="bridge-Shorewall-perl.html">the new Shorewall-shell bridging url="bridge-Shorewall-perl.html"> Shorewall-perl bridging
documentation</ulink> for information about configuring a documentation</ulink> for information about how to configure
bridge/firewall under kernel 2.6.20 and later with Shorewall shell or bridge/firewalls.<note>
the<ulink url="bridge-Shorewall-perl.html"> Shorewall-perl bridging
documentation</ulink> if you use Shorewall-perl
(highly-recommended).<note>
<para>Following the instructions in the new bridging documentation <para>Following the instructions in the new bridging documentation
will not prevent the above message from being issued.</para> will not prevent the above message from being issued.</para>
</note></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 <ulink url="manpages/shorewall-rules.html">rule</ulink> to that
effect.</para> effect.</para>
<para>Beginning with Shorewall 3.3.3, packets logged out of these <para>Packets logged out of these chains may have a source and/or
chains may have a source and/or destination that is not in any destination that is not in any defined zone (see the output of
defined zone (see the output of <command>shorewall[-lite] show <command>shorewall[-lite] show zones</command>). Remember that
zones</command>). Remember that zone membership involves both a zone membership involves both a firewall interface and an ip
firewall interface and an ip address.</para> address.</para>
</listitem> </listitem>
</varlistentry> </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 or you've done something silly like define a default route out of
an internal interface.</filename></para> an internal interface.</filename></para>
<para>In Shorewall 3.3.3 and later versions with OPTIMIZE=1 in <para>With OPTIMIZE=1 in <ulink
<ulink url="manpages/shorewall.conf.html">shorewall.conf</ulink>, url="manpages/shorewall.conf.html">shorewall.conf</ulink>, such
such packets may also be logged out of a &lt;zone&gt;2all chain or packets may also be logged out of a &lt;zone&gt;2all chain or the
the all2all chain.</para> all2all chain.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1407,10 +1386,10 @@ teastep@ursa:~$ </programlisting>The first number determines the maximum log
your defined zones(<command>shorewall[-lite] show zones</command> your defined zones(<command>shorewall[-lite] show zones</command>
and look at the printed zone definitions).</para> and look at the printed zone definitions).</para>
<para>In Shorewall 3.3.3 and later versions with OPTIMIZE=1 in <para>With OPTIMIZE=1 in <ulink
<ulink url="manpages/shorewall.conf.html">shorewall.conf</ulink>, url="manpages/shorewall.conf.html">shorewall.conf</ulink>, such
such packets may also be logged out of the fw2all chain or the packets may also be logged out of the fw2all chain or the all2all
all2all chain.</para> chain.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1770,21 +1749,6 @@ Creating input Chains...
at the -I (--insert) command.</para> at the -I (--insert) command.</para>
</section> </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"> <section id="faq43">
<title>(FAQ 43) I just installed the Shorewall RPM and Shorewall doesn't <title>(FAQ 43) I just installed the Shorewall RPM and Shorewall doesn't
start at boot time.</title> start at boot time.</title>
@ -1864,12 +1828,11 @@ iptables: Invalid argument
</itemizedlist> </itemizedlist>
<note> <note>
<para>Beginning with Shorewall 3.4.0, Shorewall no longer attempts to <para>Shorewall does not attempt to use policy match if you have no
use policy match if you have no IPSEC zones and you have not specified IPSEC zones and you have not specified the <option>ipsec</option>
the <option>ipsec</option> option on any entry in option on any entry in <filename>/etc/shorewall/hosts</filename>. The
<filename>/etc/shorewall/hosts</filename>. The subject message will subject message will still appear in your kernel log each time that
still appear in your kernel log each time that Shorewall determines Shorewall determines the capabilities of your kernel/iptables.</para>
the capabilities of your kernel/iptables.</para>
</note> </note>
</section> </section>
@ -2072,8 +2035,8 @@ We have an error talking to the kernel
<section id="faq12"> <section id="faq12">
<title>(FAQ 12) Is there a GUI?</title> <title>(FAQ 12) Is there a GUI?</title>
<para><emphasis role="bold">Answer:</emphasis> Yes! Shorewall 3.x <para><emphasis role="bold">Answer:</emphasis> Yes! Shorewall support is
support is available in Webmin 1.300. See <ulink available in Webmin. See <ulink
url="http://www.webmin.com">http://www.webmin.com</ulink></para> url="http://www.webmin.com">http://www.webmin.com</ulink></para>
</section> </section>
@ -2106,16 +2069,6 @@ We have an error talking to the kernel
type:</para> type:</para>
<programlisting><command>/sbin/shorewall[-lite] version</command> </programlisting> <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>
<section id="faq31"> <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 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 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 later, you can <emphasis role="bold">try</emphasis> to run Shorewall6
by hacking<filename> /usr/share/shorewall-perl/prog.footer6</filename> by hacking<filename> /usr/share/shorewall/prog.footer6</filename> and
and changing the kernel version test to check for your kernel version changing the kernel version test to check for your kernel version
rather than 2.6.25 (20625). But after that, you are on your rather than 2.6.25 (20625). But after that, you are on your
own.</para> own.</para>
@ -2399,69 +2352,8 @@ eth0 eth1 # eth1 = interface to local netwo
<title>(FAQ 60) What are the compatibility restrictions between <title>(FAQ 60) What are the compatibility restrictions between
Shorewall and Shorewall Lite</title> Shorewall and Shorewall Lite</title>
<para><emphasis role="bold">Answer:</emphasis> Beginning with version <para><emphasis role="bold">Answer:</emphasis> There are no
3.2.3, there are no compatibility constraints between Shorewall and compatibility constraints between Shorewall and Shorewall-lite.</para>
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>
</section> </section>
</section> </section>

44
docs/IPP2P.xml
View File

@ -41,26 +41,22 @@
</articleinfo> </articleinfo>
<caution> <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 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> 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> </caution>
<section id="Intro"> <section id="Intro">
<title>Introduction</title> <title>Introduction</title>
<para>Shorewall versions 2.2.0 and later include support for the ipp2p <para>Shorewall includes support for the ipp2p match facility. This is a
match facility. This is a departure from my usual policy in that the ipp2p departure from my usual policy in that the ipp2p match facility is
match facility is included in xtables-addons and is unlikely to ever be included in xtables-addons and is unlikely to ever be included in the
included in the kernel.org source tree. Questions about how to install kernel.org source tree. Questions about how to install xtables-addons or
xtables-addons or how to build your kernel and/or iptables should not be how to build your kernel and/or iptables should not be posted on the
posted on the Shorewall mailing lists but should rather be referred to the Shorewall mailing lists but should rather be referred to the Netfilter
Netfilter Mailing List.</para> Mailing List.</para>
</section> </section>
<section id="Scope"> <section id="Scope">
@ -91,25 +87,11 @@
<programlisting><command>iptables -m ipp2p --help</command></programlisting> <programlisting><command>iptables -m ipp2p --help</command></programlisting>
<para>You must not include the leading "--" on the option(s); Shorewall <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 will supply those characters for you. If you do not include an option then
then:</para> Shorewall will assume "edk,kazaa,gnu,dc".</para>
<itemizedlist> <para>If 'ipp2p' is specified, Shorewall will substitute
<listitem> "edk,kazaa,gnu,dc".</para>
<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>
</section> </section>
<section id="Example"> <section id="Example">

6
docs/IPSEC-2.6.xml
View File

@ -51,9 +51,9 @@
</articleinfo> </articleinfo>
<caution> <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 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> release.</emphasis></para>
</caution> </caution>
@ -83,7 +83,7 @@
</warning> </warning>
<section id="Overview"> <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 <para>This is <emphasis role="bold">not</emphasis> a HOWTO for Kernel 2.6
IPSEC -- for that, please see <ulink IPSEC -- for that, please see <ulink

30
docs/IPv6Support.xml
View File

@ -20,6 +20,8 @@
<copyright> <copyright>
<year>2008</year> <year>2008</year>
<year>2009</year>
<holder>Thomas M. Eastep</holder> <holder>Thomas M. Eastep</holder>
</copyright> </copyright>
@ -34,6 +36,13 @@
</legalnotice> </legalnotice>
</articleinfo> </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> <section>
<title>Overview</title> <title>Overview</title>
@ -77,9 +86,8 @@
of <filename>/sbin/shorewall</filename>. of <filename>/sbin/shorewall</filename>.
<filename>/sbin/shorewall</filename> only handles IPv4 while <filename>/sbin/shorewall</filename> only handles IPv4 while
<filename>/sbin/shorewall6</filename> handles only IPv6.. Shorewall6 <filename>/sbin/shorewall6</filename> handles only IPv6.. Shorewall6
depends on both Shorewall-common and on Shorewall-perl. The depends on Shorewall. The Shorewall6 configuration is stored in
Shorewall6 configuration is stored in <filename <filename class="directory">/etc/shorewall6</filename>.</para>
class="directory">/etc/shorewall6</filename>.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -476,11 +484,7 @@ ACCEPT net:wlan0:&lt;2002:ce7c:92b4::3&gt; tcp
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para>Also, please note that since Shorewall6 is based on <para></para>
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>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -505,19 +509,15 @@ ACCEPT net:wlan0:&lt;2002:ce7c:92b4::3&gt; tcp
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Shorewall-common 4.2.4 or later.</para> <para>Shorewall 4.3.5 or later.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Shorewall-perl 4.2.4 or later.</para> <para>Shorewall6 4.3.5 or later.</para>
</listitem>
<listitem>
<para>Shorewall6 4.2.4 or later.</para>
</listitem> </listitem>
</itemizedlist> </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> remote firewalls to allow for central IPv6 firewall administration.</para>
</section> </section>

303
docs/Install.xml
View File

@ -22,6 +22,8 @@
<year>2006</year> <year>2006</year>
<year>2009</year>
<holder>Thomas M. Eastep</holder> <holder>Thomas M. Eastep</holder>
</copyright> </copyright>
@ -37,9 +39,9 @@
</articleinfo> </articleinfo>
<caution> <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 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> release.</emphasis></para>
</caution> </caution>
@ -47,7 +49,9 @@
<para>Before attempting installation, I strongly urge you to read and <para>Before attempting installation, I strongly urge you to read and
print a copy of the <ulink url="shorewall_quickstart_guide.htm">Shorewall print a copy of the <ulink url="shorewall_quickstart_guide.htm">Shorewall
QuickStart</ulink> Guide for the configuration that most closely matches 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>
<important> <important>
@ -91,27 +95,13 @@
page</ulink>.</para> page</ulink>.</para>
<para>If you try to install the wrong package, it probably won't <para>If you try to install the wrong package, it probably won't
work.<note> work.</para>
<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>
</listitem> </listitem>
<listitem> <listitem>
<para>Install the RPMs</para> <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> <caution>
<para>Some users are in the habit of using the <command>rpm <para>Some users are in the habit of using the <command>rpm
@ -123,15 +113,6 @@
links.</para> links.</para>
</caution> </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> <note>
<para>Shorewall is dependent on the iproute package. Unfortunately, <para>Shorewall is dependent on the iproute package. Unfortunately,
some distributions call this package iproute2 which will cause the some distributions call this package iproute2 which will cause the
@ -146,39 +127,7 @@
<programlisting><command>rpm -ivh --nodeps &lt;rpms&gt;</command></programlisting> <programlisting><command>rpm -ivh --nodeps &lt;rpms&gt;</command></programlisting>
</note> </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>Example:<programlisting><command>rpm -ivh shorewall-4.3.5-0base.noarch.rpm</command></programlisting></para>
<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>
</listitem> </listitem>
</orderedlist> </orderedlist>
</section> </section>
@ -186,35 +135,16 @@
<section id="Install_Tarball"> <section id="Install_Tarball">
<title>Install using tarball</title> <title>Install using tarball</title>
<note> <para>To install Shorewall using the tarball and install script:</para>
<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>
<orderedlist> <orderedlist>
<listitem> <listitem>
<para>unpack the tarballs:<programlisting><command>tar -jxf shorewall-common-4.0.0.tar.bz2</command> <para>unpack the tarballs:<programlisting><command>tar -jxf shorewall-4.3.5.tar.bz2</command></programlisting></para>
<command>tar -jxf shorewall-perl-4.0.0.tar.bz2
</command></programlisting></para>
</listitem> </listitem>
<listitem> <listitem>
<para>cd to the shorewall-perl directory (the version is encoded in <para>cd to the shorewall directory (the version is encoded in the
the directory name as in <quote>shorewall-perl-4.0.0</quote>).</para> directory name as in <quote>shorewall-4.3.5</quote>).</para>
</listitem> </listitem>
<listitem> <listitem>
@ -223,34 +153,6 @@
<programlisting><command>./install.sh</command></programlisting> <programlisting><command>./install.sh</command></programlisting>
</listitem> </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> <listitem>
<para>If the install script was unable to configure Shorewall to be <para>If the install script was unable to configure Shorewall to be
started automatically at boot, see <ulink started automatically at boot, see <ulink
@ -280,11 +182,7 @@
Shorewall, please modify your Shorewall, please modify your
<filename>/etc/apt/preferences:</filename></para> <filename>/etc/apt/preferences:</filename></para>
<para><programlisting>Package: shorewall-common <para><programlisting>Package: shorewall
Pin: release o=Debian,a=testing
Pin-Priority: 700
Package: shorewall-perl
Pin: release o=Debian,a=testing Pin: release o=Debian,a=testing
Pin-Priority: 700 Pin-Priority: 700
@ -292,7 +190,7 @@ Package: shorewall-doc
Pin: release o=Debian,a=testing Pin: release o=Debian,a=testing
Pin-Priority: 700</programlisting><emphasis role="bold"><emphasis>Then Pin-Priority: 700</programlisting><emphasis role="bold"><emphasis>Then
run:</emphasis></emphasis><programlisting># apt-get update 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 <para><emphasis><emphasis role="bold">Once you have completed configuring
Shorewall, you can enable startup at boot time by setting startup=1 in 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> <listitem>
<para>Upgrade the RPM</para> <para>Upgrade the RPM</para>
<programlisting><command>rpm -Uvh &lt;compiler rpm file&gt; ... &lt;shorewall-common rpm file&gt; </command></programlisting> <programlisting><command>rpm -Uvh &lt;shorewall 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>
<note> <note>
<para>Shorewall is dependent on the iproute package. Unfortunately, <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 <para>This may be worked around by using the --nodeps option of
rpm.</para> 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> </note>
</listitem> </listitem>
@ -420,30 +309,12 @@ Pin-Priority: 700</programlisting><emphasis role="bold"><emphasis>Then
<orderedlist> <orderedlist>
<listitem> <listitem>
<para>unpack the tarballs:<programlisting><command>tar -jxf shorewall-common-4.0.0.tar.bz2</command> <para>unpack the tarball:<programlisting><command>tar -jxf shorewall-4.3.5.tar.bz2</command></programlisting></para>
<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>
</listitem> </listitem>
<listitem> <listitem>
<para>cd to the shorewall-perl directory (the version is encoded in <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> the directory name as in <quote>shorewall-4.3.5</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>
</listitem> </listitem>
<listitem> <listitem>
@ -485,140 +356,6 @@ tar -jxf shorewall-shell-4.0.0.tar.bz2</command> (if you use this compiler)</pro
</warning> </warning>
</section> </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"> <section id="Config_Files">
<title>Configuring Shorewall</title> <title>Configuring Shorewall</title>

70
docs/Introduction.xml
View File

@ -16,7 +16,7 @@
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate> <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
<copyright> <copyright>
<year>2003-2007</year> <year>2003-2009</year>
<holder>Thomas M. Eastep</holder> <holder>Thomas M. Eastep</holder>
</copyright> </copyright>
@ -35,8 +35,8 @@
<section id="Intro"> <section id="Intro">
<title>Introduction</title> <title>Introduction</title>
<para>The information in this document applies only to 4.x releases of <para>The information in this document applies only to 4.3 and later
Shorewall.</para> releases of Shorewall.</para>
<section id="Glossary"> <section id="Glossary">
<title>Glossary</title> <title>Glossary</title>
@ -337,12 +337,11 @@ ACCEPT net $FW tcp 22</programlisting>
<section id="Compile"> <section id="Compile">
<title>Compile then Execute</title> <title>Compile then Execute</title>
<para>Shorewall versions beginning with 3.2.0 use a "compile" then <para>Shorewall uses a "compile" then "execute" approach. The Shorewall
"execute" approach. The Shorewall configuration compiler reads the configuration compiler reads the configuration files and generates a shell
configuration files and generates a shell script. Errors in the script. Errors in the compilation step cause the script to be discarded
compilation step cause the script to be discarded and the command to be and the command to be aborted. If the compilation step doesn't find any
aborted. If the compilation step doesn't find any errors then the shell errors then the shell script is executed.</para>
script is executed.</para>
<para>The 'compiled' scripts are placed in the directory <filename <para>The 'compiled' scripts are placed in the directory <filename
class="directory">/var/lib/shorewall</filename> and are named to class="directory">/var/lib/shorewall</filename> and are named to
@ -355,54 +354,37 @@ ACCEPT net $FW tcp 22</programlisting>
<section id="Packages"> <section id="Packages">
<title>Shorewall Packages</title> <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> <orderedlist>
<listitem> <listitem>
<para><emphasis role="bold">Shorewall-common</emphasis>. This package <para><emphasis role="bold">Shorewall</emphasis>. This package must be
must be installed on at least one system in your network. That system installed on at least one system in your network. It contains
must also have Shorewall-shell and/or Shorewall-perl installed.</para> everything needed to create an IPv4 firewall.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><emphasis role="bold">Shorewall-shell</emphasis>. This package <para><emphasis role="bold">Shorewall6</emphasis>. This package
includes the legacy Shorewall configuration compiler written in Bourne requires the Shorewall package and adds those components needed to
Shell. This compiler is very portable but suffers from performance create an IPv6 fireawall.</para>
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>
</listitem> </listitem>
<listitem> <listitem>
<para><emphasis role="bold">Shorewall-lite</emphasis>. Shorewall <para><emphasis role="bold">Shorewall-lite</emphasis>. Shorewall
allows for central administration of multiple firewalls through use of allows for central administration of multiple IPv4 firewalls through
Shorewall lite. The full Shorewall product (along with Shorewall-shell use of Shorewall lite. The full Shorewall product is installed on a
and/or Shorewall-perl) are installed on a central administrative central administrative system where compiled Shorewall scripts are
system where compiled Shorewall scripts are generated. These scripts generated. These scripts are copied to the firewall systems where they
are copied to the firewall systems where they run under the control of run under the control of Shorewall-lite.</para>
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>
</listitem> </listitem>
<listitem> <listitem>
<para><emphasis role="bold">Shorewall6-lite</emphasis> - The IPv6 <para><emphasis role="bold">Shorewall6-lite</emphasis>. Shorewall
equivalent 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>
</orderedlist> </orderedlist>
</section> </section>

26
docs/MAC_Validation.xml
View File

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

79
docs/Macros.xml
View File

@ -41,9 +41,9 @@
</articleinfo> </articleinfo>
<caution> <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 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> release.</emphasis></para>
</caution> </caution>
@ -112,33 +112,9 @@ PARAM - - tcp 135,139,445
when you invoke the macro. The SMB macro shown above is parameterized when you invoke the macro. The SMB macro shown above is parameterized
(note PARAM in the TARGET column).</para> (note PARAM in the TARGET column).</para>
<para><emphasis role="bold">Shorewall versions prior to 4.2.0:</emphasis> <para>When invoking a parameterized macro, you follow the name of the
When invoking a parameterized macro, you follow the name of the macro with macro with the action that you want to substitute for PARAM enclosed in
a slash ("/") and the action that you want to substitute for PARAM.</para> parentheses. </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>Example:</para> <para>Example:</para>
@ -168,11 +144,10 @@ ACCEPT loc fw tcp 135,139,445</programlisting>
<listitem> <listitem>
<para>If a value other than "-" appears in both the macro body and <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 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 examined and the appropriate action is taken. If the value in the
running Shorewall 3.0.1 or later). If the value in the invocation invocation appears to be an address (IP or MAC) or the name of an
appears to be an address (IP or MAC) or the name of an ipset, then ipset, then it is placed after the value in the macro body.
it is placed after the value in the macro body. Otherwise, it is Otherwise, it is placed before the value in the macro body.</para>
placed before the value in the macro body.</para>
<para>Example 1:</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> DNAT:info net loc:192.168.1.5 tcp 25</programlisting>
</blockquote> </blockquote>
<para>Beginning with Shorewall 3.1, you may also specify SOURCE or <para>You may also specify SOURCE or DEST in the SOURCE and DEST
DEST in the SOURCE and DEST columns. This allows you to define columns. This allows you to define macros that work in both
macros that work in both directions.</para> directions.</para>
<para>Example 3:</para> <para>Example 3:</para>
<blockquote> <blockquote>
<para><filename>/etc/shorewall/macro.SMBBI</filename> (Note: there <para><filename>/etc/shorewall/macro.SMBBI</filename> (Note: there
is already a macro like this released as part of Shorewall 3.1 and is already a standard macro like this released as part of
later):</para> Shorewall):</para>
<programlisting>#ACTION SOURCE DEST PROTO DEST SOURCE ORIGINAL RATE USER/ <programlisting>#ACTION SOURCE DEST PROTO DEST SOURCE ORIGINAL RATE USER/
# PORT PORT(S) DEST LIMIT GROUP # 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> from actions cannot themselves invoke other actions.</para>
</section> </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"> <section id="Defining">
<title>Defining your own Macros</title> <title>Defining your own Macros</title>

12
docs/ManualChains.xml
View File

@ -18,7 +18,9 @@
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate> <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
<copyright> <copyright>
<year>2007</year> <year>2008</year>
<year>2009</year>
<holder>Thomas M. Eastep</holder> <holder>Thomas M. Eastep</holder>
</copyright> </copyright>
@ -37,10 +39,10 @@
<section id="Intro"> <section id="Intro">
<title>Introduction</title> <title>Introduction</title>
<para>Manual chains were introduced in Shorewall-perl 4.0.6; for Perl <para>For Perl programmers, manual chains provide an alternative to
programmers, manual chains provide an alternative to Actions with Actions with extension scripts. Manual chains are chains which you create
extension scripts. Manual chains are chains which you create and populate and populate yourself using the low-level functions in
yourself using the low-level functions in Shorewall::Chains.</para> Shorewall::Chains.</para>
<para>Manual chains work in conjunction with the <para>Manual chains work in conjunction with the
<firstterm>compile</firstterm> <ulink <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> </articleinfo>
<warning> <warning>
<para>This document describes the Multi-ISP facility in Shorewall 4.0 and <para>This document describes the Multi-ISP facility in Shorewall 4.3.5
later. If you are running an earlier release, please see the documentation and later. If you are running an earlier release, please see the
for that release.</para> documentation for that release.</para>
</warning> </warning>
<warning> <warning>
@ -76,14 +76,13 @@
<section id="Support"> <section id="Support">
<title>Multiple Internet Connection Support</title> <title>Multiple Internet Connection Support</title>
<para>Beginning with Shorewall 2.3.2, limited support is included for <para>Shorewall includes limited support for multiple Internet
multiple Internet connections. Limitations of this support are as connections. Limitations of this support are as follows:</para>
follows:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>It utilizes static routing configuration. As such, there is no <para>It utilizes static routing configuration. If there is a change
provision for reacting to the failure of any of the uplinks.</para> in the routing topopogy, Shorewall must be restarted.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -94,13 +93,6 @@
filter should have no effect on routing.</para> filter should have no effect on routing.</para>
</listitem> </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> <listitem>
<para>For most routing applications, <ulink <para>For most routing applications, <ulink
url="http://www.quagga.net/">Quagga</ulink> is a better solution 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. value and will restore the packet mark in the PREROUTING CHAIN.
Mark values must be in the range 1-255.</para> Mark values must be in the range 1-255.</para>
<para>Beginning with Shorewall version 3.2.0 Beta 6, you may use <para>Alternatively, you may set HIGH_ROUTE_MARKS=Yes in
may set HIGH_ROUTE_MARKS=Yes in
<filename>/etc/shorewall/shorewall.conf</filename>. This allows <filename>/etc/shorewall/shorewall.conf</filename>. This allows
you to:</para> you to:</para>
@ -417,7 +408,7 @@
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>optional (added in Shorewall 3.2.2)</term> <term>optional</term>
<listitem> <listitem>
<para>Shorewall will determine of this interface is up and <para>Shorewall will determine of this interface is up and
@ -432,8 +423,7 @@
without error doesn't mean that traffic can actually be without error doesn't mean that traffic can actually be
sent through the interface.</para> sent through the interface.</para>
<para>Beginning with Shorewall-perl 4.0.3, you can supply <para>You can supply an 'isusable' <ulink
an 'isusable' <ulink
url="shorewall_extension_scripts.htm">extension url="shorewall_extension_scripts.htm">extension
script</ulink> to extend Shorewall's interface state script</ulink> to extend Shorewall's interface state
detection.</para> detection.</para>
@ -442,8 +432,7 @@
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>src=<replaceable>source-address</replaceable> (Added in <term>src=<replaceable>source-address</replaceable></term>
Shorewall-perl 4.1.5)</term>
<listitem> <listitem>
<para>Specifies the source address to use when routing to <para>Specifies the source address to use when routing to
@ -457,8 +446,7 @@
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term>mtu=<replaceable>number</replaceable> (Added in <term>mtu=<replaceable>number</replaceable></term>
Shorewall-perl 4.1.5)</term>
<listitem> <listitem>
<para>Specifies the MTU when forwarding through this <para>Specifies the MTU when forwarding through this
@ -469,8 +457,7 @@
<varlistentry> <varlistentry>
<term><emphasis <term><emphasis
role="bold">fallback[=<replaceable>weight</replaceable>] role="bold">fallback[=<replaceable>weight</replaceable>]</emphasis></term>
(Added in Shorewall-perl 4.2.5)</emphasis></term>
<listitem> <listitem>
<para>Indicates that a default route through the provider <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 <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 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 url="traffic_shaping.htm">/etc/shorewall/tcrules</ulink> </para>
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>
<programlisting>#MARK SOURCE DEST PROTO PORT(S) CLIENT USER TEST <programlisting>#MARK SOURCE DEST PROTO PORT(S) CLIENT USER TEST
# PORT(S) # PORT(S)
@ -863,12 +847,11 @@ eth3 eth2 16.105.78.4</programlisting></para>
<section id="route_rules"> <section id="route_rules">
<title>/etc/shorewall/route_rules</title> <title>/etc/shorewall/route_rules</title>
<para>The <filename>/etc/shorewall/route_rules</filename> file was added <para>The <filename>route_rules</filename> file allows assigning certain
in Shorewall version 3.2.0. The <filename>route_rules</filename> file traffic to a particular provider just as entries in the
allows assigning certain traffic to a particular provider just as <filename>tcrules</filename> file. The difference between the two files
entries in the <filename>tcrules</filename> file. The difference between is that entries in <filename>route_rules</filename> are independent of
the two files is that entries in <filename>route_rules</filename> are Netfilter.</para>
independent of Netfilter.</para>
<section id="Routing_rules"> <section id="Routing_rules">
<title>Routing Rules</title> <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"> <section id="USE_DEFAULT_RT">
<title>USE_DEFAULT_RT</title> <title>USE_DEFAULT_RT</title>
<para>Beginning with Shorewall 4.2.0 Beta3, Shorewall-perl has supported <para>USE_DEFAULT_RT is an option in <ulink
a USE_DEFAULT_RT option in <ulink
url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5).</para> url="manpages/shorewall.conf.html">shorewall.conf</ulink> (5).</para>
<para>One of the drawbacks of the Multi-ISP support as described in the <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 <para>All provider gateways must be specified explicitly in the
GATEWAY column. 'detect' may not be specified. Note that for ppp GATEWAY column. 'detect' may not be specified. Note that for ppp
interfaces, the GATEWAY may remain unspecified ("-").<note> interfaces, the GATEWAY may remain unspecified ("-").<note>
<para>Beginning with Shorewall 4.2.6, 'detect' may be specified <para>'detect' may be specified for interfaces whose
for interfaces whose configuration is managed by dhcpcd. configuration is managed by dhcpcd. Shorewall will use dhcpcd's
Shorewall will use dhcpcd's database to determine the gateway IP database to determine the gateway IP address.</para>
address.</para>
</note></para> </note></para>
</listitem> </listitem>
@ -1084,19 +1065,15 @@ shorewall 2 2 - eth0 192.168.1.254 track,balance=2,optional<
<section id="swping"> <section id="swping">
<title>SWPING</title> <title>SWPING</title>
<para>Beginning with Shorewall 4.2.6, Shorewall includes a sample <para>Shorewall includes a sample monitoring script
monitoring script <filename>swping</filename>. The <filename>swping</filename>. The <filename>swping</filename> file is
<filename>swping</filename> file is available in the main directory available in the main directory contained in the Shorewall-common
contained in the Shorewall-common tarball and is included in the tarball and is included in the Shorewall-common documentation
Shorewall-common documentation directory on the Shorewall-common RPM. directory on the Shorewall-common RPM. The script is inspired by
The script is inspired by Angsuman Chakraborty's <ulink 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> 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> 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> <important>
<para>These samples are offered <emphasis>as is</emphasis> — they <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 work for me but I don't make any claim that they will work for
@ -1411,8 +1388,7 @@ exit 0;
<section id="Shared"> <section id="Shared">
<title>Two Providers Sharing an Interface</title> <title>Two Providers Sharing an Interface</title>
<para>Shared interface support is available only in Shorewall-perl 4.2.0 <para>Shared interface support has the following characteristics"</para>
and later.</para>
<orderedlist numeration="loweralpha"> <orderedlist numeration="loweralpha">
<listitem> <listitem>
@ -1685,10 +1661,10 @@ wlan0 192.168.0.0/24</programlisting><note>
<programlisting>ROUTE_FILTER=No <programlisting>ROUTE_FILTER=No
RESTORE_DEFAULT_ROUTE=No</programlisting> RESTORE_DEFAULT_ROUTE=No</programlisting>
<para>The RESTORE_DEFAULT_ROUTE option was added in Shorewall-perl 4.2.6 <para>RESTORE_DEFAULT_ROUTE=No causes the default route in the main table
and causes the default route in the main table to be deleted when the to be deleted when the Comcast link is unavailable. That way, the default
Comcast link is unavailable. That way, the default route in the default route in the default table will be used until Comcast is available
table will be used until Comcast is available again.</para> again.</para>
<para><filename>/etc/shorewall/providers</filename>:</para> <para><filename>/etc/shorewall/providers</filename>:</para>

4
docs/Multiple_Zones.xml
View File

@ -35,9 +35,9 @@
</articleinfo> </articleinfo>
<caution> <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 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> release.</emphasis></para>
</caution> </caution>

11
docs/NAT.xml
View File

@ -35,9 +35,9 @@
</articleinfo> </articleinfo>
<caution> <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 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> release.</emphasis></para>
</caution> </caution>
@ -48,7 +48,8 @@
<para><emphasis role="bold">If all you want to do is forward ports to <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. 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 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> </important>
<para>One-to-one NAT is a way to make systems behind a firewall and <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 <quote>yes</quote> or <quote>Yes</quote> (and the ALL INTERFACES COLUMN
also contains <quote>Yes</quote> or <quote>yes</quote>) then such also contains <quote>Yes</quote> or <quote>yes</quote>) then such
packets are redirected; otherwise, such packets are not redirected. This 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 feature requires that you enabled CONFIG_IP_NF_NAT_LOCAL in your
you must have enabled CONFIG_IP_NF_NAT_LOCAL in your kernel.</para> kernel.</para>
</note> </note>
<para>Entries in <filename>/etc/shorewall/nat</filename> only arrange for <para>Entries in <filename>/etc/shorewall/nat</filename> only arrange for

22
docs/PortKnocking.xml
View File

@ -89,20 +89,7 @@
<listitem> <listitem>
<para>Create /etc/shorewall/SSHKnock with the following <para>Create /etc/shorewall/SSHKnock with the following
contents.</para> contents.<programlisting>use Shorewall::Chains;
<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;
if ( $level ) { if ( $level ) {
log_rule_limit( $level, log_rule_limit( $level,
@ -148,10 +135,9 @@ SSHKnock:info net $FW tcp 22,1599,1600,1601<
</listitem> </listitem>
<listitem> <listitem>
<para>If you wish to use SSHKnock with a forwarded connection, you <para>Assume that you forward port 22 from external IP address
must be using Shorewall 2.3.1 or later for fullest protection. Assume 206.124.146.178 to internal system 192.168.1.5. In
that you forward port 22 from external IP address 206.124.146.178 to /etc/shorewall/rules:</para>
internal system 192.168.1.5. In /etc/shorewall/rules:</para>
<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S) SOURCE ORIGINAL <programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S) SOURCE ORIGINAL
# PORT(S) DEST # 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> <copyright>
<year>2007</year> <year>2007</year>
<year>2009</year>
<holder>Thomas M. Eastep</holder> <holder>Thomas M. Eastep</holder>
</copyright> </copyright>
@ -37,43 +39,47 @@
<section id="What"> <section id="What">
<title>Shorewall-perl - What is it?</title> <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 compiler written in Perl. The advantages of using Shorewall-perl over
Shorewall-shell (the shell-based compiler included in earlier Shorewall Shorewall-shell (the shell-based compiler included in earlier Shorewall
3.x releases) are:</para> 3.x releases) were:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>The Shorewall-perl compiler is much faster.</para> <para>The Shorewall-perl compiler was much faster.</para>
</listitem> </listitem>
<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 <command>iptables-restore</command> to instantiate the Netfilter
configuration. So it runs much faster than the script generated by the configuration. So it ran much faster than the script generated by the
Shorewall-shell compiler and doesn't stop new connections during Shorewall-shell compiler and did not stop new connections during
<command>shorewall restart</command>.</para> <command>shorewall restart</command>.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>The Shorewall-perl compiler does more thorough checking of the <para>The Shorewall-perl compiler did more thorough checking of the
configuration than the Shorewall-shell compiler does.</para> configuration than the Shorewall-shell compiler did.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>The error messages produced by the compiler are better, more <para>The error messages produced by the compiler were better, more
consistent and always include the file name and line number where the consistent and always included the file name and line number where the
error was detected.</para> error was detected.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Going forward, the Shorewall-perl compiler will get all <para>Going forward, the Shorewall-perl compiler got all enhancements;
enhancements; the Shorewall-shell compiler will only get those the Shorewall-shell compilerl only got those enhancements that were
enhancements that are easy to retrofit.</para> easy to retrofit.</para>
</listitem> </listitem>
</itemizedlist> </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>
<section id="DownSide"> <section id="DownSide">
@ -555,112 +561,14 @@ DNAT- net 192.168.1.3 tcp 21</programl
<section id="PerlDep"> <section id="PerlDep">
<title>Dependence on Perl</title> <title>Dependence on Perl</title>
<para>Shorewall-perl is dependent on Perl (see the next section) which <para>Shorewall-perl is dependent on Perl which has a large disk
has a large disk footprint. This makes Shorewall-perl less desirable in footprint. This makes Shorewall-perl less desirable in an embedded
an embedded environment. The best way to work around this limitation is environment. The best way to work around this limitation is to install
to install Shorewall-perl on an administrative system and employ Shorewall-perl on an administrative system and employ Shorewall-lite on
Shorewall-lite on your embedded systems.</para> your embedded systems.</para>
</section> </section>
</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"> <section id="Modules">
<title>The Shorewall Perl Modules</title> <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> <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
<copyright> <copyright>
<year>2001-2007</year> <year>2001-2009</year>
<holder>Thomas M. Eastep</holder> <holder>Thomas M. Eastep</holder>
</copyright> </copyright>
@ -35,9 +35,9 @@
</articleinfo> </articleinfo>
<caution> <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 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> release.</emphasis></para>
</caution> </caution>
@ -198,11 +198,10 @@ eth0 eth1 206.124.146.178</programlisting>
connections using those addresses may be severed.</para> connections using those addresses may be severed.</para>
</warning> </warning>
<para>Beginning with Shorewall 1.3.14, Shorewall can actually create the <para>Shorewall can create the <quote>label</quote> (virtual interface)
<quote>label</quote> (virtual interface) so that you can see the created so that you can see the created address using ifconfig. In addition to
address using ifconfig. In addition to setting ADD_SNAT_ALIASES=Yes, you setting ADD_SNAT_ALIASES=Yes, you specify the virtual interface name in
specify the virtual interface name in the INTERFACE column as the INTERFACE column as follows.</para>
follows.</para>
<para><filename>/etc/shorewall/masq</filename><programlisting>#INTERFACE SUBNET ADDRESS <para><filename>/etc/shorewall/masq</filename><programlisting>#INTERFACE SUBNET ADDRESS
eth0:0 eth1 206.124.146.178</programlisting></para> 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> connections using those addresses may be severed.</para>
</warning> </warning>
<para>Beginning with Shorewall 1.3.14, Shorewall can actually create the <para>Shorewall can create the <quote>label</quote> (virtual interface)
<quote>label</quote> (virtual interface) so that you can see the created so that you can see the created address using ifconfig. In addition to
address using ifconfig. In addition to setting ADD_IP_ALIASES=Yes, you setting ADD_IP_ALIASES=Yes, you specify the virtual interface name in
specify the virtual interface name in the INTERFACE column as the INTERFACE column as follows.</para>
follows.</para>
<para><filename>/etc/shorewall/nat</filename><programlisting>#EXTERNAL INTERFACE INTERNAL ALL INTERFACES LOCAL <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> 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 eth1:0 is 192.168.20.254. You simply want your firewall to route
between these two subnetworks.</title> 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> <para>In <filename>/etc/shorewall/zones</filename>:</para>
<programlisting>#ZONE TYPE OPTIONS <programlisting>#ZONE TYPE OPTIONS

4
docs/UPnP.xml
View File

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

11
docs/blacklisting_support.xml
View File

@ -43,9 +43,9 @@
<orderedlist> <orderedlist>
<listitem> <listitem>
<para>BLACKLISTNEWONLY=No -- All incoming packets are checked <para>BLACKLISTNEWONLY=No -- All incoming packets are checked against
against the blacklist. New blacklist entries can be used to terminate the blacklist. New blacklist entries can be used to terminate existing
existing connections.</para> connections.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -189,12 +189,7 @@ ipset -B Blacklist 206.124.146.177 -b SMTP</programlisting>
<para>show dynamic - displays the dynamic blacklisting <para>show dynamic - displays the dynamic blacklisting
configuration.</para> configuration.</para>
</listitem> </listitem>
</itemizedlist>
<para>If you are running Shorewall 3.2.0 Beta2 or later, there are two
additional commands:</para>
<itemizedlist>
<listitem> <listitem>
<para>logdrop <emphasis>&lt;ip address list&gt;</emphasis> - causes <para>logdrop <emphasis>&lt;ip address list&gt;</emphasis> - causes
packets from the listed IP addresses to be dropped and logged by the 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> <copyright>
<year>2007</year> <year>2007</year>
<year>2009</year>
<holder>Thomas M. Eastep</holder> <holder>Thomas M. Eastep</holder>
</copyright> </copyright>
@ -35,10 +37,8 @@
</articleinfo> </articleinfo>
<caution> <caution>
<para><emphasis role="bold">This article applies to Shorewall-perl 4.0 and <para><emphasis role="bold">This article applies to Shorewall-perl 4.3 and
later. If you are running a version of Shorewall earlier than Shorewall later.</emphasis></para>
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>
</caution> </caution>
<section id="Background"> <section id="Background">

157
docs/configuration_file_basics.xml
View File

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

37
docs/fallback.xml
View File

@ -18,7 +18,7 @@
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate> <pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
<copyright> <copyright>
<year>2001-2005</year> <year>2001-2009</year>
<holder>Thomas M. Eastep</holder> <holder>Thomas M. Eastep</holder>
</copyright> </copyright>
@ -44,22 +44,13 @@
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>cd to the distribution directory for the version of Shoreline <para>cd to the distribution directory for the version of Shoreline
Firewall that you are currently running (NOT the version that you want Firewall that you want to fall back to.</para>
to fall back to).</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Type <quote>./fallback.sh</quote></para> <para>Type <quote>./install.sh</quote></para>
</listitem> </listitem>
</itemizedlist> </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>
<section id="RPM"> <section id="RPM">
@ -91,26 +82,4 @@
<para>If you installed using an rpm, at a root shell prompt type <para>If you installed using an rpm, at a root shell prompt type
<quote>rpm -e shorewall</quote>.</para> <quote>rpm -e shorewall</quote>.</para>
</section> </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> </article>

123
docs/ipsets.xml
View File

@ -78,7 +78,7 @@
<para>Example: "+Mirrors"</para> <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> follows:</para>
<itemizedlist> <itemizedlist>
@ -130,76 +130,21 @@
<para><filename>/etc/shorewall/rules</filename><programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S) <para><filename>/etc/shorewall/rules</filename><programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
ACCEPT +sshok $FW tcp 22</programlisting></para> 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>So:</para>
<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>Regardless of the setting of SAVE_IPSETS, the <command>shorewall <orderedlist numeration="upperroman">
-f start</command> and <command>shorewall restore</command> commands <listitem>
will restore the ipset contents corresponding to the Shorewall <para>Your ipsets must be loaded before Shorewall starts. You are free
configuration restored provided that the saved Shorewall configuration to try to do that with the following code in
specified exists.</para> <filename>/etc/shorewall/init (it works for me; your mileage may
vary)</filename>:</para>
<para>For example, <command>shorewall restore standard</command> would <programlisting>if [ "$COMMAND" = start ]; then
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
ipset -U :all: :all: ipset -U :all: :all:
ipset -U :all: :default: ipset -U :all: :default:
ipset -F ipset -F
@ -207,32 +152,30 @@ ACCEPT +sshok $FW tcp 22</programlisting></para>
ipset -R &lt; /etc/shorewall/ipsets ipset -R &lt; /etc/shorewall/ipsets
fi</programlisting> fi</programlisting>
<para>The file <filename>/etc/shorewall/ipsets</filename> will <para>The file <filename>/etc/shorewall/ipsets</filename> will
normally be produced using the <command>ipset -S</command> normally be produced using the <command>ipset -S</command>
command.</para> command.</para>
<para>The above will work most of the time but will fail in a <para>The above will work most of the time but will fail in a
<command>shorewall stop</command> - <command>shorewall <command>shorewall stop</command> - <command>shorewall start</command>
start</command> sequence if you use ipsets in your routestopped file sequence if you use ipsets in your routestopped file (see
(see below).</para> below).</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Your ipsets may not be reloaded until Shorewall is stopped or <para>Your ipsets may not be reloaded until Shorewall is stopped or
cleared.</para> cleared.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>If you specify ipsets in your routestopped file then Shorewall <para>If you specify ipsets in your routestopped file then Shorewall
must be cleared in order to reload your ipsets.</para> must be cleared in order to reload your ipsets.</para>
</listitem> </listitem>
</orderedlist> </orderedlist>
<para>As a consequence, scripts generated by the Perl-based compiler <para>As a consequence, scripts generated by the Perl-based compiler will
will ignore <filename>/etc/shorewall/ipsets</filename> and will issue a ignore <filename>/etc/shorewall/ipsets</filename> and will issue a warning
warning if you set SAVE_IPSETS=Yes in if you set SAVE_IPSETS=Yes in <filename>shorewall.conf</filename></para>
<filename>shorewall.conf</filename>.</para>
</blockquote>
<para>Example (Note -- this example is applicable to ipset versions up to <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 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> </articleinfo>
<caution> <caution>
<para>This article applies to Shorewall 4.0 and later. If you are running <para><emphasis role="bold">This article applies to Shorewall 4.3 and
a version of Shorewall earlier than Shorewall 4.0.0 then please see the later. If you are running a version of Shorewall earlier than Shorewall
documentation for that release.</para> 4.3.5 then please see the documentation for that
release.</emphasis></para>
</caution> </caution>
<section id="Scripts"> <section id="Scripts">
@ -69,9 +70,8 @@
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para><filename>compile</filename> -- (Added in Shorewall-perl version <para><filename>compile</filename> -- Invoked by the rules compiler
4.0.6). Invoked by the Shorewall-perl compiler early in the early in the compilation process. Must be written in Perl.</para>
compilation process. Must be written in Perl.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -87,14 +87,12 @@
<listitem> <listitem>
<para><filename>start</filename> -- invoked after the firewall has <para><filename>start</filename> -- invoked after the firewall has
been started or restarted. The script is also invoked by been started or restarted.</para>
Shorewall-shell after a successful 'restore'.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><filename>started</filename> -- invoked after the firewall has <para><filename>started</filename> -- invoked after the firewall has
been marked as 'running'. The script is also invoked by been marked as 'running'.</para>
Shorewall-shell after a successful 'restore'.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -147,11 +145,11 @@
</listitem> </listitem>
<listitem> <listitem>
<para><filename>isusable</filename> -- (Added in Shorewall-perl <para><filename>isusable</filename> -- invoked when Shorewall is
version 4.0.3) invoked when Shorewall is trying to determine the trying to determine the usability of the network interface associated
usability of the network interface associated with an optional entry with an optional entry in
in <filename>/etc/shorewall/providers</filename>. $1 is the name of <filename>/etc/shorewall/providers</filename>. $1 is the name of the
the interface which will have been determined to be up and configured interface which will have been determined to be up and configured
before the script is invoked. The return value from the script before the script is invoked. The return value from the script
indicates whether or not the interface is usable (0 = usable, other = indicates whether or not the interface is usable (0 = usable, other =
unusable).</para> unusable).</para>
@ -185,16 +183,14 @@ esac</programlisting><caution>
</listitem> </listitem>
<listitem> <listitem>
<para><filename>save</filename> -- (Added in Shorewall version 4.2.0 <para><filename>save</filename> -- This script is invoked during
Beta2). This script is invoked during execution of the execution of the <command>shorewall save</command> and
<command>shorewall save</command> and <command>shorewall-lite <command>shorewall-lite save</command> commands.</para>
save</command> commands.</para>
</listitem> </listitem>
<listitem> <listitem>
<para><filename>restored</filename> -- (Added in Shorewall-perl <para><filename>restored</filename> -- This script is invoked at the
version 4.2.6). This script is invoked at the completion of a completion of a successful <command>shorewall restore</command> and
successful <command>shorewall restore</command> and
<command>shorewall-lite restore</command>.</para> <command>shorewall-lite restore</command>.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -210,29 +206,23 @@ esac</programlisting><caution>
scripts.</para> scripts.</para>
<informaltable frame="none" rowheader="firstcol"> <informaltable frame="none" rowheader="firstcol">
<tgroup cols="3"> <tgroup cols="2">
<tbody> <tbody>
<row> <row>
<entry><emphasis role="bold">script</emphasis></entry> <entry><emphasis role="bold">script</emphasis></entry>
<entry><emphasis role="bold">Shorewall-shell</emphasis></entry> <entry><emphasis role="bold">Commands</emphasis></entry>
<entry><emphasis role="bold">Shorewall-perl</emphasis></entry>
</row> </row>
<row> <row>
<entry>clear</entry> <entry>clear</entry>
<entry>clear</entry> <entry>clear</entry>
<entry>clear</entry>
</row> </row>
<row> <row>
<entry>compile</entry> <entry>compile</entry>
<entry>-</entry>
<entry>check, compile, export, load, refresh, reload, restart, <entry>check, compile, export, load, refresh, reload, restart,
restore,start</entry> restore,start</entry>
</row> </row>
@ -240,24 +230,18 @@ esac</programlisting><caution>
<row> <row>
<entry>continue</entry> <entry>continue</entry>
<entry>load, refresh, reload, restart, restore, start</entry>
<entry></entry> <entry></entry>
</row> </row>
<row> <row>
<entry>init</entry> <entry>init</entry>
<entry>load, refresh, reload, restart, restore, start</entry>
<entry>load, refresh, reload, restart restore, start</entry> <entry>load, refresh, reload, restart restore, start</entry>
</row> </row>
<row> <row>
<entry>initdone</entry> <entry>initdone</entry>
<entry>refresh, restart, restore, start</entry>
<entry>check, compile, export, refresh, restart, start</entry> <entry>check, compile, export, refresh, restart, start</entry>
</row> </row>
@ -265,15 +249,11 @@ esac</programlisting><caution>
<entry>isusable</entry> <entry>isusable</entry>
<entry>refresh, restart, restore, start</entry> <entry>refresh, restart, restore, start</entry>
<entry>refresh, restart, restore, start</entry>
</row> </row>
<row> <row>
<entry>maclog</entry> <entry>maclog</entry>
<entry>load, refresh, reload, restart, restore, start</entry>
<entry>check, compile, export, refresh, restart, start</entry> <entry>check, compile, export, refresh, restart, start</entry>
</row> </row>
@ -281,23 +261,17 @@ esac</programlisting><caution>
<entry>refresh</entry> <entry>refresh</entry>
<entry>refresh</entry> <entry>refresh</entry>
<entry>refresh</entry>
</row> </row>
<row> <row>
<entry>refreshed</entry> <entry>refreshed</entry>
<entry>refresh</entry> <entry>refresh</entry>
<entry>refresh</entry>
</row> </row>
<row> <row>
<entry>restored</entry> <entry>restored</entry>
<entry>-</entry>
<entry>restore</entry> <entry>restore</entry>
</row> </row>
@ -305,23 +279,17 @@ esac</programlisting><caution>
<entry>save</entry> <entry>save</entry>
<entry>save</entry> <entry>save</entry>
<entry>save</entry>
</row> </row>
<row> <row>
<entry>start</entry> <entry>start</entry>
<entry>load, reload, restart, restore, start</entry>
<entry>load, reload, restart, start</entry> <entry>load, reload, restart, start</entry>
</row> </row>
<row> <row>
<entry>started</entry> <entry>started</entry>
<entry>load, reload, restart, restore, start</entry>
<entry>load, reload, restart, start</entry> <entry>load, reload, restart, start</entry>
</row> </row>
@ -329,24 +297,18 @@ esac</programlisting><caution>
<entry>stop</entry> <entry>stop</entry>
<entry>stop, clear</entry> <entry>stop, clear</entry>
<entry>stop, clear</entry>
</row> </row>
<row> <row>
<entry>stopped</entry> <entry>stopped</entry>
<entry>stop, clear</entry> <entry>stop, clear</entry>
<entry>stop, clear</entry>
</row> </row>
<row> <row>
<entry>tcclear</entry> <entry>tcclear</entry>
<entry>load, reload, restart, restore, start</entry> <entry>load, reload, restart, restore, start</entry>
<entry>load, reload, restart, restore, start</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
@ -362,12 +324,10 @@ esac</programlisting><caution>
<command>run_iptables</command> will run the iptables utility passing <command>run_iptables</command> will run the iptables utility passing
the arguments to <command>run_iptables</command> and if the command the arguments to <command>run_iptables</command> and if the command
fails, the firewall will be stopped (or restored from the last fails, the firewall will be stopped (or restored from the last
<command>save</command> command, if any). Note that when <command>save</command> command, if any).
Shorewall-shell invokes this script during <command>restore</command>, <command>run_iptables</command> should not be called from the
The <command>run_iptables</command> function does nothing; calls to <filename>started</filename> or <filename>restored</filename>
that function are effectively ignored. <command>run_iptables</command> scripts.</para>
should not be called from the <filename>started</filename> or
<filename>restored</filename> scripts.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -428,99 +388,38 @@ esac</programlisting><caution>
<para></para> <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"> <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 <para>Shorewall runs some extension scripts at compile-time rather than
scripts from earlier versions will no longer work because Shorewall-perl at run-time.</para>
runs those extension scripts at compile-time rather than at
run-time.</para>
<para>The following table summarizes when the various extension scripts <para>The following table summarizes when the various extension scripts
are run:<informaltable frame="all"> are run:<informaltable frame="all">
<tgroup cols="3"> <tgroup cols="2">
<tbody> <tbody>
<row> <row>
<entry><emphasis role="bold">Compile-time</emphasis></entry> <entry><emphasis role="bold">Compile-time</emphasis></entry>
<entry><emphasis role="bold">Run-time</emphasis></entry> <entry><emphasis role="bold">Run-time</emphasis></entry>
<entry><emphasis role="bold">Eliminated</emphasis></entry>
</row> </row>
<row> <row>
<entry>compile</entry> <entry>compile</entry>
<entry>clear</entry> <entry>clear</entry>
<entry>continue</entry>
</row> </row>
<row> <row>
<entry>initdone</entry> <entry>initdone</entry>
<entry>init</entry> <entry>init</entry>
<entry></entry>
</row> </row>
<row> <row>
<entry>maclog</entry> <entry>maclog</entry>
<entry>isusable</entry> <entry>isusable</entry>
<entry></entry>
</row> </row>
<row> <row>
@ -528,32 +427,24 @@ esac</programlisting><caution>
actions)</entry> actions)</entry>
<entry>start</entry> <entry>start</entry>
<entry></entry>
</row> </row>
<row> <row>
<entry></entry> <entry></entry>
<entry>started</entry> <entry>started</entry>
<entry></entry>
</row> </row>
<row> <row>
<entry></entry> <entry></entry>
<entry>stop</entry> <entry>stop</entry>
<entry></entry>
</row> </row>
<row> <row>
<entry></entry> <entry></entry>
<entry>stopped</entry> <entry>stopped</entry>
<entry></entry>
</row> </row>
<row> <row>
@ -588,8 +479,7 @@ esac</programlisting><caution>
script returns a 'true' value; otherwise, the compiler will assume that script returns a 'true' value; otherwise, the compiler will assume that
the script failed and will abort the compilation.</para> the script failed and will abort the compilation.</para>
<para>Beginning with Shorewall version 4.0.6, each compile-time script <para>Each compile-time script is implicitly prefaced with:</para>
is implicitly prefaced with:</para>
<programlisting>package Shorewall::User;</programlisting> <programlisting>package Shorewall::User;</programlisting>
@ -597,7 +487,7 @@ esac</programlisting><caution>
line:<programlisting>use Shorewall::Chains;</programlisting>For more line:<programlisting>use Shorewall::Chains;</programlisting>For more
complex scripts, you may need to 'use' other Shorewall Perl modules -- complex scripts, you may need to 'use' other Shorewall Perl modules --
browse <filename 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> what's available.</para>
<para>When a script is invoked, the <emphasis <para>When a script is invoked, the <emphasis
@ -616,12 +506,12 @@ esac</programlisting><caution>
name</emphasis>&gt;"</member> name</emphasis>&gt;"</member>
</simplelist>Example:<programlisting>add_rule( $chainref, '-j ACCEPT' );</programlisting></para> </simplelist>Example:<programlisting>add_rule( $chainref, '-j ACCEPT' );</programlisting></para>
<para>Beginning with Shorewall 4.0.5, add_rule() accepts an optional <para>The add_rule() function accepts an optional third argument; If
third argument; If that argument evaluates to true and the passed rule that argument evaluates to true and the passed rule contains a <emphasis
contains a <emphasis role="bold">--dports</emphasis> list with more than role="bold">--dports</emphasis> list with more than 15 ports (a port
15 ports (a port range counts as two ports), the rule will be split into range counts as two ports), the rule will be split into multiple rules
multiple rules where each resulting rule has 15 or fewer ports in its where each resulting rule has 15 or fewer ports in its <emphasis
<emphasis role="bold">--dports</emphasis> list.</para> 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 <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 <emphasis role="bold">log_rule_limit()</emphasis> function works like it
@ -662,12 +552,6 @@ esac</programlisting><caution>
<para>Example:</para> <para>Example:</para>
<programlisting>my $chainref = $filter_table-&gt;{INPUT}; #Same as above with a few less keystrokes; runs faster too</programlisting> <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>
</section> </section>
</article> </article>

27
docs/shorewall_logging.xml
View File

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

56
docs/shorewall_prerequisites.xml
View File

@ -33,9 +33,9 @@
</articleinfo> </articleinfo>
<caution> <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 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> release.</emphasis></para>
</caution> </caution>
@ -90,17 +90,47 @@
<para>The firewall monitoring display is greatly improved if you have <para>The firewall monitoring display is greatly improved if you have
awk (gawk) installed.</para> awk (gawk) installed.</para>
</listitem> </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> </itemizedlist>
</section> </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> </article>

42
docs/starting_and_stopping_shorewall.xml
View File

@ -41,9 +41,9 @@
</articleinfo> </articleinfo>
<caution> <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 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> release</emphasis>.</para>
</caution> </caution>
@ -133,12 +133,12 @@
executed.</para> executed.</para>
<important> <important>
<para>Beginning with Shorewall 3.1, <command>shorewall <para><command>shorewall start</command> is implemented as a
start</command> is implemented as a <firstterm>compile and <firstterm>compile and go</firstterm>; that is, the configuration is
go</firstterm>; that is, the configuration is compiled and if there compiled and if there are no compilation errors then the resulting
are no compilation errors then the resulting compiled script is compiled script is executed. If there are compilation errors, the
executed. If there are compilation errors, the command is aborted command is aborted and the state of the firewall is not
and the state of the firewall is not altered.</para> altered.</para>
</important> </important>
</listitem> </listitem>
@ -207,15 +207,14 @@
<para>To trace the execution of <command>shorewall start</command> and <para>To trace the execution of <command>shorewall start</command> and
write the trace to the file <filename>/tmp/trace</filename>, you would 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> enter:<programlisting><command>shorewall trace start 2&gt; /tmp/trace</command></programlisting><note>
<para>If you are running Shorewall-perl, the <emphasis <para>The <emphasis role="bold">trace</emphasis> keyword does not
role="bold">trace</emphasis> keyword does not result in a trace of result in a trace of the execution of the Shorewall rules compiler.
the execution of the Shorewall-perl compiler. It rather causes It rather causes additional diagnostic information to be included in
additional diagnostic information to be included in warning and warning and error messages generated by the compiler.</para>
error messages generated by the compiler.</para>
</note></para> </note></para>
<para>Beginning with Shorewall 4.0.5, you may also include the word <para>You may also include the word <emphasis
<emphasis role="bold">debug</emphasis> as the first argument to the role="bold">debug</emphasis> as the first argument to the
<filename>/sbin/shorewall</filename> and <filename>/sbin/shorewall</filename> and
<filename>/sbin/shorewall-lite</filename> commands.<programlisting><command>shorewall debug restart</command></programlisting>In <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 most cases, <emphasis role="bold">debug</emphasis> is a synonym for
@ -346,17 +345,12 @@
running <command>iptables</command> dozens or even hundreds of running <command>iptables</command> dozens or even hundreds of
times.</para> times.</para>
<para><filename>Under Shorewall versions &lt; 4.0.0, <para>The default is to not use -f. If you wish to change the default,
/etc/init.d/shorewall</filename> you must set the OPTIONS shell variable in either
(<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
<filename>/etc/default/shorewall</filename> or <filename>/etc/default/shorewall</filename> or
<filename>/etc/sysconfig/shorewall</filename> (if your distribution <filename>/etc/sysconfig/shorewall</filename> (if your distribution
provides neither of these files, you must create one or the other). 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, </para>
you would have:<programlisting>OPTIONS="-f"</programlisting></para>
</listitem> </listitem>
<listitem> <listitem>
@ -515,7 +509,7 @@
<section id="Commands"> <section id="Commands">
<title>Commands</title> <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> <blockquote>
<para><command>shorewall [ &lt;options&gt; ] &lt;command&gt; [ <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 classes (and their bandwidth limits), and it uses SFQ inside these classes
to make sure, that different data streams are handled equally.</para> to make sure, that different data streams are handled equally.</para>
<para><emphasis role="bold">If you are running Shorewall-shell or if you <para>You can shape incoming traffic through use of an
are running Shorewall-perl 4.1.5 or earlier:</emphasis><blockquote> <firstterm>Intermediate Frame Block</firstterm> (IFB) device. <link
<para><emphasis role="bold">You can only shape outgoing traffic. The linkend="IFB">See below</link>. <emphasis role="bold">But beware: using an
reason for this is simple, the packets were already received by your IFB can result in queues building up both at your ISPs router and at your
network card before you can decide what to do with them</emphasis>. So own.</emphasis></para>
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>There is one exception, though. Limiting incoming traffic to a <para>If you wish to shape downloads, you can also configure traffic
value a bit slower than your actual line speed will avoid queuing on shaping on your firewall's local interface. An example appears <link
the other end of that connection. This is mostly useful if you don't linkend="Downloads">below</link>. Again, however, <emphasis
have access to traffic control on the other side and if this other role="bold">this can result in queues building up both at your ISPs router
side has a faster network connection than you do (the line speed and at your own</emphasis>.</para>
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>You shape and control outgoing traffic by assigning the traffic to <para>You shape and control outgoing traffic by assigning the traffic to
<firstterm>classes</firstterm>. Each class is associated with exactly one <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 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>. (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 You man NOT specify wildcards here, e.g. if you have multiple ppp
interfaces, you need to put them all in here! With Shorewall interfaces, you need to put them all in here! Shorewall will
versions prior to 3.0.8 and 3.2.0 Beta 8, the device named in this determine if the device exists and will only configure the device if
column must exist at the time that Shorewall is started, restarted it does exist. If it doesn't exist, the following warning is
or refreshed. Beginning with Shorewall 3.0.8 and 3.2.0 Beta 8, issued:</para>
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 <para><emphasis role="bold">WARNING: Device &lt;device name&gt; not
found -- traffic-shaping configuration skipped</emphasis></para> found -- traffic-shaping configuration skipped</emphasis></para>
@ -385,10 +334,9 @@
<para>Shorewall assigns a sequential <firstterm>interface <para>Shorewall assigns a sequential <firstterm>interface
number</firstterm> to each interface (the first entry in number</firstterm> to each interface (the first entry in
<filename>/etc/shorewall/tcdevices</filename> is interface 1, the <filename>/etc/shorewall/tcdevices</filename> is interface 1, the
second is interface 2 and so on) Beginning with Shorewall-perl second is interface 2 and so on) You can also explicitly specify the
4.1.6, you can explicitly specify the interface number by prefixing interface number by prefixing the interface name with the number and
the interface name with the number and a colon (":"). Example: a colon (":"). Example: 1:eth0.</para>
1:eth0.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -400,8 +348,8 @@
exceeded, the excess packets are dropped. You want this mainly if exceeded, the excess packets are dropped. You want this mainly if
you have a DSL or Cable Connection to avoid queuing at your 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 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), to a value faster than your interface maximum rate (or to 0
if you are running Shorewall 3.2.6 or later).</para> (zero).</para>
<para>To determine the optimum value for this setting, we recommend <para>To determine the optimum value for this setting, we recommend
that you start by setting it significantly below your measured that you start by setting it significantly below your measured
@ -420,8 +368,8 @@
</listitem> </listitem>
<listitem> <listitem>
<para>OPTIONS (Added in Shorewall-perl 4.1.4) — A comma-separated <para>OPTIONS — A comma-separated list of options from the following
list of options from the following list:</para> list:</para>
<variablelist> <variablelist>
<varlistentry> <varlistentry>
@ -439,14 +387,13 @@
</listitem> </listitem>
<listitem> <listitem>
<para>REDIRECTED INTERFACES (Added in Shorewall-perl 4.1.6) — <para>REDIRECTED INTERFACES — Entries are appropriate in this column
Entries are appropriate in this column only if the device in the only if the device in the INTERFACE column names a <link
INTERFACE column names a <link linkend="IFB">Intermediate Frame linkend="IFB">Intermediate Frame Block (IFB)</link>. It lists the
Block (IFB)</link>. It lists the physical interfaces that will have physical interfaces that will have their input shaped using classes
their input shaped using classes defined on the IFB. Neither the IFB defined on the IFB. Neither the IFB nor any of the interfaces listed
nor any of the interfaces listed in this column may have an in this column may have an IN-BANDWIDTH specified. You may specify
IN-BANDWIDTH specified. You may specify zero (0) or a dash ("-:) in zero (0) or a dash ("-:) in the IN-BANDWIDTH column.</para>
the IN-BANDWIDTH column.</para>
<para>IFB devices automatically get the <emphasis <para>IFB devices automatically get the <emphasis
role="bold">classify</emphasis> option.</para> role="bold">classify</emphasis> option.</para>
@ -473,15 +420,14 @@ ppp0 6000kbit 500kbit</programlisting>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>INTERFACE - Name of interface. Users of Shorewall-perl 4.1.6 <para>INTERFACE - Name of interface. Users may also specify the
or later may also specify the interface number. Must match the name interface number. Must match the name (or number) of an interface
(or number) of an interface with an entry in with an entry in <filename>/etc/shorewall/tcdevices</filename>. If
<filename>/etc/shorewall/tcdevices</filename>. If the interface has the interface has the <emphasis role="bold">classify</emphasis>
the <emphasis role="bold">classify</emphasis> option in option in <filename>/etc/shorewall/tcdevices</filename>, then the
<filename>/etc/shorewall/tcdevices</filename>, then the interface interface name or number must be followed by a colon and a
name or number must be followed by a colon and a <firstterm>class <firstterm>class number</firstterm>. Examples: eth0:1, 4:9. Class
number</firstterm>. Examples: eth0:1, 4:9. Class numbers must be numbers must be unique for a given interface.</para>
unique for a given interface.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -685,11 +631,10 @@ ppp0 6000kbit 500kbit</programlisting>
</itemizedlist> </itemizedlist>
<note> <note>
<para>The "T" qualifier was added in Shorewall version 3.3.6 and <para> <emphasis role="bold">Use the 'T' qualifier if you want the
is not available in earlier versions. <emphasis role="bold">Use rule to apply equally to traffic being routed through the firewall
this qualifier if you want the rule to apply equally to traffic and to traffic originating on the firewall
being routed through the firewall and to traffic originating on itself.</emphasis></para>
the firewall itself.</emphasis></para>
</note> </note>
<para>Normally, the mark is applied to the packet. If you follow the <para>Normally, the mark is applied to the packet. If you follow the
@ -735,12 +680,11 @@ ppp0 6000kbit 500kbit</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para><emphasis role="bold">COMMENT</emphasis> (Added in <para><emphasis role="bold">COMMENT</emphasis> -- the rest of
Shorewall version 3.3.3) -- the rest of the line will be the line will be attached as a comment to the Netfilter rule(s)
attached as a comment to the Netfilter rule(s) generated by the generated by the following entries. The comment will appear
following entries. The comment will appear delimited by "/* ... delimited by "/* ... */" in the output of <command>shorewall
*/" in the output of <command>shorewall show show mangle</command></para>
mangle</command></para>
<para>To stop the comment from being attached to further rules, <para>To stop the comment from being attached to further rules,
simply include COMMENT on a line by itself.</para> simply include COMMENT on a line by itself.</para>
@ -767,9 +711,7 @@ ppp0 6000kbit 500kbit</programlisting>
<member>prio</member> <member>prio</member>
</simplelist> </simplelist>
<para>With Shorewall versions prior to 3.2.3, classify rules are <para>Classification occurs in the POSTROUTING chain <emphasis
always placed in the POSTROUTING chain. Beginning with Shorewall
3.2.3, classification occurs in the POSTROUTING chain <emphasis
role="bold">except</emphasis> when the SOURCE contains role="bold">except</emphasis> when the SOURCE contains
$FW[:&lt;<emphasis>address</emphasis>&gt;] in which case, the $FW[:&lt;<emphasis>address</emphasis>&gt;] in which case, the
classify action takes place in the OUTPUT chain. When used with the classify action takes place in the OUTPUT chain. When used with the
@ -783,7 +725,7 @@ ppp0 6000kbit 500kbit</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para>SOURCE - Source of the packet. </para> <para>SOURCE - Source of the packet.</para>
<para>May be:</para> <para>May be:</para>
@ -835,7 +777,7 @@ ppp0 6000kbit 500kbit</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para>DEST - Destination of the packet. </para> <para>DEST - Destination of the packet.</para>
<para>May be:</para> <para>May be:</para>
@ -873,12 +815,8 @@ ppp0 6000kbit 500kbit</programlisting>
ipp2p option without the leading "--" (example "bit" for ipp2p option without the leading "--" (example "bit" for
bit-torrent). If no PORT is given, "ipp2p" is assumed. Note that the bit-torrent). If no PORT is given, "ipp2p" is assumed. Note that the
xtables-addons version of IPP2P does not support the "ipp2p" option; xtables-addons version of IPP2P does not support the "ipp2p" option;
to use that version of IPP2P with Shorewall-shell or with if the column is empty or contains "ipp2p" when using that version
Shorewall-perl 4.2.4 or earlier, you must specify an option other of IPP2P, Shorewall will substitute "edk,kazaa,gnu,dc".</para>
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>
<para>This column is ignored if PROTOCOL = all but must be entered <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 if any of the following field is supplied. In that case, it is
@ -893,11 +831,10 @@ ppp0 6000kbit 500kbit</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para>USER/GROUP (Added in Shorewall version 1.4.10) - (Optional) <para>USER/GROUP (Optional) This column may only be non-empty if the
This column may only be non-empty if the SOURCE is the firewall SOURCE is the firewall itself. When this column is non-empty, the
itself. When this column is non-empty, the rule applies only if the rule applies only if the program generating the output is running
program generating the output is running under the effective user under the effective user and/or group. It may contain :</para>
and/or group. It may contain :</para>
<para>[!][&lt;user name or number&gt;]:[&lt;group name or <para>[!][&lt;user name or number&gt;]:[&lt;group name or
number&gt;][+&lt;program name&gt;]</para> number&gt;][+&lt;program name&gt;]</para>
@ -913,9 +850,9 @@ ppp0 6000kbit 500kbit</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para>TEST - Defines a test on the existing packet or connection <para>TEST (Optional) Defines a test on the existing packet or
mark. The rule will match only if the test returns true. Tests have connection mark. The rule will match only if the test returns true.
the format [!]&lt;value&gt;[/&lt;mask&gt;][:C]</para> Tests have the format [!]&lt;value&gt;[/&lt;mask&gt;][:C]</para>
<para>Where:</para> <para>Where:</para>
@ -934,11 +871,10 @@ ppp0 6000kbit 500kbit</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para>LENGTH (Optional, added in Shorewall version 3.2.0) Packet <para>LENGTH (Optional) This field, if present, allows you to match
Length - This field, if present, allows you to match the length of a the length of a packet against a specific value or range of values.
packet against a specific value or range of values. A range is A range is specified in the form &lt;min&gt;:&lt;max&gt; where
specified in the form &lt;min&gt;:&lt;max&gt; where either either &lt;min&gt; or &lt;max&gt; (but not both) may be omitted. If
&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 &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 omitted, than any packet that is &lt;min&gt; or longer will
match.</para> match.</para>
@ -951,9 +887,8 @@ ppp0 6000kbit 500kbit</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para>TOS (Optional, added in Shorewall version 3.2.0 Beta 6) Type <para>TOS (Optional) Type of Service. Either a standard name, or a
of Service. Either a standard name, or a numeric value to numeric value to match.</para>
match.</para>
<blockquote> <blockquote>
<simplelist> <simplelist>
@ -971,9 +906,8 @@ ppp0 6000kbit 500kbit</programlisting>
</listitem> </listitem>
<listitem> <listitem>
<para>HELPER (Optional, added in Shorewall version 4.2.0 Beta 2). <para>HELPER (Optional). Names one of the Netfilter protocol helper
Names one of the Netfilter protocol helper modules such as modules such as <emphasis>ftp</emphasis>, <emphasis>sip</emphasis>,
<emphasis>ftp</emphasis>, <emphasis>sip</emphasis>,
<emphasis>amanda</emphasis>, etc.</para> <emphasis>amanda</emphasis>, etc.</para>
</listitem> </listitem>
</itemizedlist> </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 <para>Mark all forwarded VOIP connections with connection mark 1 and
ensure that all VOIP packets also receive that mark (assumes that 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 nf_conntrack_sip is loaded).</para>
being used).</para>
<programlisting>#MARK SOURCE DESTINATION PROTOCOL PORT(S) CLIENT USER/ TEST CONNBYTES TOS HELPER <programlisting>#MARK SOURCE DESTINATION PROTOCOL PORT(S) CLIENT USER/ TEST CONNBYTES TOS HELPER
# PORT(S) GROUP # PORT(S) GROUP
@ -1328,8 +1261,7 @@ eth0 4 94mbit full default #for local traff
<section id="IFB"> <section id="IFB">
<title>Intermediate Frame Block (IFB) Devices</title> <title>Intermediate Frame Block (IFB) Devices</title>
<para>Beginning with Shorewall 4.1.6, Shorewall-perl includes support for <para>The principles behind an IFB is fairly simple:</para>
IFBs. The principles behind an IFB is fairly simple:</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>

280
docs/troubleshoot.xml
View File

@ -36,25 +36,109 @@
<title><quote>shorewall start</quote> and <quote>shorewall restart</quote> <title><quote>shorewall start</quote> and <quote>shorewall restart</quote>
Errors</title> Errors</title>
<section id="Start-shell"> <para>If the error is detected by the Shorewall compiler, it should be
<title>Shorewall-shell</title> 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 <para>Example:<programlisting>gateway:~/test # shorewall restart .
message when starting or restarting the firewall and you can't determine Compiling...
the cause. First, if your VERBOSITY setting in shorewall.conf is less ERROR: Invalid ICMP Type (0/400) : /root/test/rules (line 19)
than 2, then try running with a higher verbosity level by using the "-v" gateway:~/test # </programlisting>In this case, line 19 in the rules file
option:</para> specified an invalid ICMP Type (0/400).</para>
<blockquote> <para>Additional information about the error can be obtained using the
<programlisting><command>shorewall -vv [re]start</command></programlisting> 'debug' keyword:<programlisting>gateway:~/test # shorewall debug restart .
</blockquote> 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 <para>The end of the compile phase is signaled by a message such as the
clear which entry in which file is generating the error.</para> 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> <listitem>
<para>Make a note of the error message that you see.</para> <para>Make a note of the error message that you see.</para>
</listitem> </listitem>
@ -67,177 +151,15 @@
<listitem> <listitem>
<para>Look at the <filename>/tmp/trace</filename> file and see if <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 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 place in the log where the error message you saw is generated -- you
you are using Shorewall 1.4.0 or later, you should find the message should find the message near the end of the log.</para>
near the end of the log.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>If you still can't determine what's wrong then see the <ulink <para>If you still can't determine what's wrong then see the <ulink
url="support.htm">support page</ulink>.</para> url="support.htm">support page</ulink>.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist></para>
<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>
</section> </section>
<section id="Network"> <section id="Network">

18
docs/upgrade_issues.xml
View File

@ -29,6 +29,8 @@
<year>2008</year> <year>2008</year>
<year>2009</year>
<holder>Thomas M. Eastep</holder> <holder>Thomas M. Eastep</holder>
<holder></holder> <holder></holder>
@ -71,12 +73,22 @@
command to see the groups associated with each of your zones.</para> command to see the groups associated with each of your zones.</para>
</section> </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> <section>
<title>Versions &gt;= 4.2.0</title> <title>Versions &gt;= 4.2.0</title>
<orderedlist> <orderedlist>
<listitem> <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 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. has been changed so that only high mark values may be assigned there.
Packet marking rules for traffic shaping of packets originating on the Packet marking rules for traffic shaping of packets originating on the
@ -158,7 +170,7 @@
<listitem> <listitem>
<para>The value of IMPLICIT_CONTINUE in shorewall.conf (and samples) <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>
<listitem> <listitem>
@ -169,7 +181,7 @@
<listitem> <listitem>
<para>DYNAMIC_ZONES=Yes is no longer supported by Shorewall-perl. Use <para>DYNAMIC_ZONES=Yes is no longer supported by Shorewall-perl. Use
ipset-based zones instead. </para> ipset-based zones instead.</para>
</listitem> </listitem>
</orderedlist> </orderedlist>
</section> </section>