Man Linux: Main Page and Category List

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/