---
name: "iprelay"
section: "1"
platform: "linux"
package: "iprelay"
version: "0.71-4"
release: "Debian 7 (Wheezy)"
platforms: ["linux"]
url: "https://new.carta.tech/iprelay"
---

# iprelay(1)

A user-space bandwidth shaping TCP proxy daemon

## 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/