$Id: README 684 2018-11-07 19:26:36Z bhockney $
(C) 2003-2018 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 Cisco and Netscreen routers, and Windows XP(R).
Supported log file formats are netfilter, ipfilter, Cisco IOS, netscreen,
ipfw, ipchains and Windows XP(R).  Webfwlog also supports logs stored in a
database with the layout described in the mysql or pgsql directories, which
is based on the layout used by the ULOG and NFLOG targets of the linux
netfilter project. The setup scripts can also create a view to support the
Snort IDS format. 

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 report definitions for later use.  You
can also create a link to directly create a report from a saved definition.

PREREQUISITES

- A web server with PHP >= 4.1 with session, pcre, and pgsql or mysqli database
    extension for your server. The deprecated mysql extension is also supported.
    For geoip, PHP >=5.3 is required.
- Log files in standard netfilter, ipfilter, Cisco IOS, Cisco PIX, ipfw, snort,
    netscreen, ipchains or Windows XP(R) format, or database logs populated
    with the Snort IDS or the ULOG and NFLOG targets of netfilter.
- A MySQL, mariadb or PostgreSQL database server:
    - MySQL >= 3.23.52 or any production release of 4.x or 5.x
               for IPv6 support 5.0 or later
    - Mariadb - any production release
    - PostgreSQL >= 7.1
               for IPv6 support 7.4 or later
               for geoip support 9.1 or later
- For full geoip support with the syslog parser libmaxminddb is required.
- Berkeley db >= 4 is optional for performance with libmaxminddb.
- Your favorite web browser.

MYSQL AND MARIADB

Mariadb is a binary compatible drop-in replacement for mysql, and is
increasingly used in the open source community in place of mysql. Mariadb was
forked from mysql when Oracle acquired the rights to mysql and is maintained by
some of the original developers of mysql out of concern about the future
direction of mysql under Oracle, particularly with respect to licensing.
Mariadb is guaranteed to remain open source, and changes to the mysql code
base is regularly merged into mariadb to maintain the feature set of mariadb
with that of mysql. Webfwlog is agnostic about which program is in use and
treats them the same. All references to mysql in the webfwlog documentation
and configuration apply without change to mariadb.

Windows XP(R) support provided via Cygwin.

GEOIP

Geoip version 2 lookup-only support is built in to webfwlog and only requires
that the maxmind mmdb files be installed; full support has additional
considerations. See README.geoip is this directory for more information.

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 report
definitions you have previously saved, and the example report definitions if
you imported them during setup.  You can run a report 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 definition by pressing the
Report Editor button 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.

TROUBLESHOOTING

If you get only part of a report output, or no output after a long time, try
increasing the php_max_memory parameter in webfwlog.conf.  You can also try
increasing the timeout settings.

Please report bugs to zeus@ix.netcom.com.

COMMENTS

Please let me know what you think!  If you have questions or comments please
email me at zeus@ix.netcom.com.

Enjoy!
