extern/shorewall_code
1
0
Fork 1
mirror of https://gitlab.com/shorewall/code.git synced 2025-01-03 03:59:16 +01:00
Code Issues Packages Projects Releases Wiki Activity

More Shorewall-4 Documentation Updates

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

128
docs/Shorewall-4.xml
View File

@ -145,6 +145,10 @@
<listitem> <listitem>
<para>Perl Getopt::Long Module</para> <para>Perl Getopt::Long Module</para>
</listitem> </listitem>
<listitem>
<para>Perl Carp Module</para>
</listitem>
</itemizedlist> </itemizedlist>
</section> </section>
@ -202,12 +206,90 @@
</listitem> </listitem>
<listitem> <listitem>
<para>Because the compiler is now written in Perl, your compile-time <para>With the shell-based compiler, extension scripts were copied
extension scripts from earlier versions will no longer work. into the compiled script and executed at run-time. In many cases, this
Compile-time extension scripts are executed using the Perl 'eval `cat approach doesn't work with Shorewall Perl because (almost) the entire
&lt;file&gt;`' mechanism. Be sure that each script returns a 'true' ruleset is built by the compiler. As a result, Shorewall-perl runs
value; otherwise, the compiler will assume that the script failed and many extension scripts at compile-time rather than at run-time.
will abort the compilation.</para> 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 <para>When a script is invoked, the <emphasis
role="bold">$chainref</emphasis> scalar variable will hold a reference role="bold">$chainref</emphasis> scalar variable will hold a reference
@ -281,6 +363,26 @@
'' , #Log tag '' , #Log tag
'add' 'add'
'-p tcp '; </programlisting> '-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>
<listitem> <listitem>
@ -314,13 +416,13 @@
</listitem> </listitem>
<listitem> <listitem>
<para>Currently, support for ipsets is untested. That will change with <para>Currently, support for ipsets is lightly tested. That will
future pre-releases but one thing is certain -- Shorewall is now out change with future pre-releases but one thing is certain -- Shorewall
of the ipset load/reload business. With scripts generated by the is now out of the ipset load/reload business. With scripts generated
Perl-based Compiler, the Netfilter ruleset is never cleared. That by the Perl-based Compiler, the Netfilter ruleset is never cleared.
means that there is no opportunity for Shorewall to load/reload your That means that there is no opportunity for Shorewall to load/reload
ipsets since that cannot be done while there are any current rules your ipsets since that cannot be done while there are any current
using ipsets.</para> rules using ipsets.</para>
<para>So:</para> <para>So:</para>

130
docs/Shorewall-perl.xml
View File

@ -137,21 +137,104 @@
</listitem> </listitem>
<listitem> <listitem>
<para>Because the compiler is now written in Perl, your <para>With the shell-based compiler, extension scripts were copied
compile-time extension scripts from earlier versions will no into the compiled script and executed at run-time. In many cases,
longer work. Compile-time extension scripts are executed using the this approach doesn't work with Shorewall Perl because (almost)
Perl 'eval `cat &lt;file&gt;`' mechanism. Be sure that each script 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 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>When a script is invoked, the $chainref scalar variable will <para>When a script is invoked, the <emphasis
hold a reference to a chain table entry.</para> role="bold">$chainref</emphasis> scalar variable will hold a
reference to a chain table entry.</para>
<simplelist> <simplelist>
<member>$chainref-&gt;{name} contains the name of the <member><emphasis role="bold">$chainref-&gt;{name}</emphasis>
chain</member> contains the name of the chain</member>
<member>$chainref-&gt;{table} holds the table name</member> <member><emphasis role="bold">$chainref-&gt;{table}</emphasis>
holds the table name</member>
</simplelist> </simplelist>
<para>To add a rule to the chain:</para> <para>To add a rule to the chain:</para>
@ -199,21 +282,42 @@
<listitem> <listitem>
<para>There is only a single "pass as-is to iptables" argument <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> </listitem>
</itemizedlist> </itemizedlist>
<para>Example:</para> <para>Example:</para>
<programlisting> log_rule_limit( <programlisting> log_rule_limit
'info' , 'info' ,
$chainref , $chainref ,
$chainref-&gt;{name}, $chainref-&gt;{name},
'DROP' , 'DROP' ,
'', #Limit '', #Limit
'' , #Log tag '' , #Log tag
'add', #Command 'add'
'-p tcp'); #Added 'as-is' to the generated rule</programlisting> '-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>
<listitem> <listitem>

84
docs/shorewall_extension_scripts.xml
View File

@ -337,12 +337,84 @@
<listitem> <listitem>
<para><emphasis role="bold">Shorewall-perl</emphasis>. Because the <para><emphasis role="bold">Shorewall-perl</emphasis>. Because the
compiler is now written in Perl, your compile-time extension scripts compiler is written in Perl, some of your extension scripts from earlier
from earlier versions will no longer work. Compile-time extension versions will no longer work because Shorewall-perl runs those extension
scripts are executed using the Perl 'eval `cat &lt;file&gt;`' mechanism. scripts at compile-time rather than at run-time.</para>
Be sure that each script returns a 'true' value; otherwise, the compiler
will assume that the script failed and will abort the <para>The following table summarizes when the various extension scripts
compilation.</para> 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 &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>All scripts will need to begin with the following <para>All scripts will need to begin with the following
line:<programlisting>use Shorewall::Chains;</programlisting> For more line:<programlisting>use Shorewall::Chains;</programlisting> For more

8
docs/starting_and_stopping_shorewall.xml
View File

@ -187,7 +187,13 @@
<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></para> enter:<programlisting><command>shorewall trace start 2&gt; /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> </example>
</section> </section>