fCluster-1.0.0b README Updated 6/20/2000

INTRODUCTION
==============================================================================
This document explains fCluster, a client/server application for handling
firewall redundancy. 


PACKAGE CONTENTS
==============================================================================
Binaries:
fcluster_server - fCluster server wrapper
fcluster_srv - fCluster server program
fcluster_cli - fCluster client program

Config files:
fcluster.filters - belongs in /etc and is for IP filtering.
fcluster_srv.conf - Server config file
fcluster_cli.conf - Client config file

Support files:
example_ipt_firewall - Example iptables firewall

The live firewall will need the following files:
fcluster_server - installed anywhere you like
fcluster_srv - should go in same directory as fcluster_server
fcluster_srv.conf - should go in same directory as fcluster_server
fcluster.filters - should go in /etc/fcluster.filters

The backup firewall will need the following files:
fcluster_cli - installed anywhere you like
fcluster_cli.conf - should go in same directory as fcluster_cli


REQUIREMENTS
==============================================================================
In order to run fCluster you need to be using kernels 2.2.x or greater with
ipchains, or kernel 2.3.99-preX or greater with iptables-1.x or greater. No
users of ipfwadm will be able to use fCluster.


INSTALLATION & QUICK START
==============================================================================
Just run the install script and follow the directions listed. After you
have installed fCluster, you will need to copy the license file you
received in your email into the /usr/local/fcluster directory. You may now
use the fCluster configuration utility (fcluster.cgi) to create the
configuration files needed by fcluster_srv and fcluster_cli. NOTE: Only
RedHat users my use the "view status" function of the administration
utility. To access the administration utility, open your browser and insert
the following URL: http://xxx.xxx.xxx.xxx:9000 where xxx = the IP address
of your fCluster server machine. Once you have completed the configurations
needed to run both the server and client, you may start the programs. It is
recommended that you start the server first, or your client may start it's
fail-over sequence.


STARTING THE SERVER
==============================================================================
Starting fcluster_server:

./fcluster_server -p 5000 -n

This tells fcluster_srv to listen on port 5000 and run in debug mode. Here
is a complete list of command line options:

Usage: fcluster_srv OPTIONS
Respond to polling requests about firewall

-s, --srcip              Source IP (optional)
-p, --srcport            Source port (required)
-n  --nodaemon           Run fcluster_srv _not_ as daemon
    --help               display this help and exit
    --version            output version information and exit


STARTING THE CLIENT
==============================================================================
Starting fcluster_cli:

./fcluster_cli -d gw.company.com -p 5000 -n

This tells fcluster_cli to connect to gw.company.com on port 5000 and run
in debug mode. Here is a complete list of command line options:

Usage: fcluster_cli OPTIONS
Respond to polling requests about firewall

-d, --destip             Destination IP (required)
-p, --destport           Destination port (required)
-n  --nodaemon           Run fcluster _not_ as daemon
    --help               display this help and exit
    --version            output version information and exit

There are two modes of operation, debug mode and non-debug mode. In debug
mode, fcluster will not run as a daemon, and will print all messages to
stderr. In non-debug mode, fcluster will run as a daemon and print all
messages to syslog, with log level being LOG_ERR.


CONFIGURATION
==============================================================================
Configuring fcluster is straight forward. Edit the configuration files to
your liking. The configuration files are fairly well commented. Here is an
excerpt from fcluster_cli.conf:

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# IP fail over info
#
# These fields should be set to the ip address, netmask, device and 
# gateway of the live firewall machine so fCluster_cli knows what 
# to make it's own IP in the event of a fail over.
int_device=eth0
int_ip=192.168.4.85
int_netmask=255.255.255.0
ext_device=eth0
ext_ip=192.168.4.85
ext_netmask=255.255.255.0
gateway=192.168.4.250
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

So, in short, follow the comments in the configuration files for each
configuration parameter.


FILTERING 
==============================================================================
fCluster_srv can also do filtering. In order to take advantage of the
filtering rules, you must make a config file. The file will reside in the
/etc directory of the live firewall and it will be called "fcluster.filters"
(i.e. /etc/fcluster.filters).  The filter file can contain comments, only if
the first character of the line starts with the pound sign '#'. Example:

Example 1:
# This is a proper comment. (correct)

Example 2:
DENY.209.209.123.12 # DENY this host (Not correct)

The first example is a correct comment, the second isn't. 

The filters file can be setup with a default policy for either accept or
deny.  If a default policy of deny is chosen, then all traffic that hasn't
been specifically allowed, will be denied. By contrast, if a default policy
of accept is given, all traffic that isn't specifically denied will be
allowed.

fCluster filters are to be written as 'rule.ip', here is an example:

ACCEPT.127.0.0.1
DENY.127.0.0.1

The words ACCEPT and DENY are not case sensitive, so rules can be written
as:

ACCEPT.192.168.4.98
or
accept.192.168.4.98

Please note that names are not allowed, so:

DENY.localhost 

will _not_ work.

There is no order in which filter rules have to be written, however, it's
recommended that the default policy be last. The default policy must be
written on a line by itself terminated by a semi-colon, example:

ACCEPT;

or

DENY; 

Alternatively, if there is no filters file in place, all connections will
be allowed. Please see the file called "example_fCluster.filters" in this
directory for more detail.


PROGRAM OPERATION
==============================================================================

fcluster_cli will poll fcluster_srv every x seconds/minutes. Where x is the
number configured by the administrator. In order to understand how fcluster
works, a brief summary of it's operation is needed.

States:
non-live - every thing is good
livepend - was not able to connect to live firewall machine, and the retry
sequence has been started.
live - fcluster_cli has failed over and become the live firewall. 

There are three possible answers fcluster_cli will return:

1.) Was able to connect, and found a running firewall
    If state is currently livepend, our state changes
    to non-live. Otherwise nothing happens, and no state
    change occurs.

2.) Was able to connect, and found no running firewall
    If state is currently livepend, our state changes
    to non-live. Otherwise, no state change occurs.
    An email will be sent to level 1 recipients.

3.) Was not able to connect.
    If our state is currently non-live, our state changes to livepend and
    the retry sequence begins. The retry sequence is defined by the
    administrator in the fcluster_cli.conf file. Once fcluster reaches the
    retry count, it will fail over and become the live firewall. An email
    will be sent to level 2 recipients.  Once the fail over has occurred,
    fcluster_cli will exit. 

If the state of fcluster is livepend, and a connection is successfully made
during one of the retry attempts, the state is changed back to non-live and
all counters are set back to zero.

During every poll from the client to the server, a check against the
server's firewall script's modification stamp is done. If the file has been
modified, fcluster_cli will request a new copy of the firewall script
file. When fcluster_cli starts up, it has no way of knowing if it has the
latest firewall script from the server. So even if fcluster_cli already has
a copy of the firewall script from the server, it will request a new one
almost immediately after starting up. After that, it will only request a new
script file from the server, if the server's script file has been modified.


CONCLUSION
==============================================================================
This should be enough to get you started. Please send all
questions/comments to support@innertek.com.