Shorewall 1.3 Reference

This documentation is intended primarily for reference. Step-by-step instructions for configuring Shorewall in common setups may be found in the QuickStart Guides.

Components

Shorewall consists of the following components:

• params -- a parameter file installed in /etc/shorewall that can be used to establish the values of shell variables for use in other files.
• shorewall.conf -- a parameter file installed in /etc/shorewall that is used to set several firewall parameters.
• zones - a parameter file installed in /etc/shorewall that defines a network partitioning into "zones"
• policy -- a parameter file installed in /etc/shorewall/ that establishes overall firewall policy.
• rules -- a parameter file installed in /etc/shorewall and used to express firewall rules that are exceptions to the high-level policies established in /etc/shorewall/policy.
• blacklist -- a parameter file installed in /etc/shorewall and used to list blacklisted IP/subnet/MAC addresses.
• functions -- a set of shell functions used by both the firewall and shorewall shell programs. Installed in /etc/shorewall prior to version 1.3.2 and in /var/lib/shorewall in later versions.
• modules -- a parameter file installed in /etc/shorewall and that specifies kernel modules and their parameters. Shorewall will automatically load the modules specified in this file.
• tos -- a parameter file installed in /etc/shorewall that is used to specify how the Type of Service (TOS) field in packets is to be set.
• icmp.def -- a parameter file installed in /etc/shorewall and that specifies the default handling of ICMP packets when the applicable policy is DROP or REJECT.
• common.def -- a parameter file installed in in /etc/shorewall that defines firewall-wide rules that are applied before a DROP or REJECT policy is applied.
• interfaces -- a parameter file installed in /etc/shorewall/ and used to describe the interfaces on the firewall system.
• hosts -- a parameter file installed in /etc/shorewall/ and used to describe individual hosts or subnetworks in zones.
• masq - This file also describes IP masquerading under Shorewall and is installed in /etc/shorewall.
• firewall -- a shell program that reads the configuration files in /etc/shorewall and configures your firewall. This file is installed in your init.d directory (/etc/rc.d/init.d ) where it is renamed shorewall.  /etc/shorewall/firewall (/var/lib/shorewall/firewall in version 1.3.2 and later) is a symbolic link to this program.
• nat -- a parameter file in /etc/shorewall used to define static NAT .
• proxyarp -- a parameter file in /etc/shorewall used to define Proxy Arp .
• routestopped -- a parameter file in /etc/shorewall used to define those hosts that can access the firewall when Shorewall is stopped.
• tcrules -- a parameter file in /etc/shorewall used to define rules for classifying packets for Traffic Shaping/Control.
• tunnels -- a parameter file in /etc/shorewall used to define IPSec tunnels.
• shorewall -- a shell program (requiring a Bourne shell or derivative) used to control and monitor the firewall. This should be placed in /sbin or in /usr/sbin (the install.sh script and the rpm install this file in /sbin).
• version -- a file created in /etc/shorewall/ (/var/lib/shorewall in version 1.3.2 and later) that describes the version of  Shorewall installed on your system.

/etc/shorewall/params

You may use the file /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.

/etc/shorewall/zones

This file is used to define the network zones. There is one entry in /etc/shorewall/zones for each zone; Columns in an entry are:

• ZONE - short name for the zone. The name should be 5 characters or less in length and consist of lower-case letters or numbers. Short names must begin with a letter and the name assigned to the firewall is reserved for use by Shorewall itself. Note that the output produced by iptables is much easier to read if you select short names that are three characters or less in length.
• DISPLAY - The name of the zone as displayed during Shorewall startup.
• COMMENTS - Any comments that you want to make about the zone. Shorewall ignores these comments.

The /etc/shorewall/zones file released with Shorewall is as follows:

You may add, delete and modify entries in the /etc/shorewall/zones file as desired so long as you have at least one zone defined.

Warning 1: If you rename or delete a zone, you should perform "shorewall stop; shorewall start" to install the change rather than "shorewall restart".

Warning 2: The order of entries in the /etc/shorewall/zones file is significant in some cases.

/etc/shorewall/interfaces

This file is used to tell the firewall which of your firewall's network interfaces are connected to which zone. There will be one entry in /etc/shorewall/interfaces for each of your interfaces. Columns in an entry are:

• ZONE - A zone defined in the /etc/shorewall/zones file or  "-". If you specify "-", you must use the /etc/shorewall/hosts file to define the zones accessed via this interface.
• INTERFACE - the name of the interface (examples: eth0, ppp0, ipsec+)
• BROADCAST - the broadcast address(es) for the sub-network(s) attached to the interface. This should be left empty for P-T-P interfaces (ppp*, ippp*); if you need to specify options for such an interface, enter "-" in this column. If you supply the special value "detect" in this column, the firewall will automatically determine the broadcast address. In order to use "detect":
  • you must have iproute installed
  • the interface must be up before you start your firewall
  • the interface must only be attached to a single sub-network (i.e., there must have a single broadcast address). 
