$Id: README,v 1.111 2004/04/13 22:12:23 flacoste Exp $

Installation
============

Read INSTALL for installation instructions.

Generating a Report From a Log File
===================================
 
Once Lire is installed, you can generate a report from a log file by
invoking the command: 

 $ lr_run lr_log2report sendmail > /tmp/report.txt < /var/log/maillog.2.gz

Of course, if your log file isn't a sendmail log file, you'll will
need to change the 'sendmail' argument for the format of your log
file. This argument is what's called a `service'. A list of `Lire's
services' gets printed by

 $ lr_run lr_check_service -l

This will learn you which log file types are supported. Some popular
services are `postfix', `combined' (for webserver logs) and
`bind9_query'.

By default, text report are generated, you can use the '-o' option to
specify another output format:

 $ lr_run lr_log2report -o html -i combined \
   < /var/log/apache/combined.log.gz \
   |  tar -xf -

The service argument is `combined' here, for webserver's combined, a.k.a.
"extended common log format" as first implemented by NSCA.  In this case, a
report in HTML format is generated in a newly created subdirectory ./report/.
You'll need xsltproc, ploticus and jade for this. PDF output is supported
too.

Read the lr_log2report manpage for more details.

Read the lire(7) manpage for an overview of all available documentation.

Configuring Lire
================

The lire(1) command should be used to modify Lire's configuration. This
is a curses application. You should use the TAB key to navigate across
the various interface elements. The arrow keys should use to navigate
menus. The main menubar can be accessed using F10. 

The mouse might be available depending on your terminal.

The 'Preferences' menu item in the 'Lire' menu will give you access to
all of the Lire settings.

Automatic Report Generation
===========================

DLF Store
---------

The lire(1) command can also be used to create and manage a DLF store.
A DLF store is a log database. In a DLF store, you can configure ImportJobs
and ReportJobs that will be executed regurlarly.

ImportJob
---------

An ImportJob is a job that will import log data into the DLF store. This data
will be used later to generate the reports.

ReportJob
---------

ReportJobs should be used to generate periodical reports. Reports are
generated from the DLF streams available in your DLF store.
The report can be generated for different schedule. Lire supports 5
different schedules: hourly, daily, weekly, monthly and yearly.

ReportSchedules
---------------

You will need to select the report configuration file to use for each
schedule. Defaults are located in <sysconfdir>/lire/, which you should use
as templates that you need to customize according to your purpose.

The reports can be generated either from the log data imported in the
database or from previously generated *daily* reports. This is useful
when you have lots of log data and you don't want to keep all the data
available. The source is selected automatically based on data
availability. But you should note that only 'daily' reports are
considered as a data source for other reports (making that possible
only with weekly or longer schedules).

OutputJob
---------

When executed, a ReportSchedule will only generate the report and save
it in the DLF store. If you want to obtain a formatted copy of the
report, you will need to configure one or more OutputJobs.

Two types of OutputJob are supported:

1- The report can be sent by email to one or more address;

2- or it can saved in a file on the disk. A useful configuration is to
generate HTML reports in a directory published on web site. When using
a "file" OutputJob you will probably want to use strftime(3) expansion so
that the filename is different each time the report is generated. The
most common expansions are:

  %Y - fou digits year (2000);
  %m - two-digits month number (01 for january);
  %V - ISO week number;
  %d - day of the month number; 
  %H - hour of day (01-23).

Also, contrary to the lr_log2report command, HTML reports are
generated in a directory (not as a tar file).

Cron Configuration
------------------

To run the scheduled jobs, you will need to setup cron jobs. For each
schedule you use, you should configure a cron job to be executed
according to that period. The command that shall be executed is:

lr_cron <period> /path/to/store

Here is a crontab(5) entry that will make sure that all possible
schedules are supportd in the /home/flacoste/myStore DLF store:

05  *  *  *  * lr_run lr_cron hourly  /home/flacoste/myStore
15 01  *  *  * lr_run lr_cron daily   /home/flacoste/myStore
15 02  *  * 02 lr_run lr_cron weekly  /home/flacoste/myStore
15 03 01  *  * lr_run lr_cron monthly /home/flacoste/myStore
15 04 01  01 * lr_run lr_cron yearly  /home/flacoste/myStore
