Operating Shorewall and Shorewall Lite

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

2007/10/06

Table of Contents

/sbin/shorewall and /sbin/shorewall-lite
Starting, Stopping and Clearing
/etc/init.d/shorewall and /etc/init.d/shorewall-lite
Tracing Command Execution and other Debugging Aids
Having Shorewall Start Automatically at Boot Time
Saving a Working Configuration for Error Recovery and Fast Startup
Additional Configuration Directories
Alternate Configuration Directories
Commands
Shorewall State Diagram

Caution

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.

/sbin/shorewall and /sbin/shorewall-lite

/sbin/shorewall is the program that you use to interact with Shorewall. Normally the root user's PATH includes /sbin and the program can be run from a shell prompt by simply typing shorewall followed by a command.

Warning

In some releases of KDE, the default configuration of the konsole program is brain dead with respect to the "Root Console". It executes the command "su" where it should execute "su -"; the latter will cause a login shell to be created which will in turn set PATH properly. You can correct this problem as follows:

Click on "Settings" on the toolbar and select "Configure Konsole"
Select the "Session" tab.
Click on "Root Console"
Change the Execute command from "su" to "su -"
Click on "Save Session"
Click on "Ok"

To see a list of supported commands, use the help command:

shorewall help

To get further information about a particular command, use the man command:

man shorewall

The program /sbin/shorewall-lite performs a similar role with Shorewall-lite.

For a more complete description of the files and directories involved in Shorewall and Shorewall-lite, see the Shorewall Anatomy article.

Starting, Stopping and Clearing

As explained in the Introduction, Shorewall is not something that runs all of the time in your system. Nevertheless, for integrating Shorewall into your initialization scripts it is useful to speak of starting Shorewall and stopping Shorewall.

Shorewall is started using the shorewall start command. Once the start command completes successfully, Netfilter is configured as described in your Shorewall configuration files. If there is an error during shorewall start, then if you have a saved configuration then that configuration is restored. Otherwise, an implicit shorewall stop is executed.
Important
Beginning with Shorewall 3.1, shorewall start is implemented as a compile and go; that is, the configuration is compiled and if there are no compilation errors then the resulting compiled script is executed. If there are compilation errors, the command is aborted and the state of the firewall is not altered.
Shorewall is stopped using the shorewall stop command.
Important
The shorewall stop command does not remove all netfilter rules and open your firewall for all traffic to pass. It rather places your firewall in a safe state defined by the contents of your /etc/shorewall/routestopped file and the setting of ADMINISABSENTMINDED in /etc/shorewall/shorewall.conf.
If you want to remove all Netfilter rules and open your firewall for all traffic to pass, use the shorewall clear command.
If you change your configuration and want to install the changes, use the shorewall restart command.

For additional information, see the Shorewall State Diagram section.

/etc/init.d/shorewall and /etc/init.d/shorewall-lite

Because of the different requirements of distribution packaging systems, the behavior of /etc/init.d/shorewall and /etc/init.d/shorewall-lite is not consistent between distributions. As an example, when using the distributon Shorewall packages on Debian™ and Ubuntu™ systems, running /etc/init.d/shorewall stop will actually execute the command /sbin/shorewall clear rather than /sbin/shorewall stop! So don't expect the meaning of start, stop, restart, etc. to be consistent between /sbin/shorewall (or /sbin/shorewall-lite) and your init scripts unless you got your Shorewall package from shorewall.net.

Tracing Command Execution and other Debugging Aids

If you include the word trace as the first parameter to an /sbin/shorewall command that transfers control to /usr/share/shorewall/firewall, execution of the latter program will be traced to STDERR.

Example 1. Tracing shorewall start

To trace the execution of shorewall start and write the trace to the file /tmp/trace, you would enter:

shorewall trace start 2> /tmp/trace

Note

If you are running Shorewall-perl, the trace keyword does not result in a trace of the execution of the Shorewall-perl compiler. It rather causes additional diagnostic information to be included in warning and error messages generated by the compiler.

Beginning with Shorewall 4.0.5, you may also include the word debug as the first argument to the /sbin/shorewall and /sbin/shorewall-lite commands.

shorewall debug restart

In most cases, debug is a synonym for trace. The exceptions are:

debug is ignored by the Shorewall-perl compiler.
debug causes altered behavior of scripts generated by the Shorewall-perl compiler. These scripts normally use iptables-restore to install the Netfilter ruleset but with debug, the commands normally passed to iptables-restore in its input file are passed individually to iptables. This is a diagnostic aid which allows identifying the individual command that is causing iptables-restore to fail; it should be used when iptables-restore fails when executing a COMMIT command.

Warning

The debug feature is strictly for problem analysis. When debug is used:

The firewall is made 'wide open' before the rules are applied.
The routestopped file is not consulted.
The rules are applied in the canonical iptables-restore order. So if you need critical hosts to be always available during start/restart, you may not be able to use debug.

Having Shorewall Start Automatically at Boot Time

The .rpm, .deb and .tgz all try to configure your startup scripts so that Shorewall will start automatically at boot time. If you are using the install.sh script from the .tgz and it cannot determine how to configure automatic startup, a message to that effect will be displayed. You will need to consult your distribution's documentation to see how to integrate the /etc/init.d/shorewall script into the distribution's startup mechanism.

Caution

Shorewall startup is disabled by default. Once you have configured your firewall, you can enable startup by editing /etc/shorewall/shorewall.conf and setting STARTUP_ENABLED=Yes.. Note: Users of the .deb package must rather edit /etc/default/shorewall and set “startup=1”.
If you use dialup or some flavor of PPP where your IP address can change arbitrarily, you may want to start the firewall in your /etc/ppp/ip-up.local script. I recommend just placing “/sbin/shorewall restart” in that script.

Saving a Working Configuration for Error Recovery and Fast Startup

Once you have Shorewall working the way that you want it to, you can use shorewall save to save the commands necessary to recreate that configuration in a restore script.

In its simplest form, the save command is just:

shorewall save

That command creates the default restore script, /var/lib/shorewall/restore. The default may be changed using the RESTOREFILE option in /etc/shorewall/shorewall.conf. A different file name may also be specified in the save command:

shorewall save <filename>

Where <filename> is a simple file name (no slashes).

Once created, the default restore script serves several useful purposes:

If you change your configuration and there is an error when you try to restart Shorewall, the restore script will be run to restore your firewall to working order.
Bootup is faster (although with Shorewall-perl, the difference is minimal). The -f option of the start command (e.g., shorewall -f start) causes Shorewall to look for the default restore script and if it exists, the script is run. When using Shorewall-shell, this is much faster than starting Shorewall using the normal mechanism of reading the configuration files and running iptables dozens or even hundreds of times.
Under Shorewall versions < 4.0.0, /etc/init.d/shorewall (/etc/rc.d/rc.firewall) uses the -f option when it is processing a request to start Shorewall. Beginning with Shorewall 4.0.0, the default is to not use -f. If you wish to change the default, you must set the OPTIONS shell variable in either /etc/default/shorewall or /etc/sysconfig/shorewall (if your distribution provides neither of these files, you must create one or the other). For example, to continue to use -f under Shorewall 4.0.0 and later, you would have:
```
OPTIONS="-f"
```
The shorewall restore command can be used at any time to quickly configure the firewall.
```
shorewall restore [ <filename> ]
```
If no <filename> is given, the default restore script is used. Otherwise, the script /var/lib/shorewall/<filename> is used.

The ability to have multiple restore scripts means that you can save different Shorewall firewall configurations and switch between them quickly using the restore command.

Restore scripts may be removed using the shorewall forget command:

shorewall forget [ <filename> ]

If no <filename> is given, the default restore script is removed. Otherwise, /var/lib/shorewall/<filename> is removed (of course, you can also use the Linux rm command from the shell prompt to remove these files).

Additional Configuration Directories

The CONFIG_PATH setting in /etc/shorewall/shorewall.conf determines where Shorewall looks for configuration files. The default setting is CONFIG_PATH=/etc/shorewall:/usr/share/shorewall which means that /etc/shorewall is searched first and if the file is not found then /usr/share/shorewall is searched. You can change the value of CONFIG_PATH to cause additional directories to be searched but CONFIG_PATH should always include both /etc/shorewall and /usr/share/shorewall.

When an alternate configuration directory is specified as described in the next section, that directory is searched before those directories listed in CONFIG_PATH.

Example - Search /etc/shorewall, /etc/shorewall/actiondir and /usr/share/shorewall in that order:

CONFIG_PATH=/etc/shorewall:/etc/shorewall/actiondir:/usr/share/shorewall