• OPTIONS - a comma-separated list of options. Possible options include:

  blacklist - This option causes incoming packets on this interface to be checked against the blacklist.
  
  dhcp - The interface is assigned an IP address via DHCP or is used by a DHCP server running on the firewall. The firewall will be configured to allow DHCP traffic to and from the interface even when the firewall is stopped. You may also wish to use this option if you have a static IP but you are on a LAN segment that has a lot of Laptops that use DHCP and you select the norfc1918 option (see below).

  noping - ICMP echo-request (ping) packets addressed to the firewall will be ignored by this interface.
  
  filterping - ICMP echo-request (ping) packets addressed to the firewall will be handled according to the /etc/shorewall/rules and /etc/shorewall/policy file. If the applicable policy is DROP or REJECT and you have supplied your own /etc/shorewall/icmpdef file then these 'ping' requests will be passed through the rules in that file before being dropped or rejected. If neither noping nor filterping is specified then the firewall will automatically ACCEPT these 'ping' requests. If both noping and filterping are specified, filterping takes precedence.

  routestopped - Beginning with Shorewall 1.3.4, this option is deprecated in favor of the /etc/shorewall/routestopped file. When the firewall is stopped, traffic to and from this interface will be accepted and routing will occur between this interface and other routestopped interfaces.

  norfc1918 - Packets arriving on this interface and that have a source address that is reserved in RFC 1918 or in other RFCs will be dropped after being optionally logged. If packet mangling is enabled in /etc/shorewall/shorewall.conf , then packets arriving on this interface that have a destination address that is reserved by one of these RFCs will also be logged and dropped.
  
  Addresses blocked by the standard rfc1918 file include those addresses reserved by RFC1918 plus other ranges reserved by the IANA or by other RFCs.

  Beware that as IPv4 addresses become in increasingly short supply, ISPs are beginning to use RFC 1918 addresses within their own infrastructure. Also, many cable and DSL "modems" have an RFC 1918 address that can be used through a web browser for management and monitoring functions. If you want to specify norfc1918 on your external interface but need to allow access to certain addresses from the above list, see FAQ 14.

  routefilter - Invoke the Kernel's route filtering (anti-spoofing) facility on this interface. The kernel will reject any packets incoming on this interface that have a source address that would be routed outbound through another interface on the firewall. Warning: If you specify this option for an interface then the interface must be up prior to starting the firewall.

  multi - The interface has multiple addresses and you want to be able to route between them. Example: you have two addresses on your single local interface eth1, one each in subnets 192.168.1.0/24 and 192.168.2.0/24 and you want to route between these subnets. Because you only have one interface in the local zone, Shorewall won't normally create a rule to forward packets from eth1 to eth1. Adding "multi" to the entry for eth1 will cause Shorewall to create the loc2loc chain and the appropriate forwarding rule.

  dropunclean - Packets from this interface that are selected by the 'unclean' match target in iptables will be optionally logged and then dropped. Warning: This feature requires that UNCLEAN match support be configured in your kernel, either in the kernel itself or as a module. UNCLEAN support is broken in some versions of the kernel but appears to work ok in 2.4.17-rc1.
  
  Update 12/17/2001: The unclean match patch from 2.4.17-rc1 is available for download. I am currently running this patch applied to kernel 2.4.16.

  Update 12/20/2001: I've seen a number of tcp connection requests with OPT (020405B40000080A...) being dropped in the badpkt chain. This appears to be a bug in the remote TCP stack whereby it is 8-byte aligning a timestamp (TCP option 8) but rather than padding with 0x01 it is padding with 0x00. It's a tough call whether to deny people access to your servers because of this rather minor bug in their networking software. If you wish to disable the check that causes these connections to be dropped, here's a kernel patch against 2.4.17-rc2.

  logunclean - This option works like dropunclean with the exception that packets selected by the 'unclean' match target in iptables are logged but not dropped. The level at which the packets are logged is determined by the setting of LOGUNCLEAN and if LOGUNCLEAN has not been set, "info" is assumed.

  proxyarp (Added in version 1.3.5) - This option causes Shorewall to set /proc/sys/net/ipv4/conf/<interface>/proxy_arp and is used when implementing Proxy ARP Sub-netting as described at http://www.tldp.org/HOWTO/mini/Proxy-ARP-Subnet/. Do not set this option if you are implementing Proxy ARP through entries in /etc/shorewall/proxyarp.

Example 1: You have a conventional firewall setup in which eth0 connects to a Cable or DSL modem and eth1 connects to your local network and eth0 gets its IP address via DHCP. You want to ignore ping requests from the internet and you want to check all packets entering from the internet against the black list. Your /etc/shorewall/interfaces file would be as follows:

ZONE	INTERFACE	BROADCAST	OPTIONS
net	eth0	detect	dhcp,noping,norfc1918,blacklist
loc	eth1	detect

Example 2: You have a standalone dialup GNU/Linux System. Your /etc/shorewall/interfaces file would be:

ZONE	INTERFACE	BROADCAST	OPTIONS
net	ppp0

Example 3: You have local interface eth1 with two IP addresses - 192.168.1.1/24 and 192.168.12.1/24

ZONE	INTERFACE	BROADCAST	OPTIONS
loc	eth1	192.168.1.255,192.168.12.255

/etc/shorewall/hosts Configuration

For most applications, specifying zones entirely in terms of network interfaces is sufficient. There may be times though where you need to define a zone to be a more general collection of hosts. This is the purpose of the /etc/shorewall/hosts file.

WARNING: 90% of Shorewall users don't need to put entries in this file and 80% of those who try to add such entries do it wrong. Unless you are ABSOLUTELY SURE that you need entries in this file, don't touch it.

Columns in this file are:

• ZONE - A zone defined in the /etc/shorewall/zones file.
• HOST(S) - The name of a network interface followed by a colon (":") followed by either:

1. An IP address (example - eth1:192.168.1.3)
2. A subnet in the form <subnet address>/<width> (example - eth2:192.168.2.0/2)

The interface name much match an entry in /etc/shorewall/interfaces.

• OPTIONS - A comma-separated list of options. Currently only a single option is defined:

routestopped - Beginning with Shorewall 1.3.4, this option is deprecated in favor of the /etc/shorewall/routestopped file. When the firewall is stopped, traffic to and from this host (these hosts) will be accepted and routing will occur between this host and other routestopped interfaces and hosts.

If you don't define any hosts for a zone, the hosts in the zone default to i0:0.0.0.0/0 , i1:0.0.0.0/0, ... where i0, i1, ... are the interfaces to the zone.

Note 1: You probably DON'T want to specify any hosts for your internet zone since the hosts that you specify will be the only ones that you will be able to access without adding additional rules.

Note 2: The setting of the MERGE_HOSTS variable in /etc/shorewall/shorewall.conf has an important effect on how the host file is processed. Please read the description of that variable carefully.

Example:

Your local interface is eth1 and you have two groups of local hosts that you want to make into separate zones:

