"Adaptive Quality of Service Architecture"
(for the Linux kernel)

Documentation

Documentation

Mod_reserve

This is the documentation of mod_reserve (version 0.1), Resource Reservation Module for Apache.

Table of Contents

Introduction
Installation
Build Requirements
Building and installing
Using mod_reserve
Configuration Directives
RsvEnable
RsvUseAgreement
RsvCpuBwReservation
RsvSetHandler

Introduction

The mod_reserve is an Apache2 module (available for Linux) which extends the Apache HTTP server allowing to reserve a certain CPU bandwith for the provisioning of a service.

The mod_reserve module exploits the functionalities provided by AQuoSA, whose API is used to reserve CPU bandwith for execution of tasks. In this way, the module can force the web server to provide services, like cgi or perl script, using exactly the configured CPU bandwith. This behaviour is useful in order to provide Quality of Service (QoS) to certain type of services or to prevent that kind of attacks in which a service can starve all the others (e.g. denial of service).

Installation

This is a description of the installation issues of mod_reserve.

Build Requirements

In order to compile mod_reserve the following packages are needed.
Apache HTTP server

The mod_reserve module has been designed for the Apache 2.2 web server.In particular, the module actually requires an Apache server using the prefork Multi-Processing Module.

The mod_reserve also requires the Apache2 headers and the APR library. An Apache2 package builded from sources usually provides all of them, so no extra installation is required. Otherwise, the proper packages for the reference Linux distribution have to be installed. As an example, on a Debian system they can be installed with 

# apt-get install apache2-prefork-dev libapr1-dev

The mod_reserve module requires, for the installation, an Apache server supporting shared objects. If compiling Apache from sources, this feature can be enabled by using the --enable-so apache configuration option.

AQuoSA

The mod_reserve module requires a working installation of AQuoSA (Adaptive Quality of Service Architecture). This includes the aquosa-qosres component and a modified version of the Linux kernel. The necessary packages can be found here (in case it is necessary to build them from sources, follow the installation instructions).

SQLite

The mod_reserve module requires SQLite 3 in order to be able to exploit the functionalities of the negotiation framework based on WS-Agreement.

xsltproc

In case of building from sources, the mod_reserve module requires the xsltproc tool in order to build documentation from docbook sources (for interested readers about the docbook format, please refer to The DocBook Project site). If xsltproc is not installed in your system, you will not able to generate documentation from sources.

Building and installing

In order to build the module from sources, besides the packages described in the section called “Build Requirements”, a working C compiler and GNU Make are needed. The building and installing procedure follows the well-known pattern: 

$ ./configure
$ make
# make install

According to the host system status, the configuration phase of building may need to be adapted. In this case, the following configuration options can be used:

  • --with-apache=dir

    This option allows to specify the path of a directory containing the Apache2 HTTP server. This is useful if you have performed a custom Apache2 installation (e.g. builded from sources). A common use can be the following: --with-apache=/usr/local/apache2.

  • --enable-debug

    This option allows to enable the module debug. If enabled, the debug will produce its output on the error.conf Apache log file.

The install target of make should work fine if using the --with-apache configure option or if using a Debian-based system. Otherwise, you make require to manually install the module, by using the apxs tool. For specific issues related to your Linux distribution, please refer to the documentation of your system.

The mod_reserve installation can be verified by pointing to the reserv-info location of the installed Apache2 web server (e.g. http://localhost/reserv-info). If the module has been correctly installed, the resulting page will return information about mod_reserve, including declared directives and build options.

Using mod_reserve

In order to use mod_reserve for the first time, the following steps have to be performed:

  1. Start the aquosa-qosres service. As an example by using the command: 
    # /etc/init.d/aquosa-qresmod start
  2. Modify mod_reserve configuration by editing the resolv.conf file (see the section called “Configuration Directives”).
  3. Start the Apache2 web server. As an example by using the command:
    # /etc/init.d/apache2 start
  4. Make a request to the web server.

As a simple test, the loop cgi script provided with the distribution can be used, verifying it occupies the specified CPU bandwidth. To do this, point your browser to http://localhost/cgi-bin/loop and then use top.

Configuration Directives

This is a description of the specific directives that can be used for configuring the mod_reserve module.

Values for directives can be set by editing the reserve.conf configuration file. The location of this file depends on the build options you have used: if the module has been build with the --with-apache=dir option, then configuration file will be located in /dir/conf/extra/reserve.conf; otherwise refer to your distribution specific path (e.g. on a Debian system, it will be /etc/apache2/modules/mods-available/reserve.conf).

RsvEnable

Description: Allows to enable or disable mod_reserve
Syntax: RsvEnable On|Off
Example: RsvEnable On
Scope: Server config, virtual host
Dependencies: None

This directive allows to enable or disable mod_reserve, regarding the parameter value is On or Off. If the module is disabled, by setting the value to Off, the other directives will be ignored.

RsvUseAgreement

Description: Allows to use the mod_reserve Module with the negotiation infrastructure
Syntax: RsvUseAgreement On|Off
Example: RsvUseAgreement Off
Scope: Server config, virtual host
Dependencies: Must have the RsvEnable set to On, otherwise this directive does not have any relevance.

This directive allows to use mod_reserve with a negotiation infrastructure using WS-Agreement protocol to establish contracts that specify guarantees about service parameters. If the module use negotiation infrastructure, by setting the value to On, the other directives will be ignored.

RsvCpuBwReservation

Description: Allows to specify the CPU bandwidth to reserve to a certain type of service.
Syntax: RsvCpuBwReservation cpu_bw_value
Example: RsvCpuBwReservation 0.02
Scope: Server config, virtual host
Dependencies: Must have the RsvEnable set to On and the RsvUseAgreement set to Off, otherwise this directive does not have any relevance.

This directive allows to specify the CPU bandwidth to reserve to a certain type of service. The bandwidth must be specified as a decimal number (e.g. to specify the 2% of CPU bandwidth use 0.02). The specified value represents the CPU bandwidth associated to each equest of a certain service type. The service type can be specified through the RsvSetHandler directive.

Please note that, at this time, the specified bandwidth will be guarantee only until it is available. If, at a certain time, the specified bandwidth can not be guarantee to that request, the system behaviour depends on the configuration of the aquosa-qosres component of AQuoSA.

RsvSetHandler

Description: Allows to specify what kinds of request must be served with a specified CPU bandwidth.
Syntax: RsvSetHandler handlers
Example: RsvCpuBwReservation cgi-script
Scope: Server config, virtual host
Dependencies: Must have the RsvEnable set to On and the RsvUseAgreement set to Off, otherwise this directive does not have any relevance.

This directive allows to specify what kinds of request must be served with a specified CPU bandwidth. It acceps a list of parameters separeted by space, each of them represents the request handler of a certain MIME type. Common handler are cgi-script, perl-script, etc. The CPU bandwidth can be specified through the RsvCpuBwReservation directive.

Latest news

2010-08-04
The IRMOS Real-Time Scheduler on lwn.net

2010-07-03
New real-time SMP scheduler (IRMOS)

2010-05-30
About page added to website

2009-11-25
Papers page added to website





Last update:
August 4, 2010