mirror of
https://gitlab.com/shorewall/code.git
synced 2024-11-27 18:13:13 +01:00
1233 lines
45 KiB
XML
1233 lines
45 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.4/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>
|
|
|
|
<year>2009</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 id="What">
|
|
<title>Shorewall-perl - What is it?</title>
|
|
|
|
<para>Shorewall-perl was released as a companion product to Shorewall in
|
|
Shorewall 4.0.0.</para>
|
|
|
|
<para>Shorewall-perl contained a re-implementation of the Shorewall
|
|
compiler written in Perl. The advantages of using Shorewall-perl over
|
|
Shorewall-shell (the shell-based compiler included in earlier Shorewall
|
|
3.x releases) were:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The Shorewall-perl compiler was much faster.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The script generated by the compiler used
|
|
<command>iptables-restore</command> to instantiate the Netfilter
|
|
configuration. So it ran much faster than the script generated by the
|
|
Shorewall-shell compiler and did not stop new connections during
|
|
<command>shorewall restart</command>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The Shorewall-perl compiler did more thorough checking of the
|
|
configuration than the Shorewall-shell compiler did.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The error messages produced by the compiler were better, more
|
|
consistent and always included the file name and line number where the
|
|
error was detected.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Going forward, the Shorewall-perl compiler got all enhancements;
|
|
the Shorewall-shell compilerl only got those enhancements that were
|
|
easy to retrofit.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Beginning with Shorewall 4.3.5, Shorewall-perl is an integral part
|
|
of Shorewall and support for Shorewall-shell has been discontinued.</para>
|
|
</section>
|
|
|
|
<section id="DownSide">
|
|
<title>Shorewall-perl - The down side</title>
|
|
|
|
<para>While there are significant advantages to using Shorewall-perl,
|
|
there are also disadvantages.</para>
|
|
|
|
<section id="Incompatibilities">
|
|
<title>Incompatibilities</title>
|
|
|
|
<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 multiport match in your
|
|
kernel and iptables.</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. <ulink
|
|
url="bridge-Shorewall-perl.html">Alternative bridge support</ulink>
|
|
is provided by Shorewall-perl.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>DYNAMIC_ZONES=Yes is not supported in Shorewall-perl 4.2.
|
|
<ulink url="ipsets.html#Dynamic">Use an ipset </ulink>to define your
|
|
dytnamic zones. In Shorewall 4.4, dynamic zone support based on
|
|
ipsets was added to Shorewall.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The BROADCAST column in the interfaces file is essentially
|
|
unused if your kernel/iptables has Address Type Match support. If
|
|
that support is present and you enter anything in this column but
|
|
'-' or 'detect', you will receive a warning.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The 'refresh' command is now similar to restart with the
|
|
exceptions that:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The command fails if Shorewall is not running.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>A directory name cannot be specified in the
|
|
command.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The refresh command does not alter the Netfilter
|
|
configuration except for the static blacklist (it also refreshes
|
|
the mangle table, beginning with Shorewall 4.2.0).</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem id="Extensions">
|
|
<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 rule set is built by the compiler. As a result,
|
|
Shorewall-perl runs some 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:</para>
|
|
|
|
<informaltable align="left" frame="none">
|
|
<tgroup cols="3">
|
|
<tbody>
|
|
<row>
|
|
<entry><emphasis role="bold">Compile-time (Must be written
|
|
in Perl)</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>init</entry>
|
|
|
|
<entry></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>Compile-time extension scripts are executed using the Perl
|
|
'eval `cat <file>`' mechanism. Be sure that each script
|
|
returns a 'true' value; otherwise, the Shorewall-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
|
|
reference to a chain table entry.</para>
|
|
|
|
<simplelist>
|
|
<member><emphasis role="bold">$chainref->{name}</emphasis>
|
|
contains the name of the chain</member>
|
|
|
|
<member><emphasis role="bold">$chainref->{table}</emphasis>
|
|
holds the table name</member>
|
|
</simplelist>
|
|
|
|
<para>To add a rule to the chain:</para>
|
|
|
|
<simplelist>
|
|
<member>add_rule $chainref,
|
|
<replaceable>the-rule</replaceable></member>
|
|
</simplelist>
|
|
|
|
<para>Where</para>
|
|
|
|
<simplelist>
|
|
<member><replaceable>the rule</replaceable> is a scalar argument
|
|
holding the rule text. Do not include "-A
|
|
<replaceable>chain-name</replaceable>"</member>
|
|
</simplelist>
|
|
|
|
<para>Example:</para>
|
|
|
|
<simplelist>
|
|
<member>add_rule $chainref, '-j ACCEPT';</member>
|
|
</simplelist>
|
|
|
|
<para>To insert a rule into the chain:</para>
|
|
|
|
<simplelist>
|
|
<member>insert_rule $chainref, <replaceable>rulenum</replaceable>,
|
|
<replaceable>the-rule</replaceable></member>
|
|
</simplelist>
|
|
|
|
<para>The log_rule_limit function works like it does in the shell
|
|
compiler with three exceptions:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>You pass the chain reference rather than the name of the
|
|
chain.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The commands are 'add' and 'insert' rather than '-A' and
|
|
'-I'.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>There is only a single "pass as-is to iptables" argument
|
|
(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'
|
|
'-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>
|
|
<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 id="SAVE_IPSETS">
|
|
<para>Shorewall-perl insists that ipset names begin with a letter
|
|
and be composed of alphanumeric characters and underscores (_). When
|
|
used in a Shorewall configuration file, the name must be preceded by
|
|
a plus sign (+) as with the shell-based compiler.</para>
|
|
|
|
<para>From Shorewall-perl 4.0.0 - Shorewall 4.4.5, Shorewall was out
|
|
of the ipset load/reload business with the exception of ipsets used
|
|
for dynamic zones:</para>
|
|
|
|
<blockquote>
|
|
<para>With scripts generated by the Perl-based Compiler, the
|
|
Netfilter rule set 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/init (it works for me; your mileage
|
|
may vary)</filename>:</para>
|
|
|
|
<programlisting>if [ "$COMMAND" = start ]; then
|
|
ipset -U :all: :all:
|
|
ipset -U :all: :default:
|
|
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. I have this in my<filename>
|
|
/etc/shorewall/stop</filename> file:</para>
|
|
|
|
<programlisting>if ipset -S > /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>
|
|
<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>
|
|
</blockquote>
|
|
|
|
<para>Beginning with Shorewall 4.4.6 (and 4.5.3), SAVE_IPSETS=Yes is
|
|
once again supported. See <ulink
|
|
url="manpages/shorewall.conf.html">shorewall.conf</ulink>(5).</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 by
|
|
Shorewall-perl.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>DELAYBLACKLISTLOAD=Yes is not supported. The entire rule set
|
|
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 (IPSECFILE=ipsec); neither is the
|
|
<filename>/etc/shorewall/ipsec</filename> file.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>BLACKLISTNEWONLY=No is not permitted with FASTACCEPT=Yes. This
|
|
combination doesn't work in previous versions of Shorewall so the
|
|
Perl-based compiler simply rejects it.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Shorewall-perl has a single rule generator that is used for
|
|
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
|
|
firewall on this interface except...".</para>
|
|
|
|
<para>Example:<programlisting>#INTERFACE SOURCE ADDRESSES
|
|
eth0 eth1!192.168.4.9 ...</programlisting>Shorewall-perl
|
|
uses syntax that is consistent with the rest of
|
|
Shorewall:<programlisting>#INTERFACE SOURCE ADDRESSES
|
|
eth0 eth1:!192.168.4.9 ...</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The 'allowoutUPnP' built-in action is no longer supported. In
|
|
kernel 2.6.14, the Netfilter team have removed support for '-m owner
|
|
--owner-cmd' which that action depended on.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The PKTTYPE option is ignored by Shorewall-perl.
|
|
Shorewall-perl will use Address type match if it is available;
|
|
otherwise, it will behave as if PKTTYPE=No had been
|
|
specified.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Shorewall-perl detects dead policy file entries that result
|
|
when an entry is masked by an earlier more general entry.</para>
|
|
|
|
<para>Example:</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->net policy is useless. Shorewall-perl generates a fatal
|
|
compilation error.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>In the SOURCE column of the rules file, when an interface name
|
|
is followed by a list of IP addresses, the behavior of
|
|
Shorewall-perl differs from that of Shorewall-shell.</para>
|
|
|
|
<para>Example:<programlisting>#ACTION SOURCE DEST PROTO DEST
|
|
# PORT(S)
|
|
ACCEPT loc:eth0:192.168.1.3,192.168.1.5 $FW tcp 22</programlisting>With
|
|
Shorewall-shell, this rule accepts SSH connection to the firewall
|
|
from 192.168.1.3 through eth0 or from 192.168.1.5 through any
|
|
interface. With Shorewall-perl, the rule accepts SSH connections
|
|
through eth0 from 192.168.1.3 and through eth0 from 192.168.1.5.
|
|
Shorewall-shell supports this syntax that gives the same result as
|
|
Shorewall-perl.<programlisting>#ACTION SOURCE DEST PROTO DEST
|
|
# PORT(S)
|
|
ACCEPT loc:eth0:192.168.1.3,eth0:192.168.1.5 $fw tcp 22</programlisting>
|
|
Shorewall-perl does not support this alternative syntax.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Shorewall-perl gives a warning if a zone name is entered in
|
|
the DEST column of a <firstterm>nonat</firstterm> rule. Nonat rules
|
|
include:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>DNAT-</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>REDIRECT-</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>NONAT</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>So rather than this:<programlisting>#ACTION SOURCE DEST PROTO DEST PORT(S)
|
|
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>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Supplying an interface name in the SOURCE column of
|
|
/etc/shorewall/masq is deprecated as of Shorewall 4.4. Entering the
|
|
name of an interface there will result in a compile-time
|
|
warning:</para>
|
|
|
|
<para>WARNING: Using an interface as the masq SOURCE requires the
|
|
interface to be up and configured when Shorewall
|
|
starts/restarts</para>
|
|
|
|
<para>To avoid this warning, replace interface names by the
|
|
corresponding network() in CIDR format (e.g.,
|
|
192.168.144.0/24).</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
|
|
<section id="PerlDep">
|
|
<title>Dependence on Perl</title>
|
|
|
|
<para>Shorewall-perl is dependent on Perl which has a large disk
|
|
footprint. This makes Shorewall-perl less desirable in 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. Shorewall-perl will run on Windows under <ulink
|
|
url="http://www.cygwin.com/">Cygwin</ulink> and on an <ulink
|
|
url="http://www.apple.com/mac/">Apple MacIntosh</ulink> running OS X.
|
|
Install from a shell prompt <ulink url="Install.htm">using the
|
|
install.sh script</ulink>.</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="Install">
|
|
<title>Installing Shorewall Version 4.0 or 4.2</title>
|
|
|
|
<para>Shorewall 4.2 contains six packages, four of which are also included
|
|
in Shorewall 4.0:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold">Shorewall-shell</emphasis> - the old
|
|
shell-based compiler and related components.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">Shorewall-perl</emphasis> - the new
|
|
Perl-based compiler.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">Shorewall-common</emphasis> - the part of
|
|
Shorewall common to both compilers.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<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><emphasis role="bold">Shorewall6</emphasis> - The utilities for
|
|
creating and operating an Ipv6 firewall. Requires Shorewall-perl and
|
|
Shorewall-common. Introduced in Shorewall 4.2.4.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<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>
|
|
|
|
<para>If you upgrade to Shorewall Version 4.0 or 4.2, you must install
|
|
Shorewall-shell and/or Shorewall-perl; in fact, if you are using the
|
|
tarball for your installation, you must install Shorewall-shell and/or
|
|
Shorewall-perl <emphasis role="bold">before</emphasis> you upgrade
|
|
Shorewall. See the <ulink url="upgrade_issues.htm">upgrade issues</ulink>
|
|
for details.</para>
|
|
</section>
|
|
|
|
<section id="CompilerSelection">
|
|
<title>Compiler Selection (Shorewall 4.0-4.2)</title>
|
|
|
|
<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 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>
|
|
|
|
<para>If you add 'SHOREWALL_COMPILER=perl' 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>If you only install one compiler, it is suggested that you do not
|
|
set SHOREWALL_COMPILER.</para>
|
|
|
|
<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>
|
|
</simplelist>The -C option overrides the setting in
|
|
shorewall.conf.</para>
|
|
|
|
<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 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
|
|
within the other Shorewall configuration files.</para>
|
|
</section>
|
|
|
|
<section id="Modules">
|
|
<title>The Shorewall Perl Modules</title>
|
|
|
|
<para>In Shorewall 4.4 and later, Shorewall's Perl modules are installed
|
|
in /usr/share/shorewall/Shorewall and the names of the packages are of the
|
|
form Shorewall::<firstterm>name</firstterm>. So by using this
|
|
directive<programlisting>use lib '/usr/share/shorewall';</programlisting></para>
|
|
|
|
<para>You can then load the modules via normal Perl use statements.</para>
|
|
|
|
<section id="compiler.pl">
|
|
<title>/usr/share/shorewall/compiler.pl</title>
|
|
|
|
<para>While the compiler is normally run indirectly using
|
|
/sbin/shorewall, it can be run directly as well.<programlisting><command>compiler.pl</command> [ <emphasis>option</emphasis> ... ] [ <emphasis>filename</emphasis> ]</programlisting></para>
|
|
|
|
<para>If a <emphasis>filename</emphasis> is given, then the
|
|
configuration will be compiled and the output placed in the named file.
|
|
If <emphasis>filename</emphasis> is not given, then the configuration
|
|
will simply be syntax checked.</para>
|
|
|
|
<para>Options are:</para>
|
|
|
|
<para><simplelist>
|
|
<member><command>-v</command><<emphasis>verbosity</emphasis>></member>
|
|
|
|
<member><command>--verbosity=</command><<emphasis>verbosity</emphasis>></member>
|
|
</simplelist>The <<emphasis>verbosity</emphasis>> is a number
|
|
between 0 and 2 and corresponds to the VERBOSITY setting in
|
|
<filename>shorewall.conf</filename>. This setting controls the verbosity
|
|
of the compiler itself.<note>
|
|
<para>The VERBOSITY setting in the
|
|
<filename>shorewall.conf</filename> file read by the compiler will
|
|
determine the default verbosity for the compiled program.</para>
|
|
</note><simplelist>
|
|
<member><emphasis role="bold">-e</emphasis></member>
|
|
|
|
<member><emphasis role="bold">--export</emphasis></member>
|
|
</simplelist>If given, the configuration will be compiled for export
|
|
to another system.<simplelist>
|
|
<member><emphasis role="bold">-d</emphasis>
|
|
<<emphasis>directory</emphasis>></member>
|
|
|
|
<member><emphasis
|
|
role="bold">--directory=</emphasis><<emphasis>directory</emphasis>></member>
|
|
</simplelist>If this option is omitted, the configuration in
|
|
/etc/shorewall is compiled/checked. Otherwise, the configuration in the
|
|
named directory will be compiled/checked.<simplelist>
|
|
<member><emphasis role="bold">-t</emphasis></member>
|
|
|
|
<member><emphasis role="bold">--timestamp</emphasis></member>
|
|
</simplelist>If given, each progress message issued by the compiler
|
|
and by the compiled program will be timestamped.<simplelist>
|
|
<member><emphasis role="bold">--debug</emphasis></member>
|
|
</simplelist>If given, when a warning or error message is issued, it
|
|
is supplemented with a stack trace. Requires the Carp Perl
|
|
module.<simplelist>
|
|
<member><emphasis
|
|
role="bold">--refresh=</emphasis><<emphasis>chainlist</emphasis>></member>
|
|
</simplelist>If given, the compiled script's 'refresh' command will
|
|
refresh the chains in the comma-separated
|
|
<<emphasis>chainlist</emphasis>> rather than
|
|
'blacklst'.<simplelist>
|
|
<member><emphasis
|
|
role="bold">--log</emphasis>=<logfile></member>
|
|
</simplelist></para>
|
|
|
|
<para>If given, compiler will log to this file provider that
|
|
--log_verbosity is > -1.<simplelist>
|
|
<member><emphasis
|
|
role="bold">--log_verbosity</emphasis>=-1|0|1|2</member>
|
|
</simplelist></para>
|
|
|
|
<para>If given, controls the verbosity of logging to the log specified
|
|
by the --log parameter.</para>
|
|
|
|
<simplelist>
|
|
<member><emphasis role="bold">-f</emphasis>=4|6</member>
|
|
|
|
<member><emphasis role="bold">--family=</emphasis>4|6</member>
|
|
</simplelist>
|
|
|
|
<para>Specifies whether an IPv4 or an IPv6 firewall is to be
|
|
created.</para>
|
|
|
|
<simplelist>
|
|
<member><emphasis role="bold">--preview</emphasis></member>
|
|
</simplelist>
|
|
|
|
<para>Added in Shorewall 4.4.6. If no filename is given, this option
|
|
causes the generated input to iptables-input to be displayed on standard
|
|
output.</para>
|
|
|
|
<simplelist>
|
|
<member><emphasis role="bold">-c</emphasis></member>
|
|
|
|
<member><emphasis role="bold">--confess</emphasis></member>
|
|
</simplelist>
|
|
|
|
<para>Added in Shorewall 4.4.20. Causes error and warning messages to
|
|
include a Perl stack trace. Useful for finding the place in the code
|
|
where the message is generated.</para>
|
|
|
|
<simplelist>
|
|
<member><emphasis role="bold">-u</emphasis></member>
|
|
|
|
<member><emphasis role="bold">--update</emphasis></member>
|
|
</simplelist>
|
|
|
|
<para>Added in Shorewall 4.4.21. Causes the .conf file to be updated
|
|
(<command>shorewall update</command> command).</para>
|
|
|
|
<simplelist>
|
|
<member><emphasis role="bold">-a</emphasis></member>
|
|
|
|
<member><emphasis role="bold">--annotate</emphasis></member>
|
|
</simplelist>
|
|
|
|
<para>Added in Shorewall 4.4.21. Causes the updated .conf file to be
|
|
annotated with documentation. Ignored unless <emphasis
|
|
role="bold">--update</emphasis> is also specified.</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/compiler.pl -v 2 -d . firewall</emphasis></programlisting><note>
|
|
<para>The Perl-based compiler does not process
|
|
<filename>/etc/shorewall/params</filename>. To include definitions
|
|
in that file, you would need to do something like the
|
|
following:<programlisting><command>. /usr/share/shorewall/lib.base # In case /etc/shorewall/params does INCLUDE
|
|
set -a # Export all variables set in /etc/shorewall/params
|
|
. /etc/shorewall/params
|
|
set +a
|
|
/usr/share/compiler.pl ...</command></programlisting></para>
|
|
</note></para>
|
|
</section>
|
|
|
|
<section id="Compiler">
|
|
<title>Shorewall::Compiler</title>
|
|
|
|
<para>To avoid a proliferation of parameters to
|
|
Shorewall::Compiler::compile(), that function uses named parameters.
|
|
Parameter names are:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>script ('object' is also accepted but deprecated)</term>
|
|
|
|
<listitem>
|
|
<para>Output script file. If omitted or '', the configuration is
|
|
syntax checked.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>directory</term>
|
|
|
|
<listitem>
|
|
<para>Directory. If omitted or '', configuration files are located
|
|
using CONFIG_PATH. Otherwise, the directory named by this
|
|
parameter is searched first.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>verbosity</term>
|
|
|
|
<listitem>
|
|
<para>Verbosity; range -1 to 2</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>timestamp</term>
|
|
|
|
<listitem>
|
|
<para>0|1 -- timestamp messages.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>debug</term>
|
|
|
|
<listitem>
|
|
<para>0|1 -- include stack trace in warning/error messages.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>export</term>
|
|
|
|
<listitem>
|
|
<para>0|1 -- compile for export.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>chains</term>
|
|
|
|
<listitem>
|
|
<para>List of chains to be reloaded by 'refresh'</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>log</term>
|
|
|
|
<listitem>
|
|
<para>File to log compiler messages to.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>log_verbosity</term>
|
|
|
|
<listitem>
|
|
<para>Log Verbosity; range -1 to 2.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>family</term>
|
|
|
|
<listitem>
|
|
<para>Address family: 4 or 6</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>preview</term>
|
|
|
|
<listitem>
|
|
<para>Added in Shorewall 4.4.6.l Preview the ruleset on standard
|
|
output.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>Those parameters that are supplied must have defined values.
|
|
Defaults are: <simplelist>
|
|
<member>script '' ('check' command)</member>
|
|
|
|
<member>directory ''</member>
|
|
|
|
<member>verbosity 1</member>
|
|
|
|
<member>timestamp 0</member>
|
|
|
|
<member>debug 0</member>
|
|
|
|
<member>export 0</member>
|
|
|
|
<member>chains ''</member>
|
|
|
|
<member>log ''</member>
|
|
|
|
<member>log_verbosity -1</member>
|
|
|
|
<member>family 4</member>
|
|
</simplelist></para>
|
|
|
|
<para>Example: <programlisting>use lib '/usr/share/shorewall/';
|
|
use Shorewall::Compiler;
|
|
|
|
compiler( script => '/root/firewall', log => '/root/compile.log', log_verbosity => 2 ); </programlisting></para>
|
|
</section>
|
|
|
|
<section id="Chains">
|
|
<title>Shorewall::Chains</title>
|
|
|
|
<para><programlisting>use lib '/usr/share/shorewall';
|
|
use Shorewall::Chains;
|
|
|
|
my $chainref1 = chain_new $table, $name1;
|
|
add_rule $chainref1, $rule;
|
|
insert_rule $chainref1, $ordinal, $rule;
|
|
my $chainref2 = new_manual_chain $name3;
|
|
my $chainref3 = ensure_manual_chain $name;
|
|
log_rule_limit $level, $chainref3, $name, $disposition, $limit, $tag, $command, $predicates;
|
|
|
|
|
|
my $chainref4 = $chain_table{$table}{$name};
|
|
my $chainref5 = $nat_table{$name};
|
|
my $chainref6 = $mangle_table{$name};
|
|
my $chainref7 = $filter_table{$name};</programlisting>Shorewall::Chains is
|
|
Shorewall-perl's interface to iptables/netfilter. It creates a
|
|
<firstterm>chain table</firstterm> (%chain_table) which is populated as
|
|
the various tables are processed. The table (actually a hash) is
|
|
two-dimensional with the first dimension being the Netfilter table name
|
|
(raw, mangle, nat and filter) and the second dimension being the chain
|
|
name. Each table is a hash reference -- the hash defines the attributes
|
|
of the chain. See the large comment at the beginning of the module
|
|
(<filename>/usr/share/shorewall-perl/Shorewall/Chains.pm</filename>).</para>
|
|
|
|
<para>The module export the chain table along with three hash references
|
|
into the table:<literal></literal></para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>$nat_table</term>
|
|
|
|
<listitem>
|
|
<para>Reference to the 'nat' portion of the table
|
|
($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>
|
|
|
|
<varlistentry>
|
|
<term>$mangle_table</term>
|
|
|
|
<listitem>
|
|
<para>Reference to the 'mangle' portion of the table
|
|
($chain_table{mangle}). This is a hash whose key is the chain
|
|
name.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>$filter</term>
|
|
|
|
<listitem>
|
|
<para>Reference to the 'filter' portion of the table
|
|
($chain_table{filter}). This is a hash whose key is the chain
|
|
name.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>You can create a new chain in any of the tables using <emphasis
|
|
role="bold">new_chain()</emphasis>. Arguments to the function
|
|
are:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>$table</term>
|
|
|
|
<listitem>
|
|
<para>'nat', 'mangle', or 'filter'.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>$name</term>
|
|
|
|
<listitem>
|
|
<para>Name of the chain to create.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>The function creates a hash at $chain_table{$table}{$name} and
|
|
populates the hash with default values. A reference to the hash is
|
|
returned.</para>
|
|
|
|
<para>Each chain table entry includes a list of rules to be added to the
|
|
chain. These rules are written to the iptables-restore input file when
|
|
the resulting script is executed. To append a rule to that list, call
|
|
<emphasis role="bold">add_rule()</emphasis>. Arguments are:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>$chainref</term>
|
|
|
|
<listitem>
|
|
<para>A reference to the chain table entry.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>$rule</term>
|
|
|
|
<listitem>
|
|
<para>The rule to add. Do not include the leading '-A ' in this
|
|
argument -- it will be supplied by the function.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>To insert a rule into that list, call <emphasis
|
|
role="bold">insert_rule()</emphasis>. Arguments are:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>$chainref</term>
|
|
|
|
<listitem>
|
|
<para>A reference to the chain table entry.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>$ordinal</term>
|
|
|
|
<listitem>
|
|
<para>The position of the inserted rule in the list. A value of 1
|
|
inserts the rule at the head of the list, a value of 2 places the
|
|
rule second in the list, and so on.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>$rule</term>
|
|
|
|
<listitem>
|
|
<para>The rule to add. Do not include the leading '-I' in this
|
|
argument -- it will be supplied by the function.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>To create a <ulink url="ManualChains.html">manual chain</ulink>,
|
|
use the new_manual_chain() function. The function accepts a single
|
|
argument which is the name of the chain. The function returns a
|
|
reference to the resulting chain table entry.</para>
|
|
|
|
<para>A companion function, <emphasis
|
|
role="bold">ensure_manual_chain()</emphasis>, can be called when a
|
|
manual chain of the desired name may have already been created. If a
|
|
manual chain table entry with the passed name already exists, a
|
|
reference to the chain table entry is returned. Otherwise, the function
|
|
calls <emphasis role="bold">new_manual_chain()</emphasis> and returns
|
|
the result.</para>
|
|
|
|
<para>To create a logging rule, call <emphasis
|
|
role="bold">log_rule_limit()</emphasis>. Arguments are:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>$level</term>
|
|
|
|
<listitem>
|
|
<para>The log level. May be specified as a name or as a
|
|
number.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>$chainref</term>
|
|
|
|
<listitem>
|
|
<para>Chain table reference for the chain to which the rule is to
|
|
be added.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>$name</term>
|
|
|
|
<listitem>
|
|
<para>The chain name to be reported in the log message (see
|
|
LOGFORMAT in <ulink
|
|
url="manpages/shorewall.conf.html">shorewall.conf</ulink>(5)).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>$disposition</term>
|
|
|
|
<listitem>
|
|
<para>The disposition to be reported in the log message (see
|
|
LOGFORMAT in <ulink
|
|
url="manpages/shorewall.conf.html">shorewall.conf</ulink>(5)).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>$limit</term>
|
|
|
|
<listitem>
|
|
<para>Rate limiting match. If an empty string is passed, the
|
|
LOGRATE/LOGBURST (<ulink
|
|
url="manpages/shorewall.conf.html">shorewall.conf</ulink>(5)) is
|
|
used.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>$tag</term>
|
|
|
|
<listitem>
|
|
<para>Log tag.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>$command</term>
|
|
|
|
<listitem>
|
|
<para>If 'add', append the log rule to the chain. If 'insert',
|
|
then insert the rule at the beginning of the chain.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>$predicates</term>
|
|
|
|
<listitem>
|
|
<para>Any additional matches that are to be applied to the
|
|
rule.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
|
|
<section id="Config">
|
|
<title>Shorewall::Config</title>
|
|
|
|
<para><programlisting>use lib '/usr/share/shorewall';
|
|
use Shorewall::Config;
|
|
|
|
warning message "This entry is bogus";
|
|
fatal_error "You have made an error";
|
|
|
|
progress_message "This will only be seen if VERBOSITY >= 2";
|
|
progress_message2 "This will only be seen if VERBOSITY >= 1";
|
|
progress_message3 "This will be seen unless VERBOSITY < 0";
|
|
</programlisting>The <emphasis role="bold">shorewall()</emphasis> function may
|
|
be optionally included:<programlisting>use lib '/usr/share/shorewall';
|
|
use Shorewall::Config qw/shorewall/;
|
|
|
|
shorewall $config_file_entry;</programlisting>The Shorewall::Config module
|
|
provides basic services to Shorewall-perl. By default, it exports the
|
|
functions that produce progress messages and warning/error
|
|
messages.</para>
|
|
|
|
<para>To issue a warning message, call <emphasis
|
|
role="bold">warning_message()</emphasis>. The single argument describes
|
|
the warning.</para>
|
|
|
|
<para>To raise a fatal error, call <emphasis
|
|
role="bold">fatal_error()</emphasis>. Again, the single argument
|
|
described the error.</para>
|
|
|
|
<para>In both cases, the function will augment the warning/error with
|
|
the current configuration file and line number, if any. <emphasis
|
|
role="bold">fatal_error()</emphasis> raised an exception via either
|
|
<emphasis role="bold">confess()</emphasis> or <emphasis
|
|
role="bold">die()</emphasis>, depending on whether the debugging stack
|
|
trace is enabled or not..</para>
|
|
|
|
<para>The three 'progress message' functions conditionally produce
|
|
output depending on the current verbosity setting.</para>
|
|
|
|
<para>The <emphasis role="bold">shorewall()</emphasis> function is used
|
|
by <ulink url="configuration_file_basics.htm#Embedded">embedded Perl
|
|
scripts</ulink> to generate entries to be included in the current
|
|
configuration file.</para>
|
|
</section>
|
|
</section>
|
|
</article>
|