$Id: INSTALL,v 1.61 2003/05/07 13:23:59 vanbaal Exp $

(If you are interested in the Lire client software only, i.e. you want to
be able to anonymize 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 1.1 or earlier, make sure to read the section
about backwards incompatible changes in the section about version 1.2 in the
NEWS file.

If you are upgrading from version 1.0 or earlier (which would mean you missed
Lire 1.1 and Lire 1.2), make sure to read the "Upgrading From Version 1.0 or
Earlier" section at the end of this file.


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

We suggests that you use a binary distribution of Lire when they are available
for your platform. Currently, we offer binary distributions of Lire for Debian
and GNU/Linux RPM based distributions as well as for FreeBSD.


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 send reports by email or to install an online responder, you'll need the 
MIME::Tools package available from you local CPAN mirror.

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 want to generate graphics, you need either:

    - The GD::Graph Perl module, or
    - ploticus

(If you have both installed, that's fine too)

If you plan to use the anonymizer, 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 process big log files, and you'd have to read files > 2 GByte,
your perl should be compiled with large file support.  You can check wether
your perl is OK by running `perl -V' and inspecting `uselargefiles='.  (The
default Red Hat Linux 7.2 perl RPM is reported to lack this support.)  See
also http://logreport.org/contact/lists/development/msg00575.php .

Platform specific information about the requirements is in the `Frequently
Asked Question About Lire' document, shipped with the Lire tarball as doc/faq.*
.


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.


Upgrading from Lire 1.2.1 and earlier
=====================================

With Lire 1.3 and later, some scripts have been removed, and new ones have
been introduced.

New scripts, in bin/:

 lr_env2conf
 lr_store

in libexec/:
 
 lr_functions
 lr_environment

New convertors:

 s1ms2dlf
 tinydns2dlf
 (fw1_lea2dlf FIXME)

Scripts removed from libexec:

 lr_archive_log      (moved to lr_store)
 lr_check_errlines
 lr_db_fetch         (moved to lr_store)
 lr_db_purge         (moved to lr_store)
 lr_db_store         (moved to lr_store)
 lr_dlf_analyze
 lr_prof_report
 lr_tag              (moved to lr_functions)

The convertor test2dlf has been removed.




Upgrading from Lire 1.1 and earlier
===================================

With Lire 1.2 and later you cannot process XML reports generated by a
version 1.1 and earlier of Lire. If there is demand for it, we may
provide a 1.0-2.0 report converter in the future.  For now, you'll have to
reprocess your old log files, if you want reporting on them.

Because of the many changes to the report specifications, one can't merge new
reports with reports generated by a previous version of Lire.  If you're not
using lr_xml_merge(1) or lr_xml2report(1) s' merging capabilities, this won't
affect you.

The summary operator is removed in Lire 1.2 (it's obsoleted by the summary
feature of the new reporting engine).  This will only affect you if you've
written your own report definitions, and used this operator.

LogML output format was dropped in Lire 1.2 (see the NEWS file for more
information).

The configuration variable used to select the way weeks are numbered (this
affect the way weekly aggregation is done) was changed from LR_WEEK_STARTS_ON
to LR_WEEK_NUMBERING in Lire 1.2. You can now choose between U, W and ISO (see
comments in .../etc/lire/defaults for the meaning of these) . You'll get a
warning if you have a LR_WEEK_STARTS_ON configuration variable set.  You might
want to inspect your .../etc/lire/defaults.local and ~/.lire/etc/defaults for
this variable, and adjust it accordingly.


Upgrading from Lire 1.0 and earlier
===================================

With Lire 1.1, some scripts changed names:

 bind8-query2dlf   was renamed to  bind8_query2dlf
 bind9-query2dlf   was renamed to  bind9_query2dlf
 acl_cisco_log2dlf was renamed to  cisco_ios2dlf
 squid2dlf         was renamed to  squid_access2dlf
 ipmon2dlf         was renamed to  ipfilter2dlf

.  Locations of 2dlf convertors changed: all convertors are now installed in
<libexecdir>/lire/convertors/ .  (They used to be in
<libexecdir>/lire/<superservice>/ .)

Services were renamed:

 bind8             was renamed to  bind8_query
 bind9             was renamed to  bind9_query
 cisco             was renamed to  cisco_ios
 squid             was renamed to  squid_access
 lprng             was renamed to  lprng_account
 cups              was renamed to  cups_pagelog

(lr_log2report, lr_log2mail and other command line interfaces still offer
backwards compatibility: they still grok the old service names.)

However, backward compatibility is supported only for commandline tools, not
for online responders' lr_spoold: If you're running an online responder, you
have to rename your mailboxen to the new servicenames manually.  You might want
to set up email aliases to offer backwards compatibility for people mailing
their logs to your responder.

lr_addresses2serviceflags and lr_getaddresses are no longer distributed with
Lire.

LR_TODLF is no longer set in etc/lire/defaults .

Some user interfaces to scripts have changed:  The following scripts no longer
take a superservice argument:

 lr_log2mail
 lr_log2report
 lr_log2xml
 lr_processmail

.

The jobfiles as used by lr_cron(1) no longer need to set the superservice
environment variable.  You might want to clean up your jobfiles (these
have names like /usr/local/etc/lire/email.daily.postfix.1.local).  However,
keeping the variable in won't harm (now).

The subject of the email's send out by lr_log2mail has changed from e.g.

 [LogReport] email / postfix report (was: blah blah)

to

 [LogReport] postfix report (was: blah blah)

.  You might want to update your procmailrc (or any other configation for
your mailfiltering software).



If you made some local extensions, you might get bitten by these change.


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

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


