Shorewall Version 4

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

2008/06/24

Table of Contents

Introduction
Installing Shorewall Version 4
Prerequisites for using the Shorewall Version 4 Perl-based Compiler
Incompatibilities Introduced in the Shorewall Version 4 Perl-based Compiler
Package Compatibility Matrix
Compiler Selection

Introduction

Shorewall version 4 represents a substantial shift in direction for Shorewall. Up to now

Shorewall has been written entirely in Bourne Shell.
Shorewall has run the iptables utility to add each Netfilter rule.

Shorewall version 4 offers you a choice. You can continue to use the existing shell-based implementation or you can use a new implementation of the Shorewall compiler written in the Perl programming language. The new compiler:

has a small disk footprint
is very fast.
generates a firewall script that uses iptables-restore; so the script is very fast.
generates better and more consistent error messages.
does a much more thorough job of checking the configuration to avoid run-time errors.

Both compilers may be installed on your system and you can use whichever one suits you in a particular case.

Installing Shorewall Version 4

Shorewall 4 contains four packages:

Shorewall-shell - the old shell-based compiler and related components.
Shorewall-perl - the new Perl-based compiler.
Shorewall-common - the part of Shorewall common to both compilers.
Shorewall-lite- same as the 3.4 version of Shorewall Lite. Can run scripts generated by either Shorewall-perl or Shorewall-shell.

If you upgrade to Shorewall Version 4, you must install Shorewall-shell and/or Shorewall-perl; in fact, if you are using the tarball for your installation, you must install Shorewall-shell and/or Shorewall-perl before you upgrade Shorewall. See the upgrade issues for details.

Prerequisites for using the Shorewall Version 4 Perl-based Compiler

Perl (I use Perl 5.8.8 but other 5.8 versions should work fine)
Perl Cwd Module
Perl File::Basename Module
Perl File::Temp Module
Perl Getopt::Long Module
Perl Carp Module
Perl FindBin Module (Shorewall 4.0.3 and later)

Incompatibilities Introduced in the Shorewall Version 4 Perl-based Compiler

The Shorewall-perl compiler is not 100% compatible with the Shorewall-shell version. See this document for details.

Package Compatibility Matrix

The following table indicates which versions of the compilers are supported by each version of Shorewall-common.

Package	Compatible With
Shorewall-common 4.0.0-RC1	Shorewall-shell 4.0.0-RC1	Shorewall-perl 4.0.0-RC1
Shorewall-common 4.0.0-RC2	Shorewall-shell 4.0.0-RC1	Shorewall-perl 4.0.0-RC1
Shorewall-common 4.0.0-RC2	Shorewall-shell 4.0.0-RC2	Shorewall-perl 4.0.0-RC2
Shorewall-common 4.0.0	Shorewall-shell 4.0.0 - 4.0.3	Shorewall-perl 4.0.0 - 4.0.2
Shorewall-common 4.0.1	Shorewall-shell 4.0.0 - 4.0.3	Shorewall-perl 4.0.0 - 4.0.1
Shorewall-common 4.0.2^[a]	Shorewall-shell 4.0.0 - 4.0.3	Shorewall-perl 4.0.0 - 4.0.2
Shorewall-common 4.0.3	Shorewall-shell 4.0.0 - 4.0.3	Shorewall-perl 4.0.0 - 4.0.3^[b]
Shorewall-common 4.0.4	Shorewall-shell 4.0.0 - 4.0.4	Shorewall-perl 4.0.0 - 4.0.4^[c]
Shorewall-common 4.0.5	Shorewall-shell 4.0.5	Shorewall-perl 4.0.5^[d]
Shorewall-common 4.0.6	Shorewall-shell 4.0.5 - 4.0.6	Shorewall-perl 4.0.5 - 4.0.6^[e]
Shorewall-common 4.0.7	Shorewall-shell 4.0.5 - 4.0.9	Shorewall-perl 4.0.5 - 4.0.9^[f]
Shorewall-common 4.0.8	Shorewall-shell 4.0.5 - 4.0.9	Shorewall-perl 4.0.5 - 4.0.9^[g]
Shorewall-common 4.0.9-4.0.12	Shorewall-shell 4.0.5 - 4.0.12	Shorewall-perl 4.0.5 - 4.0.12^[h]
^[a]Shorewall-common/lib.base should have patch-common-4.0.2-1.diff applied. ^[b]Shorewall-perl 4.0.3 requires Shorewall-common 4.0.3 if capabilities files are to be used. Shorewall-perl 4.0.3 also requires Shorewall-lite 4.0.3. ^[c]Shorewall-perl 4.0.4 requires Shorewall-common 4.0.3 or later if capabilities files are to be used. Shorewall-perl 4.0.4 also requires Shorewall-lite 4.0.3 or later. ^[d]Shorewall-perl 4.0.5 also requires Shorewall-lite 4.0.5. ^[e]Shorewall-perl 4.0.6 also requires Shorewall-lite 4.0.6. ^[f]Shorewall-perl 4.0.6 and later require Shorewall-lite 4.0.6 or later ^[g]Shorewall-perl 4.0.6 and later require Shorewall-lite 4.0.6 or later ^[h]Shorewall-perl 4.0.6 and later require Shorewall-lite 4.0.6 or later

Compiler Selection

If you only install one compiler, then that compiler will be used.

If you install both compilers, then the compiler actually used depends on the SHOREWALL_COMPILER setting in shorewall.conf.

The value of this new option can be either 'perl' or 'shell'.

If you add 'SHOREWALL_COMPILER=perl' to /etc/shorewall/shorewall.conf then by default, the new compiler will be used on the system. If you add it to shorewall.conf in a separate directory (such as a Shorewall-lite export directory) then the new compiler will only be used when you compile from that directory.

If you only install one compiler, it is suggested that you do not set SHOREWALL_COMPILER.

You can select the compiler to use on the command line using the 'C option:

'-C shell' means use the shell compiler

'-C perl' means use the perl compiler

The -C option overrides the setting in shorewall.conf.

Example:

shorewall restart -C perl

When the Shorewall-perl compiler has been selected, the params file is processed using the -a option which causes all variables set within the file to be exported automatically by the shell. The Shorewall-perl compiler uses the current environmental variables to perform variable expansion within the other Shorewall configuration files.