• 192.168.1.0/25 
• 192.168.1.128/25

Your /etc/shorewall/interfaces file might look like:

ZONE	INTERFACE	BROADCAST	OPTIONS
net	eth0	detect	dhcp,noping,norfc1918
-	eth1	detect

The '-' in the ZONE column for eth1 tells Shorewall that eth1 interfaces to multiple zones.

Your /etc/shorewall/hosts file might look like:

ZONE	HOST(S)	OPTIONS
loc1	eth1:192.168.1.0/25
loc2	eth1:192.168.1.128/25	routestopped

Hosts in 'loc2' can communicate with the firewall while Shorewall is stopped -- those in 'loc1' cannot.

Nested and Overlapping Zones

The /etc/shorewall/interfaces and /etc/shorewall/hosts file allow you to define nested or overlapping zones. Such overlapping/nested zones are allowed and Shorewall processes zones in the order that they appear in the /etc/shorewall/zones file. So if you have nested zones, you want the sub-zone to appear before the super-zone and in the case of overlapping zones, the rules that will apply to hosts that belong to both zones is determined by which zone appears first in /etc/shorewall/zones.

Hosts that belong to more than one zone may be managed by the rules of all of those zones. This is done through use of the special CONTINUE policy described below.

/etc/shorewall/policy Configuration.

This file is used to describe the firewall policy regarding establishment of connections. Connection establishment is described in terms of clients who initiate connections and servers who receive those connection requests. Policies defined in /etc/shorewall/policy describe which zones are allowed to establish connections with other zones.

Policies established in /etc/shorewall/policy can be viewed as default policies. If no rule in /etc/shorewall/rules applies to a particular connection request then the policy from /etc/shorewall/policy is applied.

Four policies are defined:

• ACCEPT - The connection is allowed.
• DROP - The connection request is ignored.
• REJECT - The connection request is rejected with an RST (TCP) or an ICMP destination-unreachable packet being returned to the client.
• CONTINUE - The connection is neither ACCEPTed, DROPped nor REJECTed. CONTINUE may be used when one or both of the zones named in the entry are sub-zones of or intersect with another zone. For more information, see below. 

For each policy specified in /etc/shorewall/policy, you can indicate that you want a message sent to your system log each time that the policy is applied.

Entries in /etc/shorewall/policy have four columns as follows:

1. SOURCE - The name of a client zone (a zone defined in the /etc/shorewall/zones file , the name of the firewall zone or "all").
2. DEST - The name of a destination zone (a zone defined in the /etc/shorewall/zones file , the name of the firewall zone or "all").
3. POLICY - The default policy for connection requests from the SOURCE zone to the DESTINATION zone.
4. LOG LEVEL - Optional. If left empty, no log message is generated when the policy is applied. Otherwise, this column should contain an integer or name indicating a syslog level. See the syslog.conf man page for a description of each log level.
5. LIMIT:BURST - Optional. If left empty, TCP connection requests from the SOURCE zone to the DEST zone will not be rate-limited. Otherwise, this column specifies the maximum rate at which TCP connection requests will be accepted followed by a colon (":") followed by the maximum burst size that will be tolerated. Example: 10/sec:40 specifies that the maximum rate of TCP connection requests allowed will be 10 per second and a burst of 40 connections will be tolerated. Connection requests in excess of these limits will be dropped.

In the SOURCE and DEST columns, you can enter "all" to indicate all zones. 

The policy file installed by default is as follows:

SOURCE	DEST	POLICY	LOG LEVEL	LIMIT:BURST
loc	net	ACCEPT
net	all	DROP	info
all	all	REJECT	info

This table may be interpreted as follows:

• All connection requests from the local network to hosts on the internet are accepted.
• All connection requests originating from the internet are ignored and logged at level KERNEL.INFO.
• All other connection requests are rejected and logged.

WARNING:

The firewall script processes  the /etc/shorewall/policy file from top to bottom and uses the first applicable policy that it finds. For example, in the following policy file, the policy for (loc, loc) connections would be ACCEPT as specified in the first entry even though the third entry in the file specifies REJECT.

SOURCE	DEST	POLICY	LOG LEVEL	LIMIT:BURST
loc	all	ACCEPT
net	all	DROP	info
loc	loc	REJECT	info

The CONTINUE policy

Where zones are nested or overlapping , the CONTINUE policy allows hosts that are within multiple zones to be managed under the rules of all of these zones. Let's look at an example:

/etc/shorewall/zones:

ZONE	DISPLAY	COMMENTS
sam	Sam	Sam's system at home
net	Internet	The Internet
loc	Loc	Local Network

/etc/shorewall/interfaces:

ZONE	INTERFACE	BROADCAST	OPTIONS
-	eth0	detect	dhcp,noping,norfc1918
loc	eth1	detect	routestopped

/etc/shorewall/hosts:

ZONE	HOST(S)	OPTIONS
net	eth0:0.0.0.0/0
sam	eth0:206.191.149.197	routestopped

Note that Sam's home system is a member of both the sam zone and the net zone and as described above , that means that sam must be listed before net  in /etc/shorewall/zones.

/etc/shorewall/policy:

SOURCE	DEST	POLICY	LOG LEVEL
loc	net	ACCEPT
sam	all	CONTINUE
net	all	DROP	info
all	all	REJECT	info

The second entry above says that when Sam is the client, connection requests should first be process under rules where the source zone is sam and if there is no match then the connection request should be treated under rules where the source zone is net. It is important that this policy be listed BEFORE the next policy (net to all).

Partial /etc/shorewall/rules:

ACTION	SOURCE	DEST	PROTO	DEST PORT(S)	SOURCE PORT(S)	ORIGINAL DEST
...
DNAT	sam	loc:192.168.1.3	tcp	ssh	-
DNAT	net	loc:192.168.1.5	tcp	www	-
...

Given these two rules, Sam can connect to the firewall's internet interface with ssh and the connection request will be forwarded to 192.168.1.3. Like all hosts in the net zone, Sam can connect to the firewall's internet interface on TCP port 80 and the connection request will be forwarded to 192.168.1.5. The order of the rules is not significant.

