Configuration Files

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

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

Any 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 assumed to reside in /etc/shorewall or in an alternate configuration directory if one has been specified for the command.

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

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

Host addresses in Shorewall configuration files may be specified as either IP addresses or DNS Names.

DNS names in iptables rules aren't nearly as useful as they first appear. When a DNS name appears in a rule, the iptables utility resolves the name to one or more IP addresses and inserts those addresses into the rule. So changes in the DNS->IP address relationship that occur after the firewall has started have absolutely no effect on the firewall's ruleset.

If your firewall rules include DNS names then:

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

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

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 port number you can use either an integer or a service name from /etc/services.

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.

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:

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

Example:

Variables may be used anywhere in the other configuration files.

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:

One possible use of this feature is to compensate for recent Linux behavior in which the identity of network interfaces varies from boot to boot (what is eth0 after one boot may be eth1 after the next). SUSE™ users, for example, can take the following approach:

wookie:~ # lspci
0000:00:00.0 Host bridge: VIA Technologies, Inc. VT82C598 [Apollo MVP3] (rev 04)
0000:00:01.0 PCI bridge: VIA Technologies, Inc. VT82C598/694x [Apollo MVP3/Pro133x AGP]
0000:00:03.0 Ethernet controller: Intel Corporation 82557/8/9 [Ethernet Pro 100] (rev 01)
0000:00:04.0 Ethernet controller: Lite-On Communications Inc LNE100TX (rev 20)
0000:00:05.0 Ethernet controller: Digital Equipment Corporation DECchip 21142/43 (rev 41)
0000:00:14.0 ISA bridge: VIA Technologies, Inc. VT82C586/A/B PCI-to-ISA [Apollo VP] (rev 45)
0000:00:14.1 IDE interface: VIA Technologies, Inc. VT82C586A/B/VT82C686/A/B/VT823x/A/C PIPC Bus Master IDE (rev 06)
0000:00:14.2 USB Controller: VIA Technologies, Inc. VT82xxxxx UHCI USB 1.1 Controller (rev 02)
0000:00:14.3 Bridge: VIA Technologies, Inc. VT82C586B ACPI (rev 10)
0000:01:00.0 VGA compatible controller: ATI Technologies Inc 3D Rage LT Pro AGP-133 (rev dc)
wookie:~ #

If the firewall's external interface is the DECchip controller at 0000:00:05.0 and the internal interface is the Ethernet Pro 100 at 0000:00:03.0, then the following entries in /etc/shorewall/params will set EXT_IF and INT_IF to the names of these two controllers respectively:

EXT_IF=$(getcfg-interface bus-pci-0000:00:05.0)
INT_IF=$(getcfg-interface bus-pci-0000:00:03.0)

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.

      [root@gateway root]# ifconfig eth0
      eth0 Link encap:Ethernet HWaddr 02:00:08:E3:FA:55
      inet addr:206.124.146.176 Bcast:206.124.146.255 Mask:255.255.255.0
      UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
      RX packets:2398102 errors:0 dropped:0 overruns:0 frame:0
      TX packets:3044698 errors:0 dropped:0 overruns:0 carrier:0
      collisions:30394 txqueuelen:100
      RX bytes:419871805 (400.4 Mb) TX bytes:1659782221 (1582.8 Mb)
      Interrupt:11 Base address:0x1800

Because Shorewall uses colons as a separator for address fields, Shorewall requires MAC addresses to be written in another way. In Shorewall, MAC addresses begin with a tilde (“~”) and consist of 6 hex numbers separated by hyphens. In Shorewall, the MAC address in the example above would be written ~02-00-08-E3-FA-55.

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

The try command allows you to attempt to restart using an alternate configuration and if an error occurs to automatically restart the standard configuration.

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.