The above is the setting that I once used to allow me to place all of my user-defined 'action.' files in /etc/shorewall/actiondir.

Alternate Configuration Directories

As explained above, Shorewall normally looks for configuration files in the directories specified by the CONFIG_PATH option in /etc/shorewall/shorewall.conf. The shorewall start, shorewall restart, shorewall check, and shorewall try commands allow you to specify an additional directory for Shorewall to check before looking in the directories listed in CONFIG_PATH.

     shorewall {start|restart|check} <configuration-directory>
     shorewall try <configuration-directory> [ <timeout> ]

If a <configuration-directory> is specified, each time that Shorewall is going to read a file, it will first look in the <configuration-directory> . If the file is present in the <configuration-directory>, that file will be used; otherwise, the directories in the CONFIG_PATH will be searched. When changing the configuration of a production firewall, I recommend the following:

If you haven't saved the current working configuration, do so using shorewall save.
mkdir /etc/test
cd /etc/test
<copy any files that you need to change from /etc/shorewall to . and change them here>
shorewall check ./
<correct any errors found by check and check again>
shorewall restart ./

If the restart fails, your configuration will be restored to its state at the last shorewall save.

When the new configuration works then just:

cp -f * /etc/shorewall
cd
rm -rf /etc/test
shorewall save

Important

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.

Commands

The general form of a command in Shorewall 4.0 is:

shorewall [ <options> ] <command> [ <command options> ] [ <argument> ... ]
Available options are:
-c <directory>
Specifies an alternate configuration directory. Use of this option is deprecated.
-f
Specifies fast restart. See the start command below.
-n
Prevents the command from changing the firewall system's routing configuration.
-q
Reduces the verbosity level (see VERBOSITY setting in shorewall.conf). May be repeated (e.g., "-qq") with each instance reducing the verbosity level by one.
-v
Increases the verbosity level (see VERBOSITY setting in shorewall.conf). May be repeated (e.g., "-qq") with each instance increasing the verbosity level by one.
-x
Causes all iptables -L commands to display actual packet and byte counts.
-t
All progress messages are timestamped with the date and time.
In addition, the -q and -v options may be repeated to make the output less or more verbose respectively. The default level of verbosity is determined by the setting of the VERBOSITY option in /etc/shorewall/shorewall.conf.
For Shorewall Lite, the general command form is:
shorewall-lite [ <options> ] <command> [ <command options> ] [ <argument> ... ]
where the options are the same as with Shorewall.
The complete documentation for each command may be found in the shorewall and shorewall-lite man pages.

Shorewall State Diagram

The Shorewall State Diargram is depicted below.

/sbin/shorewall Command	Resulting /usr/share/shorewall/firewall Command	Effect if the Command Succeeds
shorewall start	firewall start	The system filters packets based on your current Shorewall Configuration
shorewall stop	firewall stop	Only traffic to/from hosts listed in /etc/shorewall/hosts is passed to/from/through the firewall. If ADMINISABSENTMINDED=Yes in /etc/shorewall/shorewall.conf then in addition, all existing connections are retained and all connection requests from the firewall are accepted.
shorewall restart	firewall restart	Logically equivalent to “firewall stop;firewall start”
shorewall add	firewall add	Adds a host or subnet to a dynamic zone
shorewall delete	firewall delete	Deletes a host or subnet from a dynamic zone
shorewall refresh	firewall refresh	Reloads rules dealing with static blacklisting, traffic control and ECN.
shorewall reset	firewall reset	Resets traffic counters
shorewall clear	firewall clear	Removes all Shorewall rules, chains, addresses, routes and ARP entries.
shorewall try	firewall -c <new configuration> restart If unsuccessful then firewall start (standard configuration) If timeout then firewall restart (standard configuration)

The only time that a program other than /usr/share/shorewall[-lite[/firewall performs a state transition itself is when the shorewall[-lite] restore command is executed. In that case, the /var/lib/shorewall[-lite]/restore program sets the state to "Started".

With any command that involves compilation, there is no state transition while the compiler is running. If compilation fails, the state remains unchanged.

Also, shorewall start and shorewall restart involve compilation followed by execution of the compiled script. So it is the compiled script that performs the state transition in these commands rather than /usr/share/shorewall/firewall.

The compiled script is placed in /var/lib/shorewall and is named either .start or .restart depending on the command.