SOCKSPY README

Sockspy 1.0  Copyright Tom Poindexter, 1998
tpoindex@nyx.net
  
See the file 'LICENSE.TERMS' for licensing information.
It's a BSD style, open source license.


WHERE TO GET IT

http://www.neosoft.com/tcl/ftparchive/sorted/net/sockspy-1.0/1.0/sockspy-1.0.tar.gz
ftp://ftp.neosoft.com/pub/tcl/sorted/net/sockspy-1.0/1.0/sockspy-1.0.tar.gz

Web info:
http://www.nyx.net/~tpoindex


WHAT IS SOCKSPY ?

Sockspy lets you watch the conversation of a Tcp client and server.  Sockspy
acts much like a gateway: it waits for a Tcp connection, then connects to 
the real server.  Data from the client is passed onto the server, and 
data from the server is passed onto the client.  

Along the way, the data streams are also displayed in listboxes, one for
client originated data, another for the server.  The data can be displayed
as printable ASCII strings, or as a hex dump format of both hex and printable
characters.

Why might you want to use Sockspy?  Debugging Tcp client/server programs,
examining protocols and diagnosing network problems are top candidates.
Perhaps you just want to figure out how somethings work.  It's not a
replacement for heavy duty tools such as 'tcpdump' and other passive
packet sniffers.  On the other hand, Sockspy doesn't require any
special priviledges to run (unless of course, you try to listen on a
Unix reserved Tcp port less than 1024.)


REQUIREMENTS

Sockspy requires Tcl/Tk 8.0.  If you don't already have Tcl/Tk, you can get
it from:

	http://www.scriptics.com
	ftp://ftp.scriptics.com/pub/tcl/tcl8_0/tcl8.0.4.tar.gz
	ftp://ftp.scriptics.com/pub/tcl/tcl8_0/tk8.0.4.tar.gz


WINDOWS & MACINTOSH

Sockspy is 100% Tcl, and can run on Windows and Macintosh. I've tested on 
Windows.  You will need to start Sockspy from a command line (or possibly
a batch file), as command line arguments are used to configure Sockspy.


USING SOCKSPY

Start Sockspy from the command line: 

	$ sockspy <listen-port> <server-host> <server-port>

	listen-port:  The Tcp port on which to listen.  Clients should
			connect to this port.

	server-host:  The host where the real server runs.  Host can be
			specified as an dotted IP address or as a hostname.

	server-port:  The Tcp port on which the real server listens.

Examples:

   1. HTTP
	To watch the HTTP protocol traffic to a particular web server:

	$ sockspy 8000 www.some.com 80

	then with your browser, use a url of:
		http://localhost:8000/index.html

	Using this method, you will have to start a new sockspy for each
	HTTP host you access.
	If you normally run an HTTP proxy, start 'sockspy 8000 webproxyhost 80'
	and just set your browser's proxy to use the Sockspy host and port.

   2. Telnet
	To watch your Telnet session to 'otherhost':

	$ sockspy 2000 otherhost 23
	$ telnet localhost 2000

   3. Database connectivity (Sybase example)
	Define an 'interfaces' entry for sockspy:

		SYBASE
			query tcp ether dbserv 5000
			master tcp ether dbserv 5000

		SPY
			query tcp ether sockspyhost 5500
			master tcp ether sockspyhost 5500

	$ sockspy 5500 dbserv 5000
	$ isql -SSPY 


INSTALLATION

Simply copy 'sockspy' to the executable directory of your choice.
You may need to 'chmod +x sockspy' to allow direct execution.  You
will also need access to a 'wish8.0' Tcl/Tk interpreter on your PATH.


RUNNING SOCKSPY

If you've gotten this far, you probably don't need any help with the
user interface.  Sockspy has few controls:

	hex    	display as hex dump format, 16 hexadecimal digits
		per line, plus whatever printable ASCII characters might
		be usable.
	ascii 	display as printable string, 66 characters maximum per line.
		Newline characters (\n) in the data stream cause a new
		line to be added to the listbox.  Lines that exceed 66 
		characters are continued on the next line, with a plus 
		symbol ("+") marking the continuation.
	autoscroll
		whether or not the display should scroll to the bottom
		when new data is recieved.
	+ font  increase the font size by one.
	- font  decrease the font size by one.
	clear  	clear the display
	save 	save either the server, client, or both windows to a file.
	kill 	exit Sockspy.

        <selection> you can select one or more lines in either listbox.  A
		selection handler allows the selection to be pasted as
		ordinary lines rather than Tcl lists.

NOTES

Sockspy uses one scroll bar for two listboxes.  Scrolling with the scrollbar
scrolls both windows, keeping them in sync.  If you happen to scroll one
listbox using Button 2 motion, or use Button 1 motion while selecting, the
listboxes may become unsynchronized.  I'm not sure if this is a bug or
a feature.  In any case, if you have checked 'autoscroll', the next
input will then re-synchronize the listboxes.


Tom Poindexter
tpoindex@nyx.net