Configuration Files

Tom Eastep

Permission 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”.


Table of Contents

Man Pages
Attach Comment to Netfilter Rules
"Blank" Columns
Line Continuation
INCLUDE Directive
Using Shell Variables
Embedded Shell and Perl
Using DNS Names
Comma-separated Lists
Complementing an Address or Subnet
Exclusion Lists
IP Address Ranges
Protocol Number/Names and Port Numbers/Service Names
Port Ranges
Port Lists
Using MAC Addresses
Shorewall Configurations
Saved Configurations


This article applies to Shorewall 3.0 and later. If you are running a version of Shorewall earlier than Shorewall 3.0.0 then please see the documentation for that release.


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.


  • /etc/shorewall/shorewall.conf - used to set global 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 - 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 tunnels (VPN) 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 allow user-defined actions.

  • /etc/shorewall/providers - defines an alternate routing table.

  • /etc/shorewall/route_rules (Added in Shorewall 3.2.0) - Defines routing rules to be used in conjunction with the routing tables defined in /etc/shorewall/providers.

  • /etc/shorewall/tcdevices, /etc/shorewall/tcclasses, /etc/shorewall/tcfilters (tcfilters added in Shorewall 4.2.0) - Define traffic shaping.

  • /etc/shorewall/tcrules - Mark or classify traffic for traffic shaping or multiple providers.

  • /etc/shorewall/vardir - (Added in Shorewall 4.0.0-RC2) - Determines the directory where Shorewall maintains its state.

  • /usr/share/shorewall/actions.std - Actions defined by Shorewall.

  • /usr/share/shorewall/action.* - Details of actions defined by Shorewall.

  • /usr/share/shorewall/macro.* - Details of macros defined by Shorewall.

  • /usr/share/rfc1918 — Defines the behavior of the 'norfc1918' interface option in /etc/shorewall/interfaces. If you need to change this file, copy it to /etc/shorewall and modify the copy.

Man Pages

Beginning with Shorewall version 3.4, 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.

Example 1. Comments in a Configuration File

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

Attach Comment to Netfilter Rules

Beginning with Shorewall version 3.3.3, 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:

  • /etc/shorewall/accounting (Shorewall-perl only)

  • /etc/shorewall/masq

  • /etc/shorewall/nat

  • /etc/shorewall/notrack (Shorewall-perl 4.2.7 and later)

  • /etc/shorewall/rules

  • /etc/shorewall/tcrules

  • /etc/shorewall/tunnels (Shorewall-perl only)

  • Action definition files (/etc/shorewall/action.*)

  • Macro definition files (/etc/shorewall/macro.*)

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


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:!             net


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

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

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  --  *      *             tcp dpt:25 LOG flags 0 level 6 prefix `FW:loc2net:REJECT:'
    0     0 reject     tcp  --  *      *             tcp dpt:25
    0     0 LOG        udp  --  *      *             udp dpts:1025:1031 LOG flags 0 level 6 prefix `FW:loc2net:REJECT:'
    0     0 reject     udp  --  *      *             udp dpts:1025:1031
    0     0 reject     tcp  --  *      *             multiport dports 137,445 /* Stop NETBIOS noise */
    0     0 reject     udp  --  *      *             udp dpts:137:139 /* Stop NETBIOS noise */
    0     0 DROP       all  --  *      *      !           /* Stop my idiotic work laptop from sending to the net with an HP source/dest IP address */
    5   316 ACCEPT     all  --  *      *  
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:


#                          PORT(S) PORT(S) LIMIT GROUP
PARAM   -      -     tcp   22 


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

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.

"Blank" Columns

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.


br0                -                    routeback

Line Continuation

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

Example 2. Line Continuation

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

INCLUDE Directive

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.


If you are using Shorewall Lite and are running a version of Shorewall earlier than 3.2.9, it is not advisable to use INCLUDE in the params file in an export directory. If you do that, you must ensure that the included file is also present on the firewall system's /etc/shorewall-lite/ directory.

Beginning with Shorewall version 3.2.9 (3.4.0 RC2), you can set EXPORTPARAMS=No in shorewall.conf. That prevents the params file from being copied into the compiled script. With EXPORTPARAMS=No, it is perfectly okay to use INCLUDE in the params file.

Example 3. Use of INCLUDE

        ----- end params.mgmt -----
        # Shorewall 1.3 /etc/shorewall/params
         INCLUDE params.mgmt    
       # params unique to this host here
       ----- end params -----
       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 version 1.3 - Rules File
       INCLUDE rules.mgmt     
       # rules unique to this host here
     ----- end rules -----

Users of Shorewall-perl 4.0.6 and later may include multiple files in one command using an embedded shell command.

Example (include all of the files ending in ".rules" in a directory:):

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


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

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


    /etc/shorewall/interfaces record:

    The result will be the same as if the record had been written
        net eth0 routefilter,norfc1918

Variables may be used anywhere in the other configuration files.


