File	Date	Author	Commit
COPYING	2010-01-22	Ryo Tsuruta	[5cc34c] files for the dm-ioband config package.
README	2010-01-22	Ryo Tsuruta	[5cc34c] files for the dm-ioband config package.
dm-ioband-config.spec	2010-01-22	Ryo Tsuruta	[5cc34c] files for the dm-ioband config package.
ioband.conf	2010-01-22	Ryo Tsuruta	[5cc34c] files for the dm-ioband config package.
ioband.init	2010-01-22	Ryo Tsuruta	[e0dc4f] a missed substitution.

Read Me

dm-ioband-config package
========================

Introduction
------------

The dm-ioband-config package provides a configuration file and an init
script to make it easy to assign bandwidth to LVM logical volumes. The
merits of using this are the followings:

  - I'm sure you can use this script without any efforts since most of
    modern linux distributions already make filesystems on LVM logical
    volumes.
  - You can enable and disable dm-ioband anytime you want. No need to
    modify any configuration files which refer to the logical volumes,
    because enabling/disabling dm-ioband doesn't make any changes to
    device names and numbers.
  - You can apply dm-ioband to a root device even if it is already
    mounted.

The following diagram shows how dm-ioband is applied to the existing
logical volumes.

                          run "service ioband start"
                                    ===>
   -------------------------------       -------------------------------    
  |   LogVol00    |    LogVol01   |     |   LogVol00    |    LogVol01   |     
  |  (dm-linear)  |  (dm-linear)  |     |  (dm-ioband)  |  (dm-ioband)  | 
  |-------------------------------|     |-------------------------------|
  |           VolGroup00          |     | LogVol00-orig | LogVol01-orig |
   -------------------------------      |  (dm-linear)  |  (dm-linear)  |
                                        |-------------------------------|
                                        |          VolGroup00           |
                                         -------------------------------
                                    <===
                          run "service ioband stop"

Thanks for the device mapper infrastructure, any device mapper modules
can be dynamically pushed into kernel or replaced with other modules
anytime.

How to configure dm-ioband
--------------------------

The configuration file is located at /etc/ioband.conf.

    # Configuration file for dm-ioband
    #
    # device                  ID   thrott limit policy        weight token
    /dev/VolGroup00/LogVol00 disk1      0     0 weight            80     0
    /dev/VolGroup00/LogVol01 disk1      0     0 weight            20     0
    /dev/VolGroup01/LogVol00 disk2      0     0 weight-iosize     30 16384
    /dev/VolGroup01/LogVol01 disk2      0     0 weight-iosize     60 16384

Each line describes a device which is controlled bandwidth; fields on
each line are separated by tabs or spaces. Lines starting '#' are
comments.

The first field describes the LVM logical volume to be applied
dm-ioband. 

The second field describes the ioband device ID. Bandwidth is shared
among devices which have the same ioband device ID. In the above
configuration, two groups "disk1" and "disk2" are created.

           ID=disk1                    ID=disk2
    /dev/VolGroup00/LogVol00    /dev/VolGroup01/LogVol00
    /dev/VolGroup00/LogVol01    /dev/VolGroup01/LogVol01

The third field describes io_throttle. When a device has a lot of
tokens (tokens are distributed among devices and consumed each time
dm-ioband issues an I/O) and the number of in-flight I/Os in dm-ioband
exceeds io_throttle, dm-ioband gives priority to the device and issues
I/Os to the device until no tokens of the device are left.
This setting affects all devices which have the same ioband device ID.
If you set 0, the default value is used. If you set different values
on each device, the first value is used. In the following example, the
value of io_throttle is set to 8.

    # device                 ID    thrott limit policy weight token
    /dev/VolGroup00/LogVol00 disk1      8     0 weight     80     0
    /dev/VolGroup00/LogVol01 disk1     16     0 weight     20     0

The fourth field describes io_limit. The value determines how many in-
flight I/Os can dm-ioband hold. If the number of in-flight I/Os
reaches the limit, dm-ioband doesn't accept a new request and the
requesting process is suspended until it falls below the limit.
This setting affects all devices which have the same ioband device ID.
If you set 0, the default value is used. If you set different values
on each device, the first value is used. 

The fifth field describes the bandwidth control policy. dm-ioband has
two policies at the moment:

    weight
        Throttling I/O based on the number of I/O counts.
    weight-iosize
        Throttling I/O based on the number of I/O sectors.

This setting affects all devices which have the same ioband device ID.
If you set different policies on each device, the last policy is used.

The sixth field describes a weight value of the device. The bandwidth
of each device is determined according to a proportion of the weights
of each device. In the example at the top of this text, the bandwidth
is calculated like the following:

                              weight    bandwidth of disk1
    /dev/VolGroup00/LogVol00    80      80/(80+20)*100 = 80%
    /dev/VolGroup00/LogVol01    20      20/(80+20)*100 = 20%
                                                  total 100%

                              weight    bandwidth of disk2
    /dev/VolGroup01/LogVol00    30      30/(30+60)*100 = 33%
    /dev/VolGroup01/LogVol01    60      60/(30+60)*100 = 67%
                                                  total 100%


The seventh field describes a total amount of tokens which is
distributed among devices which have the same ioband device ID.
This setting affects all devices which have the same ioband device ID.
If you set 0, the default value is used. If you set different values
on each device, the first value is used. 

Running dm-ioband
-----------------

To start and stop dm-ioband, type the following commands.

    # service ioband start
    Starting dm-ioband:                                        [  OK  ]
    # service ioband stop
    Stopping dm-ioband:                                        [  OK  ]

If something goes wrong, error messages will be written to the
/var/log/messages file.

    # service ioband start
    Starting dm-ioband:                                        [FAILED]
    # tail -1 /var/log/messages
    Feb 18 16:05:54 pc1 dm-ioband: /dev/sda1: not a dm-device

To show a list of devices which use dm-ioband, type the following
command.

    # service ioband status
    vg0-lv3: 0 134217728 ioband 253:11 disk0 4 128 none weight 4096 :20
    vg0-lv2: 0 134217728 ioband 253:10 disk0 4 128 none weight 4096 :20
    vg0-lv1: 0 134217728 ioband 253:9 disk0 4 128 none weight 4096 :20
    vg0-lv0: 0 134217728 ioband 253:8 disk0 4 128 none weight 4096 :40

Note
----

You must stop dm-ioband before changing logical volume settings, such
as activate, rename, resize and so on. These constraints would be
eliminated once dm-ioband was supported by LVM tools.