mirror of
https://gitlab.com/shorewall/code.git
synced 2024-11-28 10:33:21 +01:00
36aa2c8e88
git-svn-id: https://shorewall.svn.sourceforge.net/svnroot/shorewall/trunk@385 fbd18981-670d-0410-9b5c-8dc0c1a9a2bb
437 lines
21 KiB
HTML
437 lines
21 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
<html>
|
||
<head>
|
||
|
||
<meta http-equiv="Content-Language" content="en-us">
|
||
|
||
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
|
||
|
||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||
|
||
<meta http-equiv="Content-Type"
|
||
content="text/html; charset=windows-1252">
|
||
<title>Configuration File Basics</title>
|
||
</head>
|
||
<body>
|
||
|
||
<table border="0" cellpadding="0" cellspacing="0"
|
||
style="border-collapse: collapse;" bordercolor="#111111" width="100%"
|
||
id="AutoNumber1" bgcolor="#400169" height="90">
|
||
<tbody>
|
||
<tr>
|
||
<td width="100%">
|
||
|
||
<h1 align="center"><font color="#ffffff">Configuration Files</font></h1>
|
||
</td>
|
||
</tr>
|
||
|
||
</tbody>
|
||
</table>
|
||
|
||
<p><b><font color="#ff0000">Warning: </font>If you copy or edit your
|
||
configuration files on a system running Microsoft Windows, you <u>must</u>
|
||
run them through <a
|
||
href="http://www.megaloman.com/%7Ehany/software/hd2u/"> dos2unix</a>
|
||
before you use them with Shorewall.</b></p>
|
||
|
||
<h2>Files</h2>
|
||
|
||
<p>Shorewall's configuration files are in the directory /etc/shorewall.</p>
|
||
|
||
<ul>
|
||
<li>/etc/shorewall/shorewall.conf - used to set several
|
||
firewall parameters.</li>
|
||
<li>/etc/shorewall/params - use this file to set shell
|
||
variables that you will expand in other files.</li>
|
||
<li>/etc/shorewall/zones - partition the firewall's
|
||
view of the world into <i>zones.</i></li>
|
||
<li>/etc/shorewall/policy - establishes firewall high-level
|
||
policy.</li>
|
||
<li>/etc/shorewall/interfaces - describes the interfaces
|
||
on the firewall system.</li>
|
||
<li>/etc/shorewall/hosts - allows defining zones in
|
||
terms of individual hosts and subnetworks.</li>
|
||
<li>/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).</li>
|
||
<li>/etc/shorewall/modules - directs the firewall to
|
||
load kernel modules.</li>
|
||
<li>/etc/shorewall/rules - defines rules that are exceptions
|
||
to the overall policies established in /etc/shorewall/policy.</li>
|
||
<li>/etc/shorewall/nat - defines static NAT rules.</li>
|
||
<li>/etc/shorewall/proxyarp - defines use of Proxy
|
||
ARP.</li>
|
||
<li>/etc/shorewall/routestopped (Shorewall 1.3.4 and
|
||
later) - defines hosts accessible when Shorewall is stopped.</li>
|
||
<li>/etc/shorewall/tcrules - defines marking of packets
|
||
for later use by traffic control/shaping or policy routing.</li>
|
||
<li>/etc/shorewall/tos - defines rules for setting
|
||
the TOS field in packet headers.</li>
|
||
<li>/etc/shorewall/tunnels - defines IPSEC, GRE and
|
||
IPIP tunnels with end-points on the firewall system.</li>
|
||
<li>/etc/shorewall/blacklist - lists blacklisted IP/subnet/MAC
|
||
addresses.</li>
|
||
<li>/etc/shorewall/init - commands that you wish to execute at the beginning
|
||
of a "shorewall start" or "shorewall restart".</li>
|
||
<li>/etc/shorewall/start - commands that you wish to execute at the completion
|
||
of a "shorewall start" or "shorewall restart"</li>
|
||
<li>/etc/shorewall/stop - commands that you wish to execute at the beginning
|
||
of a "shorewall stop".</li>
|
||
<li>/etc/shorewall/stopped - commands that you wish to execute at the
|
||
completion of a "shorewall stop".<br>
|
||
</li>
|
||
|
||
</ul>
|
||
|
||
<h2>Comments</h2>
|
||
|
||
<p>You may place comments in configuration files by making the first non-whitespace
|
||
character a pound sign ("#"). 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.</p>
|
||
|
||
<p>Examples:</p>
|
||
|
||
<pre># This is a comment</pre>
|
||
|
||
<pre>ACCEPT net fw tcp www #This is an end-of-line comment</pre>
|
||
|
||
<h2>Line Continuation</h2>
|
||
|
||
<p>You may continue lines in the configuration files using the usual backslash
|
||
("\") followed immediately by a new line character.</p>
|
||
|
||
<p>Example:</p>
|
||
|
||
<pre>ACCEPT net fw tcp \<br>smtp,www,pop3,imap #Services running on the firewall</pre>
|
||
|
||
<h2><a name="dnsnames"></a>Using DNS Names</h2>
|
||
|
||
<p align="left"> </p>
|
||
|
||
<p align="left"><b>WARNING: I personally recommend strongly <u>against</u>
|
||
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.
|
||
<br>
|
||
</b></p>
|
||
|
||
<p align="left"><b><EFBFBD><EFBFBD><EFBFBD> -Tom<br>
|
||
</b></p>
|
||
|
||
<p align="left">Beginning with Shorwall 1.3.9, Host addresses in Shorewall
|
||
configuration files may be specified as either IP addresses or DNS
|
||
Names.<br>
|
||
<br>
|
||
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. </p>
|
||
|
||
<p align="left"> If your firewall rules include DNS names then:</p>
|
||
|
||
<ul>
|
||
<li>If your /etc/resolv.conf is wrong then your firewall won't
|
||
start.</li>
|
||
<li>If your /etc/nsswitch.conf is wrong then your firewall
|
||
won't start.</li>
|
||
<li>If your Name Server(s) is(are) down then your firewall
|
||
won't start.</li>
|
||
<li>If your startup scripts try to start your firewall before
|
||
starting your DNS server then your firewall won't start.<br>
|
||
</li>
|
||
<li>Factors totally outside your control (your ISP's router
|
||
is down for example), can prevent your firewall from starting.</li>
|
||
<li>You must bring up your network interfaces prior to starting
|
||
your firewall.<br>
|
||
</li>
|
||
|
||
</ul>
|
||
|
||
<p align="left"> 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.<br>
|
||
<br>
|
||
Examples of valid DNS names:<br>
|
||
</p>
|
||
|
||
<ul>
|
||
<li>mail.shorewall.net</li>
|
||
<li>shorewall.net. (note the trailing period).</li>
|
||
|
||
</ul>
|
||
Examples of invalid DNS names:<br>
|
||
|
||
<ul>
|
||
<li>mail (not fully qualified)</li>
|
||
<li>shorewall.net (only one period)</li>
|
||
|
||
</ul>
|
||
DNS names may not be used as:<br>
|
||
|
||
<ul>
|
||
<li>The server address in a DNAT rule (/etc/shorewall/rules
|
||
file)</li>
|
||
<li>In the ADDRESS column of an entry in /etc/shorewall/masq.</li>
|
||
<li>In the /etc/shorewall/nat file.</li>
|
||
|
||
</ul>
|
||
These restrictions are not imposed by Shorewall simply for
|
||
your inconvenience but are rather limitations of iptables.<br>
|
||
|
||
<h2>Complementing an Address or Subnet</h2>
|
||
|
||
<p>Where specifying an IP address, a subnet or an interface, you can
|
||
precede the item with "!" to specify the complement of the item. For
|
||
example, !192.168.1.4 means "any host but 192.168.1.4". There must be
|
||
no white space following the "!".</p>
|
||
|
||
<h2>Comma-separated Lists</h2>
|
||
|
||
<p>Comma-separated lists are allowed in a number of contexts within the
|
||
configuration files. A comma separated list:</p>
|
||
|
||
<ul>
|
||
<li>Must not have any embedded white space.<br>
|
||
Valid: routestopped,dhcp,norfc1918<br>
|
||
Invalid: routestopped,<2C><><EFBFBD><EFBFBD> dhcp,<2C><><EFBFBD><EFBFBD> norfc1818</li>
|
||
<li>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)</li>
|
||
<li>Entries in a comma-separated list may appear in
|
||
any order.</li>
|
||
|
||
</ul>
|
||
|
||
<h2>Port Numbers/Service Names</h2>
|
||
|
||
<p>Unless otherwise specified, when giving a port number you can use
|
||
either an integer or a service name from /etc/services. </p>
|
||
|
||
<h2>Port Ranges</h2>
|
||
|
||
<p>If you need to specify a range of ports, the proper syntax is <<i>low
|
||
port number</i>>:<<i>high port number</i>>. 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:<br>
|
||
</p>
|
||
|
||
<pre> DNAT net loc:192.168.1.3 tcp 4000:4100<br></pre>
|
||
|
||
<h2>Using Shell Variables</h2>
|
||
|
||
<p>You may use the /etc/shorewall/params file to set shell variables
|
||
that you can then use in some of the other configuration files.</p>
|
||
|
||
<p>It is suggested that variable names begin with an upper case letter<font
|
||
size="1"> </font>to distinguish them from variables used internally
|
||
within the Shorewall programs</p>
|
||
|
||
<p>Example:</p>
|
||
|
||
<blockquote>
|
||
|
||
<pre>NET_IF=eth0<br>NET_BCAST=130.252.100.255<br>NET_OPTIONS=noping,norfc1918</pre>
|
||
</blockquote>
|
||
|
||
<p><br>
|
||
Example (/etc/shorewall/interfaces record):</p>
|
||
<font
|
||
face="Century Gothic, Arial, Helvetica">
|
||
|
||
<blockquote>
|
||
|
||
<pre><font face="Courier">net $NET_IF $NET_BCAST $NET_OPTIONS</font></pre>
|
||
</blockquote>
|
||
</font>
|
||
|
||
<p>The result will be the same as if the record had been written</p>
|
||
<font
|
||
face="Century Gothic, Arial, Helvetica">
|
||
|
||
<blockquote>
|
||
|
||
<pre>net eth0 130.252.100.255 noping,norfc1918</pre>
|
||
</blockquote>
|
||
</font>
|
||
|
||
<p>Variables may be used anywhere in the other configuration
|
||
files.</p>
|
||
|
||
<h2>Using MAC Addresses</h2>
|
||
|
||
<p>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.</p>
|
||
|
||
<p>MAC addresses are 48 bits wide and each Ethernet Controller has a
|
||
unique MAC address.<br>
|
||
<br>
|
||
In GNU/Linux, MAC addresses are usually written as a
|
||
series of 6 hex numbers separated by colons. Example:<br>
|
||
<br>
|
||
<20><><EFBFBD><EFBFBD> [root@gateway root]# ifconfig eth0<br>
|
||
<20><><EFBFBD><EFBFBD> eth0 Link encap:Ethernet HWaddr <b><u>02:00:08:E3:FA:55</u></b><br>
|
||
<20><><EFBFBD><EFBFBD> inet addr:206.124.146.176 Bcast:206.124.146.255
|
||
Mask:255.255.255.0<br>
|
||
<20><><EFBFBD><EFBFBD> UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1<br>
|
||
<20><><EFBFBD><EFBFBD> RX packets:2398102 errors:0 dropped:0 overruns:0
|
||
frame:0<br>
|
||
<20><><EFBFBD><EFBFBD> TX packets:3044698 errors:0 dropped:0 overruns:0
|
||
carrier:0<br>
|
||
<20><><EFBFBD><EFBFBD> collisions:30394 txqueuelen:100<br>
|
||
<20><><EFBFBD><EFBFBD> RX bytes:419871805 (400.4 Mb) TX bytes:1659782221
|
||
(1582.8 Mb)<br>
|
||
<20><><EFBFBD><EFBFBD> Interrupt:11 Base address:0x1800<br>
|
||
<br>
|
||
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 ("~") and
|
||
consist of 6 hex numbers separated by hyphens. In Shorewall, the
|
||
MAC address in the example above would be written "~02-00-08-E3-FA-55".<br>
|
||
</p>
|
||
|
||
<p><b>Note: </b>It is not necessary to use the special Shorewall notation
|
||
in the <a href="MAC_Validation.html">/etc/shorewall/maclist</a> file.<br>
|
||
</p>
|
||
|
||
<h2><a name="Levels"></a>Logging</h2>
|
||
By default, Shorewall directs NetFilter to log using syslog (8). Syslog
|
||
classifies log messages by a <i>facility</i> and a <i>priority</i> (using
|
||
the notation <i>facility.priority</i>). <br>
|
||
<br>
|
||
The facilities defined by syslog are <i>auth, authpriv, cron, daemon,
|
||
kern, lpr, mail, mark, news, syslog, user, uucp</i> and <i>local0</i> through
|
||
<i>local7</i>.<br>
|
||
<br>
|
||
Throughout the Shorewall documentation, I will use the term <i>level</i>
|
||
rather than <i>priority</i> since <i>level</i> is the term used by NetFilter.
|
||
The syslog documentation uses the term <i>priority</i>.<br>
|
||
|
||
<h3>Syslog Levels<br>
|
||
</h3>
|
||
Syslog levels are a method of describing to syslog (8) the importance
|
||
of a message and a number of Shorewall parameters have a syslog level
|
||
as their value.<br>
|
||
<br>
|
||
Valid levels are:<br>
|
||
<br>
|
||
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD> 7<><37><EFBFBD><EFBFBD><EFBFBD><EFBFBD> debug<br>
|
||
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD> 6<><36><EFBFBD><EFBFBD><EFBFBD><EFBFBD> info<br>
|
||
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD> 5<><35><EFBFBD><EFBFBD><EFBFBD><EFBFBD> notice<br>
|
||
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD> 4<><34><EFBFBD><EFBFBD><EFBFBD><EFBFBD> warning<br>
|
||
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD> 3<><33><EFBFBD><EFBFBD><EFBFBD><EFBFBD> err<br>
|
||
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD> 2<><32><EFBFBD><EFBFBD><EFBFBD><EFBFBD> crit<br>
|
||
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD> 1<><31><EFBFBD><EFBFBD><EFBFBD><EFBFBD> alert<br>
|
||
<20><><EFBFBD><EFBFBD><EFBFBD><EFBFBD> 0<><30><EFBFBD><EFBFBD><EFBFBD><EFBFBD> emerg<br>
|
||
<br>
|
||
For most Shorewall logging, a level of 6 (info) is appropriate. Shorewall
|
||
log messages are generated by NetFilter and are logged using the <i>kern</i>
|
||
facility and the level that you specify. If you are unsure of the level
|
||
to choose, 6 (info) is a safe bet. You may specify levels by name or by
|
||
number.<br>
|
||
<br>
|
||
Syslogd writes log messages to files (typically in /var/log/*) based
|
||
on their facility and level. The mapping of these facility/level pairs to
|
||
log files is done in /etc/syslog.conf (5). If you make changes to this file,
|
||
you must restart syslogd before the changes can take effect.<br>
|
||
|
||
<h3>Configuring a Separate Log for Shorewall Messages</h3>
|
||
There are a couple of limitations to syslogd-based logging:<br>
|
||
|
||
<ol>
|
||
<li>If you give, for example, kern.info it's own log destination then
|
||
that destination will also receive all kernel messages of levels 5 (notice)
|
||
through 0 (emerg).</li>
|
||
<li>All kernel.info messages will go to that destination and not just
|
||
those from NetFilter.<br>
|
||
</li>
|
||
|
||
</ol>
|
||
Beginning with Shorewall version 1.3.12, if your kernel has ULOG target
|
||
support (and most vendor-supplied kernels do), you may also specify a log
|
||
level of ULOG (must be all caps). When ULOG is used, Shorewall will direct
|
||
netfilter to log the related messages via the ULOG target which will send
|
||
them to a process called 'ulogd'. The ulogd program is available from http://www.gnumonks.org/projects/ulogd
|
||
and can be configured to log all Shorewall message to their own log file.<br>
|
||
<br>
|
||
Download the ulod tar file and:<br>
|
||
|
||
<ol>
|
||
<li>cd /usr/local/src (or wherever you do your builds)</li>
|
||
<li>tar -zxf <i>source-tarball-that-you-downloaded</i></li>
|
||
<li>cd ulogd-<i>version</i><br>
|
||
</li>
|
||
<li>./configure</li>
|
||
<li>make</li>
|
||
<li>make install<br>
|
||
</li>
|
||
|
||
</ol>
|
||
If you are like me and don't have a development environment on your firewall,
|
||
you can do the first five steps on another system then either NFS mount your
|
||
/usr/local/src directory or tar up the /usr/local/src/ulogd-<i>version</i>
|
||
directory and move it to your firewall system.<br>
|
||
<br>
|
||
Now on the firewall system, edit /usr/local/etc/ulogd.conf and set:<br>
|
||
|
||
<ol>
|
||
<li>syslogfile <i><file that you wish to log to></i></li>
|
||
<li>syslogsync 1</li>
|
||
|
||
</ol>
|
||
I also copied the file /usr/local/src/ulogd-<i>version</i>/ulogd.init to
|
||
/etc/init.d/ulogd. I had to edit the line that read "daemon /usr/local/sbin/ulogd"
|
||
to read daemon /usr/local/sbin/ulogd -d". On a RedHat system, a simple "chkconfig
|
||
--level 3 ulogd on" starts ulogd during boot up. Your init system may need
|
||
something else done to activate the script.<br>
|
||
<br>
|
||
Finally edit /etc/shorewall/shorewall.conf and set LOGFILE=<i><file that
|
||
you wish to log to></i>. This tells the /sbin/shorewall program where to
|
||
look for the log when processing its "show log", "logwatch" and "monitor"
|
||
commands.<br>
|
||
|
||
<h2><a name="Configs"></a>Shorewall Configurations</h2>
|
||
|
||
<p> Shorewall allows you to have configuration directories other than /etc/shorewall.
|
||
The <a href="starting_and_stopping_shorewall.htm">shorewall start and
|
||
restart</a> 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.</p>
|
||
|
||
<p> This facility permits you to easily create a test or temporary configuration
|
||
by:</p>
|
||
|
||
<ol>
|
||
<li> copying the files that need modification from
|
||
/etc/shorewall to a separate directory;</li>
|
||
<li> modify those files in the separate directory;
|
||
and</li>
|
||
<li> specifying the separate directory in a shorewall
|
||
start or shorewall restart command (e.g., <i><b>shorewall -c /etc/testconfig
|
||
restart</b></i> ).</li>
|
||
|
||
</ol>
|
||
|
||
|
||
|
||
|
||
<p><font size="2"> Updated 12/20/2002 - <a href="support.htm">Tom Eastep</a>
|
||
</font></p>
|
||
|
||
|
||
|
||
<p><font face="Trebuchet MS"><a href="copyright.htm"><font size="2">Copyright</font>
|
||
<20> <font size="2">2001, 2002 Thomas M. Eastep.</font></a></font><br>
|
||
</p>
|
||
<br>
|
||
<br>
|
||
</body>
|
||
</html>
|