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

Update the Shorewall-perl and Shorewall-4 docs with more IPv6 info

Browse Source 
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@9299 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
This commit is contained in:
teastep 2009-01-17 17:13:54 +00:00
parent b2768dc27a
commit 61299557a9
3 changed files with 106 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
docs/Shorewall-4.xml
View File

@ -99,33 +99,36 @@
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Shorewall-shell - the old shell-based compiler and related <para><emphasis role="bold">Shorewall-shell</emphasis> - the old
components.</para> shell-based compiler and related components.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Shorewall-perl - the new Perl-based compiler.</para> <para><emphasis role="bold">Shorewall-perl</emphasis> - the new
Perl-based compiler.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Shorewall-common - the part of Shorewall common to both <para><emphasis role="bold">Shorewall-common</emphasis> - the part of
compilers.</para> Shorewall common to both compilers.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Shorewall-lite- same as the 3.4 version of Shorewall Lite. Can <para><emphasis role="bold">Shorewall-lite</emphasis>- same as the 3.4
run scripts generated by either Shorewall-perl or version of Shorewall Lite. Can run scripts generated by either
Shorewall-shell.</para> Shorewall-perl or Shorewall-shell.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Shorewall6 - The utilities for creating and operating an Ipv6 <para><emphasis role="bold">Shorewall6</emphasis> - The utilities for
firewall. Requires Shorewall-perl.</para> creating and operating an Ipv6 firewall. Requires Shorewall-perl and
Shorewall-common.</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Shorewall6-lite - Ipv6 equivalent of Shorewall Lite. Can run <para><emphasis role="bold">Shorewall6-lite</emphasis> - Ipv6
scripts generated by Shoreall-perl 4.2.4 and later.</para> equivalent of Shorewall Lite. Can run scripts generated by
Shoreall-perl 4.2.4 and later.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
@ -143,32 +146,43 @@
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Perl (I use Perl 5.8.8 but other 5.8 versions should work <para>Perl (I use Perl 5.8.8 but other 5.8 versions should work fine).
fine)</para> <note>
<para>If you want to be able to use DNS names in your Shorewall6
configuration files, then Perl 5.10 is required together with the
Perl <emphasis role="bold">Socket6</emphasis> module.</para>
</note></para>
</listitem> </listitem>
<listitem> <listitem>
<para>Perl Cwd Module</para> <para>Perl <emphasis role="bold">Cwd</emphasis> Module</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Perl File::Basename Module</para> <para>Perl <emphasis role="bold">File::Basename</emphasis>
Module</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Perl File::Temp Module</para> <para>Perl <emphasis role="bold">File::Temp</emphasis> Module</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Perl Getopt::Long Module</para> <para>Perl <emphasis role="bold">Getopt::Long</emphasis> Module</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Perl Carp Module</para> <para>Perl <emphasis role="bold">Carp</emphasis> Module</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Perl FindBin Module (Shorewall 4.0.3 and later)</para> <para>Perl <emphasis role="bold">FindBin</emphasis> Module (Shorewall
4.0.3 and later)</para>
</listitem>
<listitem>
<para>Perl <emphasis role="bold">Scalar::Util </emphasis>Module
(Shorewall 4.0.6 and later)</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</section> </section>
@ -188,8 +202,8 @@
<para>If you only install one compiler, then that compiler will be <para>If you only install one compiler, then that compiler will be
used.</para> used.</para>
<para>If you install both compilers, then the compiler actually used <para>If you install both compilers, then the compiler actually used for
depends on the SHOREWALL_COMPILER setting in IPv4 depends on the SHOREWALL_COMPILER setting in
<filename>shorewall.conf</filename>.</para> <filename>shorewall.conf</filename>.</para>
<para>The value of this new option can be either 'perl' or 'shell'.</para> <para>The value of this new option can be either 'perl' or 'shell'.</para>
@ -204,8 +218,8 @@
<para>If you only install one compiler, it is suggested that you do not <para>If you only install one compiler, it is suggested that you do not
set SHOREWALL_COMPILER.</para> set SHOREWALL_COMPILER.</para>
<para>You can select the compiler to use on the command line using the 'C <para>If both compilers are installed, you can select the compiler to use
option:<simplelist> on the command line using the 'C option:<simplelist>
<member>'-C shell' means use the shell compiler</member> <member>'-C shell' means use the shell compiler</member>
<member>'-C perl' means use the perl compiler</member> <member>'-C perl' means use the perl compiler</member>
@ -215,7 +229,7 @@
<para>Example:<programlisting><command>shorewall restart -C perl</command></programlisting></para> <para>Example:<programlisting><command>shorewall restart -C perl</command></programlisting></para>
<para>When the Shorewall-perl compiler has been selected, the <para>When the Shorewall-perl compiler has been selected, the
<filename>params</filename> file is processed using the <filename>params</filename> file is processed using the shell
<option>-a</option> option which causes all variables set within the file <option>-a</option> option which causes all variables set within the file
to be exported automatically by the shell. The Shorewall-perl compiler to be exported automatically by the shell. The Shorewall-perl compiler
uses the current environmental variables to perform variable expansion uses the current environmental variables to perform variable expansion

