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>
<listitem>
<para>Shorewall-shell - the old shell-based compiler and related
components.</para>
<para><emphasis role="bold">Shorewall-shell</emphasis> - the old
shell-based compiler and related components.</para>
</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>
<para>Shorewall-common - the part of Shorewall common to both
compilers.</para>
<para><emphasis role="bold">Shorewall-common</emphasis> - the part of
Shorewall common to both compilers.</para>
</listitem>
<listitem>
<para>Shorewall-lite- same as the 3.4 version of Shorewall Lite. Can
run scripts generated by either Shorewall-perl or
Shorewall-shell.</para>
<para><emphasis role="bold">Shorewall-lite</emphasis>- same as the 3.4
version of Shorewall Lite. Can run scripts generated by either
Shorewall-perl or Shorewall-shell.</para>
</listitem>
<listitem>
<para>Shorewall6 - The utilities for creating and operating an Ipv6
firewall. Requires Shorewall-perl.</para>
<para><emphasis role="bold">Shorewall6</emphasis> - The utilities for
creating and operating an Ipv6 firewall. Requires Shorewall-perl and
Shorewall-common.</para>
</listitem>
<listitem>
<para>Shorewall6-lite - Ipv6 equivalent of Shorewall Lite. Can run
scripts generated by Shoreall-perl 4.2.4 and later.</para>
<para><emphasis role="bold">Shorewall6-lite</emphasis> - Ipv6
equivalent of Shorewall Lite. Can run scripts generated by
Shoreall-perl 4.2.4 and later.</para>
</listitem>
</itemizedlist>
@ -143,32 +146,43 @@
<itemizedlist>
<listitem>
<para>Perl (I use Perl 5.8.8 but other 5.8 versions should work
fine)</para>
<para>Perl (I use Perl 5.8.8 but other 5.8 versions should work fine).
<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>
<para>Perl Cwd Module</para>
<para>Perl <emphasis role="bold">Cwd</emphasis> Module</para>
</listitem>
<listitem>
<para>Perl File::Basename Module</para>
<para>Perl <emphasis role="bold">File::Basename</emphasis>
Module</para>
</listitem>
<listitem>
<para>Perl File::Temp Module</para>
<para>Perl <emphasis role="bold">File::Temp</emphasis> Module</para>
</listitem>
<listitem>
<para>Perl Getopt::Long Module</para>
<para>Perl <emphasis role="bold">Getopt::Long</emphasis> Module</para>
</listitem>
<listitem>
<para>Perl Carp Module</para>
<para>Perl <emphasis role="bold">Carp</emphasis> Module</para>
</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>
</itemizedlist>
</section>
@ -188,8 +202,8 @@
<para>If you only install one compiler, then that compiler will be
used.</para>
<para>If you install both compilers, then the compiler actually used
depends on the SHOREWALL_COMPILER setting in
<para>If you install both compilers, then the compiler actually used for
IPv4 depends on the SHOREWALL_COMPILER setting in
<filename>shorewall.conf</filename>.</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
set SHOREWALL_COMPILER.</para>
<para>You can select the compiler to use on the command line using the 'C
option:<simplelist>
<para>If both compilers are installed, you can select the compiler to use
on the command line using the 'C option:<simplelist>
<member>'-C shell' means use the shell 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>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
to be exported automatically by the shell. The Shorewall-perl compiler
uses the current environmental variables to perform variable expansion

88
docs/Shorewall-perl.xml
View File

