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

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

When you define an object in Shorewall (Zone, Logical Interface, ipsets, Actions, etc., you give it a name. Shorewall names start with a letter and consist of letters, digits or underscores ("_"). Except for Zone names, Shorewall does not impose a limit on name length.

When an ipset is referenced, the name must be preceded by a plus sign ("+").

The last character of an interface may also be a plus sign to indicate a wildcard name.

Physical interface names match names shown by 'ip link ls'; if the name includes an at sign ("@"), do not include that character or any character that follows. For example, "sit1@NONE" is referred to as simply 'sit1".

For a pair of zones, Shorewall creates two Netfilter chains; one for connections in each direction. The names of these chains are formed by separating the names of the two zones by either "2" or "-".

Example: Traffic from zone A to zone B would go through chain A2B (think "A to B") or "A-B".

In Shorewall 4.6, the default separator is "-" but you can override that by setting ZONE_SEPARATOR="2" in shorewall.conf (5).

Zones themselves have names that begin with a letter and are composed of letters, numerals, and "_". The maximum length of a name is dependent on the setting of LOGFORMAT in shorewall.conf (5). See shorewall-zones (5) for details.

Shorewall probes your system to determine the features that it supports. The result of this probing is a set of capabilities. This probing is normally done each time that the compiler is run but can also be done by executing the shorewall show capabilities command. Regardless of whether the compiler or the command does the probing, this probing may produce error messages in your system log. These log messages are to be expected and do not represent a problem; they merely indicate that capabilities that are being probed are not supported on your system.

Probing may be suppressed by using a capabilities file. A capabilities file may be generated using this command:

shorewall show -f capabilities > /etc/shorewall/capabilities

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

In certain cases, leading white space is ignored in continuation lines:

Example (/etc/shorewall/rules):

#ACTION     SOURCE          DEST            PROTO           DPORT
ACCEPT      net:\
            206.124.146.177,\
            206.124.146.178,\
            206.124.146.180\
                            dmz             tcp             873

The leading white space on the first through third continuation lines is ignored so the SOURCE column effectively contains "net:206.124.146.177,206.124.147.178,206.124.146.180". Because the third continuation line does not end with a comma or colon, the leading white space in the last line is not ignored.

#ACTION     SOURCE          DEST            PROTO           DPORT
#ACCEPT     net:\
            206.124.146.177,\
            206.124.146.178,\
            206.124.146.180\
                            dmz             tcp             873

Some of the configuration files now have a large number of columns. That makes it awkward to specify a value for one of the right-most columns as you must have the correct number of intervening '-' columns.

This problem is addressed by allowing column values to be specified as column-name/value pairs.

There is considerable flexibility in how you specify the pairs:

In Shorewall 5.0.3, the sample configuration files and the man pages were updated to use the same column names in both the column headings and in the alternate specification format. The following table shows the column names for each of the table-oriented configuration files.

Example (rules file):

#ACTION         SOURCE            DEST            PROTO   DPORT
DNAT            net               loc:10.0.0.1    tcp     80    ; mark="88"

Here's the same line in several equivalent formats:

{ action=>DNAT, source=>net, dest=>loc:10.0.0.1, proto=>tcp, dport=>80, mark=>88 }
; action:"DNAT" source:"net"  dest:"loc:10.0.0.1" proto:"tcp" dport:"80" mark:"88"
DNAT { source=net dest=loc:10.0.0.1 proto=tcp dport=80 mark=88 }

Beginning with Shorewall 5.0.11, ip[6]table comments can be attached to individual rules using the comment keyword.

Example from the rules file:

        ACCEPT net $FW { proto=tcp, dport=22, comment="Accept \"SSH\"" }

As shown in that example, when the comment contains whitespace, it must be enclosed in double quotes and any embedded double quotes must be escaped using a backslash ("\").

Shorewall doesn't contain built-in support for all ip[6]tables targets and matches. Nevertheless, you can still use the unsupported ip[6]tables features through several Shorewall facilities.

In both Shorewall and Shorewall6, there are two basic types of addresses:

In the Shorewall documentation and manpages, we have tried to make it clear which type of address is accepted in each specific case.

Because Shorewall uses a colon (":") as a separator in many contexts, IPv6 addresses are best written using the standard convention in which the address itself is enclosed in square brackets:

For more information about addressing, see the Setup Guide.

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.

Beginning with Shorewall 4.4.17, the INCLUDE directive may also appear in the following extension scripts:

When used in these scripts, the INCLUDEd files are copied into the compiled firewall script.

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

?SECTION NEW
SHELL cat /etc/shorewall/rules.d/*.rules 2> /dev/null || true

?INCLUDE common.rules

A number of configuration files support multiple formats. Prior to Shorewall 4.5.11, the format was specified by a line having 'FORMAT' as the first token. This requires each of the file processors to handle FORMAT separately.

In Shorewall 4.5.11, the ?FORMAT directive was created to centralize processing of FORMAT directives. The old entries, while still supported in Shorewall 4.5-4.6, are now deprecated. They are no longer supported in Shorewall 5.0 and later versions.

The ?FORMAT directive is as follows:

A number of files allow attaching comments to generated Netfilter rules:

Prior to Shorewall 4.5.11, comments were specified by a line having COMMENT as the first token. The remainder of the line is treated as a comment to be attached to rules.

In Shorewall 4.5.11, the ?COMMENT directive was created to centralize processing of COMMENT directives. The old entries, while still supported in Shorewall 4.5 and 4.6, are now deprecated. They are no longer supported in Shorewall 5.0 and later versions.

Use of this directive requires Comment support in your kernel and iptables - see the output of shorewall show capabilities.

The ?COMMENT directive is as follows:

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 loc-net
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 loc-net (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 DPORT   SPORT   RATE  USER
?COMMENT SSH
PARAM   -      -     tcp   22 

/etc/shorewall/rules:

?COMMENT Allow SSH from home
SSH(ACCEPT)    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.

Beginning with Shorewall 5.0.11, the alternate input format allows attaching comments to individual rules in the files listed above.

The CONFIG_PATH option in shorewall.conf determines where the compiler searches for configuration files. The default setting is CONFIG_PATH=/etc/shorewall:/usr/share/shorewall which means that the compiler first looks in /etc/shorewall and if it doesn't find the file, it then looks in /usr/share/shorewall.

You can change this setting to have the compiler look in different places. For example, if you want to put your own versions of standard macros in /etc/shorewall/Macros, then you could set CONFIG_PATH=/etc/shorewall:/etc/shorewall/Macros:/usr/share/shorewall and the compiler will use your versions rather than the standard ones.

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:

Beginning with Shorewall 4.4.27, you may also use options in shorewall.conf (5) (e.g., $BLACKLIST_LOGLEVEL).

Beginning with Shorewall 4.5.2, configuration files can access variables defined in the shorewallrc file.

Beginning with Shorewall 4.5.11, variables can be altered by compiler directives.

Action variables are read-only and cannot be ?SET (although you can change their values using embedded Perl).

Beginning with Shorewall 4.5.13, Shorewall Variables may be set. When setting a Shorewall Variable, the variable must include the leading '@' and the @{...} form is not allowed.

Given that shell variables are expanded at compile time, there is no way to cause such variables to be expanded at run time. Prior to Shorewall 4.4.17, this made it difficult (to impossible) to include dynamic IP addresses in a Shorewall-lite configuration.

Version 4.4.17 implemented Run-time address variables. In configuration files, these variables are expressed as an apersand ('&') followed by the logical name of an interface defined in shorewall-interfaces (5). Wildcard interfaces (those ending in '+') are not supported and will cause a compilation error.

Beginning with Shorewall 4.5.11, you can define your own address variables by using this syntax:

where variable is a valid shell variable name. The generated script will verify that the variable contains a valid host or network address, either from the environment or from it being assigned in your init extension script, and will raise an error if it does not. In the error case, the state of the firewall will remain unchanged.

Example:

/etc/shorewall/init:

SMC_ADDR=10.1.10.11

/etc/shorewall/rules:

test:debug	net:&{SMC_ADDR}		fw

A second form is also available beginning with Shorewall 4.5.11

Unlike with the first form, this form does not require the variable to be set. If the variable is empty, the generated script will supply the all-zeros address (0.0.0.0 in IPv4 and :: in IPv6). In most cases, the compiler simply omits rules containing matches on the all-zeros address.

Example:

/etc/shorewall/init:

SMC_ADDR=10.1.10.11

/etc/shorewall/rules:

test:debug	net:%{SMC_ADDR}		fw

Run-time address variables may be used in the SOURCE and DEST column of the following configuration files:

They may also appear in the ORIGDEST column of:

For optional interfaces, if the interface is not usable at the time that the firewall starts, one of two approaches are taken, depending on the context:

Beginning with Shorewall 4.5.1, Run-time Gateway Variables in the form of a percent sign ('%') followed by a logical interface name are also supported. These are expanded at run-time to the gateway through the named interface. For optional interfaces, if the interface is not usable at the time that the firewall starts, the nil address will be used (0.0.0.0 in IPv4 and :: in IPv6), resulting in no packets matching the rule. Run-time gateway variables may be used in the SOURCE and DEST columns of the following configuration files:

If there is no gateway out of the named interface, rules containing the intefaces's run-time gateway variable are omitted.

Beginning with Shorewall 5.1.5, Run-time Port Variables are supported. These variables have the format %{variable} and may appear any place that a port number or service name may appear. Like their address-variable counterparts above, Run-time Port Variables are most useful when Shorewall[6]-lite is being used.

Example using both Run-time Address and Run-time Port Variables:

/etc/shorewall/init:

     SERVER_PORT=4126
     SERVER_ADDRESS=192.0.44.12

/etc/shorewall/rules:

     ACCEPT         net            dmz:%{SERVER_ADDRESS}           tcp          %{SERVER_PORT}

Rather than assigning a numerical literal to SERVER_PORT in the init extension script as shown above, the variable could be assigned a dynamic value based on a database lookup.

      LOW_PORT=100
      HIGH_PORT=50

      ACCEPT    net     $FW      tcp      ${LOW_PORT}:${HIGH_PORT}

Action variables were introduced in Shorewall 4.4.16 and may be accessed within the body of an action.

Shorewall Variables were introduced in Shorewall 4.5.11. To insure uniqueness, these variables start with the character @; the name of the variable must be enclosed in {...} when the following character is alphanumeric or is an underscore ("_"). With the exception of @0 (or it's alias @chain), Shorewall variables may only be used within an action body.

Prior to Shorewall 4.5.13, Shorewall variables are read-only. Beginning with Shorewall 4.5.13, their values may be altered using the ?SET directive.

The Shorewall variables are:

Beginning with Shorewall 4.5.13, the values of @chain and @disposition are used to generated the --log-prefix in logging rules. When either is empty, the historical value is used to generate the --log-prefix.

Within an action body, if a parameter is omitted in a DEFAULTS statement, then the value of the corresponding action and Shorewall variables is '-', while if the parameter is specified as '-' in the parameter list, the value of the action/Shorewall variable is '', if it is expanded before the DEFAULTS statement.

Additionally, when an expression is evaluated, the value 0 evaluates as false, so '?IF @n' and '?IF $n' fail if the nth parameter is passed with value zero. To make testing of the presense of parameters more efficient and uniform, an new function has been added in Shorewall 5.0.7 for use in ?IF and ?ELSEIF:

where <variable> is an action or Shorewall variable.

'passed(@n)' and 'passed($n)' evaluate to true if the nth parameter is not empty and its contents are other than '-'. If '!' is present, the result is inverted.

In this simple form, the expression is evaluated by the compiler without having to invoke the (expensive) Perl exec() function. The 'passed' function may also be used in more complex expressions, but exec() will be invoked to evaluate those expressions.

Beginning with Shorewall 4.5.2, lines in configuration files may be conditionally included or omitted based on the setting of Shell variables.

The general form is:

?IF $variable

<lines to be included if $variable is non-empty and non-zero>

?ELSE

<lines to be omitted if $variable is non-empty and non-zero>

?ENDIF

The compiler predefines two special variables that may only be used in ?IF lines:

Unless variable is one of these pre-defined ones, it is searched for in the following places in the order listed.

If the variable is still not found:

If it is not found in any of those places, the variable is assumed to have a value of 0 (false) in Shorewall versions prior to 4.5.11. In 4.5.11 and later, it is assumed to have the value '' (an empty string, which also evaluates to false).

The setting in /etc/shorewall/params may be overridden at runtime, provided the setting in /etc/shorewall/params is done like this:

[ -n "${variable:=0}" ]

or like this:

[ -n "${variable}" ] || variable=0

Either of those will set variable to 0 if it is not set to a non-empty value in the environment. The setting can be overridden at runtime:

variable=1 shorewall restart -c # use -c to force recompilation if AUTOMAKE=Yes in /etc/shorewall/shorewall.conf

The ?ELSE may be omitted if there are no lines to be omitted.

The test may also be inverted using '!':

?IF ! $variable

<lines to be omitted if $variable is non-empty and non-zero>

?ELSE

<lines to be included if $variable is non-empty and non-zero>

?ENDIF

Conditional entries may be nested but the number of ?IFs must match the number of ?ENDs in any give file. INCLUDE directives are ignored in omitted lines.

?IF $variable1

<lines to be included if $variable1 is non-empty and non-zero>

   ?IF $variable2

<lines to be included if $variable1