mirror of
https://gitlab.com/shorewall/code.git
synced 2024-11-22 07:33:43 +01:00
Add Shorewall-perl documentation
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@5861 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
This commit is contained in:
teastep
parent
c35af63298
commit
fd6d7a3e1b
@ -122,8 +122,8 @@
|
||||
|
||||
<entry><ulink url="shorewall_logging.html">Logging</ulink></entry>
|
||||
|
||||
<entry><ulink url="shorewall_setup_guide.htm">Shorewall Setup
|
||||
Guide</ulink></entry>
|
||||
<entry><ulink url="Shorewall-perl.html">Shorewall
|
||||
Perl</ulink></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
@ -132,7 +132,8 @@
|
||||
|
||||
<entry><ulink url="Macros.html">Macros</ulink></entry>
|
||||
|
||||
<entry><ulink url="samba.htm">SMB</ulink></entry>
|
||||
<entry><ulink url="shorewall_setup_guide.htm">Shorewall Setup
|
||||
Guide</ulink></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
@ -142,8 +143,7 @@
|
||||
<entry><ulink url="MAC_Validation.html">MAC
|
||||
Verification</ulink></entry>
|
||||
|
||||
<entry><ulink url="Shorewall_Squid_Usage.html">Squid with
|
||||
Shorewall</ulink></entry>
|
||||
<entry><ulink url="samba.htm">SMB</ulink></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
@ -154,9 +154,8 @@
|
||||
from a Single Firewall</ulink> (<ulink
|
||||
url="MultiISP_ru.html">Russian</ulink>)</entry>
|
||||
|
||||
<entry><ulink
|
||||
url="starting_and_stopping_shorewall.htm">Starting/stopping the
|
||||
Firewall</ulink></entry>
|
||||
<entry><ulink url="Shorewall_Squid_Usage.html">Squid with
|
||||
Shorewall</ulink></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
@ -166,8 +165,9 @@
|
||||
<entry><ulink url="Multiple_Zones.html">Multiple Zones Through One
|
||||
Interface</ulink></entry>
|
||||
|
||||
<entry><ulink url="NAT.htm">Static (one-to-one)
|
||||
NAT</ulink></entry>
|
||||
<entry><ulink
|
||||
url="starting_and_stopping_shorewall.htm">Starting/stopping the
|
||||
Firewall</ulink></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
@ -177,7 +177,8 @@
|
||||
<entry><ulink url="XenMyWay-Routed.html">My Shorewall
|
||||
Configuration</ulink></entry>
|
||||
|
||||
<entry><ulink url="support.htm">Support</ulink></entry>
|
||||
<entry><ulink url="NAT.htm">Static (one-to-one)
|
||||
NAT</ulink></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
@ -187,8 +188,7 @@
|
||||
<entry><ulink url="NetfilterOverview.html">Netfilter
|
||||
Overview</ulink></entry>
|
||||
|
||||
<entry><ulink url="Accounting.html">Traffic
|
||||
Accounting</ulink></entry>
|
||||
<entry><ulink url="support.htm">Support</ulink></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
@ -197,9 +197,8 @@
|
||||
|
||||
<entry><ulink url="netmap.html">Network Mapping</ulink></entry>
|
||||
|
||||
<entry><ulink url="traffic_shaping.htm">Traffic
|
||||
Shaping/QOS</ulink> (<ulink
|
||||
url="traffic_shaping_ru.html">Russian</ulink>)</entry>
|
||||
<entry><ulink url="Accounting.html">Traffic
|
||||
Accounting</ulink></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
@ -208,8 +207,9 @@
|
||||
<entry><ulink url="NAT.htm">One-to-one NAT</ulink> (Static
|
||||
NAT)</entry>
|
||||
|
||||
<entry><ulink
|
||||
url="troubleshoot.htm">Troubleshooting</ulink></entry>
|
||||
<entry><ulink url="traffic_shaping.htm">Traffic
|
||||
Shaping/QOS</ulink> (<ulink
|
||||
url="traffic_shaping_ru.html">Russian</ulink>)</entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
@ -218,7 +218,8 @@
|
||||
|
||||
<entry><ulink url="OPENVPN.html">OpenVPN</ulink></entry>
|
||||
|
||||
<entry><ulink url="UPnP.html">UPnP</ulink></entry>
|
||||
<entry><ulink
|
||||
url="troubleshoot.htm">Troubleshooting</ulink></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
@ -228,8 +229,7 @@
|
||||
<entry><ulink url="starting_and_stopping_shorewall.htm">Operating
|
||||
Shorewall</ulink></entry>
|
||||
|
||||
<entry><ulink url="upgrade_issues.htm">Upgrade
|
||||
Issues</ulink></entry>
|
||||
<entry><ulink url="UPnP.html">UPnP</ulink></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
@ -239,7 +239,8 @@
|
||||
<entry><ulink url="PacketMarking.html">Packet
|
||||
Marking</ulink></entry>
|
||||
|
||||
<entry><ulink url="VPNBasics.html">VPN</ulink></entry>
|
||||
<entry><ulink url="upgrade_issues.htm">Upgrade
|
||||
Issues</ulink></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
@ -249,8 +250,7 @@
|
||||
<entry><ulink url="PacketHandling.html">Packet Processing in a
|
||||
Shorewall-based Firewall</ulink></entry>
|
||||
|
||||
<entry><ulink url="whitelisting_under_shorewall.htm">White List
|
||||
Creation</ulink></entry>
|
||||
<entry><ulink url="VPNBasics.html">VPN</ulink></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
@ -258,8 +258,8 @@
|
||||
|
||||
<entry><ulink url="ping.html">'Ping' Management</ulink></entry>
|
||||
|
||||
<entry><ulink url="XenMyWay.html">Xen - Shorewall in a Bridged Xen
|
||||
DomU</ulink></entry>
|
||||
<entry><ulink url="whitelisting_under_shorewall.htm">White List
|
||||
Creation</ulink></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
@ -268,8 +268,8 @@
|
||||
|
||||
<entry><ulink url="ports.htm">Port Information</ulink></entry>
|
||||
|
||||
<entry><ulink url="Xen.html">Xen - Shorewall in Bridged Xen
|
||||
Dom0</ulink></entry>
|
||||
<entry><ulink url="XenMyWay.html">Xen - Shorewall in a Bridged Xen
|
||||
DomU</ulink></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
@ -279,8 +279,8 @@
|
||||
<entry><ulink url="PortKnocking.html">Port Knocking and Other Uses
|
||||
of the 'Recent Match'</ulink></entry>
|
||||
|
||||
<entry><ulink url="XenMyWay-Routed.html">Xen - Shorewall in Routed
|
||||
Xen Dom0</ulink></entry>
|
||||
<entry><ulink url="Xen.html">Xen - Shorewall in Bridged Xen
|
||||
Dom0</ulink></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
@ -288,7 +288,8 @@
|
||||
|
||||
<entry><ulink url="PPTP.htm">PPTP</ulink></entry>
|
||||
|
||||
<entry></entry>
|
||||
<entry><ulink url="XenMyWay-Routed.html">Xen - Shorewall in Routed
|
||||
Xen Dom0</ulink></entry>
|
||||
</row>
|
||||
|
||||
<row>
|
||||
|
||||
350
docs/Shorewall-perl.xml
Normal file
350
docs/Shorewall-perl.xml
Normal file
@ -0,0 +1,350 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
||||
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
||||
<article>
|
||||
<!--$Id: template.xml 4194 2006-07-07 01:04:16Z judas_iscariote $-->
|
||||
|
||||
<articleinfo>
|
||||
<title>Shorewall-perl</title>
|
||||
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Tom</firstname>
|
||||
|
||||
<surname>Eastep</surname>
|
||||
</author>
|
||||
</authorgroup>
|
||||
|
||||
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
|
||||
|
||||
<copyright>
|
||||
<year>2007</year>
|
||||
|
||||
<holder>Thomas M. Eastep</holder>
|
||||
</copyright>
|
||||
|
||||
<legalnotice>
|
||||
<para>Permission is granted to copy, distribute and/or modify this
|
||||
document under the terms of the GNU Free Documentation License, Version
|
||||
1.2 or any later version published by the Free Software Foundation; with
|
||||
no Invariant Sections, with no Front-Cover, and with no Back-Cover
|
||||
Texts. A copy of the license is included in the section entitled
|
||||
<quote><ulink url="GnuCopyright.htm">GNU Free Documentation
|
||||
License</ulink></quote>.</para>
|
||||
</legalnotice>
|
||||
</articleinfo>
|
||||
|
||||
<section>
|
||||
<title>Shorewall-perl - What is it?</title>
|
||||
|
||||
<para>Shorewall-perl is a companion product to Shorewall. It requires
|
||||
Shorewall 3.4.2 or later. </para>
|
||||
|
||||
<para>Shorewall-perl contains a re-implementation of the Shorewall
|
||||
compiler written in Perl. The advantages of using Shorewall-perl are over
|
||||
Shorewall-shell (the shell-based compiler included in earlier Shorewall
|
||||
3.x releases) are:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>The Shorewall-perl compiler is much faster.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<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>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>The Shorewall-perl compiler does more thorough checking of the
|
||||
configuration than the Shorewall-shell compiler does.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Going forward, the Shorewall-perl compiler will get all
|
||||
enhancements; the Shorewall-shell compiler will only get those
|
||||
enhancements that are easy to retrofit.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Shorewall-perl - The down side</title>
|
||||
|
||||
<para>While there are advantages to using Shorewall-perl, there are also
|
||||
disadvantages:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>There are a number of incompatibilities between the
|
||||
Shorewall-perl compiler and the earlier one.</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> Because the compiler is now written in Perl, your
|
||||
compile-time extension scripts from earlier versions will no
|
||||
longer work. For now, if you want to use extension scripts, you
|
||||
will need to read the Perl code to see how the compiler operates
|
||||
internally. I will produce documentation before the first official
|
||||
release. Compile-time extension scripts are executed using the
|
||||
Perl 'do FILE' mechanism.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>The 'refresh' command is now synonymous with
|
||||
'restart'.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Some run-time extension scripts are no longer supported
|
||||
because they make no sense (iptables-restore instantiates the new
|
||||
configuration atomically).</para>
|
||||
|
||||
<simplelist>
|
||||
<member>continue</member>
|
||||
|
||||
<member>initdone</member>
|
||||
|
||||
<member>continue</member>
|
||||
|
||||
<member>refresh</member>
|
||||
|
||||
<member>refreshed</member>
|
||||
</simplelist>
|
||||
</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 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>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>
|
||||
</orderedlist>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Shorewall-perl - Prerequisites</title>
|
||||
|
||||
<para>In addition to Shorewall-3.4.2 or later, you need:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Perl (I use Perl 5.8.8 but other versions should work
|
||||
fine)</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Perl Cwd Module</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Perl File::Basename Module</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Perl File::Temp Module</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Shorewall-perl - Installation</title>
|
||||
|
||||
<caution>
|
||||
<para>Shorewall-perl is still part of the <ulink
|
||||
url="ReleaseModel.html">current development release</ulink>. Use it at
|
||||
your own risk. </para>
|
||||
</caution>
|
||||
|
||||
<para>Either</para>
|
||||
|
||||
<programlisting><command>tar -jxf shorewall-perl-3.9.1.tar.bz2</command>
|
||||
<command>cd shorewall-perl-3.9.1</command>
|
||||
<command>./install.sh</command></programlisting>
|
||||
|
||||
<para>or</para>
|
||||
|
||||
<programlisting><command>rpm -ivh shoreawll-pl-3.9.1-1.noarch.rpm</command></programlisting>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Using Shorewall-perl</title>
|
||||
|
||||
<para>By default, the Shorewall-shell compiler will be used.</para>
|
||||
|
||||
<para>To use the Shorewall-perl compiler, add this to
|
||||
<filename>shorewall.conf</filename>:</para>
|
||||
|
||||
<para>SHOREWALL_COMPILER=perl</para>
|
||||
|
||||
<para>If you add this setting to
|
||||
<filename>/etc/shorewall/shorewall.conf</filename> then by default, the
|
||||
new compiler will be used on the system. If you add it to
|
||||
<filename>shorewall.conf</filename> in a separate directory (such as a
|
||||
Shorewall-lite export directory) then the new compiler will only be used
|
||||
when you compile from that directory.</para>
|
||||
|
||||
<para>Regardless of the setting of SHOREWALL_COMPILER, there is one change
|
||||
in Shorewall operation that is triggered simply by installing
|
||||
Shorewall-perl. Your params file will be processed with the shell's '-a'
|
||||
option which causes any variables that you set or create in that file to
|
||||
be automatically exported. Since the params file is processed before
|
||||
<filename>shorewall.conf</filename>, using -a insures that the settings of
|
||||
your params variables are available to the new compiler should it's use be
|
||||
specified in <filename>shorewall.conf</filename>.</para>
|
||||
</section>
|
||||
</article>
|
||||
@ -85,8 +85,8 @@
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>Combination Firewall/Public Server/Private Server/Wireless
|
||||
Gateway using Xen (created by building out my Linux desktop
|
||||
system).</para>
|
||||
Gateway using Xen (created by building out my Linux desktop system --
|
||||
Now replaced by a Hewlett-Packard Pavilion a1510y).</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
@ -99,7 +99,7 @@
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
|
||||
<para>The Linux systems run either <trademark>SuSE </trademark>10.1 or
|
||||
<para>The Linux systems run either <trademark>OpenSuSE </trademark>10.2 or
|
||||
<trademark>Ubuntu</trademark> "Edgy Eft".</para>
|
||||
|
||||
<para>Here is a high-level diagram of our network.</para>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user