TCPreen : TCP re-engineering tool
==================================
$Id: README 178 2006-03-18 18:10:23Z remi $
Copyright (C) 2002-2004 Remi Denis-Courmont.

  Welcome to tcpreen's introduction manual!

Where to go?
-------------
  If you've used olders versions of this program, you should read NEWS
for a summary of the most recent updates and changes.

  For detailled usage instructions, you should refer to the Unix manual
page tcpreen(1) which should be provided with your copy of the program.
An HTML version of that manual "tcpreen1.html" is normally provided with
Windows binary packages for the convenience of Windows's users.

  See INSTALL for instructions on how to build the package and install
the program from sources on a Unix-like system.

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


What is TCPreen?
-----------------
  TCPreen is a command line tool used to monitor connection-oriented
network transmission, such as TCP/IP streams.
It acts as a bridge between the server and the client in a connection,
displays any data that is sent either way, and optionnaly logs
everything to a file.
  It can be useful for debugging, monitoring or reverse-engineering
purposes.

  Future releases might include transparent support for packet sniffing.


What are the supported platforms?
----------------------------------
  TCPreen should run fine on GNU/Linux, FreeBSD ,NetBSD , OpenBSD,
Sun Solaris, Mac OS X (with Fink) and Cygwin for Windows, with a C++
compiler. In fact, any recent Unix platform should be supported with
minimal changes.
  If you have any problem on your platform, please contact me so that we can
arrange a fix for the next release.


Quick tutorial
---------------
  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

  Let's have a very simple example:
  Say you have Mozilla running on machine "me.myisp.net" and Apache
running on machine "www.mydomain.com". You want to know exactly what
Mozilla sends to Apache and what he gets as a reply.

  So, login on "www.mydomain.com", and type:
# tcpreen -v -o mylog.txt 80 4096

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

  Alternatively, if you can't login on the Web server, you can use a
third machine or even the machine running Mozilla, and type:
# tcpreen -v -o mylog.txt -s www.mydomain.com 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 numbers under 1024 (aka "privileged ports").

  Now, you should see:

Listening on: 0.0.0.0 port 4096

  Tell Mozilla to connect to the machine running tcpreen on port 4096,
that is to say enter "http://www.mydomain.com:4096" in the URL field if
tcpreen is running on the Web server. You should see something like
this:

Connection from: me.myisp.net port 33063
Connection to: localhost port http

<<< GET / HTTP/1.1\r\nHost: www.mydomain.com\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 ">>> ".

  When you are bored, press [Ctrl]+C to terminate the program.

Happy day.

Remi Denis-Courmont <rdenis (at) simphalempin (dot) com>
http://www.simphalempin.com/dev/tcpreen/

