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 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, "play games" 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 " 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