interceptty.1

intercept tty is using for listening a UART conversation

.Sp
If \fIfront-device\fR starts with an \f(CW\*(C`@\*(C'\fR and contains a slash (\f(CW\*(C`/\*(C'\fR), it
will be treated as a Unix socket.  interceptty will create this
socket, and listen for connections.  This is the mode to use for newer
versions of \fIVMWare\fR.
.Sp
If \fIfront-device\fR starts with an \f(CW\*(C`@\*(C'\fR and \fIdoesn't\fR contain a slash
(\f(CW\*(C`/\*(C'\fR), it will be treated as a local interface name to listen on,
followed by a colon, followed by a port.  interceptty will listen on
that interface and port.  Use an interface name of 0 to listen on all
local interfaces.
.Sp
If \fIfront-device\fR starts with an equal sign (\f(CW\*(C`=\*(C'\fR), it will be
treated as a file descriptor to use, or a comma-seperated pair of file
descriptors.  The first file descriptor will be used for reading, and
the second for writing; if only one is specified, it will be used for
both.  These descriptors must already be opened by the program that
started interceptty.  This is useful for running interceptty under
another program, such as \fItcpserver\fR, \fIinetd\fR, or \fIstunnel\fR.
.IP "\-l" 4
.IX Item "-l"
Line-buffer output, displaying the intercepted data immediately as it
comes in.
.IP "\-o \fIoutput-file\fR" 4
.IX Item "-o output-file"
Write output to \fIoutput-file\fR instead of standard output.
.IP "\-s \fIback-stty\fR" 4
.IX Item "-s back-stty"
Run \fIstty\fR with the given options on the backend, to configure it.
You can use this to set the baud rate, character size, etc.  You
should only use this if you have a \s-1TTY\s0 as your back\-end.
.IP "\-q" 4
.IX Item "-q"
Be quiet.  Don't display intercepted data, and only display errors.
.IP "\-v" 4
.IX Item "-v"
Be verbose.  Asks interceptty to just say whatever's on its mind.
Useful for debugging.
.IP "\-V" 4
.IX Item "-V"
Print the version number and exit.
.IP "\-p \fIpty-dev\fR" 4
.IX Item "-p pty-dev"
Use \fIpty-dev\fR as the physical frontend device that interceptty should
connect to, instead of creating a pseudo\-tty.  This should be a
TTY-compatible device, such as a serial port.
.IP "\-t \fItty-dev\fR" 4
.IX Item "-t tty-dev"
Use \fItty-dev\fR as the device that an application should connect to,
such as the other end of a pseudo\-tty.  This device is opened and a
symlink is created to it, and that's all.  If you're using a device
that doesn't have two sides to connect to, like a serial port, don't
use this option, and specify \f(CW\*(C`\-\*(C'\fR for the frontend.
.Sh "Output"
.IX Subsection "Output"
interceptty prints its output in a fairly unattractive, painful to
look at format.  However, it is very easy for other programs to parse.
For an example of how to post-process this output into something
appropriate to whatever you are intercepting, see the included Perl
script \fIinterceptty-nicedump\fR.
.PP
Output lines are in this general format:
.PP
.Vb 7
\& < 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)
.Ve
.PP
The direction marker is a '<' if this character was sent \fIto\fR the
backend device, and '>' if it was received \fIfrom\fR the backend device.
It is always followed by a single space.  If the character was
received from the real device, a tab will appear next (this makes the
output easier to follow).  After that is the hex code for the
character, and the \s-1ASCII\s0 representation of the character if it is an
\&\s-1ASCII\s0 character.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Here's some examples of some common, useful, or interesting tasks you
can use interceptty for.
.IP "VMWare" 4
.IX Item "VMWare"
I wrote this program to watch what a program running under \fIVMWare\fR
version 2 (<http://www.vmware.com/>) was sending to the serial port.
To do that, I ran:
.Sp
.Vb 2
\&        interceptty -s 'ispeed 19200 ospeed 19200' -l /dev/ttyS0 |
\&                    interceptty-nicedump
.Ve
.Sp
then configured \fIVMWare\fR to use /tmp/interceptty for \s-1COM1\s0.
.Sp
Newer versions of \fIVMware\fR use a socket.  You can use them like this:
.Sp
.Vb 3
\&        interceptty -s 'ispeed 19200 ospeed 19200' -l \e
\&                    /dev/ttyS0 @/tmp/sersock |
\&                    interceptty-nicedump
.Ve
.Sp
then configure VMWare to use a \*(L"named pipe\*(R" at /tmp/sersock.
.Sp
You must start interceptty before you connect the serial device under
VMWare.  If you stop interceptty with \s-1CTRL\-C\s0, or if it otherwise shuts
down, once you have connected it, you will need to disconnect and
reconnect \s-1COM1\s0 before it will work again.
.IP "External Serial Monitor" 4
.IX Item "External Serial Monitor"
If you want to use interceptty as an external serial monitor\-\-\-connected to
two serial ports on your machine and relaying between them, while
recording the output\-\-\-you can use one device as the backend, and use
the \fI\-p\fR option to tell the frontend not to create it's own tty, but
just use the one you tell it:
.Sp
.Vb 2
\&    interceptty -s 'ispeed 19200 ospeed 19200' /dev/ttyS0 \e
\&      -p /dev/ttyS1 -
.Ve
.Sp
That lets you monitor serial communication between two non-PC
devices.  It's likely you'll need to use a null-modem cable to connect
one of the devices.
.IP "Network serial port server" 4
.IX Item "Network serial port server"
If you have a device connected to your serial port that you want to
make available over the network, you can create a socket frontend.
If you just want to create a serial server without monitoring the
traffic, you can use the \-q option:
.Sp
.Vb 2
\&    interceptty -q -s 'ispeed 19200 ospeed 19200' /dev/ttyS0 \e
\&      '@0:4001'
.Ve
.Sp
Note that this doesn't allow any kind of access control, but you can
run it under a program that does provide access control, like
tcpserver.  See the example below.
.IP "Network serial port client" 4
.IX Item "Network serial port client"
If you have a device available over a network serial port using a
simple \s-1TCP\s0 connection or a telnet connection, you can create a virtual
serial port on your system connected to it by using the network device
as a backend.  I've tested this with several different
serial-to-Ethernet adapters available on the market.
.Sp
.Vb 2
\&    interceptty -q '@serial-server.example.com:4001' \e
\&      /dev/serial-server
.Ve
.Sp
Some Digi brand serial-to-Ethernet adapters can use \fIssh\fR.  To
connect to this, you can use a program backend:
.Sp
.Vb 2
\&    interceptty -q '!ssh -p 4001 serial-server.example.com' \e
\&      /dev/serial-server
.Ve
.IP "Running under tcpserver/inetd/stunnel" 4
.IX Item "Running under tcpserver/inetd/stunnel"
To run under tcpserver or inetd, make sure that logging is turned off
or directed to a file, then configure a backend of file descriptors 0
and 1:
.Sp
.Vb 2
\&    tcpserver 0 9999 \e
\&      interceptty -q -s 'ispeed 19200 ospeed 19200' /dev/ttyS0 =0,1
.Ve
.SH "SECURITY"
.IX Header "SECURITY"
While an effort has been made to make sure that this code is free of
security issues, it has not been thoroughly audited, and should not
under any circumstances be set-UID or set-GID to anything.  If nothing
else, the '\-s' option will probably allow shell escapes, and using a
program back-end is also dangerous.
.PP
If this program is run as root, it will set up the pty portion of its
pseudo-terminal to be only readable by itself, and will copy the
ownership and permissions from the real device to the tty portion.  It
tries to change this back before exiting, but if it crashes such that
it doesn't get to run its cleanup code, the ownership and permission
will stay the same.
.PP
If it is not run as root, it will make no effort to change the
permissions on the pseudo\-terminal.  If you need to do this, select a
pseudo-terminal in advance, set the permissions appropriately, and use
the '\-p' and '\-t' options to instruct interceptty to use that device
instead of picking its own.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIstty\fR\|(1), \fIminicom\fR\|(1), \fItip\fR\|(1).
.SH "LICENSE"
.IX Header "LICENSE"
Copyright 2000\-2004 by Scott Gifford <[e-mail]>
This software is licensed under the \s-1GNU\s0 Public License.  See the file
\&\s-1COPYING\s0 included with this distribution for details
.SH "BUGS"
.IX Header "BUGS"
You must set all serial options, such as baud rate, flow control,
etc., up front with the '\-s' option.  Any settings that the
application 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.
.PP
We make no attempt to lock backend device.  We probably should, but I
don't know how to do it portably.  If somebody has a nice \s-1API\s0 function
I can call, I will happily add locking support in.
.PP
This program has only been tested under Linux, although the code is
fairly portable.  I don't have access to another machine with serial
ports I can play with, so I haven't tried to port it.  I probably
won't port this to any other machines, but if you manage to, please
send me the patches and I will include them in future distributions.
I have recently added autoconf support, which may be useful in making
this program more portable.  But to be honest, I just used it so I
could get \*(L"make dist\*(R".
.SH "HISTORY"
.IX Header "HISTORY"
interceptty is based in larte part on ttysnoop\-0.12d, by Carl
Declerck.  Any bugs with interceptty should be reported to me, and not
to Carl.  I basically adapted ttysnoop for my foul purposes, removed
the parts that weren't necessary anymore, and added appropriate option
processing.  ttysnoop was licensed under the \s-1GPL\s0, and I have of course
kept that license for interceptty.
.SH "AUTHOR"
.IX Header "AUTHOR"
Scott Gifford <[e-mail]>