XWatch
The Logfiles Watcher"
State University of Groningen
Westerhaven 16, 9718 AW Groningen
The Netherlands"
1996
Chapter 1: Introduction
XWatch is a small program that I wrote to monitor logfiles and to see
any changes directly (instead of having to read all the logs after a
breakin or a crash). XWatch is simply started with a few file
arguments, and any information that appears on the files is displayed.
With a slider you can see past information; i.e., lines that scroll in
xwatch's window. That's all there is to it. The appearance of the
xwatch window can furthermore be modified via command line flags or via
an application defaults file. (Older versions of XWatch had a button to
activate an `options' window. I removed this code, almost no-one uses
it.)
XWatch is incidentally my first applications with the XForms GUI
library for X, which I can highly recommend for developers who want to
start `X programming' but who don't want to go through the hassle of
having to learn about intrinsics. XForms is really excellent. Congrats,
T.C. Zhao and Mark Overmars (the latter is rumored to bootleg at a
soccer club in his free time ;). Instructions on where and how to get
the XForms library are in the Makefile, contained in xwatch's
distribution.
Debian maintainer note: XWatch doesn't have an active upstream
maintainer. If you are interested in taking over this package, please
see the file /usr/share/doc/xwatch/README.debian
Chapter 2: Using xwatch
You typically start xwatch when activating an X session; e.g., from the
file which xdm uses to fire up a user's session (this file is normally
/usr/X11/lib/X11/xdm/Xsession). The command that starts xwatch is
something like
xwatch [options] files &
where `options' are optional flags, files are the files to watch, and
the ampersand character is used to start xwatch in the background. The
files to watch are typically in the directory /var/adm/: files which
are created by the syslog daemon (see the file syslogd.conf.SAMPLE in
the distribution for an example). XWatch accepts only filenames which
are:
o ordinary files, no sockets, directory names,
o which are not binary files.
Other files as stated on the commandline are not monitored. When
any `non-proper' file is given on the commandline, xwatch warns
about the file not being acceptable and deletes it from its list
of names.
2.1: Options to the xwatch program
The options are many, start xwatch without arguments to see what is
supported. All options can also be stated in the file
/usr/lib/X11/app-defaults/XWatch as X resources (see the file XWatch.ap
as an example). In the following enumeration, a nr denotes a number:
o -border nr: Specifies whether xwatch should start with a
border. The nr must be 0 or 1. When you start xwatch without a
border, your window manager may not be able to resize or even
recognize it. Incidentally, this may be what you want -- I use
it to `hide' the presence of xwatch from my window manager fvwm.
o -geometry geom: Specifies the display geometry, a-la other X
programs. You can express the geometry in terms of WxH (width by
height), optionally postfixed by +X+Y (x and y offset) or -X-Y
(offsets relative to the lower right corner) and other
combinations.
Note that previous switches that emulated the geometry
specification, such as -xpos and -height, are now obsolete. Use
the geometry setting.
o -fg color and -bg color: These options define the default
foreground and background of the watch window.
Note that previous switches, such as -bred and -bblue, are now
obsolete.
o -printtime nr: Defines whether xwatch should prefix any info on
the watched files with a timestamp. The nr can be 0 or zero; the
timestamp is printed when nr is 1.
o -printname nr: Defines whether xwatch should prefix any info on
the watched files with the filename. The nr is again a flag, 0
or 1.
o -newline nr: Defines whether xwatch should let a newline follow
the time and/or filename stamp, so that the actual information
is displayed on its own line.
o -interval nr: Defines the scanning interval. Each nr seconds,
xwatch will check if new information has arrived on the watched
files. The nr may be between 1 and 30 seconds.
o -fontsize nr: Defines the initial size of the display font. The
nr may range from 1 to 4; 1 being the smallest font and 4 being
the largest.
o -fontstyle nr: Defines the style of the used font. The nr is a
number between 0 and 15 (0 being the default). Start xwatch
without arguments or read the application defaults file to see
what fonts the numbers choose.
o -firstwarnings nr: Defines whether xwatch should print initial
warnings into the watch window. E.g., you might like to set
firstwarnings to zero, and then start xwatch with the file
argument /var/adm/*. Warnings about, e.g., utmp being a binary
file would then be suppressed.
o -printversion nr: Controls whether xwatch prints its version
number and copyright notice upon startup in the watch window.
o -gag text: This option, when present, prevents all lines with
text in them from being shown in the display window. You can
specify more than one string to `gag', in that case, separate
the strings with |.
o -colorstring col:string: This option causes lines that contain
string to be displayed using the specified color. The string is
matched literally. E.g., if you use the option -colorstring
blue:connection then all lines containing connection are
displayed in pure blue.
You can specify several colorstrings by separating all options
with a | character, as in -colorstring
blue:connection|red:error. Note that, for reasons of shell
expansion, you should quote such options on the commandline.
o -title name: This option sets the window title of the watch
window. Note that the title will only be visible when border is
not 0. This option may be useful if you have several XWatch
windows, monitoring different things.
o -ignore fileA|fileB|fileC|...: This option is handy if you start
XWatch with a wildcard file argument, but when you want XWatch
not to process some files. The -ignore flag removes the stated
files from the watchlist. Note that, for reasons of shell
commandline expansion, you must quote the file specification (or
the shell will interpret the | characters as pipes). (Thanks,
Frank Brokken, frank@icce.rug.nl for the code).
Debian Maintainer's note: Applications defaults are stored in
/etc/X11/app-defaults/XWatch . System adminitrators who want to
customize xwatch globally may also create a file
/etc/X11/Xresources/xwatch for these configurations by prefixing
the entries with Xwatch (see
/usr/share/doc/xwatch/README.Debian for an example). Individual
users can make the same types of changes in their ~/.Xdefaults
or ~/.Xresources files.
Before you extensively use the options, create an application defaults
file /usr/lib/X11/app-defaults/XWatch. You can do so by copying the
file XWatch.ap, extracted from the archive, to
/usr/lib/X11/app-defaults/XWatch. The comments in the distributed
application defaults file explain what you can configure and show
examples.
Some systems do not have the directory /usr/lib/X11/app-defaults. In
that case, you should create the following links:
o /usr/X11 should point to your X11 distribution; e.g. to
/usr/X11R6. That way, you always have e.g. /usr/X11/bin, even
after upgrading your X11 distribution. All that is needed is one
new link.
o /usr/lib/X11 should point to /usr/X11/lib/X11.
Then edit the file XWatch in the application defaults directory,
and follow the instructions therein to define your favorite
settings. If you need to start xwatch incidentally with another
setting, use a flag.
2.2: File arguments
The filename arguments can optionally be followed by a color
specification that applies only to that particular file. E.g., say you
want to see all the files in /var/adm normally in blue text; but you
want to see /var/adm/critical (critical messages from applications) in
yellow and /var/adm/auth (authentification messages) in red. In that
case, the course to follow would be:
o The default foreground color would be blue. You could set this
with the flags -fg blue, or in the application defaults file.
o The color for /var/adm/critical should be yellow. Hence, the
first file argument would be /var/adm/critical:yellow.
o The color for file /var/adm/auth should be red, hence the second
file argument would be /var/adm/auth:red.
o The following arguments would be the files, using the standard
foreground (blue): /var/adm/*, without any extra color
specifications.
Such a commandline would cause xwatch to complain about the
multiple presence of /var/adm/critical (once from the separate
argument, and once from the wildcard argument) and similarly
about /var/adm/auth. If this bothers you, turn off the initial
warnings (e.g., using -firstwarnings 0 or in the application
defaults file).
Note that besides the color specifications for filenames, you can also
specify coloring for lines that match a given string in all files. See
the above description of the switch -colorstring for more information.
Chapter 3: Obtaining xwatch
XWatch can be obtained at the ftp site ftp.icce.rug.nl, in the
directory /pub/unix, as the file xwatch-X.YY.tar.gz. X.YY is the
version number, e.g., 1.00. This site is the primary site, so check
here for new versions.
To unpack the archive, change-dir to your `sources' directory (e.g.,
/usr/local/src) and type
tar xvzf /where/ever/you/put/it/xwatch-X.YY.tar.gz
Next, change-dir to the unpacked subdirectory xwatch and check there.
You will find a subdirectory src with the full sources.
Chapter 4: Compiling xwatch
Follow these steps.
o You will need the XForms library and include files to compile
xwatch. Check the Makefile in the src subdirectory for two ftp
sites that carry XForms for Linux. Obtain the library and
install it. XWatch will happily run with XForms version 0.81 or
0.88.
o In the src subdirectory, edit the Makefile and adjust some
defines at the top. E.g., a make install copies the binary by
default to /usr/local/X11/bin; adjust that if you don't like
this behavior.
o Next, do a make install, followed by a make clean.
o Copy the file XWatch.ap from the source directory to
/usr/lib/X11/app-defaults/XWatch. Edit the file and state your
favorite settings.
o Next, start the program xwatch with some file arguments in your
logfiles directory. If you're satisfied with the appearance and
workings of xwatch, add the invocation to your script that
starts an X session.
Chapter 5: Copyright
XWatch - a tool to monitor logfiles and display new logs in an X
window. Copyright (C) 1995 Karel Kubat. All rights reserved.
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.
You may link this software with XForms (Copyright (C) by T.C. Zhao and
Mark Overmars) and distribute the resulting binary, under the
restrictions in clause 3 of the GPL, even though the resulting binary
is not, as a whole, covered by the GPL. (You still need a separate
license to do so from the owner (s) of the copyright for XForms,
however). If a derivative no longer requires XForms, you may use the
unsupplemented GPL as its license by deleting this paragraph and
therefore removing this exemption for XForms.
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., 59 Temple Place, Suite 330, Boston, MA
02111-1307 USA
XWatch ()