This article offers hints about how to accomplish common tasks with Shorewall. The Introduction to Shorewall is required reading for being able to use this article effectively. For information about setting up your first Shorewall-based firewall, see the Quickstart Guides.

If you need to change a file in /usr/share/shorewall/, copy it to /etc/shorewall and modify the copy

Man pages are provided in section 5 for each of the Shorewall configuration files. The name of the page is formed by prefixing the file name with "shorewall-".

Example — To view the manual page for /etc/shorewall/interfaces:

man shorewall-interfaces

The /etc/shorewall/shorewall.conf file is an exception -- the man page for that file is 'shorewall.conf':

man shorewall.conf

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.

# This is a comment
ACCEPT  net     $FW      tcp     www     #This is an end-of-line comment

If you kernel and iptables contain comment match support (see the output of shorewall show capabilities), then you can attach comments to Netfilter rules. This feature is available in the following files:

To attach a comment to one or more rules, insert a record above the rules that begins with the word COMMENT (must be in all caps). The remainder of the line is treated as a comment -- that comment will appear delimited by "/* ... */" in the output of the shorewall[-lite] show and shorewall[-lite] dump commands. The comment will be attached to each generated rule until another COMMENT line appears. To stop attaching comments to rules, simply insert a line that contains the single word COMMENT.

Example (/etc/shorewall/rules):

COMMENT Stop NETBIOS noise

REJECT          loc                             net                     tcp     137,445
REJECT          loc                             net                     udp     137:139

COMMENT Stop my idiotic work laptop from sending to the net with an HP source/dest IP address

DROP            loc:!192.168.0.0/22             net

COMMENT

Here's the corresponding output from /sbin/shorewall-lite:

gateway:~ # shorewall-lite show loc2net
Shorewall Lite 4.3.3 Chains loc2net at gateway - Mon Oct 16 15:04:52 PDT 2008

Counters reset Mon Oct 16 14:52:17 PDT 2006

Chain loc2net (1 references)
 pkts bytes target     prot opt in     out     source               destination
    0     0 LOG        tcp  --  *      *       0.0.0.0/0            0.0.0.0/0           tcp dpt:25 LOG flags 0 level 6 prefix `FW:loc2net:REJECT:'
    0     0 reject     tcp  --  *      *       0.0.0.0/0            0.0.0.0/0           tcp dpt:25
    0     0 LOG        udp  --  *      *       0.0.0.0/0            0.0.0.0/0           udp dpts:1025:1031 LOG flags 0 level 6 prefix `FW:loc2net:REJECT:'
    0     0 reject     udp  --  *      *       0.0.0.0/0            0.0.0.0/0           udp dpts:1025:1031
    0     0 reject     tcp  --  *      *       0.0.0.0/0            0.0.0.0/0           multiport dports 137,445 /* Stop NETBIOS noise */
    0     0 reject     udp  --  *      *       0.0.0.0/0            0.0.0.0/0           udp dpts:137:139 /* Stop NETBIOS noise */
    0     0 DROP       all  --  *      *      !192.168.0.0/22       0.0.0.0/0           /* Stop my idiotic work laptop from sending to the net with an HP source/dest IP address */
    5   316 ACCEPT     all  --  *      *       0.0.0.0/0            0.0.0.0/0
gateway:~ #

COMMENT lines in macro files work somewhat differently from other files. COMMENT lines in macros are ignored if COMMENT support is not available or if there was a COMMENT in use when the top-level macro was invoked. This allows the following:

/usr/share/shorewall/macro.SSH:

#ACTION SOURCE DEST  PROTO DEST    SOURCE  RATE  USER/
#                          PORT(S) PORT(S) LIMIT GROUP
COMMENT SSH
PARAM   -      -     tcp   22 

/etc/shorewall/rules:

COMMENT Allow SSH from home
SSH/ALLOW    net:$MYIP      $FW
COMMENT

The comment line in macro.SSH will not override the COMMENT line in the rules file and the generated rule will show /* Allow SSH from home */ when displayed through the Shorewall show and dump commands.

If you don't want to supply a value in a column but want to supply a value in a following column, simply enter '-' to make the column appear empty.

Example:

#INTERFACE         BROADCAST            OPTIONS
br0                -                    routeback

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

ACCEPT  net     $FW      tcp \↵
smtp,www,pop3,imap  #Services running on the firewall