Sometimes it is necessary to suppress port forwarding for a sub-zone. For example, suppose that all hosts can SSH to the firewall and be forwarded to 192.168.1.5 EXCEPT Sam. When Sam connects to the firewall's external IP, he should be connected to the firewall itself. Because of the way that Netfilter is constructed, this requires two rules as follows:

 

ACTION	SOURCE	DEST	PROTO	DEST PORT(S)	SOURCE PORT(S)	ORIGINAL DEST
...
DNAT	sam	fw	tcp	ssh	-
DNAT	net!sam	loc:192.168.1.3	tcp	ssh	-
...

The first rule allows Sam SSH access to the firewall. The second rule says that any clients from the net zone with the exception of those in the 'sam' zone should have their connection port forwarded to 192.168.1.3. If you need to exclude more than one zone in this way, you can list the zones separated by commas (e.g., net!sam,joe,fred). This technique also may be used when the ACTION is REDIRECT.

/etc/shorewall/rules

The /etc/shorewall/rules file defines exceptions to the policies established in the /etc/shorewall/policy file. There is one entry in /etc/shorewall/rules for each of these rules. 

Entries in the file have the following columns:

• ACTION
  • ACCEPT, DROP or REJECT. These have the same meaning here as in the policy file above.
  • DNAT -- Causes the connection request to be forwarded to the system specified in the DEST column (port forwarding). "DNAT" stands for "Destination Network Address Translation"
  • REDIRECT -- Causes the connection request to be redirected to a port on the local (firewall) system.

  The ACTION may optionally be followed by ":" and a syslogd log level (example: REJECT:info). This causes the packet to be logged at the specified level prior to being processed according to the specified ACTION.
  
  The use of DNAT or REDIRECT requires that you have NAT enabled.
   

• SOURCE - Describes the source hosts to which the rule applies.. The contents of this field must begin with the name of a zone defined in /etc/shorewall/zones or $FW. If the ACTION is DNAT or REDIRECT, sub-zones may be excluded from the rule by following the initial zone name with "!' and a comma-separated list of those sub-zones to be excluded. There is an example above.
  
  The source may be further restricted by adding a colon (":") followed by a comma-separated list of qualifiers. Qualifiers are may include:
  • An interface name - refers to any connection requests arriving on the specified interface (example loc:eth4).
  • An IP address - refers to a connection request from the host with the specified address (example net:155.186.235.151)
  • A MAC Address in Shorewall format.
  • A subnet - refers to a connection request from any host in the specified subnet (example net:155.186.235.0/24).
• DEST - Describes the destination host(s) to which the rule applies. May take any of the forms described above for SOURCE plus the following two additional forms:
  • An IP address followed by a colon and the port number that the server is listening on (service names from /etc/services are not allowed - example loc:192.168.1.3:80). 
  • A single port number (again, service names are not allowed) -- this form is only allowed if the ACTION is REDIRECT and refers to a server running on the firewall itself and listening on the specified port.
• PROTO - Protocol. Must be a protocol name from /etc/protocols, a number, "all" or "related". Specifies the protocol of the connection request. "related" should be specified only if you have given ALLOWRELATED="no" in /etc/shorewall/shorewall.conf and you wish to override that setting for related connections originating with the client(s) and server(s) specified in this rule. When "related" is given for the protocol, the remainder of the columns should be left blank.
• DEST PORT(S) - Port or port range (<low port>:<high port>) being connected to. May only be specified if the protocol is tcp, udp or icmp. For icmp, this column's contents are interpreted as an icmp type. If you don't want to specify DEST PORT(S) but need to include information in one of the columns to the right, enter "-" in this column. You may give a list of ports and/or port ranges separated by commas. Port numbers may be either integers or service names from /etc/services.
• SOURCE PORTS(S) - May be used to restrict the rule to a particular client port or port range (a port range is specified as <low port number>:<high port number>). If you don't want to restrict client ports but want to specify something in the next column, enter "-" in this column. If you wish to specify a list of port number or ranges, separate the list elements with commas (with no embedded white space). Port numbers may be either integers or service names from /etc/services.
• ORIGINAL DEST - This column may only be non-empty if the ACTION is DNAT or REDIRECT.
  
  If DNAT or REDIRECT is the ACTION and the ORIGINAL DEST column is left empty, any connection request arriving at the firewall from the SOURCE that matches the rule will be forwarded or redirected. This works fine for connection requests arriving from the internet where the firewall has only a single external IP address. When the firewall has multiple external IP addresses or when the SOURCE is other than the internet, there will usually be a desire for the rule to only apply to those connection requests directed to a particular IP address (see Example 2 below for another usage). That IP address (or a comma-separated list of such addresses) is specified in the ORIGINAL DEST column.
  
  The IP address may be optionally followed by ":" and a second IP address. This latter address, if present, is used as the source address for packets forwarded to the server (This is called "Source NAT" or SNAT).
  
  Note:  When using SNAT, it is a good idea to qualify the source with an IP address or subnet. Otherwise, it is likely that SNAT will occur on connections other than those described in the rule. The reason for this is that SNAT occurs in the Netfilter POSTROUTING hook where it is not possible to restrict the scope of a rule by incoming interface.
  
  Example: DNAT     loc:192.168.1.0/24    loc:192.168.1.3    tcp    www    -    206.124.146.179:192.168.1.3
  
  If SNAT is not used (no ":" and second IP address), the original source address is used. If you want any destination address to match the rule but want to specify SNAT, simply use a colon followed by the SNAT address.

Example 1. You wish to forward all ssh connection requests from the internet to local system 192.168.1.3. 

ACTION	SOURCE	DEST	PROTO	DEST PORT(S)	SOURCE PORT(S)	ORIGINAL DEST
DNAT	net	loc:192.168.1.3	tcp	ssh

