Text of httpd.apache.org › docs › trunk › developer › modguide.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Developing modules for the Apache HTTP Server 2.4 - Apache HTTP Server Version 2.5

Modules | Directives | FAQ | Glossary | Sitemap | Report a bug Apache HTTP Server Version 2.5 Apache > HTTP Server > Documentation > Version 2.5 > Developer Developing modules for the Apache HTTP Server 2.4 Available Languages: en This document explains how you can develop modules for the Apache HTTP Server 2.4 Introduction Defining a module Getting started: Hooking into the server Building a handler Adding configuration options Context aware configurations Summing up Some useful snippets of code See also Request Processing in Apache 2.4 Apache 2.x Hook Functions Introduction ¶ What we will be discussing in this document This document will discuss how you can create modules for the Apache HTTP Server 2.4, by exploring an example module called mod_example .

In the first part of this document, the purpose of this module will be to calculate and print out various digest values for existing files on your web server, whenever we access the URL http://hostname/filename.sum . For instance, if we want to know the MD5 digest value of the file located at http://www.example.com/index.html , we would visit http://www.example.com/index.html.sum . In the second part of this document, which deals with configuration directive and context awareness, we will be looking at a module that simply writes out its own configuration to the client.

Prerequisites First and foremost, you are expected to have a basic knowledge of how the C programming language works. In most cases, we will try to be as pedagogical as possible and link to documents describing the functions used in the examples, but there are also many cases where it is necessary to either just assume that "it works" or do some digging yourself into what the hows and whys of various function calls. Lastly, you will need to have a basic understanding of how modules are loaded and configured in the Apache HTTP Server, as well as how to get the headers for Apache if you do not have them already, as these are needed for compiling new modules.

Compiling your module To compile the source code we are building in this document, we will be using APXS . Assuming your source file is called mod_example.c, compiling, installing and activating the module is as simple as: apxs -i -a -c mod_example.c Defining a module ¶ Every module starts with the same declaration, or name tag if you will, that defines a module as a separate entity within Apache : AP_DECLARE_MODULE(example) = { STANDARD20_MODULE_STUFF, create_dir_conf, /* Per-directory configuration handler */ merge_dir_conf, /* Merge handler for per-directory configurations */ create_svr_conf, /* Per-server configuration handler */ merge_svr_conf, /* Merge handler for per-server configurations */ directives, /* Any directives we may have for httpd */ register_hooks, /* Our hook registering function */ AP_MODULE_FLAG_NONE /* Flags */ }; This bit of code lets the server know that we have now registered a new module in the system, and that its name is example_module .

The name of the module is used primarily for three things: Letting the server know how to load the module using the LoadModule Setting up a namespace for the module to use in configurations Allowing the user to distinguish an origin of log messages For now, we're only concerned with the first purpose of the module name, which comes into play when we need to load the module: LoadModule example_module "modules/mod_example.so" In essence, this tells the server to open up mod_example.so and look for a module called example_module .

Within this name tag of ours is also a bunch of references to how we would like to handle things: Which directives do we respond to in a configuration file or .htaccess, how do we operate within specific contexts, and what handlers are we interested in registering with the Apache HTTP service. We'll return to all these elements later in this document. Getting started: Hooking into the server ¶ An introduction to hooks When handling requests in Apache HTTP Server 2.4, the first thing you will need to do is create a hook into the request handling process.

A hook is essentially a message telling the server that you are willing to either serve or at least take a glance at certain requests given by clients. All handlers, whether it's mod_rewrite, mod_authn_*, mod_proxy and so on, are hooked into specific parts of the request process. As you are probably aware, modules serve different purposes; Some are authentication/authorization handlers, others are file or script handlers while some third modules rewrite URIs or proxies content.

Furthermore, in the end, it is up to the user of the server how and when each module will come into place. Thus, the server itself does not presume to know which module is responsible for handling a specific request, and will ask each module whether they have an interest in a given request or not. It is then up to each module to either gently decline serving a request, accept serving it or flat out deny the request from being served, as authentication/authorization modules do: To make it a bit easier for handlers such as our mod_example to know whether the client is requesting content we should handle or not, the server has directives for hinting to modules whether their assistance is needed or not.

Two of these are AddHandler and SetHandler . Let's take a look at an example using AddHandler . In our example case, we want every request ending with .sum to be served by mod_example , so we'll add a configuration directive that tells the server to do just that: AddHandler example-handler ".sum" What this tells the server is the following: Whenever we receive a request for a URI ending in .sum, we are to let all modules know that we are looking for whoever goes by the name of "example-handler" .

Thus, when a request is being served that ends in .sum, the server will let all modules know, that this request should be served by "example-handler". As you will see later, when we start building mod_example, we will check for this handler tag relayed by AddHandler and reply to the server based on the value of this tag. Hooking into httpd To begin with, we only want to create a simple handler that replies to the client browser when a specific URL is requested, so we won't bother setting up configuration handlers and directives just yet.

Our initial module definition will look like this: AP_DECLARE_MODULE(example) = { STANDARD20_MODULE_STUFF, NULL, NULL, NULL, NULL, NULL, register_hooks, /* Our hook registering function */ AP_MODULE_FLAG_NONE /* Flags */ }; This lets the server know that we are not interested in anything fancy, we just want to hook onto the requests and possibly handle some of them. The reference in our example declaration, register_hooks is the name of a function we will create to manage how we hook onto the request process.

In this example module, the function has just one purpose; To create a simple hook that gets called after all the rewrites, access control etc has been handled. Thus, we will let the server know that we want to hook into its process as one of the last modules: static void register_hooks(apr_pool_t *pool) { /* Create a hook in the request handler, so we get called when a request arrives */ ap_hook_handler(example_handler, NULL, NULL, APR_HOOK_LAST); } The example_handler reference is the function that will handle the request.

We will discuss how to create a handler in the next chapter. Other useful hooks Hooking into the request handling phase is but one of many hooks that you can create. Some other ways of hooking are: ap_hook_child_init : Place a hook that executes when a child process is spawned (commonly used for initializing modules after the server has forked) ap_hook_pre_config : Place a hook that executes before any configuration data has been read (very early hook) ap_hook_post_config : Place a hook that executes after configuration has been parsed, but before the server has forked ap_hook_pre_translate_name : Place a hook that execu

The rest of this page is on the live site.