Shorewall-perl users: If you use "$FW" on the right side of assignments in the /etc/shorewall/params file, you must also set the FW variable in that file.



        #ZONE        TYPE          OPTIONS
        fw           firewall



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:

  1. The code should not have side effects, especially on other shorewall configuration files.

  2. The code should be safe to execute multiple times without producing different results.

  3. Should not depend on where the code is called from (the params file is sourced by both /sbin/shorewall and /usr/lib/shorewall/firewall).

  4. Should not assume anything about the state of Shorewall.

  5. The names of any functions or variables declared should begin with an upper case letter.

  6. The /etc/shorewall/params file is processed by the compiler at compile-time and by the compiled script at run-time. Beginning with Shorewall 3.2.9 and 3.4.0 RC2, if you have set EXPORTPARAMS=No in shorewall.conf, then the params file is only processed by the compiler; it is not run by the compiled script.

  7. If you are using Shorewall Lite and if the params script needs to set shell variables based on the configuration of the firewall system, you can use this trick:

    EXT_IP=$(ssh root@firewall "/sbin/shorewall-lite call find_first_interface_address eth0")

    The shorewall-lite call command allows you to to call interactively any Shorewall function that you can call in an extension script.

When expanding a variable, the acceptable forms of expansion depend on whether you are using Shorewall-shell or Shorewall-perl.

  • Shorewall-shell and all Shorewall versions prior to 4.0 can use any form of expansion supported by the shell ($VAR, ${VAR}, ${VAR:=val}, ...).

  • Shorewall-perl only supports the $VAR and ${VAR} forms.

Embedded Shell and Perl

This feature was added in Shorewall-perl 4.0.6. To use it, you must be running 4.0.6 or later and must be using Shorewall-perl (SHOREWALL_COMPILER=perl in shorewall.conf).

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 Shorewall-perl, Embedded scripts offer a richer and more flexible extension capability.

While inline scripts 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:

  • PERL <perl script>

  • SHELL <shell script>

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. 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() function. The Perl equivalent of the above SHELL script would be:

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

Perl scripts are implicitly prefixed by the following:

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

As part of the change that added embedded scripts:

  1. Compile-time extension scripts are also implicitly prefixed by "package Shorewall::User;".

  2. A compile extension script was added for use by Shorewall-perl. That script is run early in the compilation process and allows users to load additional modules and to define data and functions for use in subsequent embedded scripts and extension scripts.

  3. A Manual Chain facility was added.

Multi-line scripts use one of the following forms:

<shell script>
<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.

Using DNS Names


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.

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

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

;               IN A

;; ANSWER SECTION:          300   IN CNAME 300   IN A 300   IN A

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        

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

Example 4. Valid DNS Names


  • (note the trailing period).

Example 5. Invalid DNS Names

  • mail (not fully qualified)

  • (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.

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:   routefilter,dhcp,norfc1918
         Invalid: routefilter,     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.

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, ! means “any host but”. There must be no white space following the “!”.

Exclusion Lists

Shorewall 3.0 differs from earlier versions in that in most contexts 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 "!".



The above list refers to "All addresses except, and

Exclusion lists can also be added after a network address.


The above list refers to "All addresses in except, and

IP Address Ranges

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:

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

Protocol Number/Names and Port Numbers/Service Names

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.


Shorewall-perl translates protocol names to protocol numbers and service names to port numbers itself.

In Shorewall versions 4.0.0 - 4.0.4, the mapping that it uses is contained in the Perl module /usr/share/shorewall-perl/Shorewall/ That module is built when Shorewall is installed or upgraded using the current /etc/protocols and /etc/services files as input (if the build program fails, a fallback version of the module is installed).

To generate a new module:

cp /usr/share/shorewall-perl/Shorewall/ /usr/share/shorewall-perl/Shorewall/
/usr/share/shorewall/ > /usr/share/shorewall-perl/Shorewall/

Beginning with Shorewall version 4.0.5, the /usr/share/shorewall-perl/Shorewall/ has been eliminated and the Shorewall-perl compiler uses Perl's interfaces to getprotobyname(3posix) and getservbyname(3posix).

Also, unless otherwise documented, a protocol number/name can be preceded by '!' to specify "All protocols except this one" (e.g., "!tcp"). Shorewall-perl support for that feature was added in Shorewall 4.2.6.

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, the entry in /etc/shorewall/rules is:

DNAT       net        loc: 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"). Shorewall-perl support for that feature was added in Shorewall 4.2.6.

Port Lists

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 will use the Netfilter multiport match capability if it is available (see the output of "shorewall show capabilities") and if its use is appropriate.

Shorewall can use multiport match if:

  1. The list contains 15 or fewer port number; and

  2. There are no port ranges listed OR your iptables/kernel support the Extended multiport match (again see the output of "shorewall show capabilities"). Where the Extended multiport match is available, each port range counts as two ports toward the maximum of 15.


Shorewall-perl requires multiport match in order to accept port lists in Shorewall configuration files. It further requires Extended multiport match in order to accept port ranges in port lists. Shorewall-perl versions earlier than 4.0.5 will never break a list longer than 15 ports (with each range counting as two ports) into smaller lists.

Also, unless otherwise documented, a port list can be preceded by '!' to specify "All ports except these" (e.g., "!80,443"). Shorewall-perl support for that feature was added in Shorewall 4.2.6.

Using MAC Addresses

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.

Example 6. MAC Address of an Ethernet Controller

     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.


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

Shorewall Configurations

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.


Shorewall requires that the file /etc/shorewall/shorewall.conf to always exist. Certain global settings are always obtained from that file. If you create alternative configuration directories, do not remove /etc/shorewall/shorewall.conf.

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

  1. copying the files that need modification from /etc/shorewall to a separate directory;

  2. modify those files in the separate directory; and

  3. specifying the separate directory in a shorewall start or shorewall restart command (e.g., shorewall restart /etc/testconfig )

Saved Configurations

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.


The default saved configuration is used by Shorewall in a number of ways besides in the restore command; to avoid surprises, I recommend that you read the Shorewall Operations documentation section about saved configurations before creating one.