Serialmon Version 0.23
======================

A program to monitor a modem on a serial port, and simulate the
modem LEDS on a colour console using curses.

Information monitored:
Modem lines: RI DCD RXD TXD DTR

Then, for each connection:
Date and time: Line up, Line down
Duration of call
Amount of idle time on transmit and receive side
Number of characters transmitted and received
Data rate for the last second, transmit and receive
Peak data rate over 1s and 10s, transmit and receive
Overall average data rate, transmit and receive
Process id and command line of the process using the line

The logfile contains all the above, but also includes additional information:
Active time (time slices in which characters were transferred)
Average data rate excluding idle time
The time that the modem control lines (DCD and DTR) switch.
The times that ioctls return I/O errors, and thus the line is reopened.
Date and time that logging starts and finishes.

Note, all dates/times are recorded in local time, this may give interesting
effects if the line is up during a daylight savings time change.

Related programs
================

If you want a graphical version for X (KDE), check out
http://www.lpr.e-technik.tu-muenchen.de/~kuhn/ksermon/index.html

If you want a program to hold back processes from using the serial
port when traffic is already busy, check out
http://www.roestock.demon.co.uk/newsstuff/index.html#BWScript

Usage
=====

serialmon /dev/line [logfile]

The logfile may be provided to record the line activity. Additional
information is stored in the logfile.

Compiling
=========

The program has been compiled for linux-2.0.36 and later, using ncurses-1.9.7.
I use gcc v2.7.2.3, with libc-5.4.44.

Note that some kernel patches are required to record the the number of
characters transmitted and received. These kernel patches are for i386
architecture only.

The kernel patches are provided in the kernel subdirectory, and should be
applied thus:

change to the kernel source top level directory, typically /usr/src/linux,
then pipe the patch file through 'patch -sp1':

cd /usr/src/linux
cat /path/to/kernel/patch.2.0.36.serialmon | patch -sp1

The patches work at least up to kernel 2.0.36.

For kernels greater than approx 2.1.111, apply the kernel patch thus:

cd /usr/src/linux
cat /path/to/kernel/patch.2.1.111.serialmon | patch -sp1

Having patched the kernel, build it, install it and reboot using it.

After rebooting the new kernel, return to the serialmon directory
and simply type make.
The program serialmon should probably be copied into /sbin after compiling and
testing.

The default build will produce a curses based program with simulated
frontpanel LEDs, which assumes the line is up when another process locks
the serial port. For this to work, you must arrange that all programs
agree on the directory containg the lock files. Historically, the
lock files have been in /usr/spool/uucp, /var/spool/uucp, /var/locks,
/var/lock, so if you may need a few symbolic links if you are running
old binaries.

Various #defines are available to restrict the functionality if
required. See the source file for details.

Running via init
================

In my system, I run serialmon on an unused console, with the following entry
in inittab:

cB:2345:respawn:/etc/serialmon.init tty11 /dev/ttyS2 /var/log/modemlog

where /etc/serialmon.init is the following script:

#!/bin/bash
exec /sbin/serialmon $2 $3 > /dev/$1

As far as I can tell, the script is required because redirection doesn't work
in inittab, and serialmon requires stdout to point to the required screen
device.

Serialmon needs to be run as root to allow it to increase its priority. This
is required to reduce the wierd data transfer rates caused by irregular
scheduling.

Bugs
====

Times are local time. This can make the log reports look a bit weird when the
clocks change.

Would be nice to accept ^L to redraw screen.

If you are running with iso01 fonts, you may get weird characters instead of
the box characters. My solution is to add the following line before calling
serialmon:
export TERM=ti928

Any more ? Tell me.

For latest information, refer to my web pages at
http://www.roestock.demon.co.uk/serialmon/

Copyright
=========

This program and documentation is copyright P.J.H.Fox
(fox@roestock.demon.co.uk) and distributed under the GPL (see COPYING).

Copyright notices are not to be removed or altered.

If mailing patches, bug reports or comments, please put 'serialmon' somewhere
in the subject line, and mail to serialmon@roestock.demon.co.uk.

Warranty
========

There is NO WARRANTY for this program.

This program has been compiled on my machine using gcc 2.7.2, ncurses 1.9.7
and linux 2.0.33, and it seems to work for me.

Thanks
======

To "Theodore Y. Ts'o" <tytso@MIT.EDU> for straightening me out on why the
kernel hang up code is like it is.
To Roman Shterenzon for contributing most of the GLIBC changes.
Various others for bug notifications...

Peter Fox
27-Nov-98

