Provided by: iprelay_0.71-4_all bug
 

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 band‐
        width, much like a traffic shaping router would. However, this applica‐
        tion 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 pow‐
        ers  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  interac‐
        tively).
 
        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 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 ser‐
        vice 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 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.some‐
        where.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!]).   Permis‐
        sion  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.
                  /usr/share/doc/iprelay/README.gz
 
                  /usr/share/doc/iprelay/FAQ.gz
 
                  http://www.stewart.com.au/ip_relay/
 
                                                                     IPRELAY(1)