forked from extern/shorewall_code
More Shorewall-4 Documentation Updates
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@6673 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
This commit is contained in:
teastep
parent
130a9acac2
commit
bf390fe11e
@ -145,6 +145,10 @@
|
||||
<listitem>
|
||||
<para>Perl Getopt::Long Module</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Perl Carp Module</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
|
||||
@ -202,12 +206,90 @@
|
||||
</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
|
||||
<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>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
|
||||
@ -281,6 +363,26 @@
|
||||
'' , #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>
|
||||
@ -314,13 +416,13 @@
|
||||
</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>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>
|
||||
|
||||
|
||||
@ -137,21 +137,104 @@
|
||||
</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 <file>`' mechanism. Be sure that each script
|
||||
<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 $chainref scalar variable will
|
||||
hold a reference to a chain table entry.</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>$chainref->{name} contains the name of the
|
||||
chain</member>
|
||||
<member><emphasis role="bold">$chainref->{name}</emphasis>
|
||||
contains the name of the chain</member>
|
||||
|
||||
<member>$chainref->{table} holds the table name</member>
|
||||
<member><emphasis role="bold">$chainref->{table}</emphasis>
|
||||
holds the table name</member>
|
||||
</simplelist>
|
||||
|
||||
<para>To add a rule to the chain:</para>
|
||||
@ -199,21 +282,42 @@
|
||||
|
||||
<listitem>
|
||||
<para>There is only a single "pass as-is to iptables" argument
|
||||
(so you must quote that part).</para>
|
||||
(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', #Command
|
||||
'-p tcp'); #Added 'as-is' to the generated rule</programlisting>
|
||||
<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>
|
||||
|
||||
@ -337,12 +337,84 @@
|
||||
|
||||
<listitem>
|
||||
<para><emphasis role="bold">Shorewall-perl</emphasis>. 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 <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>
|
||||
compiler is written in Perl, some of your extension scripts from earlier
|
||||
versions will no longer work because Shorewall-perl runs those extension
|
||||
scripts at compile-time rather than at run-time.</para>
|
||||
|
||||
<para>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>
|
||||
</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>All scripts will need to begin with the following
|
||||
line:<programlisting>use Shorewall::Chains;</programlisting> For more
|
||||
|
||||
@ -187,7 +187,13 @@
|
||||
|
||||
<para>To trace the execution of <command>shorewall start</command> and
|
||||
write the trace to the file <filename>/tmp/trace</filename>, you would
|
||||
enter:<programlisting><command>shorewall trace start 2> /tmp/trace</command></programlisting></para>
|
||||
enter:<programlisting><command>shorewall trace start 2> /tmp/trace</command></programlisting><note>
|
||||
<para>If you are running Shorewall-perl, the <emphasis
|
||||
role="bold">trace</emphasis> keyword does not result in a trace of
|
||||
the execution of the Shorewall-perl compiler. It rather causes
|
||||
additional diagnostic information to be included in warning and
|
||||
error messages generated by the compiler.</para>
|
||||
</note></para>
|
||||
</example>
|
||||
</section>
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user