xwatch - The Logfiles Watcher

Karel Kubat (karel@icce.rug.nl)

State University of Groningen

Westerhaven 16, 9718 AW Groningen

The Netherlands

Chapter 1: Introduction

Chapter 2: Using xwatch

2.1: Options to the xwatch program

2.2: File arguments

Chapter 3: Obtaining xwatch

Chapter 4: Compiling xwatch

Chapter 5: Copyright

CWXWatch 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). CWXWatch 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 CWxwatch's window. That's all there is to it. The appearance of the CWxwatch window can furthermore be modified via command line flags or via an application defaults file. (Older versions of CWXWatch had a button to activate an `options' window. I removed this code, almost no-one uses it.)

CWXWatch 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 CWMakefile, contained in CWxwatch'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

You typically start CWxwatch when activating an X session; e.g., from the file which xdm uses to fire up a user's session (this file is normally CW/usr/X11/lib/X11/xdm/Xsession). The command that starts CWxwatch 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 CWxwatch in the background. The files to watch are typically in the directory CW/var/adm/: files which are created by the syslog daemon (see the file CWsyslogd.conf.SAMPLE in the distribution for an example). CWXWatch 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, CWxwatch warns about the file not being acceptable and deletes it from its list of names.

The options are many, start CWxwatch without arguments to see what is supported. All options can also be stated in the file CW/usr/lib/X11/app-defaults/XWatch as X resources (see the file CWXWatch.ap as an example). In the following enumeration, a nr denotes a number:

o

CW-border nr: Specifies whether CWxwatch should start with a border. The nr must be 0 or 1. When you start CWxwatch 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 CWxwatch from my window manager CWfvwm.

o

CW-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 CW-xpos and CW-height, are now obsolete. Use the geometry setting.

o

CW-fg color and CW-bg color: These options define the default foreground and background of the watch window.

Note that previous switches, such as CW-bred and CW-bblue, are now obsolete.

o

CW-printtime nr: Defines whether CWxwatch should prefix any info on the watched files with a timestamp. The CWnr can be 0 or zero; the timestamp is printed when nr is 1.

o

CW-printname nr: Defines whether CWxwatch should prefix any info on the watched files with the filename. The nr is again a flag, 0 or 1.

o

CW-newline nr: Defines whether CWxwatch should let a newline follow the time and/or filename stamp, so that the actual information is displayed on its own line.

o

CW-interval nr: Defines the scanning interval. Each nr seconds, CWxwatch will check if new information has arrived on the watched files. The nr may be between 1 and 30 seconds.

o

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

CW-fontstyle nr: Defines the style of the used font. The nr is a number between 0 and 15 (0 being the default). Start CWxwatch without arguments or read the application defaults file to see what fonts the numbers choose.

o

CW-firstwarnings nr: Defines whether CWxwatch should print initial warnings into the watch window. E.g., you might like to set CWfirstwarnings to zero, and then start CWxwatch with the file argument CW/var/adm/*. Warnings about, e.g., CWutmp being a binary file would then be suppressed.

o

CW-printversion nr: Controls whether CWxwatch prints its version number and copyright notice upon startup in the watch window.

o

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

o

CW-colorstring col:string: This option causes lines that contain CWstring to be displayed using the specified color. The string is matched literally. E.g., if you use the option CW-colorstring blue:connection then all lines containing CWconnection are displayed in pure blue.

You can specify several colorstrings by separating all options with a | character, as in CW-colorstring blue:connection|red:error. Note that, for reasons of shell expansion, you should quote such options on the commandline.

o

CW-title name: This option sets the window title of the watch window. Note that the title will only be visible when CWborder is not 0. This option may be useful if you have several XWatch windows, monitoring different things.

o

CW-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 CW-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, CWfrank@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 CW/usr/lib/X11/app-defaults/XWatch. You can do so by copying the file CWXWatch.ap, extracted from the archive, to CW/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 CW/usr/lib/X11/app-defaults. In that case, you should create the following links:

o

CW/usr/X11 should point to your X11 distribution; e.g. to CW/usr/X11R6. That way, you always have e.g. CW/usr/X11/bin, even after upgrading your X11 distribution. All that is needed is one new link.

o

CW/usr/lib/X11 should point to CW/usr/X11/lib/X11.

Then edit the file CWXWatch in the application defaults directory, and follow the instructions therein to define your favorite settings. If you need to start CWxwatch incidentally with another setting, use a flag.

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 CW/var/adm normally in blue text; but you want to see CW/var/adm/critical (critical messages from applications) in yellow and CW/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 CW-fg blue, or in the application defaults file.

o

The color for CW/var/adm/critical should be yellow. Hence, the first file argument would be CW/var/adm/critical:yellow.

o

The color for file CW/var/adm/auth should be red, hence the second file argument would be CW/var/adm/auth:red.

o

The following arguments would be the files, using the standard foreground (blue): CW/var/adm/*, without any extra color specifications.

Such a commandline would cause CWxwatch to complain about the multiple presence of CW/var/adm/critical (once from the separate argument, and once from the wildcard argument) and similarly about CW/var/adm/auth. If this bothers you, turn off the initial warnings (e.g., using CW-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 CW-colorstring for more information.

CWXWatch can be obtained at the ftp site CWftp.icce.rug.nl, in the directory CW/pub/unix, as the file CWxwatch-X.YY.tar.gz. CWX.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., CW/usr/local/src) and type

 
tar xvzf /where/ever/you/put/it/xwatch-X.YY.tar.gz

Next, change-dir to the unpacked subdirectory CWxwatch and check there. You will find a subdirectory CWsrc with the full sources.

Follow these steps.

o

You will need the XForms library and include files to compile CWxwatch. Check the CWMakefile in the CWsrc 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 CWsrc subdirectory, edit the CWMakefile and adjust some defines at the top. E.g., a CWmake install copies the binary by default to CW/usr/local/X11/bin; adjust that if you don't like this behavior.

o

Next, do a CWmake install, followed by a CWmake clean.

o

Copy the file CWXWatch.ap from the source directory to CW/usr/lib/X11/app-defaults/XWatch. Edit the file and state your favorite settings.

o

Next, start the program CWxwatch with some file arguments in your logfiles directory. If you're satisfied with the appearance and workings of CWxwatch, add the invocation to your script that starts an X session.

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