		RSHAPER - shape incoming traffic
		================================

This is a module for version  2.0 of the Linux  kernel, it is meant to
limit the incoming  bandwidth for  packets  aimed at  different hosts.
With "incoming" I mean  traffic that enters the  shaping host; if that
host is a gateway between  target hosts and the  rest of the Internet,
all the traffic of the target hosts will be shapeable.

I see two interesting uses for this tool:

	* Limiting   the bandwidth available  to permanently connected
		hosts by installing rshaper on  their gateway. This is
		interesting  for ISP  who offer  housing  and want  to
		differentiate the offer.

	* Limiting download bandwidth  from students' boxes or similar
		setups, by installing  the   rshaper directly  on  the
		target computer. This  requires that the user of  that
		computer can not gain superuser privileges.

While  the former issue can be  addressed with the conventional shaper
driver, the    latter  can't be  easily   addressed by   the  standard
shaper. As a matter of facts,  I have not been able  to use the shaper
to  address   the former situation,   either;   this because effective
filtering can only be achieved through  source-routing, but when I had
to deal  with  this problem, the  shaper  only existed for Linux-2.1
while my production setup was constrained to be 2.0.

Well, maybe all of this is completely unneeded  now that 2.2 is there.
On the other hand this module is easier to setup and maintain than the
standard shaper, at least for non-gurus.

		INSTALLATION
		============

First of  all "make". You'll end  up with an "rshaper.o" module, which
needs to be loaded  to your kernel. Note however  that the kernel must
be modified in order to support  the rshaper module. The exact changes
to the kernel depend  on your particular setup,   so a new section  is
needed:

		THEORY OF OPERATION
		===================

The  idea is easy:  whenever  a packet is   received through a network
interface, the rshaper module delays notification of the packet to the
network subsystem of Linux according to the expected data flow for the
involved host.

In order to delay reception of the  packet, the network driver must be
modified to call the shaper's receive function instead of the standard
netif_rx().   Therefore, you  must modify two  lines   of your network
device driver.  In case  you use a NE2000  clone or another 8390-based
ethernet device,  you can use  the patch included  in this  package as
"8390.c.patch". If you  are new to  patches, please refer to the  last
section.

If your ethernet driver is not an 8390-based  one, you have to do your
own changes (while I might  offer patches for  other devices, I am too
lazy to do it with this release).

The code is simple:

  (1) in global space add the following line:
          int (*net_shaper_rx_hook)(struct sk_buff *skb) = NULL;

  (2) in the receive function of the driver change
           netif_rx(skb)
  to
           if (net_shaper_rx_hook)
                   (*net_shaper_rx_hook)(skb);
           else
                   netif_rx(skb);

NOTE-A: If your network interfaces are  of different kinds, change (2)
above  must be  applied  to all  the   drivers  involved with  shaping
traffic, while change (1) must be applied differently:

  (1a) only one network driver must have this line:
          int (*net_shaper_rx_hook)(struct sk_buff *skb) = NULL;

  (1b) every other driver must have:
          extern int (*net_shaper_rx_hook)(struct sk_buff *skb);

The module with modification (1a) must  be loaded before the ones with
modification  (1b),  otherwise  loading will   fail  with ``unresolved
symbol "net_shaper_rx_hook"''

NOTE-B: If  your ethernet driver(s)  is  linked in the  kernel  image,
instead  of     being   a  module,   you   must   also    arrange  for
"net_shaper_rx_hook"   to  be   exported to  modules,      so that the
"rshaper.o"  module will  find   it.  To  do  this,   apply the  patch
"ksyms.c.patch" to kernel/ksysms.c in the kernel sources.

Please don't apply ksysms.c.patch if your eth driver is a module


		CONFIGURATION (USING RSHAPERCTL)
		================================

After  reloading  your  modules   or rebooting,  you   must load   the
"rshaper.o"  module.   To   configure   the   bandwidth,    then,  use
"./rshaperctl". For example:

           rshaperctl 192.168.1.2 6400 10

Limits the  incoming bandwidth for the host  to 6400  bytes per second
and queues packets as long  as the queue is  shorter than 10  seconds.
If the third argument is missing, it defaults to 5 seconds.

To remove the limit, just use 0 as the allowed bandwidth:

	   rshaperctl 192.168.1.2 0

From version  1.04 onwards, it  is  possible to use computer  names in
addition to IP numbers.

You can also limit the bandwidth  allocated to a network of computers.
To this aim, you  can  add a netmask  to  the  IP address.  Both   the
following forms work:

	   rshaperctl 192.168.1.16/255.255.255.240  19200
	   rshaperctl 192.168.1.16/28 19200

"rshaperctl", when   called   without arguments,   shows   the current
configuration. Two option can be passed to rshaperctl:

	-n   (numeric): don't decode IP numbers to name when reporting
		configuration information
	-t   (no-title): don't print the title line in the report. This
		is useful if you feed the output to a script

Any other option makes rshaperctl print an help message.


		PATCHES
		=======

Patch files are the output of "diff -c" or "diff -u" (preferred). They
describe how to change the original  file to obtain  a new one. A good
feature of patches is that they  are human-readable, so you can always
know what is going on.

To apply a patch, feed it to the standard  input of the patch command.
The command  receives  a few  options on   its command-line,  the most
needed being "-p". "-p" tells patch to discard path components: "patch
-p1" for example discards one path-component in the file names it find
in the patch   file before looking   for  files. You  should pass  the
correct "-p"  option according to  what your current directory is when
you apply the patch file.

Specifically, to    apply    the "8390.c"  patch    included  in  this
distribution:

	cd /your/kernel/src; patch -p0 < /.../8390.c.patch
or
	cd /your/kernel/src/drivers/net; patch -p2 < /.../8390.c.patch


		DISCLAIMER
		==========

This is not very refined, a lot of interesting things  can be done and
aren't; check shaper.c  distributed with Linux-2.2 to  see some of the
fine details  that are missing from  there.


		LICENSE
		=======

The code is released according to the GPL, in the hope you find it useful.

