interceptty.1

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "INTERCEPTTY 1"
.TH INTERCEPTTY 1 "2004-09-05" "perl v5.8.3" "User Contributed Perl Documentation"
.SH "NAME"
interceptty \- Intercept traffic to and from a serial port.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 32
\& 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)
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
interceptty is designed to sit between a serial port (or other
terminal device, or program, or socket, or something connected to a
file descriptor) and a program which is communicating with that
device, recording everything that goes back and forth between the two.
It does this by opening the real device, creating a pseudo\-tty, then
forwarding everything between the two, recording whatever it sees.  It
has a number of options that let you fine-tune the devices it uses and
the terminal options for the real device.
.PP
With the support for various backend types, interceptty is also useful
to create a fake serial port that will talk to the network or to a
program you've written.  The \-q switch will turn off its logging
output, and you can read about the different backends further down.
.PP
The output of interceptty is a somewhat ugly, rudimentary format that
I usually postprocess through interceptty\-nicedump, an included Perl
script.  More information about the output format is included later,
in the Output section.
.PP
To stop interceptty, press \s-1CTRL\-C\s0.  It doesn't exit under any other
circumstances except error conditions.
.Sh "Command-Line"
.IX Subsection "Command-Line"
.IP "\fIback-device\fR" 4
.IX Item "back-device"
Use \fIback-device\fR as the backend device\-\-\-the device to which
\&\fIinterceptty\fR connects.  Normally it will be a character-special
device file, like a serial port or other tty-compatible device.  You
can instruct interceptty to use other things for your backend by using
a \fIback-device\fR that starts with one of several special characters.
.Sp
If \fIback-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.
.Sp
If \fIback-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 an Internet hostname, followed by a
colon, followed by a port.  interceptty will connect to that address
and port.
.Sp
If \fIback-device\fR starts with an exclamation point (\f(CW\*(C`!\*(C'\fR), it will be
treated as a program to run.  That program will be started up, and its
standard input and output will be connected to the frontend.
.Sp
If \fIback-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.
.IP "\fIfront-device\fR" 4
.IX Item "front-device"
Use \fIfront-device\fR as the frontend device\-\-\-the device to which other
applications should connect to talk to the backend device through
interceptty.  Normally interceptty will create a pseudo\-terminal, then
create a symlink to the master device at \fIfront-device\fR.  You can
control whether and how it creates a pseudo-terminal with the \fI\-t\fR
and \fI\-p\fR options.  You can have it create no symlink by giving a
\&\fIfront-device\fR of a single dash (\f(CW\*(C`\-\*(C'\fR), and you can use things other
than pseudo-terminals as a frontend by using a \fIfront-device\fR that
starts with one of several special characters.
.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 <sgifford@suspectclass.com>
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 <sgifford@suspectclass.com>