1TTYWATCH(8) System Programs TTYWATCH(8)
2
6 ttywatch - log output of arbitrarily many tty devices
7
9 ttywatch [--config configfile] [--nolock]
10 [[--name machinename [--port devicename]
11 [--bps speed]
12 [--ipport portnumber [--ipaddr ipaddress]]
13 [--logspew chars]
14 [--module modpath]]
15 [--nolock]
16 [--logpath logpath]
17 [--pidfile path]
18 [--daemon]
19 [--help] [--usage]
20
22 Logs the output from arbitrarily many character devices; for now, those
23 are expected to be tty devices. For each device, the key value is the
24 the --name argument; it is possible with appropriate setup for ttywatch
25 to function with only the --name argument. Devices may be physically
26 connected to the local computer, or to a remote computer which is also
27 running ttywatch.
28
30 --name machinename
31 The most important option, --name gives a name for a connection
32 to log. The name is used for the logfile and also provides a
33 default for the device name to monitor. Without any --name
34 options, ttywatch will not do anything.
35 If machinename does not contain a "/" character, does contain a
37 ":" character, and has only numeric characters following the ":"
38 character, then it is treated as an internet address or hostname
39 followed by a port number to which to connect. In this case,
40 speed is ignored.
41 The port can send raw data or speak the telnet protocol; tty‐
43 watch will attempt to initiate a telnet session.
44 Note that this feature can be used to chain together multiple
46 instances of ttywatch. This can be useful to aggregate input
47 from many machines in a hierarchical manner. That is, many
48 "slave" machines may be using ttywatch to log serial ports, and
49 a "master" logging machine can then connect to the "slave"
50 machines and log all the data from all the ports in one place.
51 --port devicename
53 Overrides the default port name of /dev/machinename associated
54 with the most recently specified machinename.
55 If devicename does not contain a "/" character, does contain a
57 ":" character, and has only numeric characters following the ":"
58 character, then it is treated as an internet address or hostname
59 followed by a port number to which to connect, in the same way
60 as machinename.
61 --bps speed
63 Overrides the default speed of 115200 bps for the most recently
64 specified machinename.
65 --ipport portnumber [--ipaddr ipaddress]
67 Causes ttywatch to listen on port portnumber for incoming con‐
68 nections, and to connect them interactively to the most recently
69 specified machinename. More than one incoming connection can
70 interact with a single machinename, in "whiteboard" style (all
71 input accepted as it arrives, all output sent to each listener).
72 If an ipaddress is specified, then ttywatch will bind to that
73 specific IP address only. It is not normally used.
74 Note: There is currently NO option to enable authentication for
76 incoming connections. In plain english: if you specify this
77 option, anyone with network connectivity to the specified ports
78 on your machine will be able to connect and interact without
79 giving any sort of password. You have been warned.
80 --logspew chars
82 Tells ttywatch the maximum number of characters of existing log‐
83 file data for machinename to send when a connection to portnum‐
84 ber is established. It defaults to 4000 (80*50 -- two screen
85 pages if all the lines are full). This is a maximum; if there
86 are fewer characters available in the logfile, fewer characters
87 will be sent.
88 --config path
90 Path to config file to parse before continuing parsing any more
91 options. Configuration files are files which contain options
92 exactly like those contained on the command line; coments are
93 supported, and are marked by # characters in the first column.
94 The --config option is supported within configuration files as
95 well as on the command line. There is no default configuration
96 file, although the default ttywatch service (that is, the
97 /etc/rc.d/init.d/ttywatch script) is set up to explicitly
98 include /etc/ttywatch.conf and all files in /etc/ttywatch.d as
99 configuration files. When running ttywatch from the command
100 line, you must specify every config file you wish to read
101 explicitly. You can override its settings by putting contrary
102 options on the command line after the --config option.
103 --pidfile path
105 Store a pidfile. The default service uses /var/run/tty‐
106 watch.pid. The default is not to write a pidfile.
107 --logpath logpath
109 Explicitly sets the base directory in which to write the log
110 output. log output files will be in logpath/machinename.log.
111 --module modpath
113 Specify a module to use for the current port. The module should
114 contain a symbol called "process_line". This symbol should be a
115 function that takes two arguments: a "machine" (see ttywatch.h)
116 and a char *, and returns void.
117 When --module is specified for a port, output for that port is
119 not logged in a logfile.
120 --nolock
122 If specified before any machine specification, turns off port
123 locking for all machines. Otherwise, turns off port locking for
124 the current machine. (Locking is a configuration option; on
125 systems without device locking, this option does nothing.)
126 --daemon
128 ttywatch should background itself and run as a daemon.
129
131 ttywatch --logpath . \
132 --name m1 --port /dev/ttyS0 --ipport 3000 \
133 --name m2 --port /dev/ttyS1 --ipport 3001
134 This logs the output from /dev/ttyS0 (at the default 115200 bps) in the
135 file m1.log in the current directory, and the output from /dev/ttyS1 in
136 the file m2.log in the current directory. You will be able to telnet
137 to port 3000 to interact with /dev/ttyS0 and to port 3001 to interact
138 with /dev/ttyS1.
139 The command (run as root):
141 ttywatch --config /etc/ttywatch.conf --pidfile /var/run/ttywatch.pid
142 where /etc/ttywatch.conf contains
143 --name m1 --ipport 3000
144 --name m2 --port /dev/ttyS1 --bps 9600 --ipport 3001
145 --name m3 --port /dev/ttyS2 --bps 57600 --ipport 3002
146 --pidfile /tmp/badidea
147 will map the output of /dev/m1 (perhaps a symlink to /dev/ttyS0 in this
148 example) at the default 115200 bps in /var/log/ttywatch/m1.log; the
149 output of /dev/ttyS1 at 9600 bps in /var/log/ttywatch/m2.log; and the
150 output of /dev/ttyS2 at 57600 bps in /var/log/ttywatch/m3.log. It will
151 store its pid in /var/run/ttywatch.pid because the --pidfile option on
152 the command line logically follows the --pidfile option in the config
153 file, because it follows the --config option on the command line. How‐
154 ever, if the --pidfile option had preceeded the --config option on the
155 command line, ttywatch would have stored the pidfile in /tmp/badidea.
156 Note that ttywatch does not do ANY security checking when it opens
158 files, so using --pidfile /etc/passwd would be a really effective way
159 to destroy your password database—and so would --pidfile /tmp/badidea
160 if some user with a bad sense of humor had symbolically linked
161 /tmp/badidea to /etc/passwd.
162 In case you missed that the first time, I'll repeat it: Note that tty‐
164 watch does not do ANY security checking when it opens files, so using
165 --pidfile /etc/passwd would be a really effective way to destroy your
166 password database—and so would --pidfile /tmp/badidea if some user with
167 a bad sense of humor had symbolically linked /tmp/badidea to
168 /etc/passwd.
169 Therefore, make absolutely certain that you ask ttywatch to write all
171 its files in secure locations!
172
174 Exit status is 0 for a clean exit and non-0 for a non-clean exit. Non-
175 clean exits may well leave TTYs in indeterminate states.
176
178 /var/log/ttywatch/machinename.log
179 The default location of the output logs for each machine, when
180 ttywatch is run by root. When run by another user, the default
181 log directory is the directory from which ttywatch was run.
182 /dev/machinename
184 The default port for each machine is /dev/machinename; this
185 would generally be a symbolic link to the real device file. The
186 --port option overrides this.
187 /etc/rc.d/init.d/ttywatch
189 An init script to start a default system installation of tty‐
190 watch. This is normally turned off by default; use the command
191 /sbin/chkconfig ttywatch on
192 to enable the ttywatch service.
193 /etc/ttywatch.conf
195 The main configuration file used by the default
196 /etc/rc.d/init.d/ttywatch init script.
197 /etc/ttywatch.d/
199 A directory containing only ttywatch config files to be read
200 after /etc/ttywatch.conf
201 /etc/logrotate.d/ttywatch
203 The logrotate configuration script which rotates logs. The
204 default configuration compresses logfiles and reopens config
205 files appropriately.
206
208 Only TTY devices are supported. Other character devices should be
209 tested and added; logging data from network ports, including network
210 ports speaking the telnet protocol, and authentication of incoming con‐
211 nections, would be welcome additions as well.
212
214 The author's idea of a useful tool...
215
217 Michael K. Johnson <a1237+ttywatch@danlj.org>
218 Originally based very loosely on robin.c from Linux Application Devel‐
220 opment, written by Michael K. Johnson and Erik W. Troan, published by
221 Addison-Wesley ISBN 0-201-30821-5.
222 http://www.danlj.org/mkj/lad/
223Linux 7 Feb 2001 TTYWATCH(8)