Xlogmaster Tutorial

Edition 0.5, for Xlogmaster 1.4.2

August 1998

Original work by Georg C. F. Greve

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.

Copying

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

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 to 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 Xlogmaster was written in 1996, using the XVIEW toolkit. Georg 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 -- Georg did use it for two years, though, always telling himself "I'll be writing a clean version soon".

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

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 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 Xlogmaster

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 Xlogmaster

Modes

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 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. 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.

Filters

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 commandline. The following variables / environment variables are known:

`%F'
`XLM_FILENAME': absoute path to file/device of entry.
`%H'
`XLM_HELP': helptext 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 shellscript. 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 Xlogmaster iconifed because of space shortage. If you set this filter 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 commandline options for setting of the soundfiles. If nothing is given 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 filetypes used for configuration by 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 Info file `GTK', node `Resource Files') and it's format is actually pretty simple. A look at the sample files distributed along with 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 Xlogmaster any way you want and it's definitely worth risking a look.

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 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,BUTTONTEXT,HELPTEXT}'

where the fields are the same as in the customization menu:

`MODE': The mode for the entry (See see section 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 see section Modes)
`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 see section Class 0 filters)
`LOWER': A display-time filter. (See see section Class 0 filters)
`HIDE': A display-time filter. (See see section Class 0 filters)
`NOTICE': A background filter. (See see section Class 1 filters)
`ALERT': A background filter. (See see section Class 1 filters)
`UNICONIFY': A background filter. (See see section Class 1 filters)
`EXECUTE': A background filter. (See see section Class 1 filters) This filter requires another argument -- the commandline that will be executed when a line matches the REGEX. The commandline is just appended in `{ }' brackets. (See see section 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}