Configuration FilesTomEastep2004-02-152001-2004Thomas M. EastepPermission 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
GNU Free Documentation License.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/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 one-to-one 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./etc/shorewall/ecn
- disable Explicit Congestion Notification (ECN - RFC 3168) to remote
hosts or networks./etc/shorewall/accounting
- define IP traffic accounting rules/etc/shorewall/actions
and /usr/share/shorewall/action.template - define
your own actions for rules in /etc/shorewall/rules (shorewall 1.4.9 and
later)./etc/shorewall/actions.std
- Actions defined by Shorewall. Included using the INCLUDE
command by /etc/shorewall/actions./etc/shorewall/actions.*
- Details of actions defined by Shorewall.CommentsYou 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.Comments in a Configuration File# This is a comment
ACCEPT net fw tcp www #This is an end-of-line commentLine ContinuationYou may continue lines in the configuration files using the usual
backslash (\) followed immediately by a new line character.Line ContinuationACCEPT net fw tcp \
smtp,www,pop3,imap #Services running on the firewallINCLUDE DirectiveBeginning 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.INCLUDE's may be nested to a level of 3 -- further nested
INCLUDE directives are ignored with a warning message.Use of INCLUDE 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 -----Using DNS NamesI 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.Beginning with Shorewall 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.Valid DNS Namesmail.shorewall.netshorewall.net. (note the trailing period).Invalid DNS Namesmail (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 imposed by Netfilter and not by Shorewall.Complementing an Address or SubnetWhere 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 ListsComma-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: routefilter,dhcp,norfc1918
Invalid: routefilter, dhcp, norfc1818If 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 NamesUnless otherwise specified, when giving a port number you can use
either an integer or a service name from /etc/services.Port RangesIf 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:#ACTION SOURCE DESTINATION PROTO DEST PORTS(S)
DNAT net loc:192.168.1.3 tcp 4000:4100If 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.Using Shell VariablesYou 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
programsUsing Shell Variables /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
Variables may be used anywhere in the other configuration files.Using MAC AddressesMedia 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.MAC Address of a NIC [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.It is not necessary to use the special Shorewall notation in the
/etc/shorewall/maclist
file.Shorewall ConfigurationsShorewall 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.This facility permits you to easily create a test or temporary
configuration bycopying the files that need modification from /etc/shorewall to
a separate directory;modify those files in the separate directory; andspecifying the separate directory in a shorewall start or
shorewall restart command (e.g., shorewall -c /etc/testconfig
restart )The try command
allows you to attempt to restart using an alternate configuration and if
an error occurs to automatically restart the standard configuration.