Example 2. You want to redirect all local www connection requests EXCEPT those to your own http server (206.124.146.177) to a Squid transparent proxy running on the firewall and listening on port 3128. Squid will of course require access to remote web servers. This example shows yet another use for the ORIGINAL DEST column; here, connection requests that were NOT (notice the "!") originally destined to 206.124.146.177 are redirected to local port 3128.

ACTION	SOURCE	DEST	PROTO	DEST PORT(S)	SOURCE PORT(S)	ORIGINAL DEST
REDIRECT	loc	3128	tcp	www		!206.124.146.177
ACCEPT	fw	net	tcp	www

Example 3. You want to run a web server at 155.186.235.222 in your DMZ and have it accessible remotely and locally. the DMZ is managed by Proxy ARP or by classical sub-netting.

ACTION	SOURCE	DEST	PROTO	DEST PORT(S)	SOURCE PORT(S)	ORIGINAL DEST
ACCEPT	net	dmz:155.186.235.222	tcp	www	-
ACCEPT	loc	dmz:155.186.235.222	tcp	www

Example 4. You want to run wu-ftpd on 192.168.2.2 in your masqueraded DMZ. Your internet interface address is 155.186.235.151 and you want the FTP server to be accessible from the internet in addition to the local 192.168.1.0/24 and dmz 192.168.2.0/24 subnetworks. Note that since the server is in the 192.168.2.0/24 subnetwork, we can assume that access to the server from that subnet will not involve the firewall (but see FAQ 2). Note that unless you have more than one external IP address, you can leave the ORIGINAL DEST column blank in the first rule. You cannot leave it blank in the second rule though because then all ftp connections originating in the local subnet 192.168.1.0/24 would be sent to 192.168.2.2 regardless of the site that the user was trying to connect to. That is clearly not what you want .

ACTION	SOURCE	DEST	PROTO	DEST PORT(S)	SOURCE PORT(S)	ORIGINAL DEST
DNAT	net	dmz:192.168.2.2	tcp	ftp
DNAT	loc:192.168.1.0/24	dmz:192.168.2.2	tcp	ftp	-	155.186.235.151

If you are running wu-ftpd, you should restrict the range of passive in your /etc/ftpaccess file. I only need a few simultaneous FTP sessions so I use port range 65500-65535. In /etc/ftpaccess, this entry is appropriate:

passive ports  0.0.0.0/0 65500 65534

If you are running pure-ftpd, you would include "-p 65500:65534" on the pure-ftpd runline.

The important point here is to ensure that the port range used for FTP passive connections is unique and will not overlap with any usage on the firewall system.

Example 5. You wish to allow unlimited DMZ access to the host with MAC address 02:00:08:E3:FA:55.

ACTION	SOURCE	DEST	PROTO	DEST PORT(S)	SOURCE PORT(S)	ORIGINAL DEST
ACCEPT	loc:~02-00-08-E3-FA-55	dmz	all

Look here for information on other services.

/etc/shorewall/common

Shorewall allows definition of rules that apply between all zones. By default, these rules are defined in the file /etc/shorewall/common.def but may be modified to suit individual requirements. Rather than modify /etc/shorewall/common.def, you should copy that file to /etc/shorewall/common and modify that file.

The /etc/shorewall/common file is expected to contain iptables commands; rather than running iptables directly, you should run it indirectly using the Shorewall function 'run_iptables'. That way, if iptables encounters an error, the firewall will be safely stopped.

/etc/shorewall/masq

The /etc/shorewall/masq file is used to define classical IP Masquerading and Source Network Address Translation  (SNAT). There is one entry in the file for each subnet that you want to masquerade. In order to make use of this feature, you must have NAT enabled .

Columns are:

• INTERFACE - The interface that will masquerade the subnet; this is normally your internet interface. This interface name can be optionally qualified by adding ":" and a subnet or host IP. When this qualification is added, only packets addressed to that host or subnet will be masqueraded.
• SUBNET - The subnet that you want to have masqueraded through the INTERFACE. This may be expressed as a single IP address, a subnet or an interface name. In the latter instance, the interface must be configured and started before Shorewall is started as Shorewall will determine the subnet based on information obtained from the 'ip' utility.
  
  The subnet may be optionally followed by "!' and a comma-separated list of addresses and/or subnets that are to be excluded from masquerading.
• ADDRESS - The source address to be used for outgoing packets. This column is optional and if left blank, the current primary IP address of the interface in the first column is used. If you have a static IP on that interface, listing it here makes processing of output packets a little less expensive for the firewall.

Example 1: You have eth0 connected to a cable modem and eth1 connected to your local subnetwork 192.168.9.0/24. Your /etc/shorewall/masq file would look like:    

INTERFACE	SUBNET	ADDRESS
eth0	192.168.9.0/24

Example 2: You have a number of IPSEC tunnels through ipsec0 and you want to masquerade traffic from your 192.168.9.0/24 subnet to the remote subnet 10.1.0.0/16 only.

INTERFACE	SUBNET	ADDRESS
ipsec0:10.1.0.0/16	192.168.9.0/24

Example 3: You have a DSL line connected on eth0 and a local network (192.168.10.0/24) connected to eth1. You want all local->net connections to use source address 206.124.146.176.

INTERFACE	SUBNET	ADDRESS
eth0	192.168.10.0/24	206.124.146.176

Example 4: Same as example 3 except that you wish to exclude 192.168.10.44 and 192.168.10.45 from the SNAT rule.

INTERFACE	SUBNET	ADDRESS
eth0	192.168.10.0/24!192.168.10.44,192.168.10.45	206.124.146.176

/etc/shorewall/proxyarp

If you want to use proxy ARP on an entire sub-network, I suggest that you look at http://www.tldp.org/HOWTO/mini/Proxy-ARP-Subnet/. If you decide to use the technique described in that HOWTO, you can set the proxy_arp flag for an interface (/proc/sys/net/ipv4/conf/<interface>/proxy_arp) by including the proxyarp option in the interface's record in /etc/shorewall/interfaces. When using Proxy ARP sub-netting, you do NOT include any entries in /etc/shorewall/proxyarp.

