mirror of
https://gitlab.com/shorewall/code.git
synced 2024-11-27 18:13:13 +01:00
d2462f254f
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@7814 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
1008 lines
39 KiB
XML
1008 lines
39 KiB
XML
<?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$-->
|
|
|
|
<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-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>
|
|
|
|
<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/vardir</filename> - (Added in
|
|
Shoreall 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>
|
|
</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>
|
|
</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 assumed to reside in /etc/shorewall or in an alternate configuration
|
|
directory if one has been specified for the command.</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>
|
|
</example>
|
|
</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
|
|
ruleset.</para>
|
|
|
|
<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>
|
|
</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>
|
|
</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 will
|
|
never break a list longer than 15 ports (with each range counting as two
|
|
ports) into smaller lists. So you must be sure that your port lists can
|
|
be handled directly by the Netfilter/iptables capabilities
|
|
available.</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section id="Variables">
|
|
<title>Using Shell Variables</title>
|
|
|
|
<para>You may use the /etc/shorewall/params 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.</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>
|
|
</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> [root@gateway root]# <command>ifconfig eth0</command>
|
|
eth0 Link encap:Ethernet HWaddr <emphasis
|
|
role="bold">02:00:08:E3:FA:55</emphasis>
|
|
inet addr:206.124.146.176 Bcast:206.124.146.255 Mask:255.255.255.0
|
|
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
|
|
RX packets:2398102 errors:0 dropped:0 overruns:0 frame:0
|
|
TX packets:3044698 errors:0 dropped:0 overruns:0 carrier:0
|
|
collisions:30394 txqueuelen:100
|
|
RX bytes:419871805 (400.4 Mb) TX bytes:1659782221 (1582.8 Mb)
|
|
Interrupt:11 Base address:0x1800
|
|
</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> |