holm/shorewall_code
1
0
Fork 0
forked from extern/shorewall_code
Code Pull Requests Activity

Combine Shorewall-4/Shorewall-perl docs with a link

Browse Source 
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@6674 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
This commit is contained in:
teastep 2007-06-25 20:30:11 +00:00
parent bf390fe11e
commit 156baf0905
2 changed files with 24 additions and 377 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

382
docs/Shorewall-4.xml
View File

@ -49,7 +49,7 @@
</listitem> </listitem>
<listitem> <listitem>
<para>Shorewall ran the <command>iptables</command> utility to add <para>Shorewall has run the <command>iptables</command> utility to add
each Netfilter rule.</para> each Netfilter rule.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -73,6 +73,15 @@
<command>iptables-restore</command>; so the script is very <command>iptables-restore</command>; so the script is very
fast.</para> fast.</para>
</listitem> </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>
</itemizedlist> </itemizedlist>
<para>Both compilers may be installed on your system and you can use <para>Both compilers may be installed on your system and you can use
@ -157,375 +166,8 @@
Compiler</title> Compiler</title>
<para>The Shorewall-perl compiler is not 100% compatible with the <para>The Shorewall-perl compiler is not 100% compatible with the
Shorewall-shell version.</para> Shorewall-shell version. See <ulink url="Shorewall-perl.html">this
document</ulink> for details.</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>The 'refresh' command is now synonymous with 'restart'.</para>
</listitem>
<listitem>
<para>With the shell-based compiler, extension scripts were copied
into the compiled script and executed at run-time. In many cases, this
approach doesn't work with Shorewall Perl because (almost) the entire
ruleset is built by the compiler. As a result, Shorewall-perl runs
many extension scripts at compile-time rather than at run-time.
Because the compiler is written in Perl, your extension scripts from
earlier versions will no longer work.</para>
<para>The following table summarizes when the various extension
scripts are run:<informaltable frame="all">
<tgroup cols="3">
<tbody>
<row>
<entry><emphasis role="bold">Compile-time</emphasis></entry>
<entry><emphasis role="bold">Run-time</emphasis></entry>
<entry><emphasis role="bold">Eliminated</emphasis></entry>
</row>
<row>
<entry>initdone</entry>
<entry>clear</entry>
<entry>continue</entry>
</row>
<row>
<entry>maclog</entry>
<entry>initdone</entry>
<entry>refresh</entry>
</row>
<row>
<entry>Per-chain (including those associated with
actions)</entry>
<entry>start</entry>
<entry></entry>
</row>
<row>
<entry></entry>
<entry>started</entry>
<entry></entry>
</row>
<row>
<entry></entry>
<entry>stop</entry>
<entry></entry>
</row>
<row>
<entry></entry>
<entry>stopped</entry>
<entry></entry>
</row>
<row>
<entry></entry>
<entry>tcclear</entry>
<entry></entry>
</row>
</tbody>
</tgroup>
</informaltable></para>
<para>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 <emphasis
role="bold">$chainref</emphasis> scalar variable will hold a reference
to a chain table entry.</para>
<simplelist>
<member><emphasis role="bold">$chainref-&gt;{name}</emphasis>
contains the name of the chain</member>
<member><emphasis role="bold">$chainref-&gt;{table}</emphasis> 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 part</para>
</listitem>
</itemizedlist>
<para>Example:</para>
<programlisting> log_rule_limit
'info' ,
$chainref ,
$chainref-&gt;{name},
'DROP' ,
'', #Limit
'' , #Log tag
'add'
'-p tcp '; </programlisting>
<para>Here is an example of an actual initdone script used with
Shorewall 3.4:<programlisting>run_iptables -t mangle -I PREROUTING -p esp -j MARK --set-mark 0x50
run_iptables -t filter -I INPUT -p udp --dport 1701 -m mark --mark 0x50 -j ACCEPT
run_iptables -t filter -I OUTPUT -p udp --sport 1701 -j ACCEPT
</programlisting></para>
<para>Here is the corresponding script used with
Shorewall-perl:<programlisting>use Shorewall::Chains;
insert_rule $mangle_table-&gt;{PREROUTING}, 1, "-p esp -j MARK --set-mark 0x50";
insert_rule $filter_table-&gt;{INPUT}, 1, "-p udp --dport 1701 -m mark --mark 0x50 -j ACCEPT";
insert_rule $filter_table-&gt;{OUTPUT}, 1, "-p udp --sport 1701 -j ACCEPT";
1;</programlisting></para>
<para>The initdone script is unique because the $chainref variable is
not set before the script is called. The above script illustrates how
the $mangle_table, $filter_table, and $nat_table references can be
used to add or insert rules in arbitrary chains.</para>
</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 lightly tested. 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>
<listitem>
<para>BLACKLISTNEWONLY=No is not permitted with FASTACCEPT=Yes. This
combination doesn't work in previous versions of Shorewall so the
Perl-based compiler simply rejects it.</para>
</listitem>
<listitem>
<para>Shorewall-perl has a single rule generator that is used for all
rule-oriented files. So it is important that the syntax is consistent
between files.</para>
<para>With shorewall-shell, there is a special syntax in the SOURCE
column of /etc/shorewall/masq to designate "all traffic entering the
firewall on this interface except...".</para>
<para>Example:<programlisting>#INTERFACE SOURCE ADDRESSES
eth0 eth1!192.168.4.9 ...</programlisting>Shorewall-perl
uses syntax that is consistent with the rest of
Shorewall:<programlisting>#INTERFACE SOURCE ADDRESSES
eth0 eth1:!192.168.4.9 ...</programlisting></para>
</listitem>
<listitem>
<para>The 'allowoutUPnP' built-in action is no longer supported. In
kernel 2.6.14, the Netfilter team have removed support for '-m owner
--owner-cmd' which that action depended on.</para>
</listitem>
</orderedlist>
</section> </section>
<section> <section>

