$Id: INSTALL,v 1.38 2002/02/12 17:40:26 flacoste Exp $

(If you are interested in the Lire client software only, i.e. you want to
be able to anonimize your log files before you send them to the LogReport
online responder, read README.lire-client.)

The Lire software can be installed in a user's home directory or it
can be installed at the system level.

If you are upgrading from version 20010903 or earlier (which would mean you
missed lire-20011017), make sure to read the "Upgrading From Version 20010903
or Earlier" section at the end of this file.


Binary version
==============

We suggests that you use binary distribution of Lire when they are
available for your platform. Currently, we have binary distribution of
Lire for Debian and GNU/Linux RPM based distribution.


Requirements
============

Before installing Lire, you should have the following available on your
system :

    - GNU gzip
    - A recent version of perl (5.00503 or higher). Perl and pod2man 
      should be available in your PATH before installing.
    - expat 1.9.x and XML::Parser 2.29 or later. For your convenience, there 
      is a tarball of Lire, i.e. lire-version-full.tar.gz which includes
      those libraries. Alternatively, you can download expat from 
      http://expat.sourceforge.net/ and XML::Parser from your local
      CPAN mirror.
    - Standard Unix utilities like sh(1), cut(1), head(1), sort(1), grep(1),
      and cat(1) should be in your PATH.
    - Optionally, Lire can send its messages to syslog if you have
      logger(1) installed.