The /etc/shorewall/proxyarp file is used to define Proxy ARP. The file is typically used for enabling Proxy ARP on a small set of systems since you need one entry in this file for each system using proxy ARP. Columns are:

• ADDRESS - address of the system.
• INTERFACE - the interface that connects to the system. If the interface is obvious from the subnetting, you may enter "-" in this column.
• EXTERNAL - the external interface that you want to honor ARP requests for the ADDRESS specified in the first column.
• HAVEROUTE - If you already have a route through INTERFACE to ADDRESS, this column should contain "Yes" or "yes". If you want Shorewall to add the route, the column should contain "No" or "no".

Note: After you have made a change to the /etc/shorewall/proxyarp file, you may need to flush the ARP cache of all routers on the LAN segment connected to the interface specified in the EXTERNAL column of the change/added entry(s). If you are having problems communicating between an individual host (A) on that segment and a system whose entry has changed, you may need to flush the ARP cache on host A as well.

ISPs typically have ARP configured with long TTL (hours!) so if your ISPs router has a stale cache entry (as seen using "tcpdump -nei <external interface> host <IP addr>"), it may take a long while to time out. I personally have had to contact my ISP and ask them to delete a stale entry in order to restore a system to working order after changing my proxy ARP settings.

Example: You have public IP addresses 155.182.235.0/28. You configure your firewall as follows:

• eth0 - 155.186.235.1 (internet connection)
• eth1 - 192.168.9.0/24 (masqueraded local systems)
• eth2 - 192.168.10.1 (interface to your DMZ)

In your DMZ, you want to install a Web/FTP server with public address 155.186.235.4. On the Web server, you subnet just like the firewall's eth0 and you configure 155.186.235.1 as the default gateway. In your /etc/shorewall/proxyarp file, you will have:

ADDRESS	INTERFACE	EXTERNAL	HAVEROUTE
155.186.235.4	eth2	eth0	No

