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

Add a new Shorewall Version 4 document

Browse Source 
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@5908 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
This commit is contained in:
teastep 2007-04-12 23:04:36 +00:00
parent 28305df510
commit 119be1ed71
3 changed files with 505 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -0,0 +1,432 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
<!--$Id$-->
<articleinfo>
<title>Shorewall Version 4</title>
<authorgroup>
<author>
<firstname>Tom</firstname>
<surname>Eastep</surname>
</author>
</authorgroup>
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
<copyright>
<year>2007</year>
<holder>Thomas M. Eastep</holder>
</copyright>
<legalnotice>
<para>Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License, Version
1.2 or any later version published by the Free Software Foundation; with
no Invariant Sections, with no Front-Cover, and with no Back-Cover
Texts. A copy of the license is included in the section entitled
<quote><ulink url="GnuCopyright.htm">GNU Free Documentation
License</ulink></quote>.</para>
</legalnotice>
</articleinfo>
<section>
<title>Introduction</title>
<para>Shorewall version 4 is currently in development and is available for
testing as the 3.9.x series. You may download the code from any of the
Shorewall download sites (except Sourceforge); look in the
/pub/shorewall/development/3.9 directory.</para>
<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 ran 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 iptables-restore; so the
script is very fast.</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>
<title>Installing Shorewall Version 4</title>
<para>You can download the development version of Shorewall Version 4 from
any of the download sites with the exception of SourceForge. It is
contained in the <filename
class="directory">/pub/shorewall/development/3.9/</filename>
directory.</para>
<para>Shorewall 4 contains four packages:</para>
<itemizedlist>
<listitem>
<para>Shorewall-shell - the old shell-based compiler and related
components.</para>
</listitem>
<listitem>
<para>Shorewall-perl - the new Perl-based compiler. May be installed
under Shorewall 3.4.2 or 3.9.x.</para>
</listitem>
<listitem>
<para>Shorewall - the part of Shorewall common to both
compilers.</para>
</listitem>
<listitem>
<para>Shorewall-lite- same as the 3.4 version of Shorewall Lite. Can
run scripts generated by either Shorewall-perl or
Shorewall-shell.</para>
</listitem>
</itemizedlist>
<para>If you upgrade to Shorewall Version 4, you must install
Shorewall-shell and/or Shorewall-perl; in fact, if you are using the
tarball for your installation, you must install Shorewall-shell and/or
Shorewall-perl <emphasis role="bold">before</emphasis> you upgrade
Shorewall.</para>
</section>
<section>
<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.</para>
<orderedlist>
<listitem>
<para>The Perl-based compiler requires the following capabilities in
your kernel and iptables.</para>
<itemizedlist>
<listitem>
<para>addrtype match (may be relaxed later)</para>
</listitem>
<listitem>
<para>multiport match (will not be relaxed)</para>
</listitem>
</itemizedlist>
<para>These capabilities are in current distributions.</para>
</listitem>
<listitem>
<para>Now that Netfilter has features to deal reasonably with port
lists, I see no reason to duplicate those features in Shorewall. The
Shorewall-shell compiler goes to great pain (in some cases) to break
very long port lists ( &gt; 15 where port ranges in lists count as two
ports) into individual rules. In the new compiler, I'm avoiding the
ugliness required to do that. The new compiler just generates an error
if your list is too long. It will also produce an error if you insert
a port range into a port list and you don't have extended multiport
support.</para>
</listitem>
<listitem>
<para>BRIDGING=Yes is not supported. The kernel code necessary to
support this option was removed in Linux kernel 2.6.20.</para>
</listitem>
<listitem>
<para>The BROADCAST column in the interfaces file is essentially
unused; if you enter anything in this column but '-' or 'detect', you
will receive a warning. This will be relaxed if and when the addrtype
match requirement is relaxed.</para>
</listitem>
<listitem>
<para>Because the compiler is now written in Perl, your compile-time
extension scripts from earlier versions will no longer work. For now,
if you want to use extension scripts, you will need to read the Perl
code to see how the compiler operates internally. I will produce
documentation before the first official release. Compile-time
extension scripts are executed using the Perl 'do FILE'
mechanism.</para>
</listitem>
<listitem>
<para>The 'refresh' command is now synonymous with 'restart'.</para>
</listitem>
<listitem>
<para> Because the compiler is now written in Perl, your compile-time
extension scripts from earlier versions will no longer work.
Compile-time extension scripts are executed using the Perl 'eval `cat
&lt;file&gt;`' mechanism. Be sure that each script returns a 'true'
value; otherwise, the compiler will assume that the script failed and
will abort the compilation.</para>
<para>When a script is invoked, the $chainref scalar variable will
hold a reference to a chain table entry.</para>
<simplelist>
<member>$chainref-&gt;{name} contains the name of the chain</member>
<member>$chainref-&gt;{table} holds the table name</member>
</simplelist>
<para>To add a rule to the chain:</para>
<simplelist>
<member>add_rule $chainref, &lt;<replaceable>the
rule</replaceable>&gt;</member>
</simplelist>
<para>Where</para>
<simplelist>
<member>&lt;<replaceable>the rule</replaceable>&gt; is a scalar
argument holding the rule text. Do not include "-A
&lt;<replaceable>chain name</replaceable>&gt;"</member>
</simplelist>
<para>Example:</para>
<simplelist>
<member>add_rule $chainref, '-j ACCEPT';</member>
</simplelist>
<para>To insert a rule into the chain:</para>
<simplelist>
<member>insert_rule $chainref,
&lt;<replaceable>rulenum</replaceable>&gt;, &lt;<replaceable>the
rule</replaceable>&gt;</member>
</simplelist>
<para>The log_rule_limit function works like it does in the shell
compiler with two exceptions:</para>
<itemizedlist>
<listitem>
<para>You pass the chain reference rather than the name of the
chain.</para>
</listitem>
<listitem>
<para>The commands are 'add' and 'insert' rather than '-A' and
'-I'.</para>
</listitem>
<listitem>
<para>There is only a single "pass as-is to iptables" argument (so
you must quote that par</para>
</listitem>
</itemizedlist>
<para>Example:</para>
<programlisting> log_rule_limit
'info' ,
$chainref ,
$chainref-&gt;{name},
'DROP' ,
'', #Limit
'' , #Log tag
'add'; </programlisting>
</listitem>
<listitem>
<para>The <filename>/etc/shorewall/tos</filename> file now has
zone-independent SOURCE and DEST columns as do all other files except
the rules and policy files.</para>
<para>The SOURCE column may be one of the following:</para>
<simplelist>
<member>[<command>all</command>:]&lt;<replaceable>address</replaceable>&gt;[,...]</member>
<member>[<command>all</command>:]&lt;<replaceable>interface</replaceable>&gt;[:&lt;<replaceable>address</replaceable>&gt;[,...]]</member>
<member><command>$FW</command>[:&lt;<replaceable>address</replaceable>&gt;[,...]]</member>
</simplelist>
<para>The DEST column may be one of the following:</para>
<simplelist>
<member>[<command>all</command>:]&lt;<replaceable>address</replaceable>&gt;[,...]</member>
<member>[<command>all</command>:]&lt;<replaceable>interface</replaceable>&gt;[:&lt;<replaceable>address</replaceable>&gt;[,...]]</member>
</simplelist>
<para>This is a permanent change. The old zone-based rules have never
worked right and this is a good time to replace them. I've tried to
make the new syntax cover the most common cases without requiring
change to existing files. In particular, it will handle the tos file
released with Shorewall 1.4 and earlier.</para>
</listitem>
<listitem>
<para>Currently, support for ipsets is untested. That will change with
future pre-releases but one thing is certain -- Shorewall is now out
of the ipset load/reload business. With scripts generated by the
Perl-based Compiler, the Netfilter ruleset 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/start</filename>:</para>
<programlisting>if [ "$COMMAND" = start ]; then
ipset -U :all: :all:
ipset -F
ipset -X
ipset -R &lt; /etc/shorewall/ipsets
fi</programlisting>
<para>The file <filename>/etc/shorewall/ipsets</filename> will
normally be produced using the <command>ipset -S</command>
command.</para>
<para>The above will work most of the time but will fail in a
<command>shorewall stop</command> - <command>shorewall
start</command> sequence if you use ipsets in your routestopped
file (see below).</para>
</listitem>
<listitem>
<para>Your ipsets may not be reloaded until Shorewall is stopped
or cleared.</para>
</listitem>
<listitem>
<para>If you specify ipsets in your routestopped file then
Shorewall must be cleared in order to reload your ipsets.</para>
</listitem>
</orderedlist>
<para>As a consequence, scripts generated by the Perl-based compiler
will ignore <filename>/etc/shorewall/ipsets</filename> and will issue
a warning if you set SAVE_IPSETS=Yes in
<filename>shorewall.conf</filename>.</para>
</listitem>
<listitem>
<para>Because the configuration files (with the exception of
<filename>/etc/shorewall/params</filename>) are now processed by the
Shorewall-perl compiler rather than by the shell, only the basic forms
of Shell expansion ($variable and ${variable}) are supported. The more
exotic forms such as ${variable:=default} are not supported. Both
variables defined in /etc/shorewall/params and environmental variables
(exported by the shell) can be used in configuration files.</para>
</listitem>
<listitem>
<para>USE_ACTIONS=No is not supported. That option is intended to
minimize Shorewall's footprint in embedded applications. As a
consequence, Default Macros are not supported.</para>
</listitem>
<listitem>
<para>DELAYBLACKLISTLOAD=Yes is not supported. The entire ruleset is
atomically loaded with one execution of
<command>iptables-restore</command>.</para>
</listitem>
<listitem>
<para>MAPOLDACTIONS=Yes is not supported. People should have converted
to using macros by now.</para>
</listitem>
<listitem>
<para>The pre Shorewall-3.0 format of the zones file is not supported;
neither is the <filename>/etc/shorewall/ipsec</filename> file.</para>
</listitem>
</orderedlist>
</section>
<section>
<title>Prerequisites for using the Shorewall Version 4 Perl-based
Compiler</title>
<itemizedlist>
<listitem>
<para>Perl (I use Perl 5.8.8 but other versions should work
fine)</para>
</listitem>
<listitem>
<para>Perl Cwd Module</para>
</listitem>
<listitem>
<para>Perl File::Basename Module</para>
</listitem>
<listitem>
<para>Perl File::Temp Module</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Compiler Selection</title>
<para>If you only install one compiler, then that compiler will be
used.</para>
<para>If you install both compilers, then the compiler actually used
depends on the SHOREWALL_COMPILER setting in
<filename>shorewall.conf</filename>. The value of this new option can be
either 'perl' or 'shell'.</para>
<para>If you add 'SHOREWALL_COMPILER=shell' 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. If you only install one compiler, it
is suggested that you do not set SHOREWALL_COMPILER. Regardless of the
setting of SHOREWALL_COMPILER, there is one change in Shorewall operation
that is triggered simply by installing shorewall-perl. Your
<filename>params</filename> file will be processed during compilation with
the shell's '-a' option which causes any variables that you set or create
in that file to be automatically exported. Since the params file is
processed before <filename>shorewall.conf</filename>, using -a insures
that the settings of your params variables are available to the new
compiler should it's use be specified in
<filename>shorewall.conf</filename>.</para>
</section>
</article>

83
docs/Shorewall-perl.xml
View File

@ -145,21 +145,82 @@
</listitem>
<listitem>
<para>Some run-time extension scripts are no longer supported
because they make no sense (iptables-restore instantiates the new
configuration atomically).</para>
<para>Because the compiler is now written in Perl, your
compile-time extension scripts from earlier versions will no
longer work. Compile-time extension scripts are executed using the
Perl 'eval `cat &lt;file&gt;`' mechanism. Be sure that each script
returns a 'true' value; otherwise, the compiler will assume that
the script failed and will abort the compilation.</para>
<para>When a script is invoked, the $chainref scalar variable will
hold a reference to a chain table entry.</para>
<simplelist>
<member>continue</member>
<member>$chainref-&gt;{name} contains the name of the
chain</member>
<member>initdone</member>
<member>continue</member>
<member>refresh</member>
<member>refreshed</member>
<member>$chainref-&gt;{table} holds the table name</member>
</simplelist>
<para>To add a rule to the chain:</para>
<simplelist>
<member>add_rule $chainref, &lt;<replaceable>the
rule</replaceable>&gt;</member>
</simplelist>
<para>Where</para>
<simplelist>
<member>&lt;<replaceable>the rule</replaceable>&gt; is a scalar
argument holding the rule text. Do not include "-A
&lt;<replaceable>chain name</replaceable>&gt;"</member>
</simplelist>
<para>Example:</para>
<simplelist>
<member>add_rule $chainref, '-j ACCEPT';</member>
</simplelist>
<para>To insert a rule into the chain:</para>
<simplelist>
<member>insert_rule $chainref,
&lt;<replaceable>rulenum</replaceable>&gt;, &lt;<replaceable>the
rule</replaceable>&gt;</member>
</simplelist>
<para>The log_rule_limit function works like it does in the shell
compiler with two exceptions:</para>
<itemizedlist>
<listitem>
<para>You pass the chain reference rather than the name of the
chain.</para>
</listitem>
<listitem>
<para>The commands are 'add' and 'insert' rather than '-A' and
'-I'.</para>
</listitem>
<listitem>
<para>There is only a single "pass as-is to iptables" argument
(so you must quote that par</para>
</listitem>
</itemizedlist>
<para>Example:</para>
<programlisting> log_rule_limit
'info' ,
$chainref ,
$chainref-&gt;{name},
'DROP' ,
'', #Limit
'' , #Log tag
'add'; </programlisting>
</listitem>
<listitem>

2
docs/template.xml
View File

@ -18,7 +18,7 @@
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
<copyright>
<year>2006</year>
<year>2007</year>
<holder>Thomas M. Eastep</holder>
</copyright>