\input texinfo   @c -*-texinfo-*-
@c Copyright (c) 1998 by Georg C. F.  Greve <greve@gnu.org>
@c
@c %**start of header
@setfilename xlogmaster.info
@settitle Xlogmaster
@setchapternewpage on
@c %**end of header

@set EDITION 0.5
@set VERSION 1.4.2
@set UPDATED 21 August 1998
@set UPDATE-MONTH August 1998


@ifinfo
This file documents the Xlogmaster
@sp 1     
Copyright 1998 Georg C. F. Greve <greve@@gnu.org>
@sp 2
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.
@sp 1
@ignore
Permission is granted to process this file through TeX
and print the results, provided the printed document
carries a copying permission notice identical to this
one except for the removal of this paragraph (this
paragraph not being relevant to the printed manual).
@sp 1
@end ignore
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.
@sp 1     
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.
@sp 1
The Xlogmaster is a GNU program.
@sp 1
Free Software Foundation, Inc.,@*
59 Temple Place - Suite 330, Boston, MA  02111,  USA
@end ifinfo

@titlepage
@title The Xlogmaster Tutorial
@subtitle Edition @value{EDITION}, for the Xlogmaster @value{VERSION}
@subtitle @value{UPDATE-MONTH}
@author by Georg C. F. Greve

@c  The following two commands
@c  start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998 Georg C. F. Greve
@sp 2
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.
@sp 1
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.
@sp 1     
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.
@end titlepage

@ifinfo
@node Top, Copying, (dir), (dir)
@top Xlogmaster

The Xlogmaster is a program to monitor @w{system activity (logfiles)} & 
@w{hardware status (devices)} and take actions if neccessary.
@sp 1
This is edition @value{EDITION}, for the Xlogmaster version @value{VERSION}
@end ifinfo

@menu
* Copying::                     Your rights and freedoms.

* Introduction::                Introduction into the Xlogmaster

* Runtime Commands::            How to use the Xlogmaster

* Xlogmaster Concepts::         Internal Xlogmaster workings

* Configuration Files::         The file formats used for configuration

* Concept Index::               Concept Index
@end menu

@node Copying, Introduction, Top, Top
@comment node-name, next, previous, up
@chapter Copying
@cindex Your rights and freedoms.
The Xlogmaster is a GTK+ based program to monitor 
@w{system activity (logfiles)} & @w{hardware status (devices)}
and take actions if neccessary.
@sp 1
Copyright (C) 1998 Georg C. F. Greve
@sp 1
@b{The Xlogmaster is a GNU program.}
@sp 1
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.
@sp 1  
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.
@sp 1
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
@sp 1


@node    Introduction, Runtime Commands, Copying, Top
@comment node-name,     next,           previous, up
@chapter Introduction into the Xlogmaster
@cindex Introduction into the Xlogmaster

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

@cartouche
@sc{Right mouse button in text window brings up menu}
@sp 1
@sc{Middle mouse button in text window hides/shows buttons}
@end cartouche

@sp 2

