Introduction
============
This document gives an overview of the WRR scheduler.

The WRR scheduler was developed to solve a particular problem. It was developed 
at a site where many people shared a heavily used internet connection. The WRR 
scheduler is able to distribute the bandwidth allocated to the different 
machines of the site in a fair way. That is, as a default every machine will 
get equally much of the bandwidth if they have sufficient demand.

Originally the site was setup in the following way:

  +----------+     +------------+     +------------+    | 
  | LAN with |     | Router     |     | Modem      |    |
  | 200      ------- installed  ------- installed  -------
  | machines |     | by the ISP |     | by the ISP |    |
  +----------+     +------------+     +------------+    |
                                                       Wall

The problem here was, that if one machine on the LAN for example opened 10 ftp 
connections, it would get 10 times as much bandwidth as a machine just opening 
1 connection. To solve this problem the setup was changed to:

  +----------+     +-----------+     +------------+     +------------+    |
  | LAN with |     |           |     | Router     |     | Modem      |    |
  | 200      ------- Linux box ------- installed  ------- installed  -------
  | machines |     |           |     | by the ISP |     | by the ISP |    | 
  +----------+     +-----------+     +------------+     +------------+    |
                                                                         Wall

The Linux box has two Network cards. It was configured as an Ethernet Bridge 
and used Traffic Control with the WRR and CBQ (CBQ is included in the kernel) 
schedulers to distribute the bandwidth (both incoming and outgoing) in a 
fair way. Doing this is called shaping.

One good thing of this setup is, that there was no need to change 
any configuration of the other parts of the network since the box is 
transparent. Its only function is to drop and reorder packets in a clever 
way. And if it stops working for some reason or if it needs to be reconfigured
it is very easy to disconnect it by just moving a few cables.

Review note: Wrr can also run directly on routers and masqgrading firewalls.

Directions
==========
It is important to understand that there are two directions to shape the 
traffic: The incoming (from the internet) traffic and the outgoing
(to the internet) traffic. To shape the incoming traffic WRR should be
setup on the interface on the LAN side of the Linux box. To shape outgoing 
traffic it should be setup on the router side. To shape both you should 
set it up for both interfaces. The example setup included in this distribution
does this.



Setting the bandwidth parameter
===============================
To make things work the Linux box needs to limit the bandwidth data can be 
transfered with. The reason why this is necessary is, that the box only works 
if it is the bottleneck of the connection. If it is not, the box will just pass
all packets through, and it will be the router that shapes the traffic. 

Exactly what the bandwidth should be limited to is the most central and most 
difficult parameter to set.

If the bandwidth is set too high, the box will be without or with only limited 
effect. If set too low, people will be angry at you because you have decreased 
their highly valuable and probably expensive bandwidth to much.

To find a good value you will need to use the connection in full and monitor 
with which speed the machines of the LAN transfer data. The Wipl program which 
is described on the WRR homepage and elsewhere in this package is very useful 
for doing this. The example setup included in this package generates the 
relevant statistics out of the box using Wipl.

You might want to use the following strategy to find a good value for the 
bandwidth:

  1) Setup Wipl to monitor the bandwidth on the router side of the machine
  2) Set the bandwidth to bee too high.
  3) Find the maximal total transfer speed which seems to be holdable for 
     some period of time.
  4) Set the bandwidth such that the total usage on the router side interface 
     is always or almost always a bit lower than the value found in 3). Note 
     that bandwidth usage will probably increase when new TCP connections are 
     opened. Also note that it might take some time from you adjust the
     bandwidth until you see bandwidth usage reflecting the new value.

Note that to get any effect of the bandwidth limitation at all you will
probably need to use a value somewhat lower than the speed the connection
is specified to have. 

In principle you should do the steps above for the incoming and outgoing
direction separately. If you line has the same transfer speed in both 
directions, you should be able to use a higher value for the outgoing than for 
the incoming traffic.

At the site where I live we don't use all our outgoing bandwidth, so I just
use the same value at both directions. That is, I use the value optimal for
the incoming traffic.

I have used the value 240Kbit for a connection which was specified to
be 256Kbit and 470Kbit for a connection specified to be 512Kbit. And I think 
the rate was maybe a bit too high in the former case and a bit too low in the 
later. So maybe you should just subtract around 7% from the specified 
bandwidth.

Anyway I will strongly recommend you to experiment to find the values optimal
at your site.


Locally generated traffic
=========================
It is very imporatant that the box which shapes the traffic does NOT
generate any traffic on the internet connection. Such kind of traffic will
not be limited in the incomming direction and this will spoil shaping of all
incomming traffic!


--------------------------------------------------------------------
This document was written by Christian Worm Mortensen, cworm@it-c.dk
