$Id: README,v 1.19 2006/03/03 17:27:38 bhockney Exp $
(C) 2003-2006 by Bob Hockney <zeus@ix.netcom.com>

Webfwlog is distributed under the terms of GNU GPL

WELCOME

Webfwlog is a flexible web-based analysis and reporting tool for firewall logs.
It supports standard system logs for linux, FreeBSD, OpenBSD, NetBSD, Solaris,
Irix, Darwin, etc. as well as Windows XP(R).  Supported log file formats are
netfilter, ipfilter, ipfw, ipchains and Windows XP(R).  Webfwlog also supports
logs saved in a database using the ULOGD target of the linux netfilter project.

With Webfwlog you can design reports to use on your logged data in whatever 
configuration you desire.  Included are example reports as a starting point.
You can sort a report with a single click, "drill-down" on the reports all the
way to the packet level, and save your reports for later use.  You can also
create a link directly to any saved report.

PREREQUISITES

- A web server with PHP >= 4.1
- Log files in standard netfilter, ipfilter, ipfw, ipchains or Windows XP(R) format
    or database logs populated with the ULOG target of netfilter.
- A MySQL or PostgreSQL database server:
    - MySQL >= 3.23.52 or any production release of 4.x or 5.x
    - PostgreSQL >= 7.1
- Your favorite web browser.

Windows XP(R) support provided via Cygwin.

INSTALLATION

See the INSTALL file for installation directions.

SECURITY

The database login credentials used by webfwlog are stored in the webfwlog.conf
file which must be readable by PHP, which is probably running as the same user
as the web server.  By default, this file is installed owned by root and with
permissions of 644, meaning it is readable by any user.  In many installations,
the web server runs as a specific user, such as apache or www, or this user may
belong to a group, such as apache or www.  You may be able to somewhat secure
the webfwlog.conf file by changing the ownership or group id of this file and
and changing the permissions to 640 or 600.  You are strongly urged to restrict
the permissions on webfwlog.conf as allowed by your installation.

The syslog file parser is named wfwl_syslog and is installed suid root (4555)
because it needs to be able to read system log files, which are normally only
readable by root, and must also be executable by PHP which is probably running
as the same user at the web server.  If the user your web server runs as
belongs to a group such as apache or www, then you can change the gid of
wfwl_syslog to this group and change the permissions on the binary to 4550
to prevent regular users from executing the program.  wfwl_syslog rejects log
lines that are not in a recognized log file format and never outputs the
contents of the log file, only the parsed results, to prevent information leak
from the log files.

Also, any PHP script running on the web server has access to the webfwlog.conf
file and wfwl_syslog executable.  Because of this, it is not recommended to
run webfwlog on a system where non-trusted users can place PHP scripts
available to the web server, and it is important that the MySQL or PostgreSQL
user you are using for webfwlog not have more privileges than it needs.  In
particular, the user does not need and SHOULD NOT HAVE rights to create and
drop databases and tables other than temporary tables, and especially should
not have the ability grant or revoke rights to other users.  It is recommended
to use a separate database user for webfwlog.

See the README in the mysql or pgsql directory for a script to set up your
database server for use with webfwlog, including granting only the rights
needed.

USE

Before starting webfwlog for the first time, you should review the installed
webfwlog.conf file and adjust it as needed for your installation.  This
file is well-commented.

You can load webfwlog by pointing your favorite web browser to:

http://<location>/webfwlog/index.php

When you load the webfwlog home page, you will see a list of the reports
you have previously saved, and the example reports if imported during setup,
and can run one of them by clicking the link with its name in the code column,
or edit one by clicking the link in the edit column.  You can create a new
report by pressing the Report Editor bottom at the bottom of the list.  More
documentation in on the home page.

From an on-screen report, you can sort a column by clicking on the heading.
You can also "drill-down" on a cell if it has a link, which will filter 
the report by the item selected.  If there is an 'Packet' column on the
report you can click it to see all details for that logged packet.  If the
report is summarized clicking on the number in the 'Count' column will
display a list of the individual logged packets that make up the count,
and from there you can drill-down to the packet details.

From the report editor you can import and export report definitions, save them
in the database for later use, or edit them.  Documentation for the report
editor is on the report editor page.

COMMENTS

Please let me know what you think!  If you have questions or comments please
send them to the webfwlog mailing list <webfwlog-users@lists.sourceforge.net>
or email me at zeus@ix.netcom.com.

Enjoy!
