/*
 * SLogger by Romano Giannetti (C) 2001 --- released under GPLv2
 * Please READ the LICENSE and COPYING files
 */

1 - INTRODUCTION

Welcome to SLogger, the Simple Logger program by RGtti. 

This program is designed to monitor the logfiles of a Unix system. 
I know there are a lot of such programs around there, but almost all are
very nice, big, and complex programs. My objective was to have a tool as
simple as possible.

The basic idea is: to control some logfile (user-configurable), and to
print/display the new information appeared in the file; all in the same
place, with different colors for different kinds of information, so that you
could "see" at a glance what your system is doing. The target machine is the
normal workstation, not a server. 

To keep the program simple, I decided _not_ to build it with a graphical
interface. SLogger is command-line driven, and outputs its information on
the standard output, using the ANSI color codes. The graphical interface is
obtained by running it in a terminal emulator or whatever alphanumeric
display. 

2 - INSTALL

Unpack the file with the usual 
   
    tar xvzf slogger-X.X.tar.gz 
    cd slogger
    
if you have a RedHat 7.1, you will find two executable here; otherwise 
    
    make clean all

will build two executable files, 'slogger' and 'testcol'. There is no need
to install; simple copy them somewhere in the PATH. The main program is
'slogger'; 'testcol' is a simple utility to check terminal colors. 

3 - HOW-TO USE IT


3.1 - colors 

SLogger has a simple concept of colors: if the terminal is enabled, there
will be 8 colors for foreground or background. To the foreground color, it
is possible to add a number that is 8*attribute, where the attribute is a
number between 0 and 15; what you obtain depend on the terminal: in an rxvt,
for example, attribute=1 is bold (so that 9 is 8+1, color 1 bold) and 4 is
underline (33 is 4*8+1, underlined red). If you use "-1" instead of a color,
the default one is used. It is simpler to see than to explain: open a
xterm, and run "testcol" in it. You will see a table with the available
colors.

3.2 - the configuration file

