Copyright © 2006-2007 Thomas M. 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/07/19
Table of Contents
Beginning with Shorewall version 3.1, Shorewall has the capability to compile a Shorewall configuration and produce a runnable firewall program script. The script is a complete program which can be placed on a system with Shorewall Lite installed and can serve as the firewall creation script for that system.
While compiled Shorewall programs are useful in many cases, there are some important restrictions that you should be aware of before attempting to use them.
The detectnets interface option is not supported.
DYNAMIC_ZONES=Yes in shorewall.conf is
not supported.
All extension scripts used are copied into the program. The ramifications of this are:
If you update an extension script, the compiled program will not use the updated script.
With Shorewall 3.2.0 through 3.2.8, the
params extension script is executed at
compile time as well as at run time.
Running the script at compile time allows variable expansion (expanding $variable to its defined value) of variables used in Shorewall configuration files to occur at compile time. Running it at run-time allows your extension scripts to use the variables that it creates. BUT -- for any given variable, the value at compile time may be different from the value at run-time unless you only assign constant values.
For example, if you have:
EXT_IP=$(find_first_interface_address eth0)
in /etc/shorewall/params then all
occurrences of $EXT_IP in Shorewall configuration files will be
replaced with eth0's IP address when the program is being
compiled. On the other hand, if you use $EXT_IP in your start
script, the value will be the IP address of eth0 when the
program is run.
Bottom line: You probably want to use only constant values
for variables set in
/etc/shorewall/params.
Beginning with Shorewall 3.2.9 and 3.4.0 RC2, the
params file is only processed at compile
time if you set EXPORTPARAMS=No in
shorewall.conf. For run-time setting of
shell variables, use the init extension
script. Although the default setting is EXPORTPARAMS=Yes for
compatibility, the recommended setting is
EXPORTPARAMS=No.
If the params file 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.
You must install Shorewall Lite on the system where you want to run the script. You then install the compiled program in /usr/share/shorewall-lite/firewall and use the /sbin/shorewall-lite program included with Shorewall Lite to control the firewall just as if the full Shorewall distribution was installed.
A compiled script is produced using the compile command:
shorewall compile [ -e ] [ <directory name> ] <path name>
where
- -e
Indicates that the program is to be "exported" to another system. When this flag is set, neither the "detectnets" interface option nor DYNAMIC_ZONES=Yes in shorewall.conf are allowed. The created program may be run on a system that has only Shorewall Lite installed
When this flag is given, Shorewall does not probe the current system to determine the kernel/iptables features that it supports. It rather reads those capabilities from
/etc/shorewall/capabilities. See below for details.- <directory name>
specifies a directory to be searched for configuration files before those directories listed in the CONFIG_PATH variable in
shorewall.conf.When -e <directory-name> is included, only the SHOREWALL_SHELL and VERBOSITY settings from
/etc/shorewall/shorewall.confare used and these apply only to the compiler itself. The settings used by the compiled firewall script are determined by the contents of<directory name>/shorewall.conf.- <path name>
specifies the name of the script to be created.
The following information applies to Shorewall 3.2.2 and later. Users running versions of Shorewall and Shorewall Lite earlier than 3.2.2 are urged to upgrade.
Shorewall Lite is a companion product to Shorewall and is designed to allow you to maintain all Shorewall configuration information on a single system within your network.
You install the full Shorewall release on one system within your network. You need not configure Shorewall there and you may totally disable startup of Shorewall in your init scripts. For ease of reference, we call this system the 'administrative system'.
If you want to be able to allow non-root users to manage
remote filewall systems, then the file
/etc/shorewall/shorewall.conf must be readable
by all users on the administrative system. Not all packages secure
the file that way and you may have to change the file permissions
yourself. /sbin/shorewall uses the SHOREWALL_SHELL setting from
/etc/shorewall/shorewall.conf to determine the
shell to use when compiling programs and it uses the VERBOSITY
setting for determining how much output the compiler generates. All
other settings are taken from the shorewall.conf
file in the remote systems export
directory (see below).
On each system where you wish to run a Shorewall-generated firewall, you install Shorewall Lite. For ease of reference, we will call these systems the 'firewall systems'.
The firewall systems do NOT need to have the full Shorewall product installed but rather only the Shorewall Lite product. Shorewall and Shorewall LIte may be installed on the same system but that isn't encouraged.
On the administrative system you create a separate 'export directory' for each firewall system. You copy the contents of /usr/share/shorewall/configfiles into each export directory.
If you are running Shorewall 3.2.5 or earlier, then on each firewall system, you run:
/usr/share/shorewall-lite/shorecap > capabilities scp capabilities <admin system>:<this system's config dir>
If you are running Debian or one of its derivatives like Ubuntu then edit /etc/default/shorewall-lite and set startup=1.
On the administrative system, for each firewall system you do the following (this may be done by a non-root user who has root ssh access to the firewall system):
modify the files in the corresponding export directory
appropriately. It's a good idea to include the IP address of the
administrative system in the routestopped
file.
It is important to understand that with Shorewall Lite, the
firewall's export directory on the administrative system acts as
/etc/shorewall for that
firewall. So when the Shorewall documentation gives instructions
for placing entries in files in the firewall's /etc/shorewall, when using Shorewall
Lite you make those changes in the firewall's export directory on
the administrative system.
The CONFIG_PATH variable is treated as follows:
The value of CONFIG_PATH in
/etc/shorewall/shorewall.conf is ignored
when compiling for export (the -e option in given) and when
the load or reload
command is being executed (see below).
The value of CONFIG_PATH in the
shorewall.conf file in the export
directory is used to search for configuration files during
compilation of that configuration.
The value of CONFIG_PATH used when the script is run on the firewall system is "/etc/shorewall-lite:/usr/share/shorewall-lite".
If you are running Shorewall 3.2.5 or earlier then:
cd <export directory> /sbin/shorewall load firewallThe load command compiles a firewall script from the configuration files in the current working directory (using shorewall compile -e), copies that file to the remote system via scp and starts Shorewall Lite on the remote system via ssh.
Example (firewall's DNS name is 'gateway'):
/sbin/shorewall load gateway
If you are running Shorewall 3.2.6 or later then:
cd <export directory> /sbin/shorewall load -c firewallThe load command compiles a firewall script from the configuration files in the current working directory (using shorewall compile -e), copies that file to the remote system via scp and starts Shorewall Lite on the remote system via ssh. The -c option causes the capabilities of the remote system to be generated and copied to a file named capabilities in the export directory. See below.
Example (firewall's DNS name is 'gateway'):
/sbin/shorewall load -c gateway
If you later need to change the firewall's configuration, change the appropriate files in the firewall's export directory then:
cd <export directory> /sbin/shorewall reload firewall
The reload command compiles a firewall script from the configuration files in the current working directory (using shorewall compile -e), copies that file to the remote system via scp and restarts Shorewall Lite on the remote system via ssh. Note: In Shorewall 3.2.6 and later, the reload command also supports the '-c' option.
I personally place a Makefile in each
export directory as follows:
# Shorewall Packet Filtering Firewall Export Directory Makefile - V3.3 # # This program is under GPL [http://www.gnu.org/copyleft/gpl.htm] # # (c) 2006 - Tom Eastep ([email protected]) # # Shorewall documentation is available at http://www.shorewall.net # # This program is free software; you can redistribute it and/or modify # it under the terms of Version 2 of the GNU General Public License # as published by the Free Software Foundation. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program; if not, write to the Free Software # Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA ################################################################################ # Place this file in each export directory. Modify each copy to set HOST # to the name of the remote firewall corresponding to the directory. # # To make the 'firewall' script, type "make". # # Once the script is compiling correctly, you can install it by # typing "make install". # ################################################################################ # V A R I A B L E S # # Files in the export directory on which the firewall script does not depend # IGNOREFILES = firewall% Makefile% trace% %~ # # Remote Firewall system # HOST = gateway # # Save some typing # LITEDIR = /var/lib/shorewall-lite # # Set this if the remote system has a non-standard modules directory # MODULESDIR= # # Default target is the firewall script # ################################################################################ # T A R G E T S # all: firewall # # Only generate the capabilities file if it doesn't already exist # capabilities: ssh root@$(HOST) "MODULESDIR=$(MODULESDIR) /usr/share/shorewall-lite/shorecap > $(LITEDIR)/capabilities" scp root@$(HOST):$(LITEDIR)/capabilities . # # Compile the firewall script. Using the 'wildcard' function causes "*" to be expanded so that # 'filter-out' will be presented with the list of files in this directory rather than "*" # firewall: $(filter-out $(IGNOREFILES) capabilities , $(wildcard *) ) capabilities shorewall compile -e . firewall # # Only reload on demand. # install: firewall scp firewall firewall.conf root@$(HOST):$(LITEDIR) ssh root@$(HOST) "/sbin/shorewall-lite restart" # # Save running configuration # save: ssh root@$(HOST) "/sbin/shorewall-lite save" # # Remove generated files # clean: rm -f capabilities firewall firewall.conf reload
That way, after I've changed the configuration, I can simply type make or make install.
The above Makefile is available at http://www.shorewall.net/pub/shorewall/contrib/Shorewall-lite/
I omit trace% because I often trace compiler execution while I'm debugging new versions of Shorewall.
There is a shorewall-lite.conf file installed
as part of Shorewall Lite
(/etc/shorewall-lite/shorewall-lite.conf). You can
use that file on the firewall system to override some of the settings from
the shorewall.conf file in the export directory.
In Shorewall 3.2.*, the name of the file was
/etc/shorewall-lite/shorewall.conf -- it was
changed to shorewall-lite.conf in version
3.4.0.
Settings that you can override are:
VERBOSITY LOGFILE LOGFORMAT IPTABLES PATH SHOREWALL_SHELL SUBSYSLOCK RESTOREFILE
You will normally not need to touch
/etc/shorewall-lite/shorewall-lite.conf.
The /sbin/shorewall-lite program included with
Shorewall Lite supports the same set of commands as the
/sbin/shorewall program in a full Shorewall
installation with the following exceptions:
add compile delete refresh reload try safe-start safe-restart show actions show macros
On systems with only Shorewall Lite installed, I recommend that you
create a symbolic link /sbin/shorewall and point it
at /sbin/shorewall-lite. That way, you can use
shorewall as the command regardless of which product is
installed.
ln -sf shorewall-lite /sbin/shorewallConverting a firewall system that is currently running Shorewall to run Shorewall Lite instead is straight-forward.
On the administrative system, create an export directory for the firewall system.
Copy the contents of /etc/shorewall/ from the firewall
system to the export directory on the administrative system.
On the firewall system:
Be sure that the IP address of the administrative system is
included in /etc/shorewall/routestopped.
shorewall stopWe recommend that you uninstall Shorewall at this point.
Install Shorewall Lite on the firewall system.
If you are running Debian or one of its derivatives like Ubuntu then edit /etc/default/shorewall-lite and set startup=1.
If you are running Shorewall 3.2.5 or earlier, then on the firewall system:
/usr/share/shorewall-lite/shorecap > capabilities scp capabilities <admin system>:<this system's config dir>
On the administrative system:
It's a good idea to include the IP address of the
administrative system in the firewall system's
routestopped file.
Also, edit the shorewall.conf file in the firewall's export
directory and change the CONFIG_PATH setting to remove /etc/shorewall. You can replace it with
/usr/share/shorewall/configfiles if you
like.
Example:
Before editing:
CONFIG_PATH=/etc/shorewall:/usr/share/shorewallAfter editing:
CONFIG_PATH=/usr/share/shorewall/configfiles:/usr/share/shorewall
Changing CONFIG_PATH will ensure that subsequent compilations
using the export directory will not include any files from /etc/shorewall.
If you set variables in the params file, there are a couple of issues:
With Shorewall 3.2.0 through 3.2.8, the
params extension script is executed at
compile time as well as at run time.
Running the script at compile time allows variable expansion (expanding $variable to its defined value) of variables used in Shorewall configuration files to occur at compile time. Running it at run-time allows your extension scripts to use the variables that it creates. BUT -- for any given variable, the value at compile time may be different from the value at run-time unless you only assign constant values.
For example, if you have:
EXT_IP=$(find_first_interface_address eth0)
in /etc/shorewall/params then all
occurrences of $EXT_IP in Shorewall configuration files will be
replaced with eth0's IP address when the program is being
compiled. On the other hand, if you use $EXT_IP in your start
script, the value will be the IP address of eth0 when the
program is run.
Bottom line: You probably want to use only constant values
for variables set in /etc/shorewall/params
or upgrade to Shorewall 3.2.9 or later (3.4.0 RC2 or
later).
Beginning with Shorewall 3.2.9 and 3.4.0 RC2, the
params file is only processed at compile
time if you set EXPORTPARAMS=No in
shorewall.conf. For run-time setting of
shell variables, use the init extension
script.
If the params file 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.
After having made the above changes to the firewall's export directory, execute the following commands.
For Shorewall version 3.2.5 and earlier:
cd <export directory> /sbin/shorewall load <firewall system>Example (firewall's DNS name is 'gateway'):
/sbin/shorewall load gateway
For Shorewall versions 3.2.6 and later:
cd <export directory> /sbin/shorewall load -c <firewall system>Example (firewall's DNS name is 'gateway'):
/sbin/shorewall load -c gateway
The load command compiles a firewall script from the configuration files in the current working directory (using shorewall compile -e), copies that file to the remote system via scp and starts Shorewall Lite on the remote system via ssh.
If you later need to change the firewall's configuration, change the appropriate files in the firewall's export directory then:
cd <export directory> /sbin/shorewall reload firewall
The reload command compiles a firewall script from the configuration files in the current working directory (using shorewall compile -e), copies that file to the remote system via scp and restarts Shorewall Lite on the remote system via ssh.
If the kernel/iptables configuration on the firewall later changes and you need to create a new capabilities file, do the following:
/usr/share/shorewall-lite/shorecap > capabilities scp capabilities <admin system>:<this system's config dir>
Or, if you are running Shorewall 3.2.6 or later, simply use the -c option the next time that you use the reload command.
As mentioned above, the /etc/shorewall/capabilities file specifies that kernel/iptables capabilities of the target system. Here is a sample file:
NAT_ENABLED=Yes # NAT MANGLE_ENABLED=Yes # Packet Mangling MULTIPORT=Yes # Multi-port Match XMULTIPORT=Yes # Extended Multi-port Match CONNTRACK_MATCH=Yes # Connection Tracking Match USEPKTTYPE= # Packet Type Match POLICY_MATCH=Yes # Policy Match PHYSDEV_MATCH=Yes # Physdev Match LENGTH_MATCH=Yes # Packet Length Match IPRANGE_MATCH=Yes # IP range Match RECENT_MATCH=Yes # Recent Match OWNER_MATCH=Yes # Owner match IPSET_MATCH= # Ipset Match CONNMARK=Yes # CONNMARK Target XCONNMARK=Yes # Extended CONNMARK Target CONNMARK_MATCH=Yes # Connmark Match XCONNMARK_MATCH=Yes # Extended Connmark Match RAW_TABLE=Yes # Raw Table IPP2P_MATCH= # IPP2P Match CLASSIFY_TARGET=Yes # CLASSIFY Target ENHANCED_REJECT=Yes # Extended REJECT KLUDGEFREE= # iptables accepts multiple "-m iprange" or "-m physdev" in a single command MARK=Yes # MARK Target Support XMARK=YES # Extended MARK Target Support MANGLE_FORWARD # Mangle table has FORWARD chain
As you can see, the file contains a simple list of shell variable assignments — the variables correspond to the capabilities listed by the shorewall show capabilities command and they appear in the same order as the output of that command.
To aid in creating this file, Shorewall Lite includes a
shorecap program. The program is installed in the
/usr/share/shorewall-lite/ directory and may be run
as follows:
[ IPTABLES=<iptables binary> ] [ MODULESDIR=<kernel modules directory> ] /usr/share/shorewall-lite/shorecap > capabilities
The IPTABLES and MODULESDIR options have their usual Shorewall default values.
The capabilities file may then be copied to a
system with Shorewall installed and used when compiling firewall programs
to run on the remote system.
Beginning with Shorewall Lite version 3.2.2, the capabilities file
may also be creating using
/sbin/shorewall-lite:
shorewall-lite show -f capabilities > capabilities
Note that unlike the shorecap program, the show capabilities command shows the kernel's current capabilities; it does not attempt to load additional kernel modules.
Compiled firewall programs are complete programs that support the following run-line commands:
<program> [ -q ] [ -v ] [ -n ] start <program> [ -q ] [ -v ] [ -n ] stop <program> [ -q ] [ -v ] [ -n ] clear <program> [ -q ] [ -v ] [ -n ] refresh <program> [ -q ] [ -v ] [ -n ] reset <program> [ -q ] [ -v ] [ -n ] restart <program> [ -q ] [ -v ] [ -n ] status <program> [ -q ] [ -v ] [ -n ] version
The refresh command was added in Shorewall 3.2.3.
The options have their same meaning is when they are passed to
/sbin/shorewall itself. The default VERBOSITY level
is the level specified in the shorewall.conf file used when then program
was compiled.