forked from extern/shorewall_code
7d395d3571
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@9401 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
1132 lines
43 KiB
XML
1132 lines
43 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$-->
|
||
|
||
<articleinfo>
|
||
<title>Configuration Files</title>
|
||
|
||
<authorgroup>
|
||
<author>
|
||
<firstname>Tom</firstname>
|
||
|
||
<surname>Eastep</surname>
|
||
</author>
|
||
</authorgroup>
|
||
|
||
<pubdate><?dbtimestamp format="Y/m/d"?></pubdate>
|
||
|
||
<copyright>
|
||
<year>2001-2008</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>
|
||
|
||
<caution>
|
||
<para><emphasis role="bold">This article applies to Shorewall 3.0 and
|
||
later. If you are running a version of Shorewall earlier than Shorewall
|
||
3.0.0 then please see the documentation for that
|
||
release.</emphasis></para>
|
||
</caution>
|
||
|
||
<caution>
|
||
<para>If you copy or edit your configuration files on a system running
|
||
Microsoft Windows, you must run them through <ulink
|
||
url="http://www.megaloman.com/~hany/software/hd2u/">dos2unix</ulink>
|
||
before you use them with Shorewall.</para>
|
||
</caution>
|
||
|
||
<section id="Files">
|
||
<title>Files</title>
|
||
|
||
<para><itemizedlist>
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/shorewall.conf</filename> - used to
|
||
set global firewall parameters.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/params</filename> - use this file to
|
||
set shell variables that you will expand in other files.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/zones</filename> - partition the
|
||
firewall's view of the world into zones.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/policy</filename> - establishes
|
||
firewall high-level policy.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/interfaces</filename> - describes the
|
||
interfaces on the firewall system.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/hosts</filename> - allows defining
|
||
zones in terms of individual hosts and subnetworks.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/masq</filename> - directs the
|
||
firewall where to use many-to-one (dynamic) Network Address
|
||
Translation (a.k.a. Masquerading) and Source Network Address
|
||
Translation (SNAT).</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/modules</filename> - directs the
|
||
firewall to load kernel modules.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/rules</filename> - defines rules that
|
||
are exceptions to the overall policies established in
|
||
/etc/shorewall/policy.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/nat</filename> - defines one-to-one
|
||
NAT rules.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/proxyarp</filename> - defines use of
|
||
Proxy ARP.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/routestopped</filename> - defines
|
||
hosts accessible when Shorewall is stopped.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/tcrules </filename>- defines marking
|
||
of packets for later use by traffic control/shaping or policy
|
||
routing.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/tos</filename> - defines rules for
|
||
setting the TOS field in packet headers.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/tunnels</filename> - defines tunnels
|
||
(VPN) with end-points on the firewall system.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/blacklist</filename> - lists
|
||
blacklisted IP/subnet/MAC addresses.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/init</filename> - commands that you
|
||
wish to execute at the beginning of a <quote>shorewall start</quote>
|
||
or <quote>shorewall restart</quote>.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/start</filename> - commands that you
|
||
wish to execute at the completion of a <quote>shorewall
|
||
start</quote> or <quote>shorewall restart</quote></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/stop </filename>- commands that you
|
||
wish to execute at the beginning of a <quote>shorewall
|
||
stop</quote>.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/stopped</filename> - commands that
|
||
you wish to execute at the completion of a <quote>shorewall
|
||
stop</quote>.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/ecn</filename> - disable Explicit
|
||
Congestion Notification (ECN - RFC 3168) to remote hosts or
|
||
networks.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/accounting</filename> - define IP
|
||
traffic accounting rules</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/actions</filename> and
|
||
<filename>/usr/share/shorewall/action.template</filename> allow
|
||
user-defined actions.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/providers</filename> - defines an
|
||
alternate routing table.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/route_rules</filename> (Added in
|
||
Shorewall 3.2.0) - Defines routing rules to be used in conjunction
|
||
with the routing tables defined in
|
||
<filename>/etc/shorewall/providers</filename>.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/tcdevices</filename>,
|
||
<filename>/etc/shorewall/tcclasses</filename>,
|
||
<filename>/etc/shorewall/tcfilters</filename> (tcfilters added in
|
||
Shorewall 4.2.0) - Define traffic shaping.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/tcrules</filename> - Mark or classify
|
||
traffic for traffic shaping or multiple providers.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/vardir</filename> - (Added in
|
||
Shorewall 4.0.0-RC2) - Determines the directory where Shorewall
|
||
maintains its state.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/usr/share/shorewall/actions.std</filename> -
|
||
Actions defined by Shorewall.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/usr/share/shorewall/action.*</filename> - Details
|
||
of actions defined by Shorewall.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/usr/share/shorewall/macro.*</filename> - Details of
|
||
macros defined by Shorewall.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/usr/share/rfc1918</filename> — Defines the behavior
|
||
of the 'norfc1918' interface option in
|
||
<filename>/etc/shorewall/interfaces</filename>. <emphasis
|
||
role="bold">If you need to change this file, copy it to
|
||
<filename>/etc/shorewall</filename> and modify the
|
||
copy</emphasis>.</para>
|
||
</listitem>
|
||
</itemizedlist></para>
|
||
</section>
|
||
|
||
<section id="Manpages">
|
||
<title>Man Pages</title>
|
||
|
||
<para>Beginning with Shorewall version 3.4, man pages are provided in
|
||
section 5 for each of the Shorewall configuration files. The name of the
|
||
page is formed by prefixing the file name with "shorewall-".</para>
|
||
|
||
<para>Example — To view the manual page for
|
||
<filename>/etc/shorewall/interfaces</filename>:</para>
|
||
|
||
<programlisting>man shorewall-interfaces</programlisting>
|
||
|
||
<para>The /etc/shorewall/shorewall.conf file is an exception -- the man
|
||
page for that file is 'shorewall.conf':</para>
|
||
|
||
<programlisting>man shorewall.conf</programlisting>
|
||
</section>
|
||
|
||
<section id="Comments">
|
||
<title>Comments</title>
|
||
|
||
<para>You may place comments in configuration files by making the first
|
||
non-whitespace character a pound sign (<quote>#</quote>). You may also
|
||
place comments at the end of any line, again by delimiting the comment
|
||
from the rest of the line with a pound sign.</para>
|
||
|
||
<example id="comment">
|
||
<title>Comments in a Configuration File</title>
|
||
|
||
<programlisting># This is a comment
|
||
ACCEPT net $FW tcp www #This is an end-of-line comment</programlisting>
|
||
</example>
|
||
</section>
|
||
|
||
<section id="COMMENT">
|
||
<title>Attach Comment to Netfilter Rules</title>
|
||
|
||
<para>Beginning with Shorewall version 3.3.3, if you kernel and iptables
|
||
contain comment match support (see the output of <command>shorewall show
|
||
capabilities</command>), then you can attach comments to Netfilter rules.
|
||
This feature is available in the following files:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/masq</filename></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/nat</filename></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/rules</filename></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><filename>/etc/shorewall/tcrules</filename></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Action definition files
|
||
(<filename>/etc/shorewall/action.*</filename>)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Macro definition files (/etc/shorewall/macro.*) — Added in
|
||
Shorewall-perl 4.2.0. They are ignored by Shorewall-shell 4.1 and
|
||
later.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>To attach a comment to one or more rules, insert a record above the
|
||
rules that begins with the word COMMENT (must be in all caps). The
|
||
remainder of the line is treated as a comment -- that comment will appear
|
||
delimited by "/* ... */" in the output of the <command>shorewall[-lite]
|
||
show</command> and <command>shorewall[-lite] dump</command> commands. The
|
||
comment will be attached to each generated rule until another COMMENT line
|
||
appears. To stop attaching comments to rules, simply insert a line that
|
||
contains the single word COMMENT.</para>
|
||
|
||
<para>Example (<filename>/etc/shorewall/rules</filename>):</para>
|
||
|
||
<programlisting>COMMENT Stop NETBIOS noise
|
||
|
||
REJECT loc net tcp 137,445
|
||
REJECT loc net udp 137:139
|
||
|
||
COMMENT Stop my idiotic work laptop from sending to the net with an HP source/dest IP address
|
||
|
||
DROP loc:!192.168.0.0/22 net
|
||
|
||
COMMENT</programlisting>
|
||
|
||
<para>Here's the corresponding output from
|
||
<filename>/sbin/shorewall-lite</filename>:</para>
|
||
|
||
<programlisting>gateway:~ # <command>shorewall-lite show loc2net</command>
|
||
Shorewall Lite 3.3.3 Chains loc2net at gateway - Mon Oct 16 15:04:52 PDT 2006
|
||
|
||
Counters reset Mon Oct 16 14:52:17 PDT 2006
|
||
|
||
Chain loc2net (1 references)
|
||
pkts bytes target prot opt in out source destination
|
||
0 0 LOG tcp -- * * 0.0.0.0/0 0.0.0.0/0 tcp dpt:25 LOG flags 0 level 6 prefix `FW:loc2net:REJECT:'
|
||
0 0 reject tcp -- * * 0.0.0.0/0 0.0.0.0/0 tcp dpt:25
|
||
0 0 LOG udp -- * * 0.0.0.0/0 0.0.0.0/0 udp dpts:1025:1031 LOG flags 0 level 6 prefix `FW:loc2net:REJECT:'
|
||
0 0 reject udp -- * * 0.0.0.0/0 0.0.0.0/0 udp dpts:1025:1031
|
||
0 0 reject tcp -- * * 0.0.0.0/0 0.0.0.0/0 multiport dports 137,445 <emphasis
|
||
role="bold">/* Stop NETBIOS noise */</emphasis>
|
||
0 0 reject udp -- * * 0.0.0.0/0 0.0.0.0/0 udp dpts:137:139 <emphasis
|
||
role="bold">/* Stop NETBIOS noise */</emphasis>
|
||
0 0 DROP all -- * * !192.168.0.0/22 0.0.0.0/0 <emphasis
|
||
role="bold">/* Stop my idiotic work laptop from sending to the net with an HP source/dest IP address */</emphasis>
|
||
5 316 ACCEPT all -- * * 0.0.0.0/0 0.0.0.0/0
|
||
gateway:~ #
|
||
|
||
</programlisting>
|
||
|
||
<para>COMMENT lines in macro files work somewhat differently from other
|
||
files. COMMENT lines in macros are ignored if COMMENT support is not
|
||
available or if there was a COMMENT in use when the top-level macro was
|
||
invoked. This allows the following:</para>
|
||
|
||
<para><filename>/usr/share/shorewall/macro.SSH</filename>:</para>
|
||
|
||
<para><programlisting>#ACTION SOURCE DEST PROTO DEST SOURCE RATE USER/
|
||
# PORT(S) PORT(S) LIMIT GROUP
|
||
COMMENT SSH
|
||
PARAM - - tcp 22 </programlisting>
|
||
<filename>/etc/shorewall/rules</filename>:<programlisting>COMMENT Allow SSH from home
|
||
SSH/ALLOW net:$MYIP $FW
|
||
COMMENT</programlisting>The comment line in macro.SSH will not override the
|
||
COMMENT line in the rules file and the generated rule will show <emphasis
|
||
role="bold">/* Allow SSH from home */</emphasis> when displayed through
|
||
the Shorewall show and dump commands.</para>
|
||
</section>
|
||
|
||
<section id="BlankColumn">
|
||
<title>"Blank" Columns</title>
|
||
|
||
<para>If you don't want to supply a value in a column but want to supply a
|
||
value in a following column, simply enter '-' to make the column appear
|
||
empty.</para>
|
||
|
||
<para>Example:<programlisting>#INTERFACE BROADCAST OPTIONS
|
||
br0 - routeback</programlisting></para>
|
||
</section>
|
||
|
||
<section id="Continuation">
|
||
<title>Line Continuation</title>
|
||
|
||
<para>You may continue lines in the configuration files using the usual
|
||
backslash (<quote>\</quote>) followed immediately by a new line character
|
||
(Enter key).</para>
|
||
|
||
<example id="continuation">
|
||
<title>Line Continuation</title>
|
||
|
||
<programlisting>ACCEPT net $FW tcp \↵
|
||
smtp,www,pop3,imap #Services running on the firewall</programlisting>
|
||
</example>
|
||
</section>
|
||
|
||
<section id="INCLUDE">
|
||
<title>INCLUDE Directive</title>
|
||
|
||
<para>Any configuration file may contain INCLUDE directives. An INCLUDE
|
||
directive consists of the word INCLUDE followed by a path name and causes
|
||
the contents of the named file to be logically included into the file
|
||
containing the INCLUDE. Relative path names given in an INCLUDE directive
|
||
are resolved using the current CONFIG_PATH setting (see <ulink
|
||
url="manpages/shorewall.conf.html">shorewall.conf</ulink>(5)).</para>
|
||
|
||
<para>INCLUDE's may be nested to a level of 3 -- further nested INCLUDE
|
||
directives are ignored with a warning message.</para>
|
||
|
||
<caution>
|
||
<para>If you are using <ulink
|
||
url="CompiledPrograms.html%23Lite">Shorewall Lite</ulink> and are
|
||
running a version of Shorewall earlier than 3.2.9, it is not advisable
|
||
to use INCLUDE in the <filename>params</filename> file in an export
|
||
directory. If you do that, you must ensure that the included file is
|
||
also present on the firewall system's <filename
|
||
class="directory">/etc/shorewall-lite/</filename> directory.</para>
|
||
|
||
<para>Beginning with Shorewall version 3.2.9 (3.4.0 RC2), you can set
|
||
EXPORTPARAMS=No in <filename>shorewall.conf</filename>. That prevents
|
||
the <filename>params</filename> file from being copied into the compiled
|
||
script. With EXPORTPARAMS=No, it is perfectly okay to use INCLUDE in the
|
||
<filename>params</filename> file.</para>
|
||
</caution>
|
||
|
||
<example id="include">
|
||
<title>Use of INCLUDE</title>
|
||
|
||
<programlisting> shorewall/params.mgmt:
|
||
|
||
MGMT_SERVERS=1.1.1.1,2.2.2.2,3.3.3.3
|
||
TIME_SERVERS=4.4.4.4
|
||
BACKUP_SERVERS=5.5.5.5
|
||
|
||
----- end params.mgmt -----
|
||
|
||
shorewall/params:
|
||
|
||
# Shorewall 1.3 /etc/shorewall/params
|
||
[..]
|
||
#######################################
|
||
|
||
INCLUDE params.mgmt
|
||
|
||
# params unique to this host here
|
||
#LAST LINE - ADD YOUR ENTRIES ABOVE THIS ONE - DO NOT REMOVE
|
||
|
||
----- end params -----
|
||
|
||
shorewall/rules.mgmt:
|
||
|
||
ACCEPT net:$MGMT_SERVERS $FW tcp 22
|
||
ACCEPT $FW net:$TIME_SERVERS udp 123
|
||
ACCEPT $FW net:$BACKUP_SERVERS tcp 22
|
||
|
||
----- end rules.mgmt -----
|
||
|
||
shorewall/rules:
|
||
|
||
# Shorewall version 1.3 - Rules File
|
||
[..]
|
||
#######################################
|
||
|
||
INCLUDE rules.mgmt
|
||
|
||
# rules unique to this host here
|
||
#LAST LINE -- ADD YOUR ENTRIES BEFORE THIS ONE -- DO NOT REMOVE
|
||
|
||
----- end rules -----</programlisting>
|
||
|
||
<para>Users of Shorewall-perl 4.0.6 and later may include multiple files
|
||
in one command using an <link linkend="Embedded">embedded shell
|
||
command</link>.</para>
|
||
|
||
<para>Example (include all of the files ending in ".rules" in a
|
||
directory:):<programlisting>gateway:/etc/shorewall # ls rules.d
|
||
ALL.rules DNAT.rules FW.rules NET.rules REDIRECT.rules VPN.rules
|
||
gateway:/etc/shorewall # </programlisting></para>
|
||
|
||
<para>/etc/shorewall/rules:<programlisting>SECTION NEW
|
||
SHELL cat /etc/shorewall/rules.d/*.rules</programlisting></para>
|
||
</example>
|
||
</section>
|
||
|
||
<section id="Variables">
|
||
<title>Using Shell Variables</title>
|
||
|
||
<para>You may use the <filename>/etc/shorewall/params</filename> file to
|
||
set shell variables that you can then use in some of the other
|
||
configuration files.</para>
|
||
|
||
<para>It is suggested that variable names begin with an upper case letter
|
||
to distinguish them from variables used internally within the Shorewall
|
||
programs</para>
|
||
|
||
<para>Example:</para>
|
||
|
||
<blockquote>
|
||
<programlisting> /etc/shorewall/params
|
||
|
||
NET_IF=eth0
|
||
NET_BCAST=130.252.100.255
|
||
NET_OPTIONS=routefilter,norfc1918
|
||
|
||
/etc/shorewall/interfaces record:
|
||
|
||
net $NET_IF $NET_BCAST $NET_OPTIONS
|
||
|
||
The result will be the same as if the record had been written
|
||
|
||
net eth0 130.252.100.255 routefilter,norfc1918
|
||
</programlisting>
|
||
</blockquote>
|
||
|
||
<para>Variables may be used anywhere in the other configuration
|
||
files.<note>
|
||
<para>Shorewall-perl users: If you use "$FW" on the right side of
|
||
assignments in the <filename>/etc/shorewall/params</filename> file,
|
||
you must also set the FW variable in that file.</para>
|
||
|
||
<para>Example:<programlisting>/etc/shorewall/zones:
|
||
|
||
#ZONE TYPE OPTIONS
|
||
<emphasis role="bold">fw</emphasis> firewall
|
||
|
||
/etc/shorewall/params:
|
||
|
||
FW=<emphasis role="bold">fw</emphasis>
|
||
BLARG=$FW:206.124.146.176</programlisting></para>
|
||
</note></para>
|
||
|
||
<para>Because the <filename>/etc/shorewall/params</filename> file is
|
||
simply sourced into the shell, you can place arbitrary shell code in the
|
||
file and it will be executed each time that the file is read. Any code
|
||
included should follow these guidelines:</para>
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>The code should not have side effects, especially on other
|
||
shorewall configuration files.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>The code should be safe to execute multiple times without
|
||
producing different results.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Should not depend on where the code is called from (the params
|
||
file is sourced by both /sbin/shorewall and
|
||
/usr/lib/shorewall/firewall).</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Should not assume anything about the state of Shorewall.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>The names of any functions or variables declared should begin
|
||
with an upper case letter.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>The <filename>/etc/shorewall/params</filename> file is processed
|
||
by the compiler at compile-time and by the compiled script at
|
||
run-time. Beginning with Shorewall 3.2.9 and 3.4.0 RC2, if you have
|
||
set EXPORTPARAMS=No in <filename>shorewall.conf</filename>, then the
|
||
<filename><filename>params</filename></filename> file is only
|
||
processed by the compiler; it is not run by the compiled
|
||
script.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>If you are using <ulink
|
||
url="CompiledPrograms.html#Lite">Shorewall Lite</ulink> and if the
|
||
<filename>params</filename> script needs to set shell variables based
|
||
on the configuration of the firewall system, you can use this
|
||
trick:</para>
|
||
|
||
<programlisting>EXT_IP=$(ssh root@firewall "/sbin/shorewall-lite call find_first_interface_address eth0")</programlisting>
|
||
|
||
<para>The <command>shorewall-lite call</command> command allows you to
|
||
to call interactively any Shorewall function that you can call in an
|
||
extension script.</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
|
||
<para>When expanding a variable, the acceptable forms of expansion depend
|
||
on whether you are using Shorewall-shell or Shorewall-perl.</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>Shorewall-shell and all Shorewall versions prior to 4.0 can use
|
||
any form of expansion supported by the shell ($VAR, ${VAR},
|
||
${VAR:=val}, ...).</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Shorewall-perl only supports the $VAR and ${VAR} forms.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</section>
|
||
|
||
<section id="Embedded">
|
||
<title>Embedded Shell and Perl</title>
|
||
|
||
<para>This feature was added in Shorewall-perl 4.0.6. To use it, you must
|
||
be running 4.0.6 or later and must be using Shorewall-perl
|
||
(SHOREWALL_COMPILER=perl in shorewall.conf).</para>
|
||
|
||
<para>Earlier versions of Shorewall offered <ulink
|
||
url="shorewall_extension_scripts.htm">extension scripts</ulink> to allow
|
||
users to extend Shorewall's functionality. Extension scripts were designed
|
||
to work under the limitations of the Bourne Shell. With Shorewall-perl,
|
||
<firstterm>Embedded scripts</firstterm> offer a richer and more flexible
|
||
extension capability.</para>
|
||
|
||
<para>While inline scripts scripts may be written in either Shell or Perl,
|
||
those written in Perl have a lot more power.</para>
|
||
|
||
<para>Embedded scripts can be either single-line or multi-line. Single
|
||
line scripts take one of the following forms:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para><emphasis role="bold">PERL</emphasis> <<emphasis>perl
|
||
script</emphasis>></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para><emphasis role="bold">SHELL</emphasis> <<emphasis>shell
|
||
script</emphasis>></para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>Shell scripts run in a child shell process and their output is piped
|
||
back to the compiler which processes that output as if it were embedded at
|
||
the point of the script.</para>
|
||
|
||
<para>Example: The following entries in
|
||
<filename>/etc/shorewall/rules</filename> are equivalent:<programlisting>SHELL for z in net loc dmz; do echo "ACCEPT $z fw tcp 22"; done</programlisting><programlisting>ACCEPT net fw tcp 22
|
||
ACCEPT loc fw tcp 22
|
||
ACCEPT dmz fw tcp 22</programlisting></para>
|
||
|
||
<para>Perl scripts run in the context of of the compiler process. To
|
||
produce output that will be processed by the compiler as if it were
|
||
embedded in the file at the point of the script, pass that output to the
|
||
shorewall() function. The Perl equivalent of the above SHELL script would
|
||
be:<programlisting>PERL for ( qw/net loc dmz/ ) { shorewall "ACCEPT $_ fw tcp 22"; }</programlisting>Perl
|
||
scripts are implicitly prefixed by the following:</para>
|
||
|
||
<programlisting>package Shorewall::User;
|
||
use Shorewall::Config qw/shorewall/;</programlisting>
|
||
|
||
<para>As part of the change that added embedded scripts:</para>
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>Compile-time extension scripts are also implicitly prefixed by
|
||
"package Shorewall::User;".</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>A <emphasis role="bold">compile</emphasis> extension script was
|
||
added for use by Shorewall-perl. That script is run early in the
|
||
compilation process and allows users to load additional modules and to
|
||
define data and functions for use in subsequent embedded scripts and
|
||
extension scripts.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>A <ulink url="ManualChains.html">Manual Chain</ulink> facility
|
||
was added.</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
|
||
<para>Multi-line scripts use one of the following forms:<programlisting><emphasis
|
||
role="bold">BEGIN SHELL</emphasis>
|
||
<<emphasis>shell script</emphasis>>
|
||
<emphasis role="bold">END</emphasis> [ <emphasis role="bold">SHELL</emphasis> ]</programlisting><programlisting><emphasis
|
||
role="bold">BEGIN PERL</emphasis> [;]
|
||
<<emphasis>perl script</emphasis>>
|
||
<emphasis role="bold">END</emphasis> [ <emphasis role="bold">PERL</emphasis> ] [<emphasis
|
||
role="bold">;</emphasis>]</programlisting></para>
|
||
|
||
<para><emphasis role="bold">Note: </emphasis>The '[' and ']' above are
|
||
meta-characters which indicate that what they enclose is optional and may
|
||
be omitted. So you may follow PERL with a semicolon ( ':') or you may omit
|
||
the semicolon.</para>
|
||
</section>
|
||
|
||
<section id="dnsnames">
|
||
<title>Using DNS Names</title>
|
||
|
||
<caution>
|
||
<para>I personally recommend strongly against using DNS names in
|
||
Shorewall configuration files. If you use DNS names and you are called
|
||
out of bed at 2:00AM because Shorewall won't start as a result of DNS
|
||
problems then don't say that you were not forewarned.</para>
|
||
</caution>
|
||
|
||
<para>Host addresses in Shorewall configuration files may be specified as
|
||
either IP addresses or DNS Names.</para>
|
||
|
||
<para>DNS names in iptables rules aren't nearly as useful as they first
|
||
appear. When a DNS name appears in a rule, the iptables utility resolves
|
||
the name to one or more IP addresses and inserts those addresses into the
|
||
rule. So changes in the DNS->IP address relationship that occur after
|
||
the firewall has started have absolutely no effect on the firewall's rule
|
||
set.</para>
|
||
|
||
<para>For some sites, using DNS names is very risky. Here's an
|
||
example:</para>
|
||
|
||
<programlisting>teastep@ursa:~$ dig pop.gmail.com
|
||
|
||
; <<>> DiG 9.4.2-P1 <<>> pop.gmail.com
|
||
;; global options: printcmd
|
||
;; Got answer:
|
||
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 1774
|
||
;; flags: qr rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 7, ADDITIONAL: 0
|
||
|
||
;; QUESTION SECTION:
|
||
;pop.gmail.com. IN A
|
||
|
||
;; ANSWER SECTION:
|
||
pop.gmail.com. <emphasis role="bold">300</emphasis> IN CNAME gmail-pop.l.google.com.
|
||
gmail-pop.l.google.com. <emphasis role="bold">300</emphasis> IN A 209.85.201.109
|
||
gmail-pop.l.google.com. <emphasis role="bold">300</emphasis> IN A 209.85.201.111</programlisting>
|
||
|
||
<para>Note that the TTL is 300 -- 300 seconds is only 5 minutes. So five
|
||
minutes later, the answer may change!</para>
|
||
|
||
<para>So this rule may work for five minutes then suddently stop
|
||
working:</para>
|
||
|
||
<programlisting>#ACTION SOURCE DEST PROTO DEST
|
||
# PORT(S)
|
||
POP/ACCEPT loc net:pop.gmail.com</programlisting>
|
||
|
||
<para>If your firewall rules include DNS names then:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>If your <filename>/etc/resolv.conf </filename>is wrong then your
|
||
firewall won't start.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>If your <filename>/etc/nsswitch.conf</filename> is wrong then
|
||
your firewall won't start.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>If your Name Server(s) is(are) down then your firewall won't
|
||
start.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>If your startup scripts try to start your firewall before
|
||
starting your DNS server then your firewall won't start.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Factors totally outside your control (your ISP's router is down
|
||
for example), can prevent your firewall from starting.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>You must bring up your network interfaces prior to starting your
|
||
firewall.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>Each DNS name must be fully qualified and include a minimum of two
|
||
periods (although one may be trailing). This restriction is imposed by
|
||
Shorewall to insure backward compatibility with existing configuration
|
||
files.</para>
|
||
|
||
<example id="validdns">
|
||
<title>Valid DNS Names</title>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>mail.shorewall.net</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>shorewall.net. (note the trailing period).</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</example>
|
||
|
||
<example id="invaliddns">
|
||
<title>Invalid DNS Names</title>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>mail (not fully qualified)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>shorewall.net (only one period)</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</example>
|
||
|
||
<para>DNS names may not be used as:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>The server address in a DNAT rule (/etc/shorewall/rules
|
||
file)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>In the ADDRESS column of an entry in /etc/shorewall/masq.</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>In the <filename>/etc/shorewall/nat</filename> file.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
|
||
<para>These restrictions are imposed by Netfilter and not by
|
||
Shorewall.</para>
|
||
</section>
|
||
|
||
<section id="Lists">
|
||
<title>Comma-separated Lists</title>
|
||
|
||
<para>Comma-separated lists are allowed in a number of contexts within the
|
||
configuration files. A comma separated list:</para>
|
||
|
||
<itemizedlist>
|
||
<listitem>
|
||
<para>Must not have any embedded white space.<programlisting> Valid: routefilter,dhcp,norfc1918
|
||
Invalid: routefilter, dhcp, norfc1818</programlisting></para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>If you use line continuation to break a comma-separated list,
|
||
the continuation line(s) must begin in column 1 (or there would be
|
||
embedded white space)</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>Entries in a comma-separated list may appear in any
|
||
order.</para>
|
||
</listitem>
|
||
</itemizedlist>
|
||
</section>
|
||
|
||
<section id="Compliment">
|
||
<title>Complementing an Address or Subnet</title>
|
||
|
||
<para>Where specifying an IP address, a subnet or an interface, you can
|
||
precede the item with <quote>!</quote> to specify the complement of the
|
||
item. For example, !192.168.1.4 means <quote>any host but
|
||
192.168.1.4</quote>. There must be no white space following the
|
||
<quote>!</quote>.</para>
|
||
</section>
|
||
|
||
<section id="Exclusion">
|
||
<title>Exclusion Lists</title>
|
||
|
||
<para>Shorewall 3.0 differs from earlier versions in that in most contexts
|
||
where a comma-separated list of addresses is accepted, an
|
||
<firstterm>exclusion list</firstterm> may also be included. An exclusion
|
||
list is a comma-separated list of addresses that begins with "!".</para>
|
||
|
||
<para>Example:</para>
|
||
|
||
<programlisting>!192.168.1.3,192.168.1.12,192.168.1.32/27</programlisting>
|
||
|
||
<para>The above list refers to "All addresses except 192.168.1.3,
|
||
192.168.1.12 and 192.168.1.32-192.168.1.63.</para>
|
||
|
||
<para>Exclusion lists can also be added after a network address.</para>
|
||
|
||
<para>Example:</para>
|
||
|
||
<programlisting>192.168.1.0/24!192.168.1.3,192.168.1.12,192.168.1.32/27</programlisting>
|
||
|
||
<para>The above list refers to "All addresses in 192.168.1.0-192.168.1.255
|
||
except 192.168.1.3, 192.168.1.12 and 192.168.1.32-192.168.1.63.</para>
|
||
</section>
|
||
|
||
<section id="IPRanges">
|
||
<title>IP Address Ranges</title>
|
||
|
||
<para>If you kernel and iptables have iprange match support, you may use
|
||
IP address ranges in Shorewall configuration file entries; IP address
|
||
ranges have the syntax <<emphasis>low IP
|
||
address</emphasis>>-<<emphasis>high IP address</emphasis>>.
|
||
Example: 192.168.1.5-192.168.1.12.</para>
|
||
|
||
<para>To see if your kernel and iptables have the required support, use
|
||
the <command>shorewall show capabilities</command> command:</para>
|
||
|
||
<programlisting>>~ <command>shorewall show capabilities</command>
|
||
...
|
||
Shorewall has detected the following iptables/netfilter capabilities:
|
||
NAT: Available
|
||
Packet Mangling: Available
|
||
Multi-port Match: Available
|
||
Connection Tracking Match: Available
|
||
Packet Type Match: Not available
|
||
Policy Match: Available
|
||
Physdev Match: Available
|
||
<emphasis role="bold">IP range Match: Available <--------------
|
||
</emphasis></programlisting>
|
||
</section>
|
||
|
||
<section id="Ports">
|
||
<title>Protocol Number/Names and Port Numbers/Service Names</title>
|
||
|
||
<para>Unless otherwise specified, when giving a protocol number you can
|
||
use either an integer or a protocol name from
|
||
<filename>/etc/protocols</filename>. Similarly, when giving a port number
|
||
you can use either an integer or a service name from
|
||
<filename>/etc/services</filename>.<note>
|
||
<para>Shorewall-perl translates protocol names to protocol numbers and
|
||
service names to port numbers itself.</para>
|
||
|
||
<para>In Shorewall versions 4.0.0 - 4.0.4, the mapping that it uses is
|
||
contained in the Perl module
|
||
<filename>/usr/share/shorewall-perl/Shorewall/Ports.pm</filename>.
|
||
That module is built when Shorewall is installed or upgraded using the
|
||
current <filename>/etc/protocols</filename> and
|
||
<filename>/etc/services</filename> files as input (if the build
|
||
program fails, a fallback version of the module is installed).</para>
|
||
|
||
<para>To generate a new Ports.pm module:<programlisting>cp /usr/share/shorewall-perl/Shorewall/Ports.pm /usr/share/shorewall-perl/Shorewall/Ports.pm.backup
|
||
/usr/share/shorewall/buildports.pm > /usr/share/shorewall-perl/Shorewall/Ports.pm</programlisting></para>
|
||
|
||
<para>Beginning with Shorewall version 4.0.5, the
|
||
<filename>/usr/share/shorewall-perl/Shorewall/Ports.pm</filename> has
|
||
been eliminated and the Shorewall-perl compiler uses Perl's interfaces
|
||
to getprotobyname(3posix) and getservbyname(3posix).</para>
|
||
</note></para>
|
||
|
||
<para>Also, unless otherwise documented, a protocol number/name can be
|
||
preceded by '!' to specify "All protocols except this one" (e.g., "!tcp").
|
||
Shorewall-perl support for that feature was added in Shorewall
|
||
4.2.6.</para>
|
||
</section>
|
||
|
||
<section id="Ranges">
|
||
<title>Port Ranges</title>
|
||
|
||
<para>If you need to specify a range of ports, the proper syntax is
|
||
<low port number>:<high port number>. For example, if you want
|
||
to forward the range of tcp ports 4000 through 4100 to local host
|
||
192.168.1.3, the entry in /etc/shorewall/rules is:</para>
|
||
|
||
<programlisting>#ACTION SOURCE DESTINATION PROTO DEST PORTS(S)
|
||
DNAT net loc:192.168.1.3 tcp 4000:4100</programlisting>
|
||
|
||
<para>If you omit the low port number, a value of zero is assumed; if you
|
||
omit the high port number, a value of 65535 is assumed.</para>
|
||
|
||
<para>Also, unless otherwise documented, a port range can be preceded by
|
||
'!' to specify "All ports except those in this range" (e.g.,
|
||
"!4000:4100"). Shorewall-perl support for that feature was added in
|
||
Shorewall 4.2.6.</para>
|
||
</section>
|
||
|
||
<section id="Portlists">
|
||
<title>Port Lists</title>
|
||
|
||
<para>In most cases where a port or port range may appear, a
|
||
comma-separated list of ports or port ranges may also be entered.
|
||
Shorewall will use the Netfilter <emphasis
|
||
role="bold">multiport</emphasis> match capability if it is available (see
|
||
the output of "<emphasis role="bold">shorewall show
|
||
capabilities</emphasis>") and if its use is appropriate.</para>
|
||
|
||
<para>Shorewall can use multiport match if:</para>
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>The list contains 15 or fewer port number; and</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>There are no port ranges listed OR your iptables/kernel support
|
||
the Extended <emphasis role="bold">multiport</emphasis> match (again
|
||
see the output of "<command>shorewall show capabilities</command>").
|
||
Where the Extended <emphasis role="bold">multiport</emphasis> match is
|
||
available, each port range counts as two ports toward the maximum of
|
||
15.</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
|
||
<note>
|
||
<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
|
||
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>
|
||
|
||
<para>Also, unless otherwise documented, a port list can be preceded by
|
||
'!' to specify "All ports except these" (e.g., "!80,443"). Shorewall-perl
|
||
support for that feature was added in Shorewall 4.2.6.</para>
|
||
</section>
|
||
|
||
<section id="MAC">
|
||
<title>Using MAC Addresses</title>
|
||
|
||
<para>Media Access Control (MAC) addresses can be used to specify packet
|
||
source in several of the configuration files. In order to control traffic
|
||
to/from a host by its MAC address, the host must be on the same network as
|
||
the firewall.</para>
|
||
|
||
<para>To use this feature, your kernel must have MAC Address Match support
|
||
(CONFIG_IP_NF_MATCH_MAC) included.</para>
|
||
|
||
<para>MAC addresses are 48 bits wide and each Ethernet Controller has a
|
||
unique MAC address.</para>
|
||
|
||
<para>In GNU/Linux, MAC addresses are usually written as a series of 6 hex
|
||
numbers separated by colons.</para>
|
||
|
||
<example id="mac">
|
||
<title>MAC Address of an Ethernet Controller</title>
|
||
|
||
<programlisting> gateway:~ # <command>ip link ls dev eth0</command>
|
||
4: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc htb qlen 1000
|
||
link/ether <emphasis role="bold">02:00:08:E3:FA:55</emphasis> brd ff:ff:ff:ff:ff:ff
|
||
gateway:~ #</programlisting>
|
||
</example>
|
||
|
||
<para>Because Shorewall uses colons as a separator for address fields,
|
||
Shorewall requires MAC addresses to be written in another way. In
|
||
Shorewall, MAC addresses begin with a tilde (<quote>~</quote>) and consist
|
||
of 6 hex numbers separated by hyphens. In Shorewall, the MAC address in
|
||
the example above would be written <emphasis
|
||
role="bold">~02-00-08-E3-FA-55</emphasis>.</para>
|
||
|
||
<note>
|
||
<para>It is not necessary to use the special Shorewall notation in the
|
||
<filename><ulink
|
||
url="MAC_Validation.html">/etc/shorewall/maclist</ulink></filename>
|
||
file.</para>
|
||
</note>
|
||
</section>
|
||
|
||
<section id="Levels">
|
||
<title>Shorewall Configurations</title>
|
||
|
||
<para>Shorewall allows you to have configuration directories other than
|
||
<filename class="directory">/etc/shorewall</filename>. The shorewall
|
||
check, start and restart commands allow you to specify an alternate
|
||
configuration directory and Shorewall will use the files in the alternate
|
||
directory rather than the corresponding files in /etc/shorewall. The
|
||
alternate directory need not contain a complete configuration; those files
|
||
not in the alternate directory will be read from <filename
|
||
class="directory">/etc/shorewall</filename>.<important>
|
||
<para>Shorewall requires that the file
|
||
<filename>/etc/shorewall/shorewall.conf</filename> to always exist.
|
||
Certain global settings are always obtained from that file. If you
|
||
create alternative configuration directories, do not remove
|
||
/etc/shorewall/shorewall.conf.</para>
|
||
</important></para>
|
||
|
||
<para>This facility permits you to easily create a test or temporary
|
||
configuration by</para>
|
||
|
||
<orderedlist>
|
||
<listitem>
|
||
<para>copying the files that need modification from /etc/shorewall to
|
||
a separate directory;</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>modify those files in the separate directory; and</para>
|
||
</listitem>
|
||
|
||
<listitem>
|
||
<para>specifying the separate directory in a <command>shorewall
|
||
start</command> or <command>shorewall restart</command> command (e.g.,
|
||
<command>shorewall restart /etc/testconfig</command> )</para>
|
||
</listitem>
|
||
</orderedlist>
|
||
</section>
|
||
|
||
<section id="Save">
|
||
<title>Saved Configurations</title>
|
||
|
||
<para>Shorewall allows you to <firstterm>save</firstterm> the
|
||
currently-running configuration in a form that permits it to be
|
||
re-installed quickly. When you save the configuration using the
|
||
<command>shorewall save</command> command, the running configuration is
|
||
saved in a file in the <filename
|
||
class="directory">/var/lib/shorewall</filename> directory. The default
|
||
name of that file is <filename>/var/lib/shorewall/restore</filename> but
|
||
you can specify a different name as part of the command. For example, the
|
||
command <command>shorewall save standard</command> will save the running
|
||
configuration in <filename>/var/lib/shorewall/standard</filename>. A saved
|
||
configuration is re-installed using the <command>shorewall
|
||
restore</command> command. Again, that command normally will restore the
|
||
configuration saved in <filename>/var/lib/shorewall/restore</filename> but
|
||
as with the <command>save</command> command, you can specify a different
|
||
file name in the command. For example, <command>shorewall restore
|
||
standard</command> will re-install the configuration saved in
|
||
<filename>/var/lib/shorewall/standard</filename>. By permitting you to
|
||
save different configurations under different names, Shorewall provides a
|
||
means for quickly switching between these different saved
|
||
configurations.</para>
|
||
|
||
<para>As mentioned above, the default configuration is called 'restore'
|
||
but like most things in Shorewall, that default can be changed. The
|
||
default name is specified using the <emphasis
|
||
role="bold">RESTOREFILE</emphasis> option in
|
||
<filename>/etc/shorewall/shorewall.conf</filename>.</para>
|
||
|
||
<warning>
|
||
<para>The default saved configuration is used by Shorewall in a number
|
||
of ways besides in the <command>restore</command> command; to avoid
|
||
surprises, I recommend that you read the <ulink
|
||
url="starting_and_stopping_shorewall.htm#Saved">Shorewall Operations
|
||
documentation section about saved configurations</ulink> before creating
|
||
one.</para>
|
||
</warning>
|
||
</section>
|
||
</article>
|