<< Back to man.ChinaUnix.net

Compiled Firewall Programs 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”.

2006-06-17


Table of Contents

Overview
Restrictions
The "shorewall compile" command
Shorewall Lite (Added in version 3.2.0 RC 1)
Converting a system from Shorewall to Shorewall Lite
The /etc/shorewall/capabilities file and the shorecap program
Running compiled programs directly

Overview

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.

Restrictions

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.

  1. The detectnets interface option is not supported.

  2. DYNAMIC_ZONES=Yes in shorewall.conf is not supported.

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

    • The /etc/shorewall/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 it's 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=$(fiind_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 /etc/shorewall/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.

  4. 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/firewall and use the /sbin/shorewall program included with Shorewall Lite to control the firewall just as if the full Shorewall distribution was installed.

The "shorewall compile" command

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, the "detectnets" interface is not allowed but 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.conf are 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.

Shorewall Lite (Added in version 3.2.0 RC 1)

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.

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

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

    Note

    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.

  3. On the administrative system you create a separete 'configuration directory' for each firewall system. You copy the contents of /usr/share/shorewall/configfiles into each configuration directory.

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

    Shorewall Lite includes a very limited version of shorewall.conf (/etc/shorewall-lite/shorewall.conf). It includes the following options which have the same meaning as in a full Shorewall installation except as noted below:

    VERBOSITY
    LOGFILE
    LOGFORMAT — used by /sbin/shorewall for finding 'Shorewall' log messages. If LOGFORMAT was specified in the shorewall.conf file used at compile time on the administrative system, then the format of the messages themselves is defined by that value. If LOGFORMAT was not specified at compile time then the firewall script will use the value from /etc/shorewall-lite/shorewall.conf on the firewall system.
    IPTABLES — determines the iptables binary to be used by /sbin/shorewall. The compiled firewall script will use the IPTABLES specified in shorewall.conf at compile time on the administrative system, if any; if IPTABLES was not specified at compile time then the IPTABLES value from /etc/shorewall-lite/shorewall.conf on the firewall system will be used by the firewall script.
    PATH
    SHOREWALL_SHELL
    SUBSYSLOCK
    RESTOREFILE

    Edit the shorewall.conf file as required.

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

    1. modify the files in the corresponding configuration 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 configuration 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 configuration directory on the administrative system.

    2. cd <configuration directory>
      /sbin/shorewall load firewall

      The load command compiles a firewall script from the configuration files in the current working directory, 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

  6. If you later need to change the firewall's configuration, change the appropriate files in the firewall's configuration directory then:

    cd <configuration directory>
    /sbin/shorewall reload firewall

    The reload command compiles a firewall script from the configuration files in the current working directory, copies that file to the remote system via scp and restarts Shorewall Lite on the remote system via ssh.

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

Converting a system from Shorewall to Shorewall Lite

Converting a firewall system that is currently running Shorewall to run Shorewall Lite instead is straight-forward.

  1. On the administrative system, create a configuration directory for the firewall system.

  2. Copy the contents of /etc/shorewall/ from the firewall system to the configuration directory on the administrative system.

  3. On the firewall system:

    Be sure that the IP address of the administrative system is included in /etc/shorewall/routestopped.

    shorewall stop

    We recommend that you uninstall Shorewall at this point.

  4. Install Shorewall Lite on the firewall system.

    Modify /etc/shorewall-lite/shorewall.conf as needed.

    If you are running Debian or one of its derivatives like Ubuntu then edit /etc/default/shorewall-lite and set startup=1.

  5. On the firewall system:

    /usr/share/shorewall-lite/shorecap > capabilities
    scp capabilities <admin system>:<this system's config dir>
  6. 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 configuration 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/shorewall

    After editing:

    CONFIG_PATH=/usr/share/shorewall/configfiles:/usr/share/shorewall

    Changing CONFIG_PATH will ensure that subsequent compilations using the configuration directory will not include any files from /etc/shorewall.

    After having made the above changes to the firewall's configuration directory, execute the following commands:

    cd <configuration directory>
    /sbin/shorewall load <firewall system>
    

    Example (firewall's DNS name is 'gateway'):

    /sbin/shorewall load gateway

    The load command compiles a firewall script from the configuration files in the current working directory, copies that file to the remote system via scp and starts Shorewall Lite on the remote system via ssh.

  7. If you later need to change the firewall's configuration, change the appropriate files in the firewall's configuration directory then:

    cd <configuration directory>
    /sbin/shorewall reload firewall

    The reload command compiles a firewall script from the configuration files in the current working directory, copies that file to the remote system via scp and restarts Shorewall Lite on the remote system via ssh.

The /etc/shorewall/capabilities file and the shorecap program

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.

Running compiled programs directly

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 ] restart
<program> [ -q ] [ -v ] [ -n ] status
<program> [ -q ] [ -v ] [ -n ] version

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.