The first version of the Xlogmaster has been written in 1996, using the
@sc{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''.
@sp 1
June 1998 I finally managed to actually keep this promise and completely
rewrote the Xlogmaster for the @sc{Gtk}+ toolkit (see 
@w{@file{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 @sc{Gnu} program.
@sp 1
The Xlogmaster will allow you to monitor all your logfiles and all
devices that allow being read by @code{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.
@sp 1
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 
@emph{ not guarantee for anything} but my best will.


@node    Runtime Commands, Xlogmaster Concepts, Introduction, Top
@comment node-name,     next,           previous, up
@chapter How to use the Xlogmaster
@cindex 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.
@sp 1
There are more functions that are less obvious:

@example
@group

@code{right mouse button} will bring up the menu.

@code{middle mouse button} will toggle whether the buttons are being
shown/hidden.

@code{left mouse button} will pick the standard selection (for
cut&paste).

@end group
@end example

these do only work in the @emph{text window}, though.
@sp 1
Apart from that you can use the cursor-keys to move the standard
selection around and activate it by hitting @key{RET}.
@sp 1
The configuration should be self explanatory, if you keep the mouse
pointer over an object a small help window will pop up.


@node    Xlogmaster Concepts, Configuration Files, Runtime Commands, Top
@comment node-name,     next,           previous, up
@chapter Internal workings of the Xlogmaster
@cindex Internal workings of the Xlogmaster
@ifinfo

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

@end ifinfo
@menu
* Modes::                       Description of the main modes
* Filters::                     Information about the filters
* Audio Support::               Audio Support for @emph{Class 1} filters
@end menu

@node Modes, Filters, Xlogmaster Concepts, Xlogmaster Concepts
@comment  node-name,  next,  previous,  up
@section Modes
@cindex Modes

The Xlogmaster knows basically two modes of operation, the 
@emph{tail mode} and the @emph{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 (@emph{tail mode}) or how often it replaces the data in the
buffer with the current data (@emph{cat mode}).


@menu
* Tail mode::                   Details about the Tail mode
* Cat mode::                    Details about the Cat mode
@end menu

@node Tail mode, Cat mode, Modes, Modes
@comment  node-name,  next,  previous,  up
@subsection Tail mode
@cindex Tail mode
The @emph{tail} mode basically works like using @code{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.



@node Cat mode,  , Tail mode, Modes
@comment  node-name,  next,  previous,  up
@subsection Cat mode
@cindex Cat mode
The @emph{cat} mode works like doing a @code{cat <filename>} so it reads
the whole file every time. This is neccessary for reading things like
the @file{/proc} devices.


@page
@node Filters, Audio Support, Modes, Xlogmaster Concepts
@comment  node-name,  next,  previous,  up
@section Filters
@cindex Filters

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

@menu
* Class 0 filters::             Details about the Class 0 filters
* Class 1 filters::             Details about the Class 1 filters
@end menu



@node Class 0 filters, Class 1 filters, Filters, Filters
@comment  node-name,  next,  previous,  up
@subsection Class 0 filters
@cindex Class 0 filters
As mentioned before @emph{Class 0} filters are being applied at
@emph{display-time} --- if a line triggered multiple filters @b{only}
the one with the highest priority is being applied ! 

The filters are (from highest to lowest priority):

@menu
* Hide::                        Functionality of the @dfn{Hide} filter
* Raise::                       Functionality of the @dfn{Raise} filter
* Lower::                       Functionality of the @dfn{Lower} filter
@end menu

@node Hide, Raise, Class 0 filters, Class 0 filters
@comment  node-name,  next,  previous,  up
@subsubsection Hide
@cindex Hide filter (Class 0)
Lines that trigger this action will be hidden without paying attention
whether the line triggered other @emph{Class 0} filters or not. Lines
that do trigger any of these will be displayed the usual way.

@node Raise, Lower, Hide, Class 0 filters
@comment  node-name,  next,  previous,  up
@subsubsection Raise
@cindex Raise filter (Class 0)
Lines that triggered this acton will be raised (highlighted) without
paying attention whether they also triggered a @emph{Lower} action.


@node Lower,  , Raise, Class 0 filters
@comment  node-name,  next,  previous,  up
@subsubsection Lower
@cindex Lower filter (Class 0)
Lines that triggered this action will be lowered (lowlighted).



@node Class 1 filters,  , Class 0 filters, Filters
@comment  node-name,  next,  previous,  up
@subsection Class 1 filters
@cindex Class 1 filters
@emph{Class 1} filters are being applied at @emph{read-time}  ---
logfiles with @emph{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 @emph{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 @strong{not} exclude each
other, though. Each filter that can be applied will be applied !

@menu
* Alert::                       Functionality of the @dfn{Alert} filter
* Execute::                     Functionality of the @dfn{Execute} filter
* Notice::                      Functionality of the @dfn{Notice} filter
* Uniconify::                   Functionality of the @dfn{Uniconify} filter
@end menu

@node Alert, Execute, Class 1 filters, Class 1 filters
@comment  node-name,  next,  previous,  up
@subsubsection Alert
@cindex Alert filter (Class 1)
The button of the entry that triggered the alert will flash in the
@emph{alert color} and then slowly fades back
to it's normal color. The @emph{alert color}, the time it takes to fade
back and the smoothness of the fading can be controlled at
@emph{configure-time} as well as @emph{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 @emph{alert color} additionally you get an impression
of how recent the alert was if you catch it while fading back.

@node Execute, Notice, Alert, Class 1 filters
@comment  node-name,  next,  previous,  up
@subsubsection Execute
@cindex Execute filter (Class 1)

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 commandline. The following variables / environment variables are
known:
@table @samp
@item %F
@itemx XLM_FILENAME
absoute path to file/device of entry.
@item %H
@itemx XLM_HELP
helptext of entry.
@item %L
@itemx XLM_LINE
line that actually triggered the Execute filter.
@item %M
@itemx XLM_MODE
mode of entry.
@item %N
@itemx XLM_NAME
name of the Logfile that triggered the Execute filter.
@end table
@sp 1
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 shellscript. This
especially means that piping will @emph{not} work.

@node Notice, Uniconify, Execute, Class 1 filters
@comment  node-name,  next,  previous,  up
@subsubsection Notice
@cindex Notice filter (Class 1)

This filter has been implemented for events that are of extreme
importantce 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 @samp{--notice-follows-mouse} at startup the notice box will
move to the current mouse position every time something new has been
added.

@node Uniconify,  , Notice, Class 1 filters
@comment  node-name,  next,  previous,  up
@subsubsection Uniconify
@cindex Uniconify filter (Class 1)

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.

@node Audio Support,  , Filters, Xlogmaster Concepts
@comment  node-name,  next,  previous,  up
@section Audio Support
@cindex Audio Support

The Xlogmaster has Open Sound System (OSS) support. For every
@emph{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 @code{cat <soundfile> > /dev/dsp}. This usually means
they should be about 8KHz and in a standard format (@samp{Wave},
@samp{ULaw} or @samp{SUN audio} for instance).
@*
Please check out the commandline options for setting of the
soundfiles. If nothing is given the Xlogmaster will use the files in
@file{$prefix/etc/sound}. The standard is to play back the files
called @file{notice}, @file{alert} or @file{uniconify} --- I'd recommend
to make then symbolic links instead of actually copying the files there.

@node Configuration Files, Concept Index, Xlogmaster Concepts, Top
@comment  node-name,  next,  previous,  up
@chapter Configuration Files
@cindex Configuration Files

@menu
* Configfile Introduction::     A short overview over the used formats
* Xlogmasterrc format::         The main configuration file for all entries
@end menu

@node Configfile Introduction, Xlogmasterrc format, Configuration Files, Configuration Files
@comment  node-name,  next,  previous,  up
@section Configfile Introduction
@cindex Configfile Introduction

There are two different filetypes used for configuration by the
Xlogmaster. 
One is the GTK+ special style file, the @dfn{gtkrc} file I do not want
to say too much about that one because it is documented with the GTK+
toolkit 
(@inforef{Resource Files, GTK+ style file, GTK})
and it's format is actually pretty simple. 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.
@sp 1
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.
@sp 1

@node Xlogmasterrc format,  , Configfile Introduction, Configuration Files
@comment  node-name,  next,  previous,  up
@section Xlogmaster configuration file format
@cindex 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 @dfn{mode} of the entry along with it's name
and some more information. The format for this kind of entry is
@sp 1
@samp{MODE@{FILENAME,INTERVAL,BUTTONTEXT,HELPTEXT@}}
@sp 1
where the fields are the same as in the customization menu:
@*
@table @samp
@item MODE
The mode for the entry
(See @pxref{Modes, modes})
, either @dfn{TAIL} or @dfn{CAT}
@item FILENAME
The absolute path to the file or device that the entry is for.
@item INTERVAL
The interval (in tenth of seconds) for this entry.
(See @pxref{Modes, mode descriptions})
@item BUTTONTEXT
The name to appear on the button for the entry.
@item HELPTEXT
The text that should pop up when the mouse pointer has been pending over
the button for a short while.
@end table
@sp 2
The second kind of entry is the one for the filters. A filter line looks
like
@sp 1
@samp{MODES@{REGEX@}}
@sp 1
the @samp{MODES} are a comma separated list of filter modes (only one
@emph{Class 0} filter is allowed) and the @samp{REGEX} is a standard
regular expression (see GNU Regex manual). The filter lines always apply
to the
@sp 1
Available strings for the @samp{MODES} are
@table @samp
@item RAISE
A display-time filter.
(See @pxref{Class 0 filters})
@item LOWER
A display-time filter.
(See @pxref{Class 0 filters})
@item HIDE
A display-time filter.
(See @pxref{Class 0 filters})
@item NOTICE
A background filter.
(See @pxref{Class 1 filters})
@item ALERT
A background filter.
(See @pxref{Class 1 filters})
@item UNICONIFY
A background filter.
(See @pxref{Class 1 filters})
@item EXECUTE
A background filter.
(See @pxref{Class 1 filters})
This filter requires another argument -- the commandline that will be
executed when a line matches the @emph{REGEX}. The commandline is just
appended in @samp{@{   @}} brackets.
(See @pxref{Execute})
@item INVERT
invert sense of matching --- all non-matching lines will trigger a
filter
@item CASE_SENSITIVE
matching is performed case sensitive
@end table
@sp 1
Here are some lines to give you an example of how a proper xlogmasterrc
file looks.
@sp 1
@example
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@}
@end example






@node    Concept Index,  , Configuration Files, Top
@c        node-name,    next, previous,        up
@unnumbered Concept Index

@printindex cp
     
@contents
@bye
