   This file documents the Xlogmaster

   Copyright 1998 Georg C. F. Greve <greve@gnu.org>

   Contributers to this documentation also were:

   Adrian Wontroba <aw1@stade.co.uk>

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "Copying" and "GNU General Public License"
are included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by Georg C. F. Greve.

   The Xlogmaster is a GNU program.

   Free Software Foundation, Inc.,
59 Temple Place - Suite 330, Boston, MA  02111,  USA

Xlogmaster
**********

   The Xlogmaster is a program to monitor system activity (logfiles) &
hardware status (devices) and take actions if necessary.

   This is edition 0.8, for the Xlogmaster version 1.6.0

Copying
*******

   The Xlogmaster is a GTK+ based program to monitor
system activity (logfiles) & hardware status (devices) and take actions
if necessary.

   Copyright (C) 1998 Georg C. F. Greve

   The Xlogmaster is a GNU program.

   This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.

   This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

   You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software Foundation,
Inc.,  Temple Place, Suite 330, Boston, MA  02111-1307  USA

Introduction into the Xlogmaster
********************************

   Hint for people that are too impatient to read the full documentation
(as I usually am):

   RIGHT MOUSE BUTTON IN TEXT WINDOW BRINGS UP MENU

   MIDDLE MOUSE BUTTON IN TEXT WINDOW HIDES/SHOWS BUTTONS

   The first version of the Xlogmaster has been written in 1996, using
the XVIEW toolkit. I didn't like that toolkit too much so it all ended
up in a pretty messy piece of code that was only compile-time
configurable and not very stable -- I did use it for two years, though,
always telling myself "I'll be writing a clean version soon".

   June 1998 I finally managed to actually keep this promise and
