Philip Hazel's Smail Monitor
----------------------------

Smailmon version: 1.02
Last updated:     23 March 1995

Smailmon is a program for displaying things about smail in an X window. It is
currently in a preliminary stage of development. Enquiries and suggestions to
<ph10@cus.cam.ac.uk>. This is a brief note for those who want to experiment.

You should have unpacked the following files into a src directory:

README            this file

LICENCE           to keep the lawyers happy

Makefile          the main make file

Make.xxx          subsidiary system-specific make files

MakeLinks         a script to build symbolic links to the sources from
                  system-specific directories. If you want to support
                  multiple architectures from a single source, make directories
                  for each of them at the same level as src, and from each one
                  enter the command ../src/MakeLinks. Then do the building in
                  each system-specific directory.  
                  
regexp            a sub-directory containing the source of Henry Spencer's
                  freely available regular expression functions 
                  
smailmon          a shell script for firing up smailmon, containing various
                  editable parameters
                  
*.c, *.h          the source files 


Setting up
----------

. If your system is one of those for which a Make.xxx file exists, create 
  a symbolic link called Make.os pointing to the appropriate file. If not, make 
  a copy of the file that looks closest, giving it an appropriate name, and 
  point the Make.os link at that.
  
. Review the contents of the Make.os file and set the various macros 
  appropriately for your system.
  
. Type "make".

. With luck, it will build two binaries, called readspool and smailmon.code. 

. If you trust readspool enough, make it setuid root. (If not, smailmon will 
  still run, but won't display any information from inside messages.)
  
. Ensure that smailmon, readspool, and smailmon.code have got execute 
  permissions.

. Edit the shell script called smailmon - there are things in there you need
  to set up for your installation. It contains comments describing the various 
  parameters.

. Run the smailmon script...


What you should get
-------------------

The message "Smailmon ... initializing" is shown on the terminal, and the 
program then proceeds to scan the smail spool to set up its in-store data. 
While doing this, it outputs a single dot for each spool file examined, to show
you it is making progress. When it is done, the message "Smailmon running"
appears, and you should then get a window displayed containing a row of
stripcharts across the top, and two other windows beneath.

Initially the stripcharts will be pretty blank, but they will gradually fill up 
over time. Note that only one of them is mandatory - the others are what you 
configure. If the main window is reduced to its smallest size, it will display 
just the queue-length stripchart and the Quit button. I tend to keep one of 
these in the corner of my screen.

The first scrolling window is a log tailer with one line per receipt and 
delivery. Received messages are indicated by <== and deliveries by --> or ==>. 
The second of these is used if "Completed" immediately follows the delivery, 
and the "Completed" is then not shown. Other log messages are shown, but the 
"lock failed" and "permission denied" ones are omitted. If you scroll back the 
log, it stays scrolled back unless the lines you are looking at are so old that 
they are about to be thrown away. When it needs to recover space, smailmon 
throws away quite a large chunk of the log, as this is more efficient than 
doing it line by line.

The second scrolling window shows a list of messages on the queue, which can be 
sorted various ways. [Sorting not yet implemented.] For each message the time
spent on the queue is shown, together with the sender and any pending
recipients. (If readspool is not setuid, it can't get the sender, and
recipients have to be guessed from msglog and defer messages on the main log.)

The queue display update interval is specified in the smailmon script, but 
there is also a button labelled "update" which causes a refresh to happen.
[Further buttons for sorting etc. are expected to appear here in later 
versions.]

In either of the scrolling windows you can use the left and right buttons of 
the mouse to select text to be copied elsewhere in the conventional manner.
You can also use the up and down arrow keys to scroll the window by one line 
either way.

Clicking with the lefthand button while holding down shift on a line in the 
queue display window pops up a menu which allows you to look at the msglog or
the message headers (with setuid readspool).


Infelicities (sounds nicer than 'bugs')
---------------------------------------

Smailmon notices when the log file is switched, and picks up the new file. 
However, it doesn't try at all to ensure it gets all the entries from the old 
file, which can in practice be written to for several hours after the files are 
switched.

If smailmon is initialized when the queue is very long, and/or your machine is 
heavily loaded, it may take longer than the time specified for a stripchart
update to do the initial spool scan. In this case the next strip on the 
configured stripcharts will contain the number of messages processed in a 
longer than expected period.


What may go wrong
-----------------

If you aren't running smail 3.1.29, the log reading code won't work, and you 
will get strange things happening. If you are running 3.1.29, but using the new 
log format, things won't work either. It is hoped that somebody who is
using that format will help me get smailmon to work on it.

****
