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
application 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
forwarders 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
useful 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 personal
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
forwarder, 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 following 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.hostname.net:10080 to employ your forwarder. Note that all
connections to the same forwarder share the total bandwidth limit, so
two simultaneous 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 underscore
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/