completely rewrote the Xlogmaster for the GTK+ toolkit (see
`http://www.gtk.org/'). First I only intended to write it for my
private usage but when I got a lot of feedback from people around the
world I decided to make the Xlogmaster a real and regular project. With
version 1.4.0 the Xlogmaster then became an official GNU program.

   The Xlogmaster will allow you to monitor all your logfiles and all
devices that allow being read by `cat'. Furthermore it supplies several
filters that will do things from raising/hiding lines in the text
display to starting programs to send you a paging message about a
possible security breach.

   If used wisely the Xlogmaster can make it very easy to keep track of
everything that happens on your system and it can increase your systems
security by quite a lot. This program has been written and published in
the hope that it will prove useful to you but I do * not guarantee for
anything* but my best will.

How to use the Xlogmaster
*************************

   The Xlogmaster runtime usage is basically pretty simple. There is a
button on the side for each entry and as you might have guessed clicking
on the button will make the Xlogmaster display that entry.

   There are more functions that are less obvious:

     `right mouse button' will bring up the menu.

     `middle mouse button' will toggle whether the buttons are being
     shown/hidden.

     `left mouse button' will pick the standard selection (for
     cut&paste).

   these do only work in the *text window*, though.

   Apart from that you can use the cursor-keys to move the standard
selection around and activate it by hitting <RET>.

   The configuration should be self explanatory, if you keep the mouse
pointer over an object a small help window will pop up.

Internal workings of the Xlogmaster
***********************************

   The two concepts you should definitely know about within the
Xlogmaster are

Modes
=====

   The Xlogmaster knows basically two modes of operation, the *tail
mode* and the *cat mode*. Both modes are named after the programs they
emulate.

   For both modes you can give an interval -- this is the time (in 1/10
seconds) between two calls of the interrupt function. This interval
directly  determines how often the Xlogmaster checks for changes in the
logfile (*tail mode*) or how often it replaces the data in the buffer
with the current data (*cat mode*).

Tail mode
---------

   The *tail* mode basically works like using `tail -f' on a logfile.
It will read a file and then keep on reading whatever gets appended to
it over time. The Xlogmaster should also be able to catch logfile
rotations so you don't have to reopen it every time the logfiles have
been rotated.

Cat mode
--------

   The *cat* mode works like doing a `cat <filename>' so it reads the
whole file every time. This is necessary for reading things like the
`/proc' devices.

Run mode
--------

   The *run* mode gives you the opportunity to execute any script or
program that you can think of to retrieve some data that is of interest
for you and process it's *stdout* and *stderr* with the Xlogmaster.
The *run* mode has one more parameter than the other modes, the "DELAY"
interval (given in tenth of seconds) that determines the time between
an end of the monitored process and it's restart.
     If you monitor the output of `w' (a very nice one to monitor, btw.)
     and give it a *delay* of 10 and an *interval* of 3 it will
     cause the Xlogmaster to do the following:
        * execute `w'

        * look for output from it every 0.3 seconds

        * process the output with Class 1 filters

        * display if necessary

        * once the program terminated: wait 1 second

        * start at the beginning

Filters
=======

   The Xlogmaster has two classes of filters, enumerated *Class 0* and
*Class 1* filters. The main difference is that the *Class 0* filters
are filters being applied at *display time* while the *Class 1* filters
are being applied at *read-time*.
Matching for the filters is *always* done per line -- patterns that
would match more than one line will *never* match anything !

   The following filters are known:

Class 0 filters
---------------

   As mentioned before *Class 0* filters are being applied at
*display-time* -- if a line triggered multiple filters only the one
with the highest priority is being applied !

   The filters are (from highest to lowest priority):

Hide
....

   Lines that trigger this action will be hidden without paying
attention whether the line triggered other *Class 0* filters or not.
Lines that do trigger any of these will be displayed the usual way.

Raise
.....

   Lines that triggered this acton will be raised (highlighted) without
paying attention whether they also triggered a *Lower* action.

Lower
.....

   Lines that triggered this action will be lowered (lowlighted).

Class 1 filters
---------------

   *Class 1* filters are being applied at *read-time*  -- logfiles with
*Class 1* filters are being watched in the background, the filters will
do exactly the same thing regardless of whether you are just looking at
that logfile or not.

   The *Class 1* filters will be triggered for each line they can be
applied on, but each filter only once (even if the string would
theoretically match multiple times). They do *not* exclude each other,
though. Each filter that can be applied will be applied !

Alert
.....

   The button of the entry that triggered the alert will flash in the
*alert color* and then slowly fades back to it's normal color. The
*alert color*, the time it takes to fade back and the smoothness of the
fading can be controlled at *configure-time* as well as *runtime*.

   The purpose of this filter is to inform you of events that are of
interest right now but become less important over time -- the fading
back prevents a situation that you come back to your machine and find
all the buttons in *alert color* additionally you get an impression of
how recent the alert was if you catch it while fading back.

Execute
.......

   This filter allows you to start programs and/or scripts when a
certain string shows up. This is potentially the most powerful of the
filters. Your program gets it's information via environment variables or
via command line. The following variables / environment variables are
known:
`%F'
`XLM_FILENAME'
     absolute path to file/device of entry.

`%H'
`XLM_HELP'
     help text of entry.

`%L'
`XLM_LINE'
     line that actually triggered the Execute filter.

`%M'
`XLM_MODE'
     mode of entry.

`%N'
`XLM_NAME'
     name of the Logfile that triggered the Execute filter.

   A word of warning: the execute entry will only process one command
and substitute the variables accordingly. If you want to create a more
complicated setup I'd recommend to write a small shell script. This
especially means that piping will *not* work.

Notice
......

   This filter has been implemented for events that are of extreme
importance regardless of when they have been triggered. A notice box is
being popped up at the current mouse position. This notice box contains
a list with the time and date of the triggering action as well as the
name of the entry that triggered it. If you click on an entry in this
list you'll see the triggering line in the text field below the list.

   If you set `--notice-follows-mouse' at startup the notice box will
move to the current mouse position every time something new has been
added.

Uniconify
.........

   For people who like to keep the Xlogmaster iconifed because of space
shortage. If you set this filter the Xlogmaster will uniconify
automatically when a matching line has been seen.

Audio Support
=============

   The Xlogmaster has Open Sound System (OSS) support. For every *Class
1* filter type (the only exception being execute) you can define a
sound that gets played whenever this filter type has been triggered.
The requirements that the sounds have to meet are simple: They need to
be playable via `cat <soundfile> > /dev/dsp'. This usually means they
should be about 8KHz and in a standard format (`Wave', `ULaw' or `SUN
audio' for instance).
Please check out the command line options for setting of the sound
files. If nothing is given the Xlogmaster will use the files in
`$prefix/etc/sound'. The standard is to play back the files called
`notice', `alert' or `uniconify' -- I'd recommend to make then symbolic
links instead of actually copying the files there.

Configuration Files
*******************

Configfile Introduction
=======================

   There are two different file types used for configuration by the
Xlogmaster.  One is the GTK+ special style file, the "gtkrc" file I do
not want to say too much about that one because it is documented with
the GTK+ toolkit (see GTK+ style file (GTK).
A look at the sample files
distributed along with the Xlogmaster should already solve all
questions, so feel free to check them out and try around with them.
They allow you to control the look of the Xlogmaster any way you want
and it's definitely worth risking a look.

   The Xlogmaster internal configuration file is pure ASCII and can
hence be processed easily with any text editor although you will most
probably not need to do so because the customization menu is much nicer.

Xlogmaster configuration file location
======================================

   Xlogmaster looks for a configuration file in the following sequence,
using the first found. If no configuration file is found, a set of
internal defaults is used.

   * The file specified by the `-f' command line option.

   * A `.xlogmaster' file in the user's home directory.

   * A `xlogmasterrc' file in the Xlogmaster style directory.
     E.g.  `/usr/X11R6/etc/xlogmaster/xlogmasterrc' for some systems.

Xlogmaster configuration file format
====================================

   The format is line oriented, this means every entry needs to use
exactly one line. Entries that do not follow this policy will be
ignored.

   There are two kinds of entries for the configuration file, the first
is a line that contains the "mode" of the entry along with it's name
and some more information. The format for this kind of entry is

   `MODE{FILENAME,INTERVAL[/DELAY],BUTTONTEXT,HELPTEXT}'

   where the fields are the same as in the customization menu:
`MODE'
     The mode for the entry (See modes)  , either "TAIL"
     or "CAT"

`FILENAME'
     The absolute path to the file or device that the entry is for.

`INTERVAL'
     The interval (in tenth of seconds) for this entry.  (See
     mode descriptions)

`DELAY'
     The delay (in tenth of seconds) for this entry. The delay is
     *optional* and *only* applies to the "RUN" mode, anyways.  (See
     mode descriptions)

`BUTTONTEXT'
     The name to appear on the button for the entry.

`HELPTEXT'
     The text that should pop up when the mouse pointer has been
     pending over the button for a short while.

The second kind of entry is the one for the filters. A filter line looks
like

   `MODES{REGEX}'

   the `MODES' are a comma separated list of filter modes (only one
*Class 0* filter is allowed) and the `REGEX' is a standard regular
expression (see GNU Regex manual). The filter lines always apply to the

   Available strings for the `MODES' are
`RAISE'
     A display-time filter.  (See Class 0 filters.)

`LOWER'
     A display-time filter.  (See Class 0 filters.)

`HIDE'
     A display-time filter.  (See Class 0 filters.)

`NOTICE'
     A background filter.  (See Class 1 filters.)

`ALERT'
     A background filter.  (See Class 1 filters.)

`UNICONIFY'
     A background filter.  (See Class 1 filters.)

`EXECUTE'
     A background filter.  (See Class 1 filters.)  This filter
     requires another argument - the command line that will be executed
     when a line matches the *REGEX*. The command line is just appended
     in `{   }' brackets.  (See Execute.)

`INVERT'
     invert sense of matching -- all non-matching lines will trigger a
     filter

`CASE_SENSITIVE'
     matching is performed case sensitive

   Here are some lines to give you an example of how a proper
xlogmasterrc file looks.

     TAIL{/var/log/messages,3,System Messages,/var/log/messages}
     RAISE{greve}
     HIDE{accesswatch}
     HIDE{faxqclean}
     HIDE{uucpcontrol}
     HIDE{touch.*/tmp/newsrun}
     TAIL{/var/log/warn,3,Warning Messages,/var/log/warn}
     TAIL{/var/adm/kernel,3,Kernel Messages,/var/adm/kernel}
     TAIL{/var/adm/debug,3,Debugging Messages,/var/adm/debug}
     RAISE,NOTICE{accesswatch}
     HIDE{newsrun}
     EXECUTE,CASE_SENSITIVE{uucpcontrol}{xlm-mail greve}
     RUN{w,3/10,Who's Online,...tell me who's online...}
     ALERT{root}

Frequently Answered Questions
*****************************

   This is a list of frequently asked questions (FAQ's) about the
Xlogmaster with answers.

   If you know the answer of a question is in the FAQ list, please
reply to the question by e-mail instead of posting.  Help reduce noise!

   Please suggest new questions, answers, wording changes, deletions,
etc.  The most helpful form for suggestions is a context diff (i.e. the
output of `diff -c').  Include `FAQ' in the subject of messages sent to
me about the FAQ list.

   Please do not send questions to me just because you do not want to
disturb a lot of people and you think I would know the answer.  I do
not have time to answer questions individually and keep up with
everything else I have to get done. Questions to me that have been
answered before slow down development and that is bad for everyone.

Introductory Questions
======================

What is the Xlogmaster ?
------------------------

   The Xlogmaster is a GTK+ (see the GIMP toolkit page under
http://www.gimp.org/ for more information) based program that helps you
to monitor all kinds of system activity. It allows monitoring and
background surveillance of all logfiles and devices that allow being
read by `cat' like the `/proc' devices. You can configure the
Xlogmaster graphically to take almost any action you can think of upon
certain events and it can certainly help you keeping track of everything
and increasing system security.

What is the current version of the Xlogmaster ?
-----------------------------------------------

   The current version is 1.6.0, yet to be released.

Where can I find it?
--------------------

   The source can be found via anonymous FTP at `ftp.gnu.org:/pub/gnu/'.

Where can I get help for using the Xlogmaster ?
-----------------------------------------------

   If you installed everything correctly the easiest ways are probably
*
     the tutorial that should be in your info tree. Otherwise you can
     find it in the `doc' directory of the distribution

*
     the man page.

*
     executing the Xlogmaster via `xlogmaster --help' Other ways are to
check out the home page at
     `http://www.gnu.org/software/xlogmaster/xlogmaster.html' or the
mailing lists
*
     `beta-xlogmaster@gnu.org'

     Subscription is done by sending a mail to
     `beta-xlogmaster-request@gnu.org'
     leave the *subject* blank and enter `subscribe' in the *body*.

*
     `help-xlogmaster@gnu.org'

     Subscription is done by sending a mail to
     `help-xlogmaster-request@gnu.org'
     leave the *subject* blank and enter `subscribe' in the *body*.

Regular Expressions
-------------------

   This is a brief and shallow outline. For more details, consult the
'ed' man page (man ed), or the GNU regex info file (if you have it
installed).

   Regular expressions are a means of specifying a text pattern.
Xlogmaster uses them in its filter specifications, where lines
containing the pattern activate the filter.

   There are however a number of characters and character sequences
which have a special meaning - which may change on the context.

`^'
     matches start of line.
     Negates a character class.

`$'
     matches end of line.

`.'
     matches any character.

`\('
     starts a subexpression.

`\)'
     ends a subexpression.

`\|'
     Alternation (OR) operator.

`['
     Starts a character class.

`]'
     Ends a character class.

`*'
     Matches ZERO OR MORE occurrences of the preceding expression.

`+'
     Matches ONE OR MORE occurrences of the preceding expression.

   At their simplist, regular expressions are just text strings, for
example:

`kernel'
     would match any line containing the string `kernel' anywhere
     within it.

   Slightly more complicated expressions, and their effects, are:

`^kernel.*link'
     would match any line starting `kernel', followed by any number of
     characters (including zero), and `link'.

`\(kernel\)\|\(link\)'
     would match any line containing 'kernel' or 'link'.

`[a-z][0-9a-z_]*'
     would match many languages' idea of an identifier, that is, starts
     with a letter, followed by any number of letters, digits or the
     character '_'.

Compiling the Xlogmaster
========================

Normal installation
-------------------

   Normal installation is done by unpacking the archive and then
entering it. `./configure ; make ; make install' should do everything
then. The default is to install it into the `/usr/local' structure. If
you want to change that and for other configuration options, please see
`./configure --help'.

   Note. If you are using a FreeBSD system and want to compile from
source, consider using the port `/usr/ports/sysutils/xlogmaster'. If
you just want to install an executable version, consider using the
package.

Make doesn't seem to understand the Makefiles
---------------------------------------------

   This can happen on some systems (especially SunOS or old Solaris
ones) - the problem is easily fixed by using `gmake' instead of `make'.