Configuration Files

Warning: If you copy or edit your configuration files on a system running Microsoft Windows, you must run them through dos2unix before you use them with Shorewall.

Files

Shorewall's configuration files are in the directory /etc/shorewall.

/etc/shorewall/shorewall.conf - used to set several firewall parameters.
/etc/shorewall/params - use this file to set shell variables that you will expand in other files.
/etc/shorewall/zones - partition the firewall's view of the world into zones.
/etc/shorewall/policy - establishes firewall high-level policy.
/etc/shorewall/interfaces - describes the interfaces on the firewall system.
/etc/shorewall/hosts - allows defining zones in terms of individual hosts and subnetworks.
/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).
/etc/shorewall/modules - directs the firewall to load kernel modules.
/etc/shorewall/rules - defines rules that are exceptions to the overall policies established in /etc/shorewall/policy.
/etc/shorewall/nat - defines static NAT rules.
/etc/shorewall/proxyarp - defines use of Proxy ARP.
/etc/shorewall/routestopped (Shorewall 1.3.4 and later) - defines hosts accessible when Shorewall is stopped.
/etc/shorewall/tcrules - defines marking of packets for later use by traffic control/shaping or policy routing.
/etc/shorewall/tos - defines rules for setting the TOS field in packet headers.
/etc/shorewall/tunnels - defines IPSEC, GRE and IPIP tunnels with end-points on the firewall system.
/etc/shorewall/blacklist - lists blacklisted IP/subnet/MAC addresses.
/etc/shorewall/init - commands that you wish to execute at the beginning of a "shorewall start" or "shorewall restart".
/etc/shorewall/start - commands that you wish to execute at the completion of a "shorewall start" or "shorewall restart"
/etc/shorewall/stop - commands that you wish to execute at the beginning of a "shorewall stop".
/etc/shorewall/stopped - commands that you wish to execute at the completion of a "shorewall stop".

Comments

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.

Examples:

# This is a comment

ACCEPT	net	fw	tcp	www	#This is an end-of-line comment

Line Continuation

You may continue lines in the configuration files using the usual backslash ("\") followed immediately by a new line character.

Example:

ACCEPT	net	fw	tcp \
smtp,www,pop3,imap  #Services running on the firewall

Using DNS Names

WARNING: 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.

-Tom

Beginning with Shorwall 1.3.9, Host addresses in Shorewall configuration files may be specified as either IP addresses or DNS Names.

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.

If your firewall rules include DNS names then:

If your /etc/resolv.conf is wrong then your firewall won't start.
If your /etc/nsswitch.conf is wrong then your firewall won't start.
If your Name Server(s) is(are) down then your firewall won't start.
If your startup scripts try to start your firewall before starting your DNS server then your firewall won't start.
Factors totally outside your control (your ISP's router is down for example), can prevent your firewall from starting.
You must bring up your network interfaces prior to starting your firewall.

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.

Examples of valid DNS names:

mail.shorewall.net
shorewall.net. (note the trailing period).

Examples of invalid DNS names:

mail (not fully qualified)
shorewall.net (only one period)

DNS names may not be used as:

The server address in a DNAT rule (/etc/shorewall/rules file)
In the ADDRESS column of an entry in /etc/shorewall/masq.
In the /etc/shorewall/nat file.

These restrictions are not imposed by Shorewall simply for your inconvenience but are rather limitations of iptables.

Complementing an Address or Subnet

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 "!".

Comma-separated Lists

Comma-separated lists are allowed in a number of contexts within the configuration files. A comma separated list:

Must not have any embedded white space.
Valid: routestopped,dhcp,norfc1918
Invalid: routestopped, dhcp, norfc1818
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)
Entries in a comma-separated list may appear in any order.

Port Numbers/Service Names

Unless otherwise specified, when giving a port number you can use either an integer or a service name from /etc/services.

Port Ranges

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:

     DNAT	net	loc:192.168.1.3	tcp	4000:4100

Using Shell Variables

You may use the /etc/shorewall/params file to set shell variables that you can then use in some of the other configuration files.

It is suggested that variable names begin with an upper case letter to distinguish them from variables used internally within the Shorewall programs

Example:

NET_IF=eth0
NET_BCAST=130.252.100.255
NET_OPTIONS=noping,norfc1918

Example (/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 noping,norfc1918

Variables may be used anywhere in the other configuration files.

Using MAC Addresses

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.

MAC addresses are 48 bits wide and each Ethernet Controller has a unique MAC address.

In GNU/Linux, MAC addresses are usually written as a series of 6 hex numbers separated by colons. Example:

     [root@gateway root]# ifconfig eth0
     eth0 Link encap:Ethernet HWaddr 02:00:08:E3:FA:55
     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

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".

Note: It is not necessary to use the special Shorewall notation in the /etc/shorewall/maclist file.

Logging

By default, Shorewall directs NetFilter to log using syslog (8). Syslog classifies log messages by a facility and a priority (using the notation facility.priority).

The facilities defined by syslog are auth, authpriv, cron, daemon, kern, lpr, mail, mark, news, syslog, user, uucp and local0 through local7.

Throughout the Shorewall documentation, I will use the term level rather than priority since level is the term used by NetFilter. The syslog documentation uses the term priority.

Syslog Levels

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.

Valid levels are:

       7       debug
       6       info
       5       notice
       4       warning
       3       err
       2       crit
       1       alert
       0       emerg

For most Shorewall logging, a level of 6 (info) is appropriate. Shorewall log messages are generated by NetFilter and are logged using the kern 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.

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.

Configuring a Separate Log for Shorewall Messages

There are a couple of limitations to syslogd-based logging:

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).
All kernel.info messages will go to that destination and not just those from NetFilter.

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.

Download the ulod tar file and:

cd /usr/local/src (or wherever you do your builds)
tar -zxf source-tarball-that-you-downloaded
cd ulogd-version
./configure
make
make install

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-version directory and move it to your firewall system.

Now on the firewall system, edit /usr/local/etc/ulogd.conf and set:

syslogfile <file that you wish to log to>
syslogsync 1

I also copied the file /usr/local/src/ulogd-version/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.

Finally edit /etc/shorewall/shorewall.conf and set LOGFILE=<file that you wish to log to>. This tells the /sbin/shorewall program where to look for the log when processing its "show log", "logwatch" and "monitor" commands.

Shorewall Configurations

Shorewall allows you to have configuration directories other than /etc/shorewall. The shorewall 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.

This facility permits you to easily create a test or temporary configuration by:

copying the files that need modification from /etc/shorewall to a separate directory;
modify those files in the separate directory; and
specifying the separate directory in a shorewall start or shorewall restart command (e.g., shorewall -c /etc/testconfig restart ).

Updated 12/20/2002 - Tom Eastep