$Id: INSTALL 684 2018-11-07 19:26:36Z bhockney $

INSTALLATION

Webfwlog can be installed on any system with a web server with php, and a
supported database server, which does not need to be on the same host. If
you do not need the syslog parser it is not necessary to run the configure
script, but you do need to have the make program installed. Simply give these
commands from the top directory of the distribution:

make
make install (as superuser)

This will install the webfwlog files in /usr/local/share/webfwlog and
/usr/local/share/webflwog-vendor, and the webfwlog.conf configuration file in
/usr/local/etc. It is possible to change these locations by editing the
Makefile, the web files are installed in datadir and the configuration file
is installed in sysconfdir. Edit the lines in Makefile that begin "datadir ="
and "sysconfdir =" before running the make commands, above.

You should then look at the README file in the mysql or pgsql directory
for information on setting up your database server for use with webfwlog.

You should also review the sample webfwlog.conf file and adjust the settings
to suit your installation.

USING CONFIGURE

You can use the configure script to build the syslog parser and mysql plugin
for ipv6 functions (see below), as well as adjust the directories where things
get installed. You will need a working c compiler and c library header files
installed in order to use configure. To install webfwlog using configure give
these commands from the top level directory:

./configure <configure options>
make
make install (as superuser)

If you installed the mysql shared library as described below. You should also run
ldconfig.

CONFIGURE OPTIONS

The configure script has many options.  Run configure with --help to see a
list of them.  Some useful ones are discussed below.

Installation directories:
  --sysconfdir=DIR           The directory where webfwlog.conf will be
                             installed.
                             Default: ${prefix}/etc

  --datadir=DIR              webfwlog will be installed in ${datadir}/webfwlog
                             Default: ${prefix}/share

  --with-html-doc-root=DIR   Document directory of your web server.  webfwlog
                             will be installed in ${datadir}/webfwlog, and if
                             this parameter is given a symlink named webfwlog
                             will be created in this directory pointing to the
                             installation directory. If this is not given then
                             you will need to update you web server
                             configuration to provide access to webfwlog.

The following parameters relate to the syslog parser:
  --enable-syslog          build syslog parser
  --with-mysql[=DIR]       build MySQL support [library base directory DIR]
  --with-pgsql[=DIR]       build PostgreSQL support [library base directory DIR]
  --with-libmaxminddb      build support for geoipv2 support (mmdb files)
  --with-libdb[=LIB]       build berkeley db support for geoip [library name] (optional)

This parameter is to build the ipv6 plugin for mysql (see below) which also
requires --with-mysql:
  --with-mysql-ipv6[=DIR]  build MySQL shared library for ipv6 support (see below)

DATABASE SUPPORT

Database support is used by the syslog parser to resolve host names and service
names, and you only need to include support for the database server you are
using.  You must have the header files and shared libraries for your database
server installed, and configure will attempt to locate them automatically using
first the mysql_config or pg_config utilities, which must be on your path, and
then searching the location given as DIR on the --with-mysql|pgsql option, and
finally searching common locations.

The library and header files configure is looking for are libmysqlclient.so
and mysql.h, respectively for mysql and libpq.so and libpq-fe.h for postgresql.
Your package manager may have the needed files in a separate package with e.g.
-dev or -devel suffix.

If you know the files are installed and configure doesn't locate them please
let me know, or you can use environment variable as described below.

IPV6 ON POSTGRESQL

IPv6 support with webfwlog on postgresql is automatic and no additional action
is needed other than running the setup script in the pgsql directory.

IPV6 ON MYSQL

IPv6 support with webfwlog in mysql is achieved using columns with a column
type of varbinary(16). Ulogd version 2.0 and higher also use a binary(16)
column type for mysql. Mysql does not include functions that can convert
human-readable addresses to binary strings and back again.  This webfwlog
distribution includes the needed functions in two forms:

    - user-defined functions(UDF) compiled in a shared library
    - stored procedures

Each has advantages and disadvantages.  The advantage of a shared library is
speed, especially important for large tables.  The disadvantage is that you
must be able to install the library in mysql's plugin directory, in other words
you need superuser privileges on the host running the mysql server.

