mirror of
https://gitlab.com/shorewall/code.git
synced 2024-11-22 23:53:30 +01:00
Combine Shorewall-4/Shorewall-perl docs with a link
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@6674 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
This commit is contained in:
teastep
parent
bf390fe11e
commit
156baf0905
@ -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 ( > 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 <file>`' 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->{name}</emphasis>
|
|
||||||
contains the name of the chain</member>
|
|
||||||
|
|
||||||
<member><emphasis role="bold">$chainref->{table}</emphasis> holds
|
|
||||||
the table name</member>
|
|
||||||
</simplelist>
|
|
||||||
|
|
||||||
<para>To add a rule to the chain:</para>
|
|
||||||
|
|
||||||
<simplelist>
|
|
||||||
<member>add_rule $chainref, <<replaceable>the
|
|
||||||
rule</replaceable>></member>
|
|
||||||
</simplelist>
|
|
||||||
|
|
||||||
<para>Where</para>
|
|
||||||
|
|
||||||
<simplelist>
|
|
||||||
<member><<replaceable>the rule</replaceable>> is a scalar
|
|
||||||
argument holding the rule text. Do not include "-A
|
|
||||||
<<replaceable>chain name</replaceable>>"</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,
|
|
||||||
<<replaceable>rulenum</replaceable>>, <<replaceable>the
|
|
||||||
rule</replaceable>></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->{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->{PREROUTING}, 1, "-p esp -j MARK --set-mark 0x50";
|
|
||||||
insert_rule $filter_table->{INPUT}, 1, "-p udp --dport 1701 -m mark --mark 0x50 -j ACCEPT";
|
|
||||||
insert_rule $filter_table->{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>:]<<replaceable>address</replaceable>>[,...]</member>
|
|
||||||
|
|
||||||
<member>[<command>all</command>:]<<replaceable>interface</replaceable>>[:<<replaceable>address</replaceable>>[,...]]</member>
|
|
||||||
|
|
||||||
<member><command>$FW</command>[:<<replaceable>address</replaceable>>[,...]]</member>
|
|
||||||
</simplelist>
|
|
||||||
|
|
||||||
<para>The DEST column may be one of the following:</para>
|
|
||||||
|
|
||||||
<simplelist>
|
|
||||||
<member>[<command>all</command>:]<<replaceable>address</replaceable>>[,...]</member>
|
|
||||||
|
|
||||||
<member>[<command>all</command>:]<<replaceable>interface</replaceable>>[:<<replaceable>address</replaceable>>[,...]]</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 < /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>
|
||||||
|
|||||||
@ -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>
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user