IPRELAY(1)						      General Commands Manual							IPRELAY(1)

NAME

       iprelay -- A user-space bandwidth shaping TCP proxy daemon

SYNOPSIS

       iprelay [ [-d ]	[-b n ]  [proxyspec ] ]

DESCRIPTION

       This  manual  page briefly documents the iprelay command. It was written for the Debian GNU/Linux distribution because the original program
       does not have a manual page.

   Overview
       iprelay can shape the TCP traffic forwarded through it to a specified bandwidth and allow this bandwidth to be changed on-the-fly. Multiple
       data streams to different sockets may be shaped to the same total bandwidth, much like a traffic shaping router would. However, this appli-
       cation runs in user space, and works by acting as a TCP proxy.

   Usage
       The proxyspec argument can be used to setup an initial proxy (the author calls them forwarders). iprelay can theoretically handle more for-
       warders	than  you'd  ever need, but only one can be set up initially. It will be forwarder #99 in interactive mode. The format is the same
       as, e.g. ssh uses for port forwarding:

	 local_port:remote_host:remote_port

       For every defined forwarder, iprelay will bind to the  specified  local_port  and  forward  any	connections  to  the  remote_port  of  the
       remote_host  (which  may  be specified by name or IP, as usual). Only root may bind to ports 1023 and under. See the EXAMPLES section for a
       quick introduction.

       Without the -d option, iprelay will go into interactive mode (see /usr/share/doc/iprelay/README.gz for a detailed explanation of the powers
       of  interactive mode). If proxyspec is specified, it will setup the initial forwarders before presenting the prompt. At the prompt, you may
       then adjust and/or modify your initial forwarder (e.g. adjusting the bandwidth limit), add and remove forwarders, and display various  use-
       ful and not-so-useful information about the forwarder(s). Use ctrl-c (<break>) to quit interactive mode.

       The -d option daemonises iprelay. If specified, iprelay will run non-interactively and fork into the background. You will loose all logging
       and diagnostic messages, as well as the ability to reconfigure iprelay at runtime. Therefore you need to specify proxyspec to tell  iprelay
       about  the  one (and only) forwarder it's supposed to establish. You may, of course, spawn several instances of iprelay to handle your per-
       sonal proxying needs.

       The -b option allows the specification of a maximum bandwidth in bytes/second. Any connection proxied by iprelay will not shove more  bytes
       over   the   wire   per	 second   than	 specified   with   this  option.  This  limit	can  be  adjusted  at  runtime,  as  described	in
       /usr/share/doc/iprelay/README.gz. This option is only valid when the proxyspec argument is given (contrary to intuition, it can't (yet)	be
       used to setup a default bandwidth for proxies you create interactively).

       iprelay was written in Perl.

OPTIONS

       -b n	 Desired maximum bandwidth, where n is in bytes/second. Only valid when proxyspec is also specified.

       -d	 Daemon mode, go straight into the background. (you loose all logging, console access, and runtime bandwidth adjustment features).
		 Only valid when proxyspec is also specified.

       proxyspec The   proxy   (forwarder)   definition   in   the   form   of	 the   following    triple    (c.f.    ssh    port    forwarding):
		 local_port:remote_host:remote_port

EXAMPLES

   A simple forwarder
       Let's  say  you	are moving POP3 service from one server to another, but you're waiting for the DNS caches around the world to get updated.
       Thus pop3.myserver.net might point to the new machine for some users, but to the old machine for another set of users. To bridge  the  time
       until  all  users  are directed to the new machine via pop3.myserver.net, you could simply set up a forwarder as follows on the old machine
       (1.2.3.4 is the new machine's IP):

	 iprelay -d 110:1.2.3.4:110

       Now any request for POP3 that happens to arrive at the old machine still will simply be proxied to the new machine by this daemonised  for-
       warder,	and  your  users are not even going to know ;>. Note that you have to be root the install this forwarder, as it binds to the local
       port 110, which is a privileged ports on any sensible operating system.

   A simple bandwidth-shaping forwarder
       In another example, to ensure that your HTTP connection to www.microsoft.com never exceeds 512 bytes per second, you could setup  the  fol-
       lowing single line, backgrounded TCP shaper:

	 iprelay -d -b 512 10080:www.microsoft.com:80

       With  this  in the background, any connection to localhost:10080 will be proxied to www.microsoft.com, and you can be sure not to waste any
       bandwidth beyond the 512 bytes/second. Feel free to provide this service to your colleagues, who  simply  have  to  connect  to	your.host-
       name.net:10080 to employ your forwarder. Note that all connections to the same forwarder share the total bandwidth limit, so two simultane-
       ous connections are going to get 256 bytes/second each in the ideal case.

   Customized sharing of bandwidth between multiple channels
       You want more? Let's make this a little more complicated. Say that you would like to provide a total shaped bandwidth of 3072  bytes/second
       with a "subchannel" with at most 1024 bytes/second within	   the 3072 bytes/second limit:

	 iprelay -d -b 1024 10110:localhost:10001
	 iprelay -b 3072 10001:pop3.somewhere.net:110

       then, at the interactive prompt:
	 > set forwarder 1 8080:www.somewhere.net:80

       and  you  can connect to localhost:10110 to get POP3 from pop3.somewhere.net at 1024 bytes/second, you can connect to localhost:8080 to get
       HTTP from www.somewhere.net at a maximum of 3072 bytes/second, but both together are not going to use more than 3072 bytes/second; the HTTP
       forwarder delegates up to 1024 bytes/second to the POP3 forwarder if necessary.

       Please  consult	/usr/share/doc/iprelay/README.gz  for more examples, and specifically for examples on how to harness the complete power of
       the interactive prompt.

NOTES

       iprelay's author named the software ip_relay, and had the Perl script be called ip_relay.pl. In accordance with Debian policy,  the  under-
       score had to leave, and I (Martin) removed the ".pl" suffix for aesthetic reasons.

BUGS

       Let us know if you find any...

AUTHOR

       Gavin Stewart <gavin@stewart.com.au>

       This  manual  page was written by Martin F. Krafft <madduck@madduck.net> for the Debian GNU/Linux system (but may be used by others [if you
       promise to consider looking at Debian GNU/Linux sometime!]).  Permission is granted to copy, distribute and/or modify this  document  under
       the  terms  of  the  GNU  Free  Documentation  License, Version 1.1 or any later version published by the Free Software Foundation; with no
       Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.

SEE ALSO

		 /usr/share/doc/iprelay/README.gz

		 /usr/share/doc/iprelay/FAQ.gz

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

																	IPRELAY(1)