84
docs/Shorewall-perl.xml
View File

@ -53,7 +53,8 @@
<para>The script generated by the compiler uses <para>The script generated by the compiler uses
<command>iptables-restore</command> to instantiate the Netfilter <command>iptables-restore</command> to instantiate the Netfilter
configuration. So it runs much faster than the script generated by the configuration. So it runs much faster than the script generated by the
Shorewall-shell compiler.</para> Shorewall-shell compiler and doesn't stop new connections during
<command>shorewall restart</command>.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -78,8 +79,8 @@
<section id="DownSide"> <section id="DownSide">
<title>Shorewall-perl - The down side</title> <title>Shorewall-perl - The down side</title>
<para>While there are advantages to using Shorewall-perl, there are also <para>While there are significant advantages to using Shorewall-perl,
disadvantages.</para> there are also disadvantages.</para>
<section id="Incompatibilities"> <section id="Incompatibilities">
<title>Incompatibilities</title> <title>Incompatibilities</title>
@ -112,10 +113,12 @@
Shorewall-shell compiler goes to great pain (in some cases) to break 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 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 two ports) into individual rules. In the new compiler, I'm avoiding
the ugliness required to do that. The new compiler just generates an the ugliness required to do that for source port lists. The new
error if your list is too long. It will also produce an error if you compiler just generates an error if your source list is too long
insert a port range into a port list and you don't have extended (beginning with Shorewall 4.0.5, the compiler will break rules with
multiport support.</para> a long destination port list into multiple rules).. 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>
<listitem> <listitem>
@ -164,7 +167,7 @@
extension scripts from earlier versions will no longer work.</para> extension scripts from earlier versions will no longer work.</para>
<para>The following table summarizes when the various extension <para>The following table summarizes when the various extension
scripts are run:<informaltable frame="all"> scripts are run:<informaltable align="left" frame="none">
<tgroup cols="3"> <tgroup cols="3">
<tbody> <tbody>
<row> <row>
@ -228,8 +231,8 @@
<para>Compile-time extension scripts are executed using the Perl <para>Compile-time extension scripts are executed using the Perl
'eval `cat &lt;file&gt;`' mechanism. Be sure that each script 'eval `cat &lt;file&gt;`' mechanism. Be sure that each script
returns a 'true' value; otherwise, the compiler will assume that the returns a 'true' value; otherwise, the Shorweall-perl compiler will
script failed and will abort the compilation.</para> 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 usually hold a role="bold">$chainref</emphasis> scalar variable will usually hold a
@ -385,12 +388,18 @@ fi</programlisting>
<para>The file <filename>/etc/shorewall/ipsets</filename> will <para>The file <filename>/etc/shorewall/ipsets</filename> will
normally be produced using the <command>ipset -S</command> normally be produced using the <command>ipset -S</command>
command.</para> command. I have this in my<filename>
/etc/shorewall/stop</filename> file:</para>
<para>The above will work most of the time but will fail in a <programlisting>if ipset -S &gt; /etc/shorewall/ipsets.tmp; then
<command>shorewall stop</command> - <command>shorewall mv -f /etc/shorewall/ipsets /etc/shorewall/ipsets.bak
start</command> sequence if you use ipsets in your routestopped mv /etc/shorewall/ipsets.tmp /etc/shorewall/ipsets
file (see below).</para> fi</programlisting>
<para>The above extension scripts 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>
<listitem> <listitem>
@ -424,7 +433,8 @@ fi</programlisting>
<listitem> <listitem>
<para>USE_ACTIONS=No is not supported. That option is intended to <para>USE_ACTIONS=No is not supported. That option is intended to
minimize Shorewall's footprint in embedded applications. As a minimize Shorewall's footprint in embedded applications. As a
consequence, Default Macros are not supported.</para> consequence, Default Macros are not supported by
Shorewall-perl.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -452,8 +462,8 @@ 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 is all rule-oriented files. This implementation enforces consistency of
consistent between files.</para> syntax between files.</para>
<para>With shorewall-shell, there is a special syntax in the SOURCE <para>With shorewall-shell, there is a special syntax in the SOURCE
column of /etc/shorewall/masq to designate "all traffic entering the column of /etc/shorewall/masq to designate "all traffic entering the
@ -489,6 +499,10 @@ eth0 eth1:!192.168.4.9 ...</programlisting></para>
<programlisting>#SOURCE DEST POLICY LOG LEVEL <programlisting>#SOURCE DEST POLICY LOG LEVEL
all all REJECT info all all REJECT info
loc net ACCEPT</programlisting> loc net ACCEPT</programlisting>
<para>Shorewall-shell silently accepts the above even though the
loc-&gt;net policy is useless. Shorewall-perl generates a fatal
compilation error.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -543,7 +557,9 @@ DNAT- net 192.168.1.3 tcp 21</programlisti
<para>Shorewall-perl is dependent on Perl (see the next section) which <para>Shorewall-perl is dependent on Perl (see the next section) which
has a large disk footprint. This makes Shorewall-perl less desirable in has a large disk footprint. This makes Shorewall-perl less desirable in
an embedded environment.</para> an embedded environment. The best way to work around this limitation is
to install Shorewall-perl on an administrative system and employ
Shorewall-lite on your embedded systems.</para>
</section> </section>
</section> </section>
@ -554,6 +570,12 @@ DNAT- net 192.168.1.3 tcp 21</programlisti
<listitem> <listitem>
<para>Perl (I use Perl 5.8.8 but other 5.8 or later versions should <para>Perl (I use Perl 5.8.8 but other 5.8 or later versions should
work fine)</para> work fine)</para>
<note>
<para>If you want to be able to use DNS names in your Shorewall6
configuration files, then Perl 5.10 is required together with the
Perl Socket6 module.</para>
</note>
</listitem> </listitem>
<listitem> <listitem>
@ -715,6 +737,13 @@ DNAT- net 192.168.1.3 tcp 21</programlisti
<para>Added in Shorewall 4.1. If given, controls the verbosity of <para>Added in Shorewall 4.1. If given, controls the verbosity of
logging to the log specified by the --log parameter.</para> logging to the log specified by the --log parameter.</para>
<simplelist>
<member><emphasis role="bold">--family=</emphasis>4|6</member>
</simplelist>
<para>Added in Shorewall 4.2.4. Specifies whether an IPv4 or an IPv6
firewall is to be created.</para>
<para>Example (compiles the configuration in the current directory <para>Example (compiles the configuration in the current directory
generating a script named 'firewall' and using VERBOSITY generating a script named 'firewall' and using VERBOSITY
2).<programlisting><emphasis role="bold">/usr/share/shorewall-perl/compiler.pl -v 2 -d . firewall</emphasis></programlisting><note> 2).<programlisting><emphasis role="bold">/usr/share/shorewall-perl/compiler.pl -v 2 -d . firewall</emphasis></programlisting><note>
@ -891,6 +920,14 @@ set +a
<para>Log Verbosity; range -1 to 2.</para> <para>Log Verbosity; range -1 to 2.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry>
<term>family</term>
<listitem>
<para>Address family: 4 or 6</para>
</listitem>
</varlistentry>
</variablelist> </variablelist>
<para>Those parameters that are supplied must have defined values. <para>Those parameters that are supplied must have defined values.
@ -912,6 +949,8 @@ set +a
<member>log ''</member> <member>log ''</member>
<member>log_verbosity -1</member> <member>log_verbosity -1</member>
<member>family 4</member>
</simplelist></para> </simplelist></para>
<para>Example: <programlisting>use lib '/usr/share/shorewall-perl/'; <para>Example: <programlisting>use lib '/usr/share/shorewall-perl/';
@ -957,8 +996,9 @@ my $chainref7 = $filter_table{$name};</programlisting>Shorewall::Chains is
<listitem> <listitem>
<para>Reference to the 'nat' portion of the table <para>Reference to the 'nat' portion of the table
($chain_table{nat}). This is a hash whose key is the chain ($chain_table{nat}). This is a hash whose key is the chain name.
name.</para> This variable is not set when an IPv6 firewall is being
created.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -1172,7 +1212,7 @@ progress_message "This will only be seen if VERBOSITY &gt;= 2";
progress_message2 "This will only be seen if VERBOSITY &gt;= 1"; progress_message2 "This will only be seen if VERBOSITY &gt;= 1";
progress_message3 "This will be seen unless VERBOSITY &lt; 0"; progress_message3 "This will be seen unless VERBOSITY &lt; 0";
</programlisting>The <emphasis role="bold">shorewall()</emphasis> function may </programlisting>The <emphasis role="bold">shorewall()</emphasis> function may
be optionally included.<programlisting>use lib '/usr/share/shorewall-perl'; be optionally included:<programlisting>use lib '/usr/share/shorewall-perl';
use Shorewall::Config qw/shorewall/; use Shorewall::Config qw/shorewall/;
shorewall $config_file_entry;</programlisting>The Shorewall::Config module shorewall $config_file_entry;</programlisting>The Shorewall::Config module

8
docs/configuration_file_basics.xml
View File

@ -989,11 +989,9 @@ DNAT net loc:192.168.1.3 tcp 4000:4100</programlisting>
<para>Shorewall-perl requires <emphasis role="bold">multiport</emphasis> <para>Shorewall-perl requires <emphasis role="bold">multiport</emphasis>
match in order to accept port lists in Shorewall configuration files. It match in order to accept port lists in Shorewall configuration files. It
further requires Extended <emphasis role="bold">multiport</emphasis> further requires Extended <emphasis role="bold">multiport</emphasis>
match in order to accept port ranges in port lists. Shorewall-perl will match in order to accept port ranges in port lists. Shorewall-perl
never break a list longer than 15 ports (with each range counting as two versions earlier than 4.0.5 will never break a list longer than 15 ports
ports) into smaller lists. So you must be sure that your port lists can (with each range counting as two ports) into smaller lists.</para>
be handled directly by the Netfilter/iptables capabilities
available.</para>
</note> </note>
</section> </section>