gShield is a iptables firewall script which should run
"out of the box" for most folks with minimal fuss.

gShield has the following features:

- handles dynamic or static IP's without problem
- can selectively enable NAT for multiple private ranges
- adds tcpwrapper-like functionality for access to services
- aggressive defaults; only default 'open' service is auth
- easily configurable via a well commented BSD-style conf file.

iptables configuration
==============================

gShield does not require the use of the
experiemental patches contained in the 
iptables source.  There are -some-
cases where the functionality of one
or more of those patches was absolutely
necessary in some cases (the TCPMSS fix for
PPPoE folks is one example) -- but in general
gShield does not make use of these modules.

That said, my personally approach to compiling
iptables support is simple:

	- ensure Prompt for development drivers is enabled
	- compile -all- listed iptables options directly

Yes, compiling them as modules should be fine for a
properly configured system-- it's just the way I do it.

Getting started
===============

All major configuration settings are stored in /etc/firewall/gShield.conf
You -WILL- need to look over this file before running the firewall,
but for most cases, the defaults should work fine for most
folks. Go ahead, open another term and take a peek; it's commented.

gShield itself has some runtime options you can use
to ease some typical administrative tasks.  These
are detailed below and in USAGE.

* ACL's

gShield tries to incorporate Access Control lists in a more
direct manner than the "usual" approach with firewall scripts. 

An ACL is simply a list of hosts which are allowed to connect
to pre-defined services. In this way, we can protect core
services (such as POP, SMTP, FTP, etc) from "the world", while
still having unrestricted access to "trusted" hosts.

A good example:

You wish to have access to your home machine from work,
but worry about leaving the sorts of services you'd
like access to open to the world. One way to accomplish
protecting these services would be via tcpwrappers or xinetd.

gShield takes this a bit further by allowing you to set what
hosts even get to have a packet touch the service in the first
place.

In the case of our "I want to have access to my home machine
from work" scenerio, we simply drop the ip (or range) of
our work machine into /etc/firewall/conf/client_hosts.

Any ip (or range) in client-hosts is allowed access
to those services as defined in /etc/firewall/conf/client_services, while
"other" hosts cannot. So one can easily restrict access to services
by distinguishing between "clients" and "the public".

----------------------------------------------

Other ACL's

/etc/firewall/conf contains the following 'other' files:

NATS
black_listed_hosts
client_hosts
client_services
closed_ports
highport_access
reserved_addresses
open_ports
blocked_outgoing
blocked_addresses
no_log_ports

client_hosts and client_services we've touched on already.

* NATS
	should contain the private addresses you wish to provide NAT services
	for. You can specify multiple ranges here.

* black_listed_hosts

	drop "problem" hosts in here. gShield will drop -all-
	connections from these hosts (and log them at no extra cost!)
	IF you have BLACKLISTED set to "AUTO" in gShield.conf,
	gShield will attempt to parse /etc/hosts.deny for this
	information (see gShield.conf for more details).

* highport_access

	IRC bots like to connect to high (unreserved) ports, which gShield
	drops by default. 

	Many services like to establish high TCP connections as well -- simply
	drop those hosts in here (if you need unrestricted access from
	the public to high ports, this can be configured in gShield.conf).

* closed_ports

	These are ports you simply want -fully- closed off for whatever
	reason. In most cases, this is over-kill given gShield's defaults.
	These ports are closed to -everyone-, even those hosts listed as
	clients, so be aware.

* reserved_addresses

	These are ip ranges which have no business hitting the external interface
	in the first place (i.e., private ranges)

* open_ports

	Sometimes, you just want that port open. 
    Add those ports you want open ON the firewall machine.
	gShield will open both tcp and udp on those specified ports.

* blocked_outgoing

	ports which you wish to -prevent- access to (both for the firewall
   	itself, as well as NAT'd clients)

# blocked_addresses

	addresses which you wish to -prevent- access to (both for the firewall
	itself, as well as NAT'd clients)

* no_log_ports

	ports which you do not wish logged, regardless of the default
	logging policy 

----------------------------------------------

RUNTIME options

Beginning with 2.4, gShield adds additional
run-time options to make some tasks easier.

From ./gShield help

gShield run-time options:
-------------------------
flush: flush all rulesets and disable firewall
client x: add ip "x" to clientlist
blacklist x: add ip  "x" to blacklist
highport x: add ip "x" to highport access list
help: this list

Briefly put, you can add ips to the client list, highport list
or blacklist all from the command line without having to re-load
gShield to re-read the ACL for that service.

For example, say I want to allow 1.2.3.4 as a client.  Starting with
gShield 2.4, this is a single step:

/etc/firewall/gShield.rc client 1.2.3.4

gShield will:

- add 1.2.3.4 to the -current- client list for immediate access
- add 1.2.3.4 to /etc/firewall/conf/client_hosts (for next time) and date its
insertion.
           
There ARE some limitations:

- you have to use an -ip- address; hostnames are no good (this isn't totally true)
- you can only use -single- ip addresses, not ranges or nets

----------------------------------------------
Feel free to contact me with suggestions and/or problems

Godot (godot@mindspring.com)

I can also generally be found on EFNet, #Linuxhelp
