$Id: README 643 2016-08-03 22:40:45Z bhockney $
(C) 2003-2016 by Bob Hockney <zeus@ix.netcom.com>

Setup information for PostgreSQL for use with webfwlog.

This program is distributed under the terms of the GNU GPL.


This directory contains a script to set up your PostgreSQL database for use
with webfwlog.  The script will prompt you to answer some questions and for
input needed to set up your PostgreSQL server for use with webfwlog.  The
setup script will create a PostgreSQL script specific to your installation, and
you can then save the PostgreSQL script, view it, or run it.  You must run
setup the first time you install webfwlog and you should run it whenever you
upgrade webfwlog or upgrade your PostgreSQL server.

To run the setup script cd into the directory containing setup and type:

./setup

After running the PostgreSQL script created by the setup script be sure to
update your logging program's configuration as well as your webfwlog.conf
file as needed.

Reading the rest of this file is recommended before running the setup script.

PREREQUISITES

Webfwlog requires PostgreSQL >= 7.1

Before running this script you should have your PostgreSQL server installed
and running, and you will need to have login credentials for an admin user for
PostgreSQL such as 'postgres' or 'pgsql'.  You will also need to choose a
PostgreSQL user name and password for webfwlog to use.  The user will be
created if it does not exist.  This should be a separate user not shared with
any other application and SHOULD NOT BE AN ADMIN USER.  Webfwlog does not need
admin rights on PostgreSQL to have full functionality.

If your PostgreSQL server and web server are on different hosts, you may need
to edit the pg_hba.conf and postgresql.conf files to allow tcp/ip connections
from the host that is running your web server.  You will need a line in
pg_hba.conf that begins with 'host,' and may need to set tcpip_socket = true
in PostgreSQL.conf for older servers.  See the PostgreSQL Administrator's
Guide for details.

If you want to use webfwlog with database logs, you must set up your logging
program to log data to your PostgreSQL server before you can set up webfwlog
to report on the data.  See the documentation for your logging program for
details on setting up your server to log data.  Webfwlog supports database log
formats for ulog, ulog2 and snort, with ulog supported natively and others
supported with the use of views. See the pgsql_data_table.sql file for the
required format.

Also, you should run VACUUM ANALYZE on your database tables periodically to
improve performance.

DATA LAYOUT CONSIDERATIONS

PostgreSQL only allows access to data in a one database during a single
connection, so if you have database logs they must be in the same
database as the webfwlog tables.  If you are not using database logs, setup will
create the database you specify if it does not exist.  If you are using
PostgreSQL < 7.3 you cannot use schemas to organize your data and the rest
of this section does not apply.

If you are using PostgreSQL >= 7.3 you can organize your tables using schemas,
and the recommended data layout is to have the webfwlog tables stored in a
separate schema.  You can use the setup script to create new webfwlog tables
in their own schema, which will be created if it does not exist, and can also
use it to copy existing webfwlog tables to a different schema if you are
upgrading or change your mind later.

ULOG

It is also recommended that if you have database logs they be stored in
their own schema with a descriptive name.  When you set up your database logs,
they were probably created in the "public" schema.

IMPORTANT: In order to use a schema other than 'public' with ulogd you will
need to do one of the following:
  - Use ulogd >= 1.22, or any 2.x version
  - Set the default search_path in postgresql.conf to include the schema with
      your data
  - Use the same name for the ulogd schema as for the PostgreSQL ulogd user.
      This works because the default search_path is '\$USER,public'.

NOTE: Unless you are using ulogd >=1.22 you can only have one table named
'ulog' in all schemas in the database.