#ACTION     SOURCE          DEST            PROTO           DEST
#                                                           PORT(S)
ACCEPT      net:\
            206.124.146.177,\
            206.124.146.178,\
            206.124.146.180\
                            dmz             tcp             873

Entries in Shorewall configuration files often deal with the source (SOURCE) and destination (DEST) of connections and Shorewall implements a uniform way for specifying them.

A SOURCE or DEST consists of one to three parts separated by colons (":"):

Examples.

Any configuration file may contain INCLUDE directives. An INCLUDE directive consists of the word INCLUDE followed by a path name and causes the contents of the named file to be logically included into the file containing the INCLUDE. Relative path names given in an INCLUDE directive are resolved using the current CONFIG_PATH setting (see shorewall.conf(5)).

INCLUDE's may be nested to a level of 3 -- further nested INCLUDE directives are ignored with a warning message.

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

gateway:/etc/shorewall # ls rules.d
ALL.rules  DNAT.rules  FW.rules  NET.rules  REDIRECT.rules  VPN.rules
gateway:/etc/shorewall # 

SECTION NEW
SHELL cat /etc/shorewall/rules.d/*.rules

You may use the /etc/shorewall/params file to set shell variables that you can then use in 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

The following variable names must be avoided. Those in bold font must be avoided in all Shorewall versions; those in regular font must be avoided in versions prior to 4.4.8.

Example:

Variables may be used anywhere in the other configuration files.

/etc/shorewall/zones:

        #ZONE        TYPE          OPTIONS
        fw           firewall

/etc/shorewall/params:

        FW=fw
        BLARG=$FW:206.124.146.176

Because the /etc/shorewall/params file is simply sourced into the shell, you can place arbitrary shell code in the file and it will be executed each time that the file is read. Any code included should follow these guidelines:

Earlier versions of Shorewall offered extension scripts to allow users to extend Shorewall's functionality. Extension scripts were designed to work under the limitations of the Bourne Shell. With the current Perl-based compiler, Embedded scripts offer a richer and more flexible extension capability.

While inline scripts may be written in either Shell or Perl, those written in Perl have a lot more power.

Embedded scripts can be either single-line or multi-line. Single line scripts take one of the following forms:

Shell scripts run in a child shell process and their output is piped back to the compiler which processes that output as if it were embedded at the point of the script.

Example: The following entries in /etc/shorewall/rules are equivalent:

SHELL for z in net loc dmz; do echo "ACCEPT $z fw tcp 22"; done

ACCEPT net fw tcp 22
ACCEPT loc fw tcp 22
ACCEPT dmz fw tcp 22

Perl scripts run in the context of of the compiler process using Perl's eval() function. Perl scripts are implicitly prefixed by the following:

package Shorewall::User;
use Shorewall::Config qw/shorewall/;

To produce output that will be processed by the compiler as if it were embedded in the file at the point of the script, pass that output to the Shorewall::Config::shorewall() function. The Perl equivalent of the above SHELL script would be:

PERL for ( qw/net loc dmz/ ) { shorewall "ACCEPT $_ fw tcp 22"; }

A couple of more points should be mentioned:

Multi-line scripts use one of the following forms:

BEGIN SHELL
<shell script>
END [ SHELL ]

BEGIN PERL [;]
<perl script>
END [ PERL ] [;]

Note: The '[' and ']' above are meta-characters which indicate that what they enclose is optional and may be omitted. So you may follow PERL with a semicolon ( ';') or you may omit the semicolon.

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 rule set.

For some sites, using DNS names is very risky. Here's an example:

teastep@ursa:~$ dig pop.gmail.com

; <<>> DiG 9.4.2-P1 <<>> pop.gmail.com
;; global options:  printcmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 1774
;; flags: qr rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 7, ADDITIONAL: 0

;; QUESTION SECTION:
;pop.gmail.com.               IN A

;; ANSWER SECTION:
pop.gmail.com.          300   IN CNAME gmail-pop.l.google.com.
gmail-pop.l.google.com. 300   IN A     209.85.201.109
gmail-pop.l.google.com. 300   IN A     209.85.201.111

Note that the TTL is 300 -- 300 seconds is only 5 minutes. So five minutes later, the answer may change!

So this rule may work for five minutes then suddently stop working:

#ACTION        SOURCE               DEST              PROTO             DEST
#                                                                       PORT(S)
POP(ACCEPT)     loc                  net:pop.gmail.com

If your firewall rules include DNS names then:

Each DNS name must be fully qualified and include a minimum of two periods (although one may be trailing). This restriction is imposed by Shorewall to insure backward compatibility with existing configuration files.

DNS names may not be used as:

These restrictions are imposed by Netfilter and not by Shorewall.

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

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 “!”.

Where a comma-separated list of addresses is accepted, an exclusion list may also be included. An exclusion list is a comma-separated list of addresses that begins with "!".

Example:

!192.168.1.3,192.168.1.12,192.168.1.32/27

The above list refers to "All addresses except 192.168.1.3, 192.168.1.12 and 192.168.1.32-192.168.1.63.

Exclusion lists can also be added after a network address.

Example:

192.168.1.0/24!192.168.1.3,192.168.1.12,192.168.1.32/27

The above list refers to "All addresses in 192.168.1.0-192.168.1.255 except 192.168.1.3, 192.168.1.12 and 192.168.1.32-192.168.1.63.

If you kernel and iptables have iprange match support, you may use IP address ranges in Shorewall configuration file entries; IP address ranges have the syntax <low IP address>-<high IP address>. Example: 192.168.1.5-192.168.1.12.

To see if your kernel and iptables have the required support, use the shorewall show capabilities command:

>~ shorewall show capabilities
... 
Shorewall has detected the following iptables/netfilter capabilities:
   NAT: Available
   Packet Mangling: Available
   Multi-port Match: Available
   Connection Tracking Match: Available
   Packet Type Match: Not available
   Policy Match: Available
   Physdev Match: Available
   IP range Match: Available <--------------

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

Also, unless otherwise documented, a protocol number/name can be preceded by '!' to specify "All protocols except this one" (e.g., "!tcp").

When dealing with ICMP, the DEST PORT specifies the type or type and code. You may specify the numeric type, the numeric type and code separated by a slash (e.g., 3/4) or you may use a type name.

Type names for IPv4 and their corresponding type or type/code are:

echo-reply'                  => 0
destination-unreachable      => 3
    network-unreachable      => 3/0
    host-unreachable         => 3/1
protocol-unreachable         => 3/2
port-unreachable             => 3/3
fragmentation-needed         => 3/4
source-route-failed          => 3/5
network-unknown              => 3/6
host-unknown                 => 3/7
network-prohibited           => 3/9
host-prohibited              => 3/10
TOS-network-unreachable      => 3/11
TOS-host-unreachable         => 3/12
communication-prohibited     => 3/13
host-precedence-violation    => 3/14
precedence-cutoff            => 3/15
source-quench                => 4
redirect                     => 5
   network-redirect          => 5/0
   host-redirect             => 5/1
   TOS-network-redirect      => 5/2
   TOS-host-redirect         => 5/3
echo-request                 => 8
router-advertisement         => 9
router-solicitation          => 10
time-exceeded                => 11
   ttl-zero-during-transit   => 11/0
   ttl-zero-during-reassembly=> 11/1
parameter-problem            => 12
   ip-header-bad             => 12/0
   required-option-missing   => 12/1
timestamp-request            => 13
timestamp-reply              => 14
address-mask-request         => 17
address-mask-reply           => 18

Type names for IPv6 and their corresponding type or type/code are:

destination-unreachable       => 1
   no-route'                  => 1/0
   communication-prohibited   => 1/1
   address-unreachable'       => 1/2
   port-unreachable'          => 1/3
packet-too-big                =>  2
time-exceeded'                =>  3
ttl-exceeded'                 =>  3
   ttl-zero-during-transit    => 3/0
   ttl-zero-during-reassembly => 3/1
parameter-problem             =>  4
   bad-header                 => 4/0
   unknown-header-type        => 4/1
   unknown-option             => 4/2
echo-request                  => 128
echo-reply                    => 129
router-solicitation           => 133
router-advertisement          => 134
neighbour-solicitation        => 135
neighbour-advertisement       => 136
redirect                      => 137

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:

#ACTION    SOURCE     DESTINATION     PROTO     DEST PORTS(S)
DNAT       net        loc:192.168.1.3 tcp       4000:4100

If you omit the low port number, a value of zero is assumed; if you omit the high port number, a value of 65535 is assumed.

Also, unless otherwise documented, a port range can be preceded by '!' to specify "All ports except those in this range" (e.g., "!4000:4100").

In most cases where a port or port range may appear, a comma-separated list of ports or port ranges may also be entered. Shorewall requires the Netfilter multiport match capability if ports lists are used (see the output of "shorewall show capabilities").

Also, unless otherwise documented, a port list can be preceded by '!' to specify "All ports except these" (e.g., "!80,443").

Prior to Shorewall 4.4.4, port lists appearing in the shorewall-routestopped (5) file may specify no more than 15 ports; port ranges appearing in a list count as two ports each.

Media Access Control (MAC) addresses can be used to specify packet source in several of the configuration files. In order to control traffic to/from a host by its MAC address, the host must be on the same network as the firewall.

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.

     gateway:~ # ip link ls dev eth0
     4: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc htb qlen 1000
         link/ether 02:00:08:E3:FA:55 brd ff:ff:ff:ff:ff:ff
     gateway:~ #

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.

Shorewall supports rate limiting in a number of ways. When specifying a rate limit, both a rate and a burst value are given.

Example from shorewall.conf (5):

For each logging rule, the first time the rule is reached, the packet will be logged; in fact, since the burst is 5, the first five packets will be logged. After this, it will be 6 seconds (1 minute divided by the rate of 10) before a message will be logged from the rule, regardless of how many packets reach it. Also, every 6 seconds which passes, one of the bursts will be regained; if no packets hit the rule for 30 seconds, the burst will be fully recharged; back where we started.

When dealing with a complex configuration, it is often awkward to use physical interface names in the Shorewall configuration.

Beginning with Shorewall 4.4.4, you can use logical interface names which are mapped to the actual interface using the physical option in shorewall-interfraces (5).

Here is an example:

#ZONE  INTERFACE  BROADCAST OPTIONS
net    COM_IF     detect    dhcp,blacklist,tcpflags,optional,upnp,routefilter=0,nosmurfs,logmartians=0,physical=eth0
net    EXT_IF     detect    dhcp,blacklist,tcpflags,optional,routefilter=0,nosmurfs,logmartians=0,proxyarp=1,physical=eth2
loc    INT_IF     detect    dhcp,logmartians=1,routefilter=1,tcpflags,nets=172.20.1.0/24,physical=eth1
dmz    VPS_IF     detect    logmartians=1,routefilter=0,routeback,physical=venet0
loc    TUN_IF     detect    physical=tun+

In this example, COM_IF is a logical interface name that refers to Ethernet interface eth0, EXT_IF is a logical interface name that refers to Ethernet interface eth2, and so on.

Here are a couple of more files from the same configuration:

shorewall-masq (5):

#INTERFACE SOURCE                    ADDRESS

COMMENT Masquerade Local Network
COM_IF     0.0.0.0/0
EXT_IF     !206.124.146.0/24         206.124.146.179:persistent

shorewall-providers (5)

#NAME   NUMBER   MARK    DUPLICATE  INTERFACE  GATEWAY         OPTIONS               COPY
Avvanta 1        0x10000 main       EXT_IF     206.124.146.254 loose,fallback        INT_IF,VPS_IF,TUN_IF
Comcast 2        0x20000 main       COM_IF     detect          balance               INT_IF,VPS_IF,TUN_IF

Note in particular that Shorewall translates TUN_IF to tun* in the COPY column.

Shorewall allows you to have configuration directories other than /etc/shorewall. The shorewall check, start and restart commands allow you to specify an alternate configuration directory and Shorewall will use the files in the alternate directory rather than the corresponding files in /etc/shorewall. The alternate directory need not contain a complete configuration; those files not in the alternate directory will be read from /etc/shorewall.

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

Shorewall allows you to save the currently-running configuration in a form that permits it to be re-installed quickly. When you save the configuration using the shorewall save command, the running configuration is saved in a file in the /var/lib/shorewall directory. The default name of that file is /var/lib/shorewall/restore but you can specify a different name as part of the command. For example, the command shorewall save standard will save the running configuration in /var/lib/shorewall/standard. A saved configuration is re-installed using the shorewall restore command. Again, that command normally will restore the configuration saved in /var/lib/shorewall/restore but as with the save command, you can specify a different file name in the command. For example, shorewall restore standard will re-install the configuration saved in /var/lib/shorewall/standard. By permitting you to save different configurations under different names, Shorewall provides a means for quickly switching between these different saved configurations.

As mentioned above, the default configuration is called 'restore' but like most things in Shorewall, that default can be changed. The default name is specified using the RESTOREFILE option in /etc/shorewall/shorewall.conf.