Serialmon Version 0.24 ====================== A program to monitor a modem on a serial port, and simulate the modem LEDS on a colour console using curses. If BWSERVER defined, the program allows external processes to be managed via shared memory and the waitforbw and sermonstats programs. 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, see waitforbw included. Usage ===== serialmon /dev/line [logfile] The logfile may be provided to record the line activity. Additional information is stored in the logfile. If BWSERVER defined (default), then a shared memory segment is setup using the /dev/line as the key. This is used to comunicate between a queue server in serialmon and waitforbw or sermonstats: waitforbw /dev/line This program will wait for the serial line usage to drop below a set threshold, then will exit normally. If serialmon is not running, or the line is down, it will return an error code. This may be used in other scripts to regulate line usage, simply put a call to waitforbw just before any process attempts to access a remote site which uses the serial line specified. To stop a mad rush of processes starting up, there is a minimum time allowed after one waitforbw exiting and another; this gives time for the traffic to start up. The threshold is 1000 chars/sec by default, and the minimum interval 0.5s. These may be changed using sermonstats below: sermonstats [options] /dev/line This program displays the line status (UP or DOWN), and three numbers indicating the total number of characters received, sent, received+sent, while the line is up. If serialmon is not running on the line, it just prints NOSERVER and an error code. If serialmon has never been run on the line, it will display an error message "Failed to get shared memory..". Options allow the rate threshold and minimum interval between signalling queued processes. Use the -h flag for details. Compiling ========= The program has been compiled for linux-2.2.17 and later, using ncurses-5.1. I use gcc v2.7.2.3, with libc-5.4.44. It requires additional ioctls to be added to the serial driver, which can be done one of two ways: kernel patch, or kernel module. Kernel patch ------------ This is the traditional method, and if you already use serialmon 0.23, you will have done it. The kernel patches allow serialmon to obtain the number of characters transmitted and received, together with a time stamp and the number of processes with the device open in one ioctl call. 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. Kernel module ------------- As an alternative to the kernel patch, there is a kernel module in the serialmon-ioctl directory which can be installed to add the required ioctl to any serial line, including the Lucent winmodem. This has the advantage of not requiring the kernel to be recompiled. Refer to serialmon-ioctl/README for details. Serialmon etc ------------- After rebooting the new kernel, or compiling and installing the kernel module, return to the serialmon directory and simply type make. The program serialmon should probably be copied into /sbin after compiling and testing. The programs waitforbw and sermonstats should be copied into /usr/bin. 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 containing 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. The program will also include the process queuing feature using waitforbw and sermonstats. 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. 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.3, ncurses 5.1 and linux 2.2.17, and it seems to work for me. Thanks ====== To "Theodore Y. Ts'o" 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 18-Mar-01