$Id: README 727 2023-11-16 20:40:20Z bhockney $
(C) 2003-2023 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. If the zlib
    library and header files are available, webfwlog can read logs compressed
    using gzip (.gz extension).
- A MySQL, Mariadb, Percona 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
    - Percona - any production release
    - PostgreSQL >= 7.4
               for geoip support 9.1 or later
- For full geoip support with the syslog parser libmaxminddb is required.
- Berkeley db >= 4.1 is optional for performance with libmaxminddb.
- Your favorite web browser.

If you are using the ulogd version 2 daemon, see also the patches in the
contrib directory.

MYSQL, MARIADB AND PERCONA

Mariadb and Percona are binary compatible drop-in replacements for mysql, and
are 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.

Percona was forked from mysql shortly thereafter and has similar goals. It is
licensed under Gnu GPLv2.

Changes to the mysql code base are regularly merged into mariadb and percona
to maintain the feature sets of mariadb and percona 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 and percona.

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 no output, review your settings in webfwlog.conf. Also, in php.ini
try setting error_reporting = E_ALL, and display_errors = On, to get error
messages from php.

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!