SLogger needs a configuration file as its only argument. An example of
configuration file is pern.slc included in this same directory. The
configuration file is structured in two parts: a preamble and a list of
"filewatches". A line starting with a hash (#) is ignored, as well as empty
lines. 

3.2.1 - the preamble

The preamble is made of some (or none) of the following commands: 

SLEEP       1000
WAIT       10000
SLCOLORS     3 0
MAXCHAR     4000
MAXDUMP        0

The value(s) shown in the lines are the defaults one. 

SLEEP 1000
      is the time, in milliseconds, between two consecutive checks on a
      file to test if it has changed in size. The lower the value, the
      "faster" is SLogger in displaying messages, but the load on the system
      will be higher, too. 
      
WAIT  10000
      is very similar. It is the time between check for "consistency" of the
      files. SLogger opens the files and then keeps them opened (so that it
      does not need to do an open+lseek every SLEEP milliseconds for every
      file). But given U*ix file descriptor semantic, this is "dangerous":
      suppose you are monitoring /var/log/messages and someone (say, a cron
      job) do a "mv /var/log/messages /var/log/messages.1". Now, your fd
      refers to the /var/log/messages.1 file, and no one will never again
      write to it. So, every WAIT milliseconds, SLogger check if its file
      descriptor is pointing to the right file, and if not, close and reopen
      it (see more about it in the WATCH description).    

SLCOLORS  3 -1
      foreground and background color for the messages from SLogger itself
      (and not some file contents). 
      
MAXCHAR 4000
      max number of character per line accepted scanning the files watched. 
      If a line is longer than this, it is broken at this value, and put in
      two different lines. 
      
MAXDUMP    0
     max number of bytes printed in a single step for any file watched. 0
     means "no limit". Sometime a rogue program dumps 1Mbyte in
     /var/log/debug, and the logger windows is scrolling fast and absolutely
     unreadable text during minutes. If set, and if a file grows of more
     bytes than the specified here, SLogger prints a warning and skips the
     bytes till the next cycle. Don't let it 0; set it to something sensible
     (like 10000 or similar). 
     
3.2.2 - the "filewatches" 

There are two kinds of entries in this section, that must appear *after* the
preamble: WATCH and REXP. 

In the following context, the <file path>, <nick> and <re> arguments are
strings. Strings can be of two types: unquoted, which are string delimited
by blank spaces (so that they cannot contain spaces), and quoted, which are
string limited by a double quotation sign '"' (ascii 34). Quoted string
can't contain an explicit '"'. For example 

     file name sil"ly  -> three strings, 'file', 'name', and 'sil"ly';
     "file name"       -> one string, 'file name" 
     "file name sil"ly"-> two strings, 'file name sil' and 'ly"' 
     
I hope that's clear enough...

WATCH <file path> <nick> <fg> <bg> <cut_b> <cut_e> <flags>
     this is the main entry in the configuration file; you need at least one
     of it. This set a "filewatch" to "spy" the contents of the file
     specified in <file path>. When one or more (complete) lines are added
     to the file, they are printed to stdout, prepending the string <nick> 
     literally, with foreground color <fg> and background color <bg>,
     cutting the first <cut_b> char (none if 0 or -1), and cutting the end
     of the line starting at char <cut_e> (print to the end if -1). 
     More about <flags> later. 
     
     If an error is returned on the open(), like a non-existent file or a
     permission denied, a "sleeping watch" is set; every WAIT millisecond
     the opening will be tried again (silently). In case of success, a
     message is printed and the file is spied normally. 
     
     If the file disappear (because someone has moved it or removed it) and
     a new one appear with name <file path>, the behavior depends on
     <flags>. If it's 1, SLogger "re-binds": close the old file descriptor 
     and begins to follow the new file. If flags is 0, SLogger continues to
     "spy" the old file descriptor. Normally you want 1 here. 
     
     For example, the entry: 
     
     WATCH /var/log/maillog          MTA:  1  -1 -1 -1 1
     
     would produce (for example) the output: 
     
     MTA: Sep 28 17:19:46 pern fetchmail[26020]:  flushed
 
     in color 1 over default (in my xterm, blue over white).
     
     Using -2 as foregrounf colors means that the line is NOT to be printed. 
     This seems silly, but it has its logic: you can "shut up" information
     from a file and then select a specific message to show with REXP (see
     below). 
          
REXP <re> <fg> <bg> <flags>  
     This set a regular expression match on the previous WATCH. You can have
     any number of REXP lines after a WATCH entry; the first checked is the
     last, so if a multiple match occurs, the REXP entry that "wins" is the
     first found in the file. <re> is a POSIX simplified regular expression
     (see man 7 regex for details); if a line is to be printed for this
     filewatch and the regular expression matches, it is printed with
     foreground color <fg> and background color <bg> instead of the ones
     specified in the WATCH entry. Here flags=0 means exact match, flags=1
     select a case-insensitive match. If <fg> is -2, suppress the output. 
     
     For example, if you want to print /var/log/maillog messages in blue,
     but emphasize in say, red (color 4) the ones from fetchmail, use
     
     WATCH /var/log/maillog          MTA:  1  -1 -1 -1 1
     REXP .*fetchmail.* 4 -1 0
     
3.3 - running SLogger

     Just run it with the full path of the configuration file as its only
     argument, i.e. 
     
           slogger /home/foo/etc/logspy.slc & 
           
     and that's it. 
     
3.4 - bonus programs 

     The little testcol utility let you see your terminal color capabilities
     and configuration. It outputs 64 lines of foreground/background
     combinations, so use it in a terminal with a decent scrollback buffer
     capacity. 
     
     Another useful program is 'colorecho', you can use it in two ways: with
     just two arguments (foreground and background colors) it copies
     everything from stdin to stdout in the said colors; with more than two
     arguments, it copies the strings after the two color specification to
     stdout such as echo would do. 

4 - HINTS 

     SLogger has not been designed to do permission checks or a graphic
     interface; I believe in the good ol' U*ix semantic "do one thing, do
     just that, and do it well". 

4.1 - permissions

     Normally the files in /var/log are not world readable (and better the
     stay so). If you want to run slogger as a normal user, you have two
     options: one is use sudo (or similar tools), and the other one is the
     one I prefer: 
           - create a new group, say "logger"; 
           - in /var/log, change all the file group ownership to logger,
             chgrp -R logger . , and group-readable, chmod -R g+r * ; 
           - change the /var/log dir itself to setgroupid, chmod g+s ., and
             all the relevant subdirectory, so that newly created files are
             assigned to group logger;
           - add logger to your normal user login groups.
     Now you can read all the logfiles. 
     
4.2 - graphical interface 

     Just use a terminal emulator (or a standard linux console) and run
     slogger in it. What I do is to create a "class" of xterm just for this
     use, adding to my .Xdefaults file the following (it is just an example): 
     
     *SLog*VT100*font:               6x13
     *SLog*scrollBar:                on   
     *SLog*saveline:                 1500
     *SLog*geometry:                 110x20
     *SLog*title:                    SLogger
     *SLog*boldColor:                false
     *SLog*foreground:               black
     *SLog*background:               grey88

     and then you can call (in X) the logger with 
     
     xterm -name SLog -e slogger /my/conf/file & 
     
     If you dislike some of the standard colors, just change it; for
     example, I find that the default green, cyan and yellow are practically
     unreadable if you use an (almost) white background terminal like the
     one specified above, so change: 
     
     *SLog*color2:                   darkgreen
     *SLog*color3:                   brown
     *SLog*color6:                   darkcyan
     
     When you are playing with it, remember that you have to reload the
     resource database after any change (xrdb -load ~/.Xdefauls will do); 
     to test colors you can use 
     
     xterm -name SLog -e testcol wait
     
     (wait is a parameter to testcol that instruct it to never exit, so that
     you can look at the colors and then close it via window manager and/or
     ctrl-c). xterm has a lot of customizable things, have a look to man
     xterm. 
     
     Finally, I instruct my window manager to never give focus the windows
     with title "SLogger" and that its. 
     
     
5 - BUGS

    In this revision, it is impossible to give to slogger any parameter which
    contains spaces, nor in regular expression, nicknames and  filenames
    (hey: spaces in filenames are the root of all evil). 


6 - TODO

    I should really add a more intelligent configuration file parser, at
    least to permit quoted string input. Next version...
    
    I will appreciate ideas, suggestions, bug reports; but remember that I
    have not much time... and slogger "works for me" just now. If you like
    it and use it, please drop me a line.
    
           Romano Giannetti <r_mano@users.sourceforge.net>
           
           
    
    

