$Id: README,v 1.9 2006/03/03 17:27:38 bhockney Exp $
(C) 2003-2006 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 ulogd.conf as needed and restart the ulogd daemon if you are
using ulogd, and also edit 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 will need to set tcpip_socket = true
in PostgreSQL.conf.  See the PostgreSQL Administrator's Guide for details.

If you want to use webfwlog with logged data in a ulog table, you must
set up ulogd to log data to your PostgreSQL server before you can set up
webfwlog to report on the data.  See the ulogd package for details on setting
up a ulog table.  NOTE: webfwlog can handle internet addresses in ip_saddr and
ip_daddr that are either integers or dotted-quad strings, as text or inet type,
saved using the --with-pgsql-log-ip-as-string option of ulogd.  However,
better performance with webfwlog will be achieved if ip addresses are stored
as integers.  Also, you should run VACUUM ANALYZE on your ulog table
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 data logged by ulogd it must be in the same
database as the webfwlog tables.  If you are not using ulogd, 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 use 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.

It is also recommended that if you have logged data from ulog it be stored in
its own schema with a descriptive name such as "ulogd."  When you set up ulogd,
the ulog table was probably created in the "public" schema, and you can use the
setup script to copy your ulog table to a different schema, which will be
created if it does not exist, or to create a new ulog table with a different
name in the same 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
  - 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, and if data is moved to a new schema the
existing ulog table WILL BE DROPPED, so be sure to back up your data first!!

Rights to the ulogd schema also need to be granted to the PostgreSQL user
ulogd is using, so the setup script will prompt for this user name, which must
already exist.
