
Interceptor 1.2.9 Copyright 2011 Christophe Gros <skylendar@yahoo.com>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU Library General Public License as
published by the Free Software Foundation; either version 2 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 Library General Public
License along with this program; if not, write to the
Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.


Interceptor is a Plasmoid for KDE4 on Posix systems, such as
Linux. Its role is to intercept (catch) the log info from the syslog
daemon, to flash whenever a log line is processed, and display it on a
panel.
In addition, interceptor can send an adequate notification to the
KDE4 systray when a log line matches a given regular expression.
This notification can even include an interaction, i.e. a button is
displayed, that executes a command when clicked.


INSTALLATION
============

In order to install interceptor, you need the KDE4 devel packages
installed on your computer, and also the cmake utility.
Then, from a shell, run the following commands:

tar xjf <your path>/interceptor-1.2.8.tar.bz2
cd interceptor
mkdir build
cd build
cmake ../interceptor
make
su
make install

...
Notice that <your path> is the path where you downloaded the
interceptor archive. You probably need to give the root password when
"su" is executed.

IMPORTANT
=========

Before using interceptor, you must execute AS ROOT the mkintfifos
utility. Then reboot the computer. If you upgrade from a prior
version, you should edit the /etc/syslog.conf or /etc/rsyslog.conf file
and replace all the lines containing *. with *.=

Example:

*.debug     |/var/run/interceptor/debug

replace with

*.=debug     |/var/run/interceptor/debug;RSYSLOG_TraditionalFileFormat


USAGE
=====

On the desktop or on the taskbar, select Add Plasmoids. You should see
the Interceptor icon. Double-click on it or drag it onto the desktop.
As an icon, the little jet will flash green when a debug, info or
notice message is coming in, flashes orange when warning or error and
red otherwise.
If needed, click on the icon in order to display the panel.
If you double-click on a message, a dialog box appears, that displays
its content.
  
CONFIGURATION
=============

Right-click on the icon or on the panel and select Interceptor
Settings.

Notifications:

The Notifications dialog box will allow you to edit the action(s)
performed when a log line matched a given pattern.
Click on New and a empty notification is created.
Give a name, a qt RegExp pattern (see
http://doc.qt.nokia.com/4.7/qregexp.html#introduction), a comment that
will be displayed on the systray message and a possible icon. Just
give the icon name. No path or extention is needed.

Example:

Name=wifi timeout
Pattern=wlan0.*Timeout
Comment=Hey! Your wifi is down!!
Icon=network-wireless-0

The qt RegExp is always tested on a text line having the following format:

level##source!!host%%text

where level is debug, warning, etc... source, the source of the
message, host the hostname and the message text. If the comment is
empty, the current line is ignored, so that you can filter out
unwanted messages.

The displayed comment accepts variables matching the captured
substrings in a RegExp pattern

 $1 the 1st pattern
 $2 the 2nd
 $3 3rd
 $4 4th

and $D for the message date and $T for its time.

Example:

Pattern=usb 1-1: (.*): TX timeout
Comment=Hey! your wifi $1 was down at $T!

On the notifications editor, you can test your current QRegExp with a
sample line. Then click on the test button and Interceptor will tell you
whether the line matches your regular expression or not.

The third line of the notification declaration optionaly proposes to
set up an interaction. The format of this interaction is a title and a
command separated with a ::
the command part of the line is also subject to variable
substitutions.

Example:

InterAction=Send immediate Email::echo "Security breach on $1 at $T" | mail -s "Security breach" root@localhost

An anonymous button has been added, that shows the chosen icon (if
any) of the selected notification. Click on this button and you will
be able to select more easily your icon from a file dialog box with a
possible preview.

Anti-flooding system.
A daemon or the kernel may send bursts of the same message,
typically when reading a damaged CD. In order to avoid a flooding of
useless messages, a delay is associated with each known pattern, so
that an incoming message will be abandoned if an equivalent log line
has already been displayed within this delay.

Interceptor works fine with the KDE4 systemsettings. You can add other
behaviors to your notifications with the Configuration of the
Notifications, such as playing a sound, executing a command or even
speaking!

								Author: Christophe Gros <skylendar@yahoo.com>

								Date: September 8th, 2011

								http://skylendar.kde.org/interceptor