To generate reports in other format than ASCII you will need 

    - xsltproc 1.0.4 (or later)
      This is included in the XSLT C library for Gnome which is available from
      http://xmlsoft.org/XSLT/ (Libxml2 will be also be required by libxslt.)
    - DocBook XML DTD V4.1.2
      (http://www.oasis-open.org/docbook/xml/4.1.2/)

To generate PDF or RTF reports, you will also need the following
requirements:

    - Jade or OpenJade
      (http://openjade.sourceforge.net/)
    - Norman's Walsh DSSSL stylesheets for DocBook
      (http://docbook.sourceforge.net/projects/dsssl/) 

To generate HTML or XHTML reports, you will need :
    - Norman's Walsh XSL stylesheets for DocBook
      (http://docbook.sourceforge.net/projects/xsl/) 

To generate PDF reports, you will also need the following tools:

    - A recent TeX installation.
    - JadeTeX
      (http://jadetex.sourceforge.net/)

If you plan to use the anonimizer, you will need:

    - The DB_File perl module and Berkeley DB (libdb.so). DB_File is
      included in the standard perl installation. 

      NOTE: Some people are reporting problems with DB_File and newer
      version of the Berkeley DB library (like 3.2.9) and older
      version of DB_File (like version 1.72 which is shipped with perl
      5.6.0) . If you run into problems, you might want to upgrade
      DB_File.pm to version 1.75.

If you plan to go running an online responder, to process logs from
other hosts, you need munpack, as shipped with mpack, a MIME
packer/unpacker. You can download this from 

ftp://ftp.andrew.cmu.edu/pub/mpack/



Local Installation
==================

To install Lire without root access, do this:
(version is e.g. 20010129)

 ~$ gunzip lire-version.tar.gz
 ~$ tar -xf lire-version.tar 
 ~$ cd lire-version

 ~/lire-version$ ./configure --prefix=$HOME/logreport

 ~/lire-version$ make
 ~/lire-version$ make install

All Lire software is now installed under $HOME/logreport.

Note: Be sure to keep the Lire Makefiles in its build tree on your
system.  This will make it easy to uninstall or upgrade Lire later.
If you care about your diskspace, do a 'make clean': this gives you back
some diskspace, and wont harm.

You should have some Lire man pages installed on your system now.  If your
system happens to be a Debian GNU/Linux box, you should add this to your
.bashrc (or whatever your shell uses)

 export MANPATH=:$HOME/logreport/man

where $HOME/logreport is the prefix you gave to configure. This lets
you access the man pages in a transparent way.

Add $HOME/logreport/bin to your PATH. (You could adjust your shell's
startup script.)

If you want to run the Lire scripts from cron, configure your system
by running

 $ lr_config

. You'll be asked some questions about your system.
(An article about Lire, with an exhaustive explanation of
lr_config is being published by LinuxFocus.  It's available on
http://www.linuxfocus.org/English/September2001/article213.shtml .)
Once finished, you can add a daily

 lr_cron daily

job to your crontab, and you'll receive daily emails about the use of
services on your system.



System Installation
===================

If you like to install the software on system level, you're strongly
advised to create a dedicated Lire user to run the scripts.  You are
advised _not_ to run the LogReport scripts as root. The user running the
scripts should have permission to read the log files you want to process,
of course. No other special permissions are needed.

Create a dedicated user account, e.g. `lire', with group `lire'.

Run the configure like this:

 lire@yourhost $ ./configure

Then build and install the software by doing:

 lire@yourhost $ make
 root@yourhost # make install

Fix permissions:

 root@yourhost # chown :lire /usr/local/etc/lire
 root@yourhost # chmod g+w /usr/local/etc/lire

 root@yourhost # mkdir -p /usr/local/var/lib/lire/data
 root@yourhost # chown :lire /usr/local/var/lib/lire/data
 root@yourhost # chmod g+w /usr/local/var/lib/lire/data

Set up cronjobs:

 lire@yourhost $ lr_config

When installed this way, there's no need to adjust your PATH or MANPATH
to use the software.

Other users who want to run the lire scripts should have a
~/.lire/etc/defaults featuring a line like this:

 LR_ARCHIVEDIR=$HOME/.lire/data



Help Us Helping You
===================

If you wish to ensure that Lire runs better on your machine, please do
us a favor and do something like:

 ~/lire-version$ mail -s "Red Hat Linux 7.0" lire-config@logreport.org < config.status

so that we can see what kinds of configurations people are running.
We will use this information to improve portability of Lire in future
releases.  Thank you!



Removing Lire From Your System
==============================

If you want to uninstall the software, make sure you keep your Makefile
in the lire-version source tree. From there, run

 $ make uninstall

This will remove all files which were installed. (Newly created directories
will stay.)



Options For ./configure
=======================

After install, these directories will be present on your system:

 <sysconfdir>/lire             - configuration files
 <mandir>/man1                 - manpages
 <mandir>/man3                 - manpages
 <datadir>/doc/lire            - documentation
 <datadir>/lire/filters        - XML files, used in reports
 <datadir>/lire/reports        - XML files, used in reports
 <datadir>/lire/schemas        - XML files, used for Lire internals
 <datadir>/lire/sgml           - SGML declaration for XML documents
 <datadir>/lire/xml            - XML stylesheets and DTD's
 <datadir>/perl5               - perl modules
 <libexecdir>/lire             - scripts, not to be run manually
 <bindir>                      - scripts
 $HOME/tmp                     - tmp files (directory gets created on the fly)
 <localstatedir>/lib/lire/data - the Lire archive, containing reports and
                                  logfiles, gets build here

Run

  ./configure --help

to see what the default for <sysconfdir>, <mandir>, <datadir>, <prefix>, 
<bindir> and <libexecdir> are.

One can even tweak internal configure variables, which lack a commandline
option.  One could e.g. run

 PATHTOJADE=/opt/jade/jade
 ./configure

to force the jade used to be the one under /opt. Other settings that can
be overwritten in this manner are, for example, PATHTOTAR, PATHTOGZIP.
Inspect the configure script itself (or configure.in) to find out more about
this advanced usage.


More Informations
=================

For information on how to test and use this software, refer to the Lire User
Manual in doc/ .



Upgrading From Lire's Version 20010903 or Earlier
=================================================

Lire version later than 20010903 introduce an all new XML based
reporting engine. This makes Lire more customizable, extendable and
performant, but it introduces a few hurdles for the user that is
upgrading her Lire installation.

The upgrade procedure is relatively straightforward :

    1- Uninstall old version.
    2- Install new requirements.
    3- Build and install Lire.
    4- Migrate old configuration.
    5- Migrate old customization.
    6- Migrate anonimizer client installation.
    7- Migrate responder.

1. Uninstalling old Lire version.

First, you should remove your old Lire installation by doing a 

 $ make uninstall 

in the old source tree. (You could also remove the directory where you
installed Lire, but you would lose all customization that you would
have done.)

2. Install new requirements.

Requirements for Lire have changed. You will need to install the XML
expat library and its perl interface, XML::Parser. With this release,
only the xsltproc XSLT processor is supported. Read the "Requirements"
section for more information.

3. Build and install Lire.

This step hasn't changed much. You can refer yourself to the "Local
Installation" or "System Installation" section.

4. Migrate Lire wide configuration.

Your old customization in the files etc/defaults.local or
$HOME/.lire/etc/defaults (~/.lirerc's successor) will still function. 

Because with this release, only xsltproc is supported as XSLT
processor, you should check your XSLT_PROCESSOR variable. It should be
set to 'xsltproc' or 'none'.

There are a couple of new variables you might like to configure :

  LR_TARGET_USER
  LR_USERLEVEL
  DEFAULT_OUTPUT_FORMAT
  LR_MAX_MEMORY

You can run lr_config to update your configuration or read about those
variables in the etc/lire/defaults comments.

5. Migrate old report configuration.

With Lire's release post-20010903, the way Lire's reports are
configured was changed altogether.  (If you didn't change any
report specific settings, you can skip this section.)

The report's configuration for a specific superservice is now in
a file named <superservice>.cfg. (i.e. www.cfg for the www
superservice). This file is looked for in <sysconfdir>/lire and
$HOME/.lire/etc.

This configuration file is a text file where each line contains the
id of a specific subreport and its customization parameters.

For example, the email.cfg file could contain :

# Report configuration for the email superservice
deliveries-by-hour
volume-by-hour
top-to-domain       domain_to_show=10
top-from-domain     domain_to_show=10

The file can include comments by starting the line with a #.

This superservice's report configuration file specifies that the
report for the email superservice will contains the
"deliveries-by-hour" report, followed by the "volume-by-hour" report,
the "top-to-domain" report and the "top-from-domain" report. The
"top-to-domain" and "top-from-domain" reports will each display the
top 10 domains. To display only 5 domains, you could change the last
two lines to :

top-to-domain       domain_to_show=5
top-from-domain     domain_to_show=5

The content of this file replaces all the configuration files that were
previously in <sysconfdir>/lire/<superservice>, i.e. the defaults,
defaults.local, and <subreport>.conf files.  BEWARE: this means the latter
files are _obsolete_ and no longer used.

Previously, the parameters for a specific subreport were specified
through the use of environment variables in a <subreport>.conf file.
You now set those parameters directly in the <superservice>.cfg file.

Previously, the subreports that would be included in the
superservice's reports were specified through files pointed to by
environment variables in the <superservice>/defaults file. The
subreports and their order are now taken directly from the
superservice's report configuration file (i.e. email.cfg).

Since the name of the subreports and their parameters names were
changed to longer, more descriptive names, the best way to migrate
your configuration is to start from the new superservice.cfg file that
is shipped with Lire.

You can find a list of all available reports and their parameters in
the Lire User's Manual in Part II: Reports Reference.

6. Migrate old homegrown reports.

If you had added specific subreports tailored to your needs, or you
had modified some of Lire's subreport script, you will need to port
you changes to the new XML format. 

Lire now has a Lire Report Specification Markup Language which is
an XML grammar used to describe the way the subreport is generated.
This XML specification now includes all information about a report:
its description, parameters and operation. 

The format isn't yet fully documented, so the best way to
port your customization is to look at the existing reports in
<superservice>/reports. If you need any help porting your customization
or you have any questions regarding the new architecture, don't hesitate
to post on questions@logreport.org

7. Migrate anonimizer client installation

The DTD for Lire's report has changed after version 20010903. This means
that you will need to upgrade your client installation to process reports'
generated by new responder version.

8. Migrate the responder

In Lire's release post-20010903, the superservice organization was
changed a bit:

    - apachemodgzip is now the 'modgzip' service in the 'www'
      superservice.
    - the apache service was split in the 'common', 'combined' and
      'referer' service which more closely reflects the log format
      which they support.
    - there are two new superservices : ftp and firewall. 

The old addresses (apachemodgzip, apachecombined and apachecommon) are
replaced by new ones: modgzip, common, combined, referer.  You should
announce these changes to the users of your responder.