Note: You may want to configure the servers in your DMZ with a subnet that is smaller than the subnet of your internet interface. See the Proxy ARP Subnet Mini HOWTO (http://www.tldp.org/HOWTO/mini/Proxy-ARP-Subnet/) for details. In this case you will want to place "Yes" in the HAVEROUTE column.

To learn how I use Proxy ARP in my DMZ, see my configuration files.

Warning: Do not use Proxy ARP and FreeS/Wan on the same system unless you are prepared to suffer the consequences. If you start or restart Shorewall with an IPSEC tunnel active, the proxied IP addresses are mistakenly assigned to the IPSEC tunnel device (ipsecX) rather than to the interface that you specify in the INTERFACE column of /etc/shorewall/proxyarp. I haven't had the time to debug this problem so I can't say if it is a bug in the Kernel or in FreeS/Wan. 

You might be able to work around this problem using the following (I haven't tried it):

In /etc/shorewall/init, include:

     qt service ipsec stop

In /etc/shorewall/start, include:

    qt service ipsec start

/etc/shorewall/nat

The /etc/shorewall/nat file is used to define static NAT. There is one entry in the file for each static NAT relationship that you wish to define. In order to make use of this feature, you must have NAT enabled .

IMPORTANT: If all you want to do is forward ports to servers behind your firewall, you do NOT want to use static NAT. Port forwarding can be accomplished with simple entries in the rules file. Also, in most cases Proxy ARP provides a superior solution to static NAT because the internal systems are accessed using the same IP address internally and externally.

Columns in an entry are:

• EXTERNAL - External IP address - This should NOT be the primary IP address of the interface named in the next column.
• INTERFACE - Interface that you want the EXTERNAL IP address to appear on.
• INTERNAL - Internal IP address.
• ALL INTERFACES - If Yes or yes (or left empty), NAT will be effective from all hosts. If No or no then NAT will be effective only through the interface named in the INTERFACE column. Note: If two or more NATed systems are connected to the same firewall interface and you want them to be able to communicate using their EXTERNAL IP addresses, then you will want to specify the multi option in the /etc/shorewall/interface entry for that interface.
• LOCAL - If Yes or yes and the ALL INTERFACES column contains Yes or yes, NAT will be effective from the firewall system. Note: For this to work, you must be running kernel 2.4.19 or later and iptables 1.2.6a or later and you must have enabled  CONFIG_IP_NF_NAT_LOCAL in your kernel.

Look here for additional information and an example.

/etc/shorewall/tunnels

The /etc/shorewall/tunnels file allows you to define IPSec, GRE and IPIP tunnels with end-points on your firewall. To use ipsec, you must install version 1.9, 1.91 or the current FreeS/WAN development snapshot. 

Note: For kernels 2.4.4 and above, you will need to use version 1.91 or a development snapshot as patching with version 1.9 results in kernel compilation errors.

Instructions for setting up IPSEC tunnels may be found here and instructions for IPIP tunnels are here . Look here for information about setting up PPTP tunnels under Shorewall.

/etc/shorewall/shorewall.conf

This file is used to set the following firewall parameters:

• LOGNEWNOTSYN - Added in Version 1.3.6
  Beginning with version 1.3.6, Shorewall drops non-SYN TCP packets that are not part of an existing connection. If you would like to log these packets, set LOGNEWNOTSYN to the syslog level at which you want the packets logged. Example: LOGNEWNOTSYN=debug|
  
  Note: Packets logged under this option are usually the result of broken remote IP stacks rather than the result of any sort of attempt to breach your firewall.
   
• MERGE_HOSTS - Added in Version 1.3.5
  Prior to 1.3.5, when the /etc/shorewall/hosts file included an entry for a zone then the entire zone had to be defined in the /etc/shorewall/hosts file and any associations between the zone and interfaces in the /etc/shorewall/interfaces file were ignored. This behavior is preserved if MERGE_HOSTS=No or if MERGE_HOSTS is not set or is set to the empty value.
  
  Beginning with version 1.3.5, if MERGE_HOSTS=Yes, then zone assignments in the /etc/shorewall/hosts file are ADDED to those in the /etc/shorewall/interfaces file.
  
  Example:
  
  Interfaces File:
   

  ZONE	HOSTS	BROADCAST	OPTIONS
  loc	eth1	-	dhcp
  -	ppp+

  
  Hosts File:
   

  ZONE	HOSTS
  loc	ppp+:192.168.12.0/24

  
  With MERGE_HOSTS=No, the loc zone consists of only ppp+:192.168.12.0/24; with MERGE_HOSTS=Yes, it includes eth1:0.0.0.0/0 and ppp+:192.168.12.0/24.
   

• MULTIPORT - Added in Version 1.3.2
  If set to "Yes" or "yes", Shorewall will use the Netfilter multiport facility. In order to use this facility, your kernel must have multiport support (CONFIG_IP_NF_MATCH_MULTIPORT). When this support is used, Shorewall will generate a single rule from each record in the /etc/shorewall/rules file that meets these criteria:
   
  • No port range(s) specified
  • Specifies 15 or fewer ports

  Rules not meeting those criteria will continue to generate an individual rule for each listed port or port range.

• NAT_BEFORE_RULES
  If set to "No" or "no", port forwarding rules can override the contents of the /etc/shorewall/nat file. If set to "Yes" or "yes", port forwarding rules cannot override static NAT. If not set or set to an empty value, "Yes" is assumed.
• FW
  This parameter specifies the name of the firewall zone. If not set or if set to an empty string, the value "fw" is assumed.
• SUBSYSLOCK
  This parameter should be set to the name of a file that the firewall should create if it starts successfully and remove when it stops. Creating and removing this file allows Shorewall to work with your distribution's initscripts. For RedHat, this should be set to /var/lock/subsys/shorewall. For Debian, the value is /var/state/shorewall and in LEAF it is /var/run/shorwall. Example: SUBSYSLOCK=/var/lock/subsys/shorewall.
• STATEDIR
  This parameter specifies the name of a directory where Shorewall stores state information. If the directory doesn't exist when Shorewall starts, it will create the directory. Example: STATEDIR=/tmp/shorewall.
  
  NOTE: If you change the STATEDIR variable while the firewall is running, create the new directory if necessary then copy the contents of the old directory to the new directory.
• ALLOWRELATED
  This parameter must be assigned the value "Yes" ("yes") or "No" ("no") and specifies whether Shorewall allows connection requests that are related to an already allowed connection. If you say "No" ("no"), you can still override this setting by including "related" rules in /etc/shorewall/rules ("related" given as the protocol).
• MODULESDIR
  This parameter specifies the directory where your kernel netfilter modules may be found. If you leave the variable empty, Shorewall will supply the value "/lib/modules/`uname -r`/kernel/net/ipv4/netfilter.
• LOGRATE and LOGBURST
  These parameters set the match rate and initial burst size for logged packets. Please see the iptables man page for a description of the behavior of these parameters (the iptables option --limit is set by LOGRATE and --limit-burst is set by LOGBURST). If both parameters are set empty, no rate-limiting will occur.
  
  Example:
      LOGRATE=10/minute
      LOGBURST=5
   
• LOGFILE
  This parameter tells the /sbin/shorewall program where to look for Shorewall messages when processing the "show log", "monitor", "status" and "hits" commands. If not assigned or if assigned an empty value, /var/log/messages is assumed.
• NAT_ENABLED
  This parameter determines whether Shorewall supports NAT operations. NAT operations include:
  
      Static NAT
      Port Forwarding
      Port Redirection
      Masquerading
  
  If the parameter has no value or has a value of "Yes" or "yes" then NAT is enabled. If the parameter has a value of "no" or "No" then NAT is disabled.
  
• MANGLE_ENABLED
  This parameter determines if packet mangling is enabled. If the parameter has no value or has a value of "Yes" or "yes" than packet mangling is enabled. If the parameter has a value of "no" or "No" then packet mangling is disabled. If packet mangling is disabled, the /etc/shorewall/tos file is ignored.
  
• IP_FORWARDING
  This parameter determines whether Shorewall enables or disables IPV4 Packet Forwarding (/proc/sys/net/ipv4/ip_forward). Possible values are:
  
      On or on - packet forwarding will be enabled.
      Off or off - packet forwarding will be disabled.
      Keep or keep - Shorewall will neither enable nor disable packet forwarding.
  
  If this variable is not set or is given an empty value (IP_FORWARD="") then IP_FORWARD=On is assumed.
  
• ADD_IP_ALIASES
  This parameter determines whether Shorewall automatically adds the external address(es) in /etc/shorewall/nat . If the variable is set to "Yes" or "yes" then Shorewall automatically adds these aliases. If it is set to "No" or "no", you must add these aliases yourself using your distribution's network configuration tools.
  
  If this variable is not set or is given an empty value (ADD_IP_ALIASES="") then ADD_IP_ALIASES=Yes is assumed.
• ADD_SNAT_ALIASES
  This parameter determines whether Shorewall automatically adds the SNAT ADDRESS in /etc/shorewall/masq. If the variable is set to "Yes" or "yes" then Shorewall automatically adds these addresses. If it is set to "No" or "no", you must add these addresses yourself using your distribution's network configuration tools.
  
  If this variable is not set or is given an empty value (ADD_SNAT_ALIASES="") then ADD_SNAT_ALIASES=No is assumed.
  
• LOGUNCLEAN
  This parameter determines the logging level of mangled/invalid packets controlled by the 'dropunclean and logunclean' interface options. If LOGUNCLEAN is empty (LOGUNCLEAN=) then packets selected by 'dropclean' are dropped silently ('logunclean' packets are logged under the 'info' log level). Otherwise, these packets are logged at the specified level (Example: LOGUNCLEAN=debug).
• BLACKLIST_DISPOSITION
  This parameter determines the disposition of packets from blacklisted hosts. It may have the value DROP if the packets are to be dropped or REJECT if the packets are to be replied with an ICMP port unreachable reply or a TCP RST (tcp only). If you do not assign a value or if you assign an empty value then DROP is assumed.
• BLACKLIST_LOGLEVEL
  This paremter determines if packets from blacklisted hosts are logged and it determines the syslog level that they are to be logged at. Its value is a syslog log level (Example: BLACKLIST_LOGLEVEL=debug). If you do not assign a value or if you assign an empty value then packets from blacklisted hosts are not logged.
• CLAMPMSS
  This parameter enables the TCP Clamp MSS to PMTU feature of Netfilter and is usually required when your internet connection is through PPPoE or PPTP. If set to "Yes" or "yes", the feature is enabled. If left blank or set to "No" or "no", the feature is not enabled. Note: This option requires CONFIG_IP_NF_TARGET_TCPMSS in your kernel.
• ROUTE_FILTER
  If this parameter is given the value "Yes" or "yes" then route filtering (anti-spoofing) is enabled on all network interfaces. The default value is "no".

/etc/shorewall/modules Configuration

The file /etc/shorewall/modules contains commands for loading the kernel modules required by Shorewall-defined firewall rules. Shorewall will source this file during start/restart provided that it exists and that the directory specified by the MODULESDIR parameter exists (see /etc/shorewall/shorewall.conf above).

The file that is released with Shorewall calls the Shorewall function "loadmodule" for the set of modules that I load.

The loadmodule function is called as follows:

loadmodule <modulename> [ <module parameters> ]

where

<modulename>                

is the name of the modules without the trailing ".o" (example ip_conntrack).

<module parameters>

Optional parameters to the insmod utility.

The function determines if the module named by <modulename> is already loaded and if not then the function determines if the ".o" file corresponding to the module exists in the moduledirectory; if so, then the following command is executed:

insmod moduledirectory/<modulename>.o <module parameters>

If the file doesn't exist, the function determines of the ".o.gz" file corresponding to the module exists in the moduledirectory. If it does, the function assumes that the running configuration supports compressed modules and execute the following command:

insmod moduledirectory/<modulename>.o.gz <module parameters>

/etc/shorewall/tos Configuration

The /etc/shorewall/tos file allows you to set the Type of Service field in packet headers based on packet source, packet destination, protocol, source port and destination port. In order for this file to be processed by Shorewall, you must have mangle support enabled .

Entries in the file have the following columns:

• SOURCE -- The source zone. May be qualified by following the zone name with a colon (":") and either an IP address, an IP subnet, a MAC address in Shorewall Format or the name of an interface. This column may also contain the name of the firewall zone to indicate packets originating on the firewall itself or "all" to indicate any source.
• DEST -- The destination zone. May be qualified by following the zone name with a colon (":") and either an IP address or an IP subnet. Because packets are marked prior to routing, you may not specify the name of an interface. This column may also contain  "all" to indicate any destination.
• PROTOCOL -- The name of a protocol in /etc/protocols or the protocol's number.
• SOURCE PORT(S) -- The source port or a port range. For all ports, place a hyphen ("-") in this column.
• DEST PORT(S)  -- The destination port or a port range. To indicate all ports, place a hyphen ("-") in this column.
• TOS -- The type of service. Must be one of the following:

Minimize-Delay (16)
Maximize-Throughput (8)
Maximize-Reliability (4)
Minimize-Cost (2)
Normal-Service (0)

The /etc/shorewall/tos file that is included with Shorewall contains the following entries.

SOURCE	DEST	PROTOCOL	SOURCE PORT(S)	DEST PORT(S)	TOS
all	all	tcp	-	ssh	16
all	all	tcp	ssh	-	16
all	all	tcp	-	ftp	16
all	all	tcp	ftp	-	16
all	all	tcp	-	ftp-data	8
all	all	tcp	ftp-data	-	8

WARNING: Users have reported that odd routing problems result from adding the ESP and AH protocols to the /etc/shorewall/tos file.

/etc/shorewall/blacklist

Each line in /etc/shorewall/blacklist contains an IP address, a MAC address in Shorewall Format or subnet address. Example:

      130.252.100.69
      206.124.146.0/24

Packets from hosts listed in the blacklist file will be disposed of according to the value assigned to the BLACKLIST_DISPOSITION and BLACKLIST_LOGLEVEL variables in /etc/shorewall/shorewall.conf. Only packets arriving on interfaces that have the 'blacklist' option in /etc/shorewall/interfaces are checked against the blacklist. The black list is designed to prevent listed hosts/subnets from accessing services on your network.

Shorewall also has a dynamic blacklist capability.

IMPORTANT: The Shorewall blacklist file is NOT designed to police your users' web browsing -- to do that, I suggest that you install and configure Squid (http://www.squid-cache.org).

/etc/shorewall/rfc1918 (Added in Version 1.3.1)

This file lists the subnets affected by the norfc1918 interface option. Columns in the file are:

• SUBNET - The subnet using VLSM notation (e.g., 192.168.0.0/16).
• TARGET - What to do with packets to/from the SUBNET:
  • RETURN - Process the packet normally thru the rules and policies.
  • DROP - Silently drop the packet.
  • logdrop - Log then drop the packet.

25. /etc/shorewall/routestopped (Added in Version 1.3.4)

This fine defines the hosts that are accessible from the firewall when the firewall is stopped.  Columns in the file are:

• INTERFACE - The firewall interface through which the host(s) comminicate with the firewall.
• HOST(S) - (Optional) - A comma-separated list of IP/Subnet addresses. If not supplied or supplied as "-" then 0.0.0.0/0 is assumed.

Example: When your firewall is stopped, you want firewall accessibility from local hosts 192.168.1.0/24 and from your DMZ. Your DMZ interfaces through eth1 and your local hosts through eth2.

INTERFACE	HOST(S)
eth2	192.168.1.0/24
eth1	-

Updated 8/14/2002 - Tom Eastep

Copyright © 2001, 2002 Thomas M. Eastep.