Linux Certif

Toute la documentation sur la certification Linux LPI

ttywatch

NAME

ttywatch - log output of arbitrarily many tty devices

SYNOPSIS

 ttywatch [--config configfile] [--nolock]
          [[--name machinename [--port devicename]
                               [--bps speed]
                               [--ipport portnumber [--ipaddr ipaddress]]
                               [--logspew chars]
                               [--module modpath]]
                               [--nolock]
          [--logpath logpath]
          [--pidfile path]
          [--daemon]
          [--help] [--usage]
 

DESCRIPTION

Logs the output from arbitrarily many character devices; for now, those are expected to be tty devices. For each device, the key value is the the --name argument; it is possible with appropriate setup for ttywatch to function with only the --name argument. Devices may be physically connected to the local computer, or to a remote computer which is also running ttywatch.

OPTIONS

--name machinename

The most important option, --name gives a name for a connection to log. The name is used for the logfile and also provides a default for the device name to monitor. Without any --name options, ttywatch will not do anything.

If machinename does not contain a "/" character, does contain a ":" character, and has only numeric characters following the ":" character, then it is treated as an internet address or hostname followed by a port number to which to connect. In this case, speed is ignored.

The port can send raw data or speak the telnet protocol; ttywatch will attempt to initiate a telnet session.

Note that this feature can be used to chain together multiple instances of ttywatch. This can be useful to aggregate input from many machines in a hierarchical manner. That is, many "slave" machines may be using ttywatch to log serial ports, and a "master" logging machine can then connect to the "slave" machines and log all the data from all the ports in one place.

--port devicename

Overrides the default port name of /dev/machinename associated with the most recently specified machinename.

If devicename does not contain a "/" character, does contain a ":" character, and has only numeric characters following the ":" character, then it is treated as an internet address or hostname followed by a port number to which to connect, in the same way as machinename.

--bps speed

Overrides the default speed of 115200 bps for the most recently specified machinename.

--ipport portnumber [--ipaddr ipaddress]

Causes ttywatch to listen on port portnumber for incoming connections, and to connect them interactively to the most recently specified machinename. More than one incoming connection can interact with a single machinename, in "whiteboard" style (all input accepted as it arrives, all output sent to each listener). If an ipaddress is specified, then ttywatch will bind to that specific IP address only. It is not normally used.

Note: There is currently NO option to enable authentication for incoming connections. In plain english: if you specify this option, anyone with network connectivity to the specified ports on your machine will be able to connect and interact without giving any sort of password. You have been warned.

--logspew chars

Tells ttywatch the maximum number of characters of existing logfile data for machinename to send when a connection to portnumber is established. It defaults to 4000 (80*50 -- two screen pages if all the lines are full). This is a maximum; if there are fewer characters available in the logfile, fewer characters will be sent.

--config path

Path to config file to parse before continuing parsing any more options. Configuration files are files which contain options exactly like those contained on the command line; coments are supported, and are marked by # characters in the first column. The --config option is supported within configuration files as well as on the command line. There is no default configuration file, although the default ttywatch service (that is, the /etc/rc.d/init.d/ttywatch script) is set up to explicitly include /etc/ttywatch.conf and all files in /etc/ttywatch.d as configuration files. When running ttywatch from the command line, you must specify every config file you wish to read explicitly. You can override its settings by putting contrary options on the command line after the --config option.

--pidfile path

Store a pidfile. The default service uses /var/run/ttywatch.pid. The default is not to write a pidfile.

--logpath logpath

Explicitly sets the base directory in which to write the log output. log output files will be in logpath/machinename.log.

--module modpath

Specify a module to use for the current port. The module should contain a symbol called "process_line". This symbol should be a function that takes two arguments: a "machine" (see ttywatch.h) and a char *, and returns void.

When --module is specified for a port, output for that port is not logged in a logfile.

--nolock

If specified before any machine specification, turns off port locking for all machines. Otherwise, turns off port locking for the current machine. (Locking is a configuration option; on systems without device locking, this option does nothing.)

--daemon

ttywatch should background itself and run as a daemon.

EXAMPLES

 ttywatch --logpath . \
   --name m1 --port /dev/ttyS0 --ipport 3000 \
   --name m2 --port /dev/ttyS1 --ipport 3001
 

This logs the output from /dev/ttyS0 (at the default 115200 bps) in the file m1.log in the current directory, and the output from /dev/ttyS1 in the file m2.log in the current directory. You will be able to telnet to port 3000 to interact with /dev/ttyS0 and to port 3001 to interact with /dev/ttyS1.

The command (run as root):

 ttywatch --config /etc/ttywatch.conf --pidfile /var/run/ttywatch.pid
 

where /etc/ttywatch.conf contains

  --name m1 --ipport 3000
  --name m2 --port /dev/ttyS1 --bps 9600  --ipport 3001
  --name m3 --port /dev/ttyS2 --bps 57600 --ipport 3002
  --pidfile /tmp/badidea
 

will map the output of /dev/m1 (perhaps a symlink to /dev/ttyS0 in this example) at the default 115200 bps in /var/log/ttywatch/m1.log; the output of /dev/ttyS1 at 9600 bps in /var/log/ttywatch/m2.log; and the output of /dev/ttyS2 at 57600 bps in /var/log/ttywatch/m3.log. It will store its pid in /var/run/ttywatch.pid because the --pidfile option on the command line logically follows the --pidfile option in the config file, because it follows the --config option on the command line. However, if the --pidfile option had preceeded the --config option on the command line, ttywatch would have stored the pidfile in /tmp/badidea.

Note that ttywatch does not do ANY security checking when it opens files, so using --pidfile /etc/passwd would be a really effective way to destroy your password database---and so would --pidfile /tmp/badidea if some user with a bad sense of humor had symbolically linked /tmp/badidea to /etc/passwd.

In case you missed that the first time, I'll repeat it: Note that ttywatch does not do ANY security checking when it opens files, so using --pidfile /etc/passwd would be a really effective way to destroy your password database---and so would --pidfile /tmp/badidea if some user with a bad sense of humor had symbolically linked /tmp/badidea to /etc/passwd.

Therefore, make absolutely certain that you ask ttywatch to write all its files in secure locations!

EXIT STATUS

Exit status is 0 for a clean exit and non-0 for a non-clean exit. Non-clean exits may well leave TTYs in indeterminate states.

FILES

/var/log/ttywatch/machinename.log

The default location of the output logs for each machine, when ttywatch is run by root. When run by another user, the default log directory is the directory from which ttywatch was run.

/dev/machinename

The default port for each machine is /dev/machinename; this would generally be a symbolic link to the real device file. The --port option overrides this.

/etc/rc.d/init.d/ttywatch

An init script to start a default system installation of ttywatch. This is normally turned off by default; use the command

 /sbin/chkconfig ttywatch on
 

to enable the ttywatch service.

/etc/ttywatch.conf

The main configuration file used by the default /etc/rc.d/init.d/ttywatch init script.

/etc/ttywatch.d/

A directory containing only ttywatch config files to be read after /etc/ttywatch.conf

/etc/logrotate.d/ttywatch

The logrotate configuration script which rotates logs. The default configuration compresses logfiles and reopens config files appropriately.

BUGS

Only TTY devices are supported. Other character devices should be tested and added; logging data from network ports, including network ports speaking the telnet protocol, and authentication of incoming connections, would be welcome additions as well.

CONFORMING TO

The author's idea of a useful tool...

AUTHOR

Michael K. Johnson <a1237+ttywatch@danlj.org>

Originally based very loosely on robin.c from Linux Application Development, written by Michael K. Johnson and Erik W. Troan, published by Addison-Wesley ISBN 0-201-30821-5.
http://www.danlj.org/mkj/lad/