mirror of
https://gitlab.com/shorewall/code.git
synced 2024-12-11 17:00:51 +01:00
8e62e0fa57
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@993 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
486 lines
18 KiB
XML
486 lines
18 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>2003-11-20</pubdate>
|
|
|
|
<copyright>
|
|
<year>2001-2003</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>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>/etc/shorewall/shorewall.conf - used
|
|
to set several firewall parameters.</para></listitem><listitem><para>/etc/shorewall/params
|
|
- use this file to set shell variables that you will expand in other
|
|
files.</para></listitem><listitem><para>/etc/shorewall/zones - partition
|
|
the firewall's view of the world into zones.</para></listitem><listitem><para>/etc/shorewall/policy
|
|
- establishes firewall high-level policy.</para></listitem><listitem><para>/etc/shorewall/interfaces
|
|
- describes the interfaces on the firewall system.</para></listitem><listitem><para>/etc/shorewall/hosts
|
|
- allows defining zones in terms of individual hosts and subnetworks.</para></listitem><listitem><para>/etc/shorewall/masq
|
|
- 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>/etc/shorewall/modules - directs
|
|
the firewall to load kernel modules.</para></listitem><listitem><para>/etc/shorewall/rules
|
|
- defines rules that are exceptions to the overall policies established in
|
|
/etc/shorewall/policy.</para></listitem><listitem><para>/etc/shorewall/nat
|
|
- defines one-to-one NAT rules.</para></listitem><listitem><para>/etc/shorewall/proxyarp
|
|
- defines use of Proxy ARP.</para></listitem><listitem><para>/etc/shorewall/routestopped
|
|
(Shorewall 1.3.4 and later) - defines hosts accessible when Shorewall is
|
|
stopped.</para></listitem><listitem><para>/etc/shorewall/tcrules - defines
|
|
marking of packets for later use by traffic control/shaping or policy
|
|
routing.</para></listitem><listitem><para>/etc/shorewall/tos - defines
|
|
rules for setting the TOS field in packet headers.</para></listitem><listitem><para>/etc/shorewall/tunnels
|
|
- defines IPSEC, GRE and IPIP tunnels with end-points on the firewall
|
|
system.</para></listitem><listitem><para>/etc/shorewall/blacklist - lists
|
|
blacklisted IP/subnet/MAC addresses.</para></listitem><listitem><para>/etc/shorewall/init
|
|
- commands that you wish to execute at the beginning of a <quote>shorewall
|
|
start</quote> or <quote>shorewall restart</quote>.</para></listitem><listitem><para>/etc/shorewall/start
|
|
- commands that you wish to execute at the completion of a <quote>shorewall
|
|
start</quote> or <quote>shorewall restart</quote></para></listitem><listitem><para>/etc/shorewall/stop
|
|
- commands that you wish to execute at the beginning of a <quote>shorewall
|
|
stop</quote>.</para></listitem><listitem><para>/etc/shorewall/stopped -
|
|
commands that you wish to execute at the completion of a <quote>shorewall
|
|
stop</quote>.</para></listitem><listitem><para>/etc/shorewall/ecn -
|
|
disable Explicit Congestion Notification (ECN - RFC 3168) to remote hosts
|
|
or networks.</para></listitem><listitem><para>/etc/shorewall/accounting -
|
|
define IP traffic accounting rules</para></listitem><listitem><para>/etc/shorewall/usersets
|
|
and /etc/shorewall/users - define sets of users/groups with similar access
|
|
rights</para></listitem><listitem><para>/etc/shorewall/actions and
|
|
/etc/shorewall/action.template - define your own actions for rules in
|
|
/etc/shorewall/rules (shorewall 1.4.9 and later).</para></listitem></itemizedlist></para>
|
|
</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>
|
|
<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="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.</para>
|
|
|
|
<example>
|
|
<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>Beginning with Shorewall version 1.4.2, any file may contain INCLUDE
|
|
directives. An INCLUDE directive consists of the word INCLUDE followed by
|
|
a file name and causes the contents of the named file to be logically
|
|
included into the file containing the INCLUDE. File 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>
|
|
|
|
<example>
|
|
<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="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>Beginning with Shorewall 1.3.9, 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 /etc/resolv.conf is wrong then your firewall won't
|
|
start.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If your /etc/nsswitch.conf 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 much be fully qualified and include a minumum of two
|
|
periods (although one may be trailing). This restriction is imposed by
|
|
Shorewall to insure backward compatibility with existing configuration
|
|
files.</para>
|
|
|
|
<example>
|
|
<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>
|
|
<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 /etc/shorewall/nat file.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>These restrictions are imposed by Netfilter and not by Shorewall.</para>
|
|
</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="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="Ports">
|
|
<title>Port Numbers/Service Names</title>
|
|
|
|
<para>Unless otherwise specified, when giving a port number you can use
|
|
either an integer or a service name from /etc/services.</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>
|
|
|
|
<informaltable>
|
|
<tgroup cols="7">
|
|
<thead>
|
|
<row>
|
|
<entry align="center">ACTION</entry>
|
|
|
|
<entry align="center">SOURCE</entry>
|
|
|
|
<entry align="center">DESTINATION</entry>
|
|
|
|
<entry align="center">PROTOCOL</entry>
|
|
|
|
<entry align="center">PORT(S)</entry>
|
|
|
|
<entry align="center">SOURCE PORT(S)</entry>
|
|
|
|
<entry align="center">ORIGINAL DEST</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry>DNAT</entry>
|
|
|
|
<entry>net</entry>
|
|
|
|
<entry>loc:192.168.1.3 tcp</entry>
|
|
|
|
<entry>tcp</entry>
|
|
|
|
<entry>4000:4100</entry>
|
|
|
|
<entry></entry>
|
|
|
|
<entry></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
|
|
<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="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>
|
|
|
|
<example>
|
|
<title>Using Shell Variables</title>
|
|
|
|
<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>
|
|
|
|
<para>Variables may be used anywhere in the other configuration files.</para>
|
|
</example>
|
|
</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. 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>
|
|
<title>MAC Address of a NIC</title>
|
|
|
|
<programlisting>      [root@gateway root]# ifconfig eth0
|
|
     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 <quote>~02-00-08-E3-FA-55</quote>.</para>
|
|
|
|
<note>
|
|
<para>It is not necessary to use the special Shorewall notation in the
|
|
<ulink url="MAC_Validation.html">/etc/shorewall/maclist</ulink> file.</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section id="Levels">
|
|
<title>Shorewall Configurations</title>
|
|
|
|
<para>Shorewall allows you to have configuration directories other than
|
|
/etc/shorewall. 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 /etc/shorewall.</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 shorewall start or
|
|
shorewall restart command (e.g., <emphasis role="bold">shorewall -c
|
|
/etc/testconfig restart</emphasis> )</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>The <ulink url="starting_and_stopping_shorewall.htm">try command</ulink>
|
|
allows you to attempt to restart using an alternate configuration and if
|
|
an error occurs to automatically restart the standard configuration.</para>
|
|
</section>
|
|
</article> |