	README for ip_relay.pl

	Gavin Stewart	20000105
	gavin@stewart.com.au

 				------------------

 - What is it.
 - What's new?
 - Why use it.
 - How to use it.
    - Quick start.
    - Advanced operation.
    - Variable summary.
 - Where to get it.
 - Copying/Modifying it.

 				------------------

  What is it.
  -----------

	ip_relay.pl is actually a TCP relay application. The primary goal
was to find a mechanism for me to apply traffic shaping to my long downloads,
so as to "free up" bandwidth when I suddenly decided that I needed it.

	In hindsight some of what it has become is remarkably like a socks
functionality subset ...... a TCP proxy.

  (What it isn't - WARNING!.
   --------------
  	- Authenticated.
	- Secure.
	- Designed for multiple users.)

  What's new?
  -----------

  	- New to version 0.71, there are two new command line options:
	  -b <num>	Used to specify the max bytes/sec on the command line.
	  -d 		To daemonise, and run in the background.

	  This allows the following single line, backgrounded tcp shaper:

	  ip_relay.pl -d -b 2000 8080:proxy.someplace.net:3128

	  You now have a 2000 byte / sec tcp port (8080) on the host you
	  ran ip_relay on forwarding to proxy.someplace.net:3128, AND now
	  daemonised as well.

	  If you were really keen, you could use this to quickly set up
	  a shaper into another shaper: Lets say you would like
	  to provide a total shaped bandwidth of 3000 bytes / sec max,
	  with a shaped bandwidth of 1000 bytes / sec for POP *within* the
	  3000 b/s max:

	  on the machine your.host:

	  ip_relay.pl -d -b 1000 1110:localhost:1210    <- this is daemonised
	  ip_relay.pl -b 3000 1210:pop.someplace.net:110  <- normal commandline

	  then at ip_realy.pl prompt:
	  > set forwarder 1 8080:proxy.someplace.net:3128

	  results in:
	    - connect to your.host:1110 to get POP shaped to a max of 1000 b/s
	    - connect to your.host:8080 to get WWW shaped to a max of 3000 b/s
	    - total *combined* bandwith is 3000 b/s max.
	    (as opposed to two completley unrelated shapers for POP and WWW,
	     that would be a total combined bandwith of 4000 bytes / sec max.)

  Why use it.
  -----------

  	I found I had a major problem with bandwidth availability .... mainly
because in Australia it is not fiscally practical to buy anything but modem
connectivity to the Internet (for home use). A convenient mechanism that I 
found was to relay all my downloads through an application that I could 
suddenly change the amount of data per unit time passed through it.

	So:
	    - If you use a modem for Internet connectivity.
	    - If you have large downloads.
	    - If you want to do something *other* than download ..... surf,
	        chat, telnet, <cough> "play games" </cough>
	    
	    then *maybe* ip_relay.pl can help you.

	Actually I found this application really neat when I was testing
the java implementation of vnc over ssh. The tests were over ethernet and I 
needed to simulate modem speeds to see if it was usable.


 How to use it.
 --------------

    Usage: ip_relay.pl [ [-d] [-b n] local_port:remote_host:remote_port]
        -d        Daemon mode, go straight into background.
                  (you loose all logging and console access.)
        -b n      Bandwidth, where n is max bytes/sec.

    Scenario:
    	- using secure copy (scp) to fetch a large file (file.dat) from
          a host (host.com) to the localhost.
	- localhost is connected to the Internet via a 33.6K modem.
	- the modem is the narrowest point in the pipe.

    Quick start:
	- Example on localhost shell prompt: 

bash$ ip_relay.pl 2222:host.com:22
  Resolving address (host.com)..... 
  .... determined as: 192.168.1.5
Using command line parameters:
  local_port    2222
  remote_addrs  192.168.1.5
  remote_port   22
  forwarder 99 set.


ip_relay.pl Version: x.x
Copyright (C) 1999 Gavin Stewart

Passive socket setup on 0.0.0.0:2222
> 

	- at this point we have set up a listening socket on localhost port
 	  2222 that will transparently forward data to and from host.com port
	  22. (We have assumed that the port for ssh is 22.)

	- '>' is the ip_relay prompt, you can issue commands here, like: ?

	- We start our scp in a different shell prompt:

bash$ scp -P 2222 localhost:file.dat .

	- At the ip_relay_prompt:

