Simple TCP re-engineering tool, aka TCPreen
============================================
$Id: README,v 1.3 2003/01/26 09:09:07 rdenisc Exp $

  If you have used previous releases of this program, you should read
NEWS for a summary of most recent updates and changes.

  See INSTALL for instructions on how to build the package and install
the program from sources.

  These package is distributed under the terms of the General Public
License (GPL) version 2 written by the Free Software Foundation, Inc.
for more details, please read COPYING.

Summary
--------
1. What is TCPreen?
2. Features
3. How it works?


1. What is TCPreen?
--------------------
  TCPreen is a small tool for monitoring a TCP connection.
It works like a bridge between the server and the client in a TCP
connection, displays any data that is sent either way, and optionnaly
logs everything to a file.

  It is mainly useful if you want to understand what informations a
client and a server exchanges during a TCP session. It was originally
meant to help reverse engineering proprietary TCP-based protocols or
protocol extensions.

  TCPreen was compiled successfully on:
* GNU/Linux kernel 2.0/2.2/2.4 + Glib 2.0/2.2
* FreeBSD 4.4/4.7/5.0,
* Redhat's Cygwin 1.3 over Microsoft Windows,
* Sun Solaris 8.

  Older versions worked on:
* NetBSD 1.5,
* OpenBSD 3.1/3.2.

  TCPreen does not work on MacOS X at the moment. Help would be appreciated.

  It should work on any hardware architecture. The following architectures
are known to work: i386, mips, powerpc and sparc64. Other supported
architectures include: alpha, arm, hppa, ia68, m68k, mipsel, s390, sparc and
vax.

  If you have any problem on your platform, please tell me so that we can
arrange a fix for the next release. I'm not going to help Windows users.
If you succesfully compiled it on another platform, you're welcome!


2. Features
------------

* IPv6-aware application (WARNING: link local addresses are not yet supported
  as there is no way to specify interface name at the moment),
* Out-of-band data support,
* reverse DNS lookup support (can be desactivated for better
  performance),
* on-demand multi-process daemon mode support (Unix only),
* single connection support (for quick manual operations),
* multiple log file formats: hexadecimal, C source-like, printable 
  characters only, raw, and ability to log to multiples files at the
  same time,
* optionnal system log (syslogd) support (Unix only),
* multiple listening socket for multiple protocols (ie. IPv4 and IPv6),
* on-demand Out-of-band data inlining (otherwise Out-of-band data is
  simply ignored),
* symetrical TCP bridge (so that you can use telnet to fake a server by
  hand),
* unprivileged UID selection for safe operation on reserved ports (Unix
  only)
* Set-UID awareness (BSD-like systems only),
* connections number limitation,
* connection length (in bytes) limitation,
* long command line options for better script readability (with GNU C
  library only, or gnugetopt package on *BSD),
* software-level networking, for better performance (need a lot less
  resources than common packet sniffers), better reliability, and
  lower protocol independance,
* GNU `gettext' support, French translation included.


3. How it works?
-----------------
  You can get help about command line syntax by typing:
# tcpreen -h | more

  For in depth help, you may refer to the man page that is provided:
# man tcpreen

  Right, let's have a very simple example:
  Say you have Mozilla running on machine clientA and Apache running on
machine serverB. We assume that Apache is listening on TCP port 80 (on
any interface) on serverB. You want to know exactly what Mozilla sends
to Apache and what your Web server reply.

  So, login on B, and type:
# tcpreen -v -o clientA.log 80 4096

"-v" enables verbosity, so that you can see what is happening on your
console. "-o clientA.log" tells the program to save informations for
future reference in log file clientA.log in the current directory.

  Alternatively, if you can't access B, you can use a third machine,
or even A, and type:
# tcpreen -v -o clientA.log -s serverB 80 4096

NOTE: 4096 is an arbitrary number. Any valid port number can be used,
but be sure to use an available port. Additionnaly, remember that only
root can use port equal to or below 1024 (aka "privileged ports").

  Now, you should see:

Listening on: [0.0.0.0]:4096

  Go to clientA, starts Mozilla and tell it to connect to serverB.
You should see something like this:

Connected from: [192.168.1.125]:33063
Connected to: [localhost.localdomain]:http

<<< GET / HTTP/1.1\r\nHost: serverB\r\n [...]
>>> HTTP/1.1 200 Ok\r\nServer: Apache\r\n [...]

  Data sent by the client appears after "<<< ". And as you guessed,
data sent by the server appears after ">>> ".

  That's all.

Happy day.

Rmi Denis-Courmont
http://www.simphalepin.com/dev/tcpreen/

