TTYWATCH

NAME

SYNOPSIS

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

DESCRIPTION

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.

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

The command (run as root):

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

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

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

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

CONFORMING TO

AUTHOR

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/lad/

Index

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

EXAMPLES

EXIT STATUS

FILES

BUGS

CONFORMING TO

AUTHOR