> sh stat
  Total connections: 1
  Bandwidth is not set.
  Forwarding connections for:
    127.0.0.1:3702 -> 192.168.1.5:22 (CONN000001)
        Connection Up: 35 secs. Idle: 0 secs.
        Bytes transfered: 86771 in, 451 out.
        Data rate       : 2.42 kB/s in, 0.01 kB/s out.
            (5 sec avg.): 3.22 kB/s in, 0.00 kB/s out.
            (1 min avg.): 1.12 kB/s in, 0.00 kB/s out.

	- Pretty obvious, we have our download working, now to the useful
	  stuff:

> sh bandwidth
bandwidth       0
> set bandwidth 2000
bandwidth       2000
> sh stat
  Total connections: 1
  Bandwidth set to: 2000 bytes / sec.
  Forwarding connections for:
    127.0.0.1:3702 -> 192.168.1.5:22 (CONN000001)
        Connection Up: 2 mins, 20 secs. Idle: 0 secs.
        Bytes transfered: 400091 in, 451 out.
        Data rate       : 2.79 kB/s in, 0.00 kB/s out.
            (5 sec avg.): 1.97 kB/s in, 0.00 kB/s out.
            (1 min avg.): 2.47 kB/s in, 0.00 kB/s out.
> 

	- We now have spared approx 1.2kB/s to be used for anything else,
	  you would probably find telnet a bit latent in response, but you
	  can certainly get a better surfing experience.

	- You can now start another download from the same host if you wished.


    Advanced operation:
	So far the example is the most basic, and also the one that I use most.
There are however many more options to use, and a little understanding of
how TCP works can help tweak maximum use out of this application.
	The command line parameter: 2222:host.com:22 set up what I have called
a "forwarder", a rule defining what port on the machine running ip_relay is
to be forwarded onto another machine and port. Multiple forwarders may be
set, for many different remote machines and ports:

> sh all
local_addrs     0.0.0.0
force_from      0.0.0.0
debug   1
dump_traff      0
idle_out        3000
dead_count      10
data_size       500
bandwidth       2000
forwarders:
  forwarder 99 2222:192.168.1.5:22
> set forwarder 2 8080:www.microsoft.com:80
  Resolving address (www.microsoft.com)..... 
  .... determined as: 207.46.131.28
  forwarder 2 set.
Passive socket setup on 0.0.0.0:8080
> sh all
local_addrs     0.0.0.0
force_from      0.0.0.0
debug   1
dump_traff      0
idle_out        3000
dead_count      10
data_size       500
bandwidth       2000
forwarders:
  forwarder 2 8080:207.46.131.28:80
  forwarder 99 2222:192.168.1.5:22
>

	- We have added another forwarding rule - 2, in addition to the one
	  originally specified on the command line - 99.

> set forwarder 99
  forwarder 99 deleted.
>

	- Most commands may use ? as a parameter to display help, in this
	  example "set forwarder <nn>" with no rule deletes the forwarder.

    Variable summary:

	local_addrs - set this to force a particular address to listen on,
		this is particularly useful for multi-homed, or multiple
		aliased interfaces on a host. (This is only relevant when
		the connection is being made, and irrelevant to any forwarding
		rule set up.)

	force_from - set this to make the connection between the ip_relay host
		and the remote host to originate from a particular address,
		again this is useful for multi-homed, or multiple aliased 
		interfaces on a host. (This is only relevant when the 
		connection is being made, and irrelevant to any forwarding 
		rule set up.)

	debug - set to view debug information, connections being established,
		connections torn down, idle time outs, etc.

	dump_traff - really ugly mess of traffic being dumped as it passes
		through ip_relay.

	idle_out - Allowed idle time, in seconds, between client<->ip_relay AND
		ip_relay<->server

	dead_count - Variable used internally to determine if socket is really
		dead.... I found the perl implementation to not return correct
		error values in some instances for reading on a closed socket.
		(Probably best left alone, should be moved internal to the
		 program.)

	data_size - Chunk of data to try and read on a socket, and so forward
		onto the write socket. This can be tweaked to a much smaller
		size when trying to maintain interactivity, and ip_relay is
		running on the other side of the bandwidth congestion. (More
		on this in the FAQ).

	bandwidth - Number of bytes / sec that ALL forwarding TCP streams should
		consume.
	

  Where to get it.
  ----------------

  	http://www.stewart.com.au/ip_relay


  Copying/Modifying it.
  ---------------------

  	ip_relay has been released under the GPL, however the code remains
copyrighted by me, Gavin Stewart.

	It would be nice to have any changes made to this application, that
would be released to the public, forwarded onto myself, so that they may be
considered for inclusion in future releases of this software. Although I
admit that it does almost all I ever wanted it to at the stage it is now.

	I may be reached via email:
		gavin@stewart.com.au