The advantage of stored procedures is that you only need create function
privileges for the database in which they are created.  The disadvantages are
that they are slower that a shared library, and require mysql >= 5.0.

If you are going to use stored procedures you only need to run the setup script
in the mysql directory; if you are going to use the shared library you must
install it as below:

This parameter relate to the shared library for mysql ipv6 support:
  --enable-mysql-ipv6=[DIR]     build shared library for mysql ipv6 support

Configure will attempt to locate the plugin directory automatically using
mysql_config, and will report the directory found in its output. If it is
not found you can log onto the mysql server and enter:

> SHOW variables LIKE 'plugin_dir';

You can also try running mysql_config from your shell:

$ mysql_config --plugindir

If the value of plugin_dir is not null, you must use that directory. If the
value is null or the variable does not exist you can use any directory searched
by your linker, such as /usr/lib, and give this as an argument to
--with-mysql-ipv6. The default is the configure value for ${libdir}.

You must also run ldconfig after make install, and may additionally need to
restart the server. You can then run the setup script in the mysql directory,
which will generate the mysql commands to load the functions into the server.

GEOIP SUPPORT

First review the README.geoip for an overview of geoip support, and information
for obtaining the necessary files. If you just need lookup-only support you
only need to install the mmdb file as described in README.geoip, and give its
location in the geoip2_file variable in webfwlog.conf.

Full geoip support for postgresql database logs is described in README.geoip in
the pgsql directory.

Full geoip support for mysql database logs is not available at this time.

Full geoip support for the syslog parser requires first that the libmaxminddb
header and library files be installed. You can then use the --with-libmaxminddb
option to configure to build support into the syslog parser, which will search
the standard system paths for the necessary files. Your package manager may
have the needed files in a separate package with a -dev or -devel suffix. If
configure cannot find the maxminddb.h and libmaxminddb.so files, but you know
they are installed, you can try setting environment variables as described
below.

Geoip support for the syslog parser also optionally uses the berkeley db
library to improve performance, and can be enable using the --with-libdb option
to configure, which will search the standard system paths for the necessary
files. Your package manager may have the needed files in a separate package
with a -dev or -devel suffix. If configure cannot find the db.h and libdb.so
files, but you know they are installed, you can try setting environment
variables as described below. Some systems allow multiple versions of libdb to
be installed, and the library file may also be named  with the version, e.g.
libdb5 or libdb-5, and in this case you can give configure the library name
(without lib), such as --enable-libdb=db5. You can also use environment
variables as described below.

ENVIRONMENT VARIABLES

The webfwlog build system respects user environment variables such as CPPFLAGS,
CFLAGS, LDFLAGS and LIBS, and these can be used if configure cannot locate the
needed installed header and/or library files. Locations to search first for
header files can be given using the preproccessor include option -I in
CPPFLAGS. Locations to search first for library files can be given using the
linker option -L in LDFLAGS, and the same locations should be given as -rpath
options using the compiler linker pass-through option -Wl (webfwlog links
indirectly using libtool) in CFLAGS so the compiled program can find the
libraries. You can also specify libraries to add to the library list using the
-l linker option in LIBS.

For example, if these files are in the listed locations:

   maxminddb.h      /usr/include/maxminddb
   libmaxminddb.so  /usr/lib/maxminddb
   db.h             /usr/include/db5
   libdb5.so        /usr/lib/db5

you could set environment variables as below (e.g., using export for bash-ish
shells) prior to running configure:

CPPFLAGS="-I/usr/include/maxminddb -I/usr/include/db5"
CFLAGS="-Wl,-rpath,/usr/lib/maxminddb -Wl,-rpath,/usr/lib/db5"
LDFLAGS="-L/usr/lib/maxminddb -L/usr/lib/db5"
LIBS=-ldb5

UPGRADING

Install will not overwrite an existing webfwlog.conf file but will install
webfwlog.conf as webfwlog.conf.new.  You should review webfwlog.conf.new as
new settings have been added to the configuration file. You should also
consider running the updated setup script in the mysql or pgsql directory.
