$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!

$Id: README.geoip 684 2018-11-07 19:26:36Z bhockney $
(C) 2003-2018 by Bob Hockney <zeus@ix.netcom.com>

GEOIP

Geoip location data based on IP is provided using maxmind's geoip databases,
version 2, either in PostgreSQL database tables for data logged using
PostgreSQL, or maxmind's geoip version 2 files (with a mmdb extension).
Both the paid and free (lite) databases are supported. Version 1 (legacy) of
geoip data is not supported.

Two levels of support are available, depending upon your log data source:
  - Lookup only, which supports all geoip data fields, but does not allow
    filtering or sorting on geoip fields. This is available for all log data
    sources.
  - Full support, which does allow filtering and sorting by geoip fields. This
    is available for file logs and postgresql database logs; mysql database
    logs are not supported.

Lookup only support is provided by the maxmind-db/reader php class, which is
included in the webfwlog distribution tarball, and provides lookup only support
out-of-the-box provided the maxmind database files are installed (with mmdb
extension). While this can look up all supported fields, from all log data
sources, filtering and sorting are not available. This is the only support
available for logs in a mysql database. The free versions of the binary
databases are available here (city recommended):

http://dev.maxmind.com/geoip/geoip2/geolite2/

Lookups using the php reader class can be slow, especially on long reports.
Maxmind provides a php extension that can be built, and provides a performance
improvement of an order of magnitude. The source is included in the webfwlog
distribution in the vendor/maxmind-db/reader/ext directory. Installation
instructions are in vendor/maxmind-db/reader/README.md. You will need the
php development tool phpize installed.

Full support for filtering and sorting by geoip fields is available for
postgresql database logs. Maxmind provides CSV files at the above location,
which can be imported into a postgresql database and used with database logs
in the same database. This requires the ip4r extension to postgresql, version
2.0 or higher, to be installed and loaded. This extension is available in many
package manager systems, or can be download from the link below. See the
README.geoip in the pgsql directory for more information.

http://pgfoundry.org/projects/ip4r

Full support for filtering and sorting by geoip fields is available for file
logs using libmaxminddb, which is available in many package manager systems,
or the source can be downloaded from maxmind.com at the location below. You
will need to give configure for webfwlog the --with-libmaxminddb option when
compiling the syslog parser. See INSTALL for more information.

https://github.com/maxmind/libmaxminddb