19
docs/Shorewall-perl.xml
View File

@ -409,10 +409,9 @@ fi</programlisting>
the Shorewall-perl compiler rather than by the shell, only the the Shorewall-perl compiler rather than by the shell, only the
basic forms of Shell expansion ($variable and ${variable}) are basic forms of Shell expansion ($variable and ${variable}) are
supported. The more exotic forms such as ${variable:=default} are supported. The more exotic forms such as ${variable:=default} are
not supported. Both variables defined in not supported. Both variables defined in /etc/shorewall/params and
<filename>/etc/shorewall/params</filename> and environmental environmental variables (exported by the shell) can be used in
variables (exported by the shell) can be used in configuration configuration files.</para>
files.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -423,8 +422,8 @@ fi</programlisting>
<listitem> <listitem>
<para>DELAYBLACKLISTLOAD=Yes is not supported. The entire ruleset <para>DELAYBLACKLISTLOAD=Yes is not supported. The entire ruleset
(with the exception of the dynamic blacklist) is atomically loaded is atomically loaded with one execution of
with one execution of <command>iptables-restore</command>.</para> <command>iptables-restore</command>.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -446,7 +445,7 @@ fi</programlisting>
<listitem> <listitem>
<para>Shorewall-perl has a single rule generator that is used for <para>Shorewall-perl has a single rule generator that is used for
all rule-oriented files. So it is important that the syntax be all rule-oriented files. So it is important that the syntax is
consistent between files.</para> consistent between files.</para>
<para>With shorewall-shell, there is a special syntax in the <para>With shorewall-shell, there is a special syntax in the
@ -467,6 +466,12 @@ eth0 eth1:!192.168.4.9 ...</programlisting></para>
</listitem> </listitem>
</orderedlist> </orderedlist>
</listitem> </listitem>
<listitem>
<para>Shorewall-perl is dependent on Perl (see the next section) which
has a large disk footprint. This makes Shorewall-perl less desirable
in an embedded environment.</para>
</listitem>
</itemizedlist> </itemizedlist>
</section> </section>