Apache 2 Module API

My latest exploits have involved writing an apache module so let’s look at a basic getting started guide for developing apache modules.

Requirements

This assumes running on a RHEL platform with httpd-dev installed.

Basic Structure

Apache modules can both process requests and output information, the following basic example outputs an extra header in response to any requests and outputs the text Hello World onto the page.


#include "httpd.h"
#include "http_config.h"
#include "http_core.h"

module AP_MODULE_DECLARE_DATA hello_module;

// Request processing function
static int hello_req (request_rec *r){
  // Add header to response
  apr_table_setn(r->headers_out, "Hello", "world");
  // Output text on page
  ap_rputs("Hello World", r);
  // Return that this module is handling the request fully
  return OK;
}

// Register processing hook
static void hello_register_hooks(apr_pool_t *p){
  // Declare our hook for processing requests
  ap_hook_handler(hello_req, NULL, NULL, APR_HOOK_MIDDLE);
}

// Declare module
module AP_MODULE_DECLARE_DATA hello_module = {
  STANDARD20_MODULE_STUFF,
  NULL,
  NULL,
  NULL,
  NULL,
  NULL,
  hello_register_hooks
};

Then assuming you have the appropriate apache devel packages and mod_so activated, you can simply install your module by running:


apxs -i -a -c hello_module.c

This will compile, install and activate your module so that after a swift restart of apache, it will now be in effect.
If you get any errors involving apxs not being found, this will generally mean you have not successfully installed the appropriate apache devel package for your distribution.

Now we have a simple module installed and working we can start modifying it to do what we want.

Return Values

Modules work by performing whatever processing is required the returning one of two main status’, OK, or DECLINED.

OK signifies that this module can definitively answer the query being made and once it has been run all processing should be ended, this will generally be the case if the request is intended for the module in question and once it has been processed then no other modules will provide any additional output of consequence.

The DECLINED status signifies that the module has not answered the query, maybe not all, or possibly just not fully, then after this other hooks will continue running until one eventually returns an OK signal to indicate that it has processed the request.

RequestRec

The request_rec parameter passed to your hook allows you to get and modify various parameters associated with the request being made, a good source of documentation for these parameters is actually the Perl RequestReq Module as the parameters provided in Perl map directly onto the underlying Apache parameters.

One of the parameters which can prove to be useful is handler, this is set by the Apache configuration allowing you to only activate your module for certain configurations.

This can be utilised by adding the block:

if(strcmp(r->handler, "my_handler"))
  return DECLINED;

Then altering your Apache config to use ‘my_handler’ for a certain set of rules, then when matched your module will activate.

This was going to be longer but it’s been sat as a draft for long enough now so I may revisit apache module writing at some point in the future with some more details! In the meantime this is all you need to get started and playing…


Also published on Medium.