shorewall_code/contrib/shoregen/README

Shoreline Firewall configuration generator
(c) Copyright 2004-2006 Paul D. Gear <paul@gear.dyndns.org>

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    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., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA


SHOREWALL

The quick plug:

  - Shorewall is the only firewall i trust.

The IT Manager plug:

  - Shorewall is a policy-driven firewall which lets you think about your
    firewall at a higher level than iptables commands.

The hard sell to you crazy people still maintaining manual firewall scripts:

  - Shorewall is a wrapper around the kernel iptables, so your existing
    Linux firewall skills transfer.  I converted from a 900-plus-line
    ipchains shell script to around 50 lines of shorewall configuration in
    less than 4 hours, with no prior experience.


ISSUES

  - I'm paranoid - i want more than one firewall between me and the world.

  - Configuring multiple firewalls separately is a recipe for getting your
    rules out of sync, and allowing security problems to creep in.

  - IT Manager types (like me) like to know their policy is consistently
    implemented.


SOLUTION

Shoregen is a script that generates shorewall configurations for multiple
firewalls from a common set of rules and policies.  Only the minimal
information necessary for operation is stored on each firewall, so, for
example, your DMZ server doesn't need to know about the rules on your
internal network, but at the same time, it gets consistent rules to your
outer guard.


PHILOSOPHY

Shoregen assumes the X-Files approach to firewall design: trust no one.
That is, paranoia is a virtue.  All access should be as limited as possible
for things to work.  If you don't already agree with this philosophy, you
may find some of the things shoregen does frustrating, but then again,
you're probably not reading this document.  :-)


DESIGN

Shoregen distinguishes between two different types of shorewall
configuration files.  Most shorewall configuration files are simply
concatenated together from parts constructed from common and host-specific
parts.  These are called simple configs; shoregen doesn't substantially
alter them, and uses little information from them.

Configs with which shoregen is more concerned are treated separately, and
additional features beyond the scope of shorewall itself are implemented.
Most importantly, two new policy/rule keywords are introduced: WARN and
BAN.  These keywords are not included in shoregen's output, but when a
subsequent rule or policy is encountered which matches a rule or policy
marked WARN or BAN, an error message is issued.  In the case of BAN, the
offending line is also dropped from the output, and a non-zero return code
issued.


PREREQUISITES

The tools you will need to use shoregen are:
	perl	The main shoregen script is written in Perl
	rsync	Used to keep /etc/shorewall directories on your firewalls
		in sync with the central repository
	ssh	Encrypted transport for rsync
	make	Optional, but saves a few keystrokes.


USAGE

Put shoregen and install_shoregen in a directory on your PATH.

Make a central directory for your configs.  I recommend somewhere in a
trusted user's home directory or central system admin repository.  This
directory should be on a trusted machine in the most secure part of your
network.  Put all of your policies, rules, and zones together in the
correct order in files in the top level of this directory.

For each of the simple configs you want to generate centrally, create a
directory, with a file called COMMON (if necessary) containing the content
you want to see in that file on all hosts, and a file named for each host
for host-specific content.  I recommend that the default shorewall
configuration file be placed in the COMMON file of the corresponding
directory, with directives that are not appropriate commented out.

When shoregen is run, it places the generated files in the directory 
SPOOL/<host>, where <host> is the hostname of the target firewall.  The
files in this directory are synchronised and the firewall checked and/or
restarted by a simple wrapper script called install_shoregen.

See the samples directory for a starting point configuration.  It provides
some suggested policies & rules for the network shown in example1.png.  The
sample configuration has not been tested in any way.

I hope you find shoregen useful.  I welcome your comments, contributions,
criticisms, and questions.