@ -53,7 +53,8 @@
<para>The script generated by the compiler uses
<command>iptables-restore</command> to instantiate the Netfilter
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>
@ -78,8 +79,8 @@
<section id="DownSide">
<title>Shorewall-perl - The down side</title>
<para>While there are advantages to using Shorewall-perl, there are also
disadvantages.</para>
<para>While there are significant advantages to using Shorewall-perl,
there are also disadvantages.</para>
<section id="Incompatibilities">
<title>Incompatibilities</title>
@ -112,10 +113,12 @@
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>
the ugliness required to do that for source port lists. The new
compiler just generates an error if your source list is too long
(beginning with Shorewall 4.0.5, the compiler will break rules with
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>
@ -164,7 +167,7 @@
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">
scripts are run:<informaltable align="left" frame="none">
<tgroup cols="3">
<tbody>
<row>
@ -228,8 +231,8 @@
<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>
returns a 'true' value; otherwise, the Shorweall-perl 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 usually hold a
@ -385,12 +388,18 @@ fi</programlisting>
<para>The file <filename>/etc/shorewall/ipsets</filename> will
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
<command>shorewall stop</command> - <command>shorewall
start</command> sequence if you use ipsets in your routestopped
file (see below).</para>
<programlisting>if ipset -S &gt; /etc/shorewall/ipsets.tmp; then
mv -f /etc/shorewall/ipsets /etc/shorewall/ipsets.bak
mv /etc/shorewall/ipsets.tmp /etc/shorewall/ipsets
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>
@ -424,7 +433,8 @@ fi</programlisting>
<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>
consequence, Default Macros are not supported by
Shorewall-perl.</para>
</listitem>
<listitem>
@ -452,8 +462,8 @@ fi</programlisting>
<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>
all rule-oriented files. This implementation enforces consistency of
syntax 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
@ -489,6 +499,10 @@ eth0 eth1:!192.168.4.9 ...</programlisting></para>
<programlisting>#SOURCE DEST POLICY LOG LEVEL
all all REJECT info
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>
@ -533,17 +547,19 @@ ACCEPT loc:eth0:192.168.1.3,eth0:192.168.1.5 $fw tcp 22</programlisting>
DNAT- net loc:192.168.1.3 tcp 21</programlisting></para>
<para>you instead want:<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
DNAT- net 192.168.1.3 tcp 21</programlisting></para>
DNAT- net 192.168.1.3 tcp 21</programlisting></para>
</listitem>
</orderedlist>
</section>
<section id="PerlDep">
<title> Dependence on Perl</title>
<title>Dependence on Perl</title>
<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>
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>
@ -554,6 +570,12 @@ DNAT- net 192.168.1.3 tcp 21</programlisti
<listitem>
<para>Perl (I use Perl 5.8.8 but other 5.8 or later versions should
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>
@ -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
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
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>
@ -891,6 +920,14 @@ set +a
<para>Log Verbosity; range -1 to 2.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>family</term>
<listitem>
<para>Address family: 4 or 6</para>
</listitem>
</varlistentry>
</variablelist>
<para>Those parameters that are supplied must have defined values.
@ -912,6 +949,8 @@ set +a
<member>log ''</member>
<member>log_verbosity -1</member>
<member>family 4</member>
</simplelist></para>
<para>Example: <programlisting>use lib '/usr/share/shorewall-perl/';
@ -957,8 +996,9 @@ my $chainref7 = $filter_table{$name};</programlisting>Shorewall::Chains is
<listitem>
<para>Reference to the 'nat' portion of the table
($chain_table{nat}). This is a hash whose key is the chain
name.</para>
($chain_table{nat}). This is a hash whose key is the chain name.
This variable is not set when an IPv6 firewall is being
created.</para>
</listitem>
</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_message3 "This will be seen unless VERBOSITY &lt; 0";
</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/;
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>
match in order to accept port lists in Shorewall configuration files. It
further requires Extended <emphasis role="bold">multiport</emphasis>
match in order to accept port ranges in port lists. Shorewall-perl will
never break a list longer than 15 ports (with each range counting as two
ports) into smaller lists. So you must be sure that your port lists can
be handled directly by the Netfilter/iptables capabilities
available.</para>
match in order to accept port ranges in port lists. Shorewall-perl
versions earlier than 4.0.5 will never break a list longer than 15 ports
(with each range counting as two ports) into smaller lists.</para>
</note>
</section>