=head1 NAMEinterceptty - Intercept traffic to and from a serial port.=head1 SYNOPSIS Usage: ./interceptty [-V] [-qvl] [-s back-set] [-o output-file]                       [-p pty-dev] [-t tty-dev]                       [-m [pty-owner,[pty-group,]]pty-mode]                      [-u uid] [-g gid] [-/ chroot-dir]                      back-device front-device	back-device	Use back-device as the device to intercept		path		TTY dev is at /path		@/path		Socket is at /path		@host:port	Inet socket is at host:port		!prog		Run prog for backend		=rfd[,wfd]	Use file descriptors	front-device	Use front-device as the device applications connect to		path		Create symlink at /path		@/path		Socket at /path		@host:port	Inet socket at host:port		=rfd[,wfd]	Use file descriptors			'-' to prevent creating a front-device.			Doesn't currently do anything.	-l		Line-buffer output	-o output-file	Write intercepted data to output-file	-s back-stty	Use given settings to set up back-device			These settings are passed directly to stty(1).        -m pty-mode     Specify permissions for the new pty.                        Format is [pty-owner,[pty-group,]]pty-mode]        -u uid          Switch to given uid after setting up (must be root)        -g gid          Switch to given gid after setting up (must be root)        -/ chroot-dir   chroot(2) to given dir after setting up (must be root)	-q		Activate quiet mode	-v		Activate verbose mode	-V		Print version number then exit	-p pty-dev	Full path to pty device for front-end (used internally)	-t tty-dev	Full path to tty device for front-end (used externally)=head1 DESCRIPTIONinterceptty is designed to sit between a serial port (or otherterminal device, or program, or socket, or something connected to afile descriptor) and a program which is communicating with thatdevice, recording everything that goes back and forth between the two.It does this by opening the real device, creating a pseudo-tty, thenforwarding everything between the two, recording whatever it sees.  Ithas a number of options that let you fine-tune the devices it uses andthe terminal options for the real device.With the support for various backend types, interceptty is also usefulto create a fake serial port that will talk to the network or to aprogram you've written.  The -q switch will turn off its loggingoutput, and you can read about the different backends further down.The output of interceptty is a somewhat ugly, rudimentary format thatI usually postprocess through interceptty-nicedump, an included Perlscript.  More information about the output format is included later,in the Output section.To stop interceptty, press CTRL-C.  It doesn't exit under any othercircumstances except error conditions.=head2 Command-Line=over 4=item I<back-device>Use I<back-device> as the backend device---the device to whichI<interceptty> connects.  Normally it will be a character-specialdevice file, like a serial port or other tty-compatible device.  Youcan instruct interceptty to use other things for your backend by usinga I<back-device> that starts with one of several special characters.If I<back-device> starts with an C<@> and contains a slash (C</>), itwill be treated as a Unix socket.If I<back-device> starts with an C<@> and I<doesn't> contain a slash(C</>), it will be treated as an Internet hostname, followed by acolon, followed by a port.  interceptty will connect to that addressand port.If I<back-device> starts with an exclamation point (C<!>), it will betreated as a program to run.  That program will be started up, and itsstandard input and output will be connected to the frontend.If I<back-device> starts with an equal sign (C<=>), it will be treatedas a file descriptor to use, or a comma-seperated pair of filedescriptors.  The first file descriptor will be used for reading, andthe second for writing; if only one is specified, it will be used forboth.  These descriptors must already be opened by the program thatstarted interceptty.=item I<front-device>Use I<front-device> as the frontend device---the device to which otherapplications should connect to talk to the backend device throughinterceptty.  Normally interceptty will create a pseudo-terminal, thencreate a symlink to the master device at I<front-device>.  You cancontrol whether and how it creates a pseudo-terminal with the I<-t>and I<-p> options.  You can have it create no symlink by giving aI<front-device> of a single dash (C<->), and you can use things otherthan pseudo-terminals as a frontend by using a I<front-device> thatstarts with one of several special characters.If I<front-device> starts with an C<@> and contains a slash (C</>), itwill be treated as a Unix socket.  interceptty will create thissocket, and listen for connections.  This is the mode to use for newerversions of I<VMWare>.If I<front-device> starts with an C<@> and I<doesn't> contain a slash(C</>), it will be treated as a local interface name to listen on,followed by a colon, followed by a port.  interceptty will listen onthat interface and port.  Use an interface name of 0 to listen on alllocal interfaces.If I<front-device> starts with an equal sign (C<=>), it will betreated as a file descriptor to use, or a comma-seperated pair of filedescriptors.  The first file descriptor will be used for reading, andthe second for writing; if only one is specified, it will be used forboth.  These descriptors must already be opened by the program thatstarted interceptty.  This is useful for running interceptty underanother program, such as I<tcpserver>, I<inetd>, or I<stunnel>.=item -lLine-buffer output, displaying the intercepted data immediately as itcomes in.=item -o I<output-file>Write output to I<output-file> instead of standard output.=item -s I<back-stty>Run I<stty> with the given options on the backend, to configure it.You can use this to set the baud rate, character size, etc.  Youshould only use this if you have a TTY as your back-end.=item -qBe quiet.  Don't display intercepted data, and only display errors.=item -vBe verbose.  Asks interceptty to just say whatever's on its mind.Useful for debugging.=item -VPrint the version number and exit.=item -p I<pty-dev>Use I<pty-dev> as the physical frontend device that interceptty shouldconnect to, instead of creating a pseudo-tty.  This should be aTTY-compatible device, such as a serial port.=item -t I<tty-dev>Use I<tty-dev> as the device that an application should connect to,such as the other end of a pseudo-tty.  This device is opened and asymlink is created to it, and that's all.  If you're using a devicethat doesn't have two sides to connect to, like a serial port, don'tuse this option, and specify C<-> for the frontend.=back=head2 Outputinterceptty prints its output in a fairly unattractive, painful tolook at format.  However, it is very easy for other programs to parse.For an example of how to post-process this output into somethingappropriate to whatever you are intercepting, see the included Perlscript I<interceptty-nicedump>.Output lines are in this general format: < 0x54 (T) >       0x4b (K) ^ Direction   ^^^^ Hex code (to real device)        ^^^ ASCII character (to real device)         ^^^^ Hex code (from real device)              ^^^ ASCII character (from real device)The direction marker is a '<' if this character was sent I<to> thebackend device, and '>' if it was received I<from> the backend device.It is always followed by a single space.  If the character wasreceived from the real device, a tab will appear next (this makes theoutput easier to follow).  After that is the hex code for thecharacter, and the ASCII representation of the character if it is anASCII character.=head1 EXAMPLESHere's some examples of some common, useful, or interesting tasks youcan use interceptty for.=over 4=item VMWareI wrote this program to watch what a program running under I<VMWare>version 2 (L<http://www.vmware.com/>) was sending to the serial port.To do that, I ran:          interceptty -s 'ispeed 19200 ospeed 19200' -l /dev/ttyS0 |		    interceptty-nicedump then configured I<VMWare> to use /tmp/interceptty for COM1.Newer versions of I<VMware> use a socket.  You can use them like this:        interceptty -s 'ispeed 19200 ospeed 19200' -l \                    /dev/ttyS0 @/tmp/sersock |		    interceptty-nicedump then configure VMWare to use a "named pipe" at /tmp/sersock.You must start interceptty before you connect the serial device underVMWare.  If you stop interceptty with CTRL-C, or if it otherwise shutsdown, once you have connected it, you will need to disconnect andreconnect COM1 before it will work again.=item External Serial MonitorIf you want to use interceptty as an external serial monitor---connected totwo serial ports on your machine and relaying between them, whilerecording the output---you can use one device as the backend, and usethe I<-p> option to tell the frontend not to create it's own tty, butjust use the one you tell it:    interceptty -s 'ispeed 19200 ospeed 19200' /dev/ttyS0 \      -p /dev/ttyS1 -That lets you monitor serial communication between two non-PCdevices.  It's likely you'll need to use a null-modem cable to connectone of the devices.=item Network serial port serverIf you have a device connected to your serial port that you want tomake available over the network, you can create a socket frontend.If you just want to create a serial server without monitoring thetraffic, you can use the -q option:    interceptty -q -s 'ispeed 19200 ospeed 19200' /dev/ttyS0 \      '@0:4001'Note that this doesn't allow any kind of access control, but you canrun it under a program that does provide access control, liketcpserver.  See the example below.=item Network serial port clientIf you have a device available over a network serial port using asimple TCP connection or a telnet connection, you can create a virtualserial port on your system connected to it by using the network deviceas a backend.  I've tested this with several differentserial-to-Ethernet adapters available on the market.    interceptty -q '@serial-server.example.com:4001' \      /dev/serial-serverSome Digi brand serial-to-Ethernet adapters can use I<ssh>.  Toconnect to this, you can use a program backend:    interceptty -q '!ssh -p 4001 serial-server.example.com' \      /dev/serial-server=item Running under tcpserver/inetd/stunnelTo run under tcpserver or inetd, make sure that logging is turned offor directed to a file, then configure a backend of file descriptors 0and 1:    tcpserver 0 9999 \      interceptty -q -s 'ispeed 19200 ospeed 19200' /dev/ttyS0 =0,1=back=head1 SECURITYWhile an effort has been made to make sure that this code is free ofsecurity issues, it has not been thoroughly audited, and should notunder any circumstances be set-UID or set-GID to anything.  If nothingelse, the '-s' option will probably allow shell escapes, and using aprogram back-end is also dangerous.If this program is run as root, it will set up the pty portion of itspseudo-terminal to be only readable by itself, and will copy theownership and permissions from the real device to the tty portion.  Ittries to change this back before exiting, but if it crashes such thatit doesn't get to run its cleanup code, the ownership and permissionwill stay the same.If it is not run as root, it will make no effort to change thepermissions on the pseudo-terminal.  If you need to do this, select apseudo-terminal in advance, set the permissions appropriately, and usethe '-p' and '-t' options to instruct interceptty to use that deviceinstead of picking its own.=head1 SEE ALSOL<stty(1)>, L<minicom(1)>, L<tip(1)>.=head1 LICENSECopyright 2000-2004 by Scott Gifford E<lt>sgifford@suspectclass.comE<gt>This software is licensed under the GNU Public License.  See the fileCOPYING included with this distribution for details=head1 BUGSYou must set all serial options, such as baud rate, flow control,etc., up front with the '-s' option.  Any settings that theapplication sets using interceptty's pseudo-terminal will be ignored.I can't find a way around this; if you have ideas, please let me know.We make no attempt to lock backend device.  We probably should, but Idon't know how to do it portably.  If somebody has a nice API functionI can call, I will happily add locking support in.This program has only been tested under Linux, although the code isfairly portable.  I don't have access to another machine with serialports I can play with, so I haven't tried to port it.  I probablywon't port this to any other machines, but if you manage to, pleasesend me the patches and I will include them in future distributions.I have recently added autoconf support, which may be useful in makingthis program more portable.  But to be honest, I just used it so Icould get "make dist".=head1 HISTORYinterceptty is based in larte part on ttysnoop-0.12d, by CarlDeclerck.  Any bugs with interceptty should be reported to me, and notto Carl.  I basically adapted ttysnoop for my foul purposes, removedthe parts that weren't necessary anymore, and added appropriate optionprocessing.  ttysnoop was licensed under the GPL, and I have of coursekept that license for interceptty.=head1 AUTHORScott Gifford E<lt>sgifford@suspectclass.comE<gt>