Firewall Monitor (fwmon) v1.1.0
-------------------------------------------------------------------------

ABOUT: 

Fwmon is a simple ipchains/iptables firewall monitor that uses the linux
kernel's netlink feature to watch firewall activity in realtime.  This 
software is released under the terms of the GNU GPL (see: COPYING). It 
integrates well with existing ipchains firewall rule sets and can provide
enhanced reporting (e.g. packet contents and/or tcpdump-style data) over that
provided by ipchains by itself.  Fwmon can be executed in a 'chrooted'
environment for additional protection during operation.


INSTALL:  See ./INSTALL for Compile-time options and directions


CONFIGURATION:

Fwmon can easily be integrated into an existing ipchains ruleset.  As an
example, fwmon can be easily integrated into the excellently commented
TrinityOS ruleset available from http://www.ecst.csuchico.edu/~dranch/LINUX.
The enhanced logging may be selectively added to specific existing rules by
adding a new user-defined rule to the default ACCEPT, REJECT and DENY rules..

If you wish to retain current ipchains logging features which RedHat and
TurboLinux among other distributions make to /var/log/messages and add the
additional features of fwmon, keep the '-l' option (or the $LOGGING
equivalent used in TrinityOS) for those rules of interest.  Fwmon data will
be placed in a separate file (user-configurable) via a new target of those
rules for which the capability is desired.  Note that this new rule will not
contain the '-l' (or $LOGGING) flag so packets trapped by a primary rule are
not logged twice by ipchains.  Additionally, by retaining the ipchains
logging in primary rules, the rule number that caused the logging is
contained in the ipchains log entries, and not the rule number of the new
chain.

As a guide for adding this new chain, the TrinityOS rule set begins with
setting of various parameters used with firewalls (flag settinga in the
/proc directory, loading of modules, etc) then rules are grouped in INPUT,
OUTPUT and FORWARD sections.  Since this new rule will be a 'target' of
other rules, it must be placed BEFORE the first rule which references it to
avoid errors the first time the ruleset is loaded.  We suggest that a new
section defining the rule be placed just before the INPUT rules section and
consist of:

  #########################################################
  ##  New Chain for logging via Fwmon
  #########################################################

  /sbin/ipchains -N Dump           # The name of this chain is 'Dump'
      # Tag any packets for blocked logging, limit size to 4096 bytes
  /sbin/ipchains -A Dump  -o 4096
      # Wind up by dumping the packet in the bit bucket (no response)
  /sbin/ipchains -A Dump  -j DENY

Any following rule may use this sequence as a target for blocked packets
(i.e. rules which originally jump to REJECT or DENY) to obtain the Fwmon
logging features by changing its jump destination (-j DENY or -j REJECT) to
'-j Dump', while keeping the remainder of the rules the same.  If you wish
to log packets which are accepted via the default ACCEPT rule target, you
will need to create yet another chain.  The format is the same as above, but
change the name from 'Dump' to something else such as 'LogOK', change the
final '-j DENY' to '-j ACCEPT'.


NOTES ON SQL:

Eeach host that you run fwmon on should have its own entry in the 'hosts'
table.

	INSERT INTO "hosts" ("uname", "ip") VALUES ('localhost', '127.0.0.1');

If you log fwmons SQL output to a file and batch add the records to your
database it is recommended that you add each file as a single transaction.
This improves performance and also means that if something should fail
half way through you dont have to try figure out exactly which records are
left to insert. This can be done as easily as adding BEGIN; at the top of
the file and COMMIT; at the bottom. Consult the documentation of your SQL DB
for details.


USAGE:

Fwmon may be run as a daemon or a normal console application program.  Two
options which you may want to examine first are flags to simply display the
version number and built-in help as:

	/usr/sbin/fwmon -v
and
	/usr/sbin/fwmon -h

The latter displays:

    Usage:
      /usr/sbin/fwmon [OPTIONS]

      -t <filename>	Name of file to output tcpdump logs
      -l <filename>	Name of file to log to
      -q                Log as SQL
      -s 		Silent, no output to screen
      -d 		Daemon mode, silent, and ran in the background
      -n <length>	Line length for hex/ascii output (No. of bytes)
      -a 		Date, show the date as well as time on packets
      -m 		Don't dump data
      -x 		Don't display hex output
      -i 		Don't display ascii output
      -u <uid>		User ID to drop to
      -g <gid>		Group ID to drop to
      -c <chroot>	Directory to chroot jail inside
      -v 		Just print version
      -h 		Display this help


To run the application manually and simply view the monitored packets on the
console without the more advanced or logging features, enter:

	/usr/sbin/fwmon

Entering a Control-C will kill the program and return the prompt.  You will
notice that packet display only includes the time and not date information. 
This may be added with the '-a' option as:

	/usr/sbin/fwmon -a

Display of Hexidecimal and Ascii output may be selectively disabled with the
'-x' and '-i' options respectively.  By default, packet contents are
displayed in both modes, so adding the flags to the command line will
disable, or turn OFF, the selected capability.  As a further refinement, the
number of bytes displayed may be altered with the '-n' option.  This option
by default is 16 for the number of bytes to be displayed before beginning a
new line.  For example, to display only Hexidecimal data without ascii and
limit each line to eight bytes of data on the console, the command would be:

	/usr/sbin/fwmon -i -n 8

Logging of packet information to an ascii file is controlled by the '-l'
followed by an explicit file to contain the logged data.  To maintain
compatibility with ipchains logging of information to '/var/log/messages',
one might choose to log fwmon data to '/var/log/fwlog' by entering:

	/usr/sbin/fwmon -l /var/log/fwlog

The specified file will be created and opened for writing if it does not
already exist.  When invoked as a normal console program with the above
command, you will see packet data on the screen and the same data will be
appended to the specified file.  Display to the console may be disabled
(while continuing to log to the file) by appending the '-s' (or 'silent')
flag to the command invocation line.

In a similar manner, data can be logged in tcpdump format with the '-t'
option.  Again, if the specified log file does not exist, one is created,
and tcpdump header information is written to the file which will be followed
by logged packet information.  An example command is:

	/usr/sbin/fwmon -t /var/log/tcplog

This file may be examined later with any program which accepts files in
tcpdump format.

Rather than running the program as a user application, it may be run as a
daemon in the background.  In this case, no information is displayed to the
console unless errors occur and the console session is not tied up while
fwmon executes.  Since it would be rather pointless to run in this mode
without some form of output, file logging to either a log file, tcpdump
file or both is normally added to command lines specifying daemon mode of
operation.  An example of running in daemon mode with outputs to both log
and tcpdump files is:

	/usr/sbin/fwmon -t /var/log/tcplog -l /var/log/fwlog -d

Again, the '-a' flag may also be appended if date logging in addition to
time is desired in the ascii log file.

The final options; '-u', '-g', and '-c', if used, must be applied together
to create a 'changed root' for fwmon as a precautionary measure against
someone obtaining root privileges via a weakness in fwmon or the support
library routines.  Take a look at README.chroot to get a clearer idea on
how to use them.

That is all, enjoy using fwmon, and we hope that it helps you monitor and
maintain your system.  Happy logging!