<section id="what"><title>What we will be discussing in this document</title>
<p>
This document will discuss how you can easily create modules for the Apache
-HTTP Server 2.4 ("Apache"), by exploring an example module called
+HTTP Server 2.4, by exploring an example module called
<code>mod_example</code>. 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 <code>
</p>
<p>
Lastly, you will need to have a basic understanding of how modules are
-loaded and configured in Apache, as well as how to get the headers for
+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.
</p>
<!-- END EXAMPLE CODE -->
-This bit of code lets Apache know that we have now registered a new module
+This bit of code lets the server know that we have now registered a new module
in the system, and that its name is <code>example_module</code>. The name
of the module is used primarilly for two things:<br/>
<ul>
-<li>Letting Apache know how to load the module using the LoadModule</li>
+<li>Letting the server know how to load the module using the LoadModule</li>
<li>Setting up a namespace for the module to use in configurations</li>
</ul>
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:<br/>
<example><pre><a href="../mod/mod_so.html#LoadModule">LoadModule</a> example_module modules/mod_example.so</pre></example>
-In essence, this tells Apache to open up <code>mod_example.so</code> and look for a module
+In essence, this tells the server to open up <code>mod_example.so</code> and look for a module
called <code>example_module</code>.
</p>
<p>
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 service. We'll
+handlers are we interested in registering with the Apache HTTP service. We'll
return to all these elements later in this document.
</p>
</section>
-<section id="hooking"><title>Getting started: Hooking into Apache</title>
+<section id="hooking"><title>Getting started: Hooking into the server</title>
<section id="hook_intro"><title>An introduction to hooks</title>
<p>
-When handling requests in Apache, the first thing you will need to do is
+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 Apache that you are willing to either serve or at least
+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 Apache
-how and when each module will come into place. Thus, Apache itself does not
+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
being served, as authentication/authorization modules do: <br/>
<img src="../images/build_a_mod_2.png" /><br/>
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, Apache
+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 <directive module="mod_mime">AddHandler</directive>
and <directive module="core">SetHandler</directive>. Let's take a look at
an example using <directive module="mod_mime">AddHandler</directive>. In
our example case, we want every request ending with .sum to be served by
<code>mod_example</code>, so we'll add a configuration directive that tells
-Apache to do just that:
+the server to do just that:
<example><pre>
AddHandler example-handler .sum
</pre></example>
-What this tells Apache is the following: <em>Whenever we receive a request
+What this tells the server is the following: <em>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" </em>.
-Thus, when a request is being served that ends in .sum, Apache will let all
+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 <code>AddHandler</code> and reply to
-Apache based on the value of this tag.
+the server based on the value of this tag.
</p>
</section>
<section id="hook_declaration"><title>Hooking into httpd</title>
<!-- END EXAMPLE CODE -->
-This lets Apache know that we are not interesting in anything fancy, we
+This lets the server know that we are not interesting in anything fancy, we
just want to hook onto the requests and possibly handle some of them. </p>
<p> The reference in our example declaration, <code>register_hooks</code>
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 Apache know, that we want
+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:
Hooking into the request handling phase is but one of many hooks that you
can create. Some other ways of hooking are:
<ul>
-<li><code>ap_hook_child_init</code>: Place a hook that executes when a child process is spawned (commonly used for initializing modules after Apache has forked)</li>
+<li><code>ap_hook_child_init</code>: Place a hook that executes when a child process is spawned (commonly used for initializing modules after the server has forked)</li>
<li><code>ap_hook_pre_config</code>: Place a hook that executes before any configuration data has been read (very early hook)</li>
-<li><code>ap_hook_post_config</code>: Place a hook that executes after configuration has been parsed, but before Apache has forked</li>
+<li><code>ap_hook_post_config</code>: Place a hook that executes after configuration has been parsed, but before the server has forked</li>
<li><code>ap_hook_translate_name</code>: Place a hook that executes when a URI needs to be translated into a filename on the server (think <code>mod_rewrite</code>)</li>
</ul>
</p>
<section id="handling"><title>Building a handler</title>
<p>
A handler is essentially a function that receives a callback when a request
-to Apache is made. It is passed a record of the current request (how it was
+to the server is made. It is passed a record of the current request (how it was
made, which headers and requests were passed along, who's giving the
-request and so on), and is put in charge of either telling Apache that it's
+request and so on), and is put in charge of either telling the server that it's
not interested in the request or handle the request with the tools provided.
</p>
<section id="simple_handler"><title>A simple "Hello, world!"
<li>Check that this is a request that should be served by "example-handler"</li>
<li>Set the content type of our output to <code>text/html</code></li>
<li>Write "Hello, world!" back to the client browser</li>
-<li>Let Apache know that we took care of this request and everything went fine</li>
+<li>Let the server know that we took care of this request and everything went fine</li>
</ol>
In C code, our example handler will now look like this:<br/>
<code style='color:#806030; '>{</code>
<code style='color:#c34e00; '>/* First off, we need to check if this is a call for the "example-handler" handler.</code>
<code style='color:#c34e00; '>     * If it is, we accept it and do our things, if not, we simply return DECLINED,</code>
-<code style='color:#c34e00; '>     * and Apache will try somewhere else.</code>
+<code style='color:#c34e00; '>     * and the server will try somewhere else.</code>
<code style='color:#c34e00; '>     */</code>
<code style='color:#400000; font-weight:bold; '>if</code> <code style='color:#806030; '>(</code><code style='color:#806030; '>!</code>r<code style='color:#806030; '>-</code><code style='color:#806030; '>></code><code style='color:#008833'>handler</code> <code style='color:#806030; '>|</code><code style='color:#806030; '>|</code> <code style='color:#800040; '>strcmp</code><code style='color:#806030; '>(</code>r<code style='color:#806030; '>-</code><code style='color:#806030; '>></code><code style='color:#008833'>handler</code><code style='color:#806030; '>,</code> <code style='color:#800000; '>"</code><code style='color:#e60000; '>example-handler</code><code style='color:#800000; '>"</code><code style='color:#806030; '>)</code><code style='color:#806030; '>)</code> <code style='color:#400000; font-weight:bold; '>return</code> <code style='color:#806030; '>(</code>DECLINED<code style='color:#806030; '>)</code><code style='color:#806030; '>;</code>
<a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__PROTO.html#gaa2f8412c400197338ec509f4a45e4579">ap_set_content_type</a><code style='color:#806030; '>(</code>r<code style='color:#806030; '>,</code> <code style='color:#800000; '>"</code><code style='color:#e60000; '>text/html</code><code style='color:#800000; '>"</code><code style='color:#806030; '>)</code><code style='color:#806030; '>;</code>
<a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__PROTO.html#ga5e91eb6ca777c9a427b2e82bf1eeb81d">ap_rprintf</a><code style='color:#806030; '>(</code>r<code style='color:#806030; '>,</code> <code style='color:#800000; '>"</code><code style='color:#e60000; '>Hello, world!</code><code style='color:#800000; '>"</code><code style='color:#806030; '>)</code><code style='color:#806030; '>;</code>
- <code style='color:#c34e00; '>/* Lastly, we must tell Apache that we took care of this request and everything went fine.</code>
-<code style='color:#c34e00; '>     * We do so by simply returning the value OK to Apache.</code>
+ <code style='color:#c34e00; '>/* Lastly, we must tell the server that we took care of this request and everything went fine.</code>
+<code style='color:#c34e00; '>     * We do so by simply returning the value OK to the server.</code>
<code style='color:#c34e00; '>     */</code>
<code style='color:#400000; font-weight:bold; '>return</code> OK<code style='color:#806030; '>;</code>
<code style='color:#806030; '>}</code>
HTTP request and respond accordingly.</p> <p>Some key elements of the <code>
request_req </code> structure are:
<ul>
-<li><code><code style='color:#008833'>r->handler</code> (char*)</code>: Contains the name of the handler Apache is currently asking to do the handling of this request</li>
+<li><code><code style='color:#008833'>r->handler</code> (char*)</code>: Contains the name of the handler the server is currently asking to do the handling of this request</li>
<li><code><code style='color:#008833'>r->method</code> (char*)</code>: Contains the HTTP method being used, f.x. GET or POST</li>
<li><code><code style='color:#008833'>r->filename</code> (char*)</code>: Contains the translated filename the client is requesting</li>
<li><code><code style='color:#008833'>r->args</code> (char*)</code>: Contains the query string of the request, if any</li>
Returning <code>OK</code> or a HTTP status code does not necessarilly mean
-that the request will end. Apache may still have other handlers that are
+that the request will end. The server may still have other handlers that are
interested in this request, for instance the logging modules which, upon a
successful request, will write down a summary of what was requested and how
it went. To do a full stop and prevent any further processing after your
-module is done, you can return the value <code>DONE</code> to let Apache
+module is done, you can return the value <code>DONE</code> to let the server
know that it should cease all activity on this request and carry on with
the next, without informing other handlers.
<br/>
<ul>
<li><code>DECLINED</code>: We are not handling this request</li>
<li><code>OK</code>: We handled this request and it went well</li>
-<li><code>DONE</code>: We handled this request and Apache should just close this thread without further processing</li>
+<li><code>DONE</code>: We handled this request and the server should just close this thread without further processing</li>
</ul><br/>
<strong>HTTP specific return codes (excerpt):</strong>
<ul>
<section id="memory"><title>Memory management</title>
<p>
-Managing your resources in Apache is quite easy, thanks to the memory pool
+Managing your resources in Apache HTTP Server 2.4 is quite easy, thanks to the memory pool
system. In essence, each server, connection and request have their own
memory pool that gets cleaned up when its scope ends, e.g. when a request
is done or when a server process shuts down. All your module needs to do is
<li><code>char* <a href="http://apr.apache.org/docs/apr/1.4/group__apr__strings.html#gabc79e99ff19abbd7cfd18308c5f85d47">apr_pstrdup</a>(
apr_pool_t *p, const char *s)</code>: Creates a duplicate of the string <code>s</code>. This is useful for copying constant values so you can edit them</li>
<li><code>char* <a href="http://apr.apache.org/docs/apr/1.4/group__apr__strings.html#ga3eca76b8d293c5c3f8021e45eda813d8">apr_psprintf</a>(
-apr_pool_t *p, const char *fmt, ...)</code>: Similar to <code>sprintf</code>, except Apache supplies you with an appropriately allocated target variable</li>
+apr_pool_t *p, const char *fmt, ...)</code>: Similar to <code>sprintf</code>, except the server supplies you with an appropriately allocated target variable</li>
</ul>
Let's put these functions into an example handler:<br/>
In this pre-request initialization function we would not be using the
same pool as we did when allocating resources for request-based functions.
-Instead, we would use the pool given to us by Apache for allocating memory
+Instead, we would use the pool given to us by the server for allocating memory
on a per-process based level.
</p>
digest.
</p>
<p>
-Since the introduction of Apache 2.4, parsing request data from GET and
+Since the introduction of Apache HTTP Server 2.4, parsing request data from GET and
POST requests have never been easier. All we require to parse both GET and
POST data is four simple lines:
- <code style='color:#c34e00; '>/* Let Apache know that we responded to this request. */</code>
+ <code style='color:#c34e00; '>/* Let the server know that we responded to this request. */</code>
<code style='color:#400000; font-weight:bold; '>return</code> OK<code style='color:#806030; '>;</code>
<code style='color:#806030; '>}</code>
</pre>
In this next segment of this document, we will turn our eyes away from the
digest module and create a new example module, whose only function is to
write out its own configuration. The purpose of this is to examine how
-Apache works with configuration, and what happens when you start writing
+the server works with configuration, and what happens when you start writing
advanced configurations
for your modules.
</p>
module.
</section>
-<section id="register_directive"><title>Registering directives with Apache</title>
+<section id="register_directive"><title>Registering directives with the server</title>
What if we want to change our configuration, not by hard-coding new values
into the module, but by using either the httpd.conf file or possibly a
-.htaccess file? It's time to let Apache know that we want this to be
+.htaccess file? It's time to let the server know that we want this to be
possible. To do so, we must first change our <em>name tag</em> to include a
-reference to the configuration directives we want to register with Apache:
+reference to the configuration directives we want to register with the server:
<!-- BEGIN EXAMPLE CODE -->
<!-- END EXAMPLE CODE -->
-This will tell Apache that we are now accepting directives from the
+This will tell the server that we are now accepting directives from the
configuration files, and that the structure called <code>example_directives
</code> holds information on what our directives are and how they work.
Since we have three different variables in our module configuration, we
<p>
As you can see, each directive needs at least 5 parameters set:
<ol>
-<li><code><a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__CONFIG.html#ga07c7d22ae17805e61204463326cf9c34">AP_INIT_TAKE1</a></code>: This is a macro that tells Apache that this directive takes one and only one argument.
+<li><code><a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__CONFIG.html#ga07c7d22ae17805e61204463326cf9c34">AP_INIT_TAKE1</a></code>: This is a macro that tells the server that this directive takes one and only one argument.
If we required two arguments, we could use the macro <code><a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__CONFIG.html#gafaec43534fcf200f37d9fecbf9247c21">AP_INIT_TAKE2</a></code> and so on (refer to httpd_conf.h
for more macros).</li>
<li><code>exampleEnabled</code>: This is the name of our directive. More precisely, it is what the user must put in his/her
configuration in order to invoke a configuration change in our module.</li>
<li><code>example_set_enabled</code>: This is a reference to a C function that parses the directive and sets the configuration
accordingly. We will discuss how to make this in the following paragraph.</li>
-<li><code>RSRC_CONF</code>: This tells Apache where the directive is permissable. We'll go into details on this value in the
-later chapters, but for now, <code>RSRC_CONF</code> means that Apache will only accept these directives in a server context.</li>
+<li><code>RSRC_CONF</code>: This tells the server where the directive is permissable. We'll go into details on this value in the
+later chapters, but for now, <code>RSRC_CONF</code> means that the server will only accept these directives in a server context.</li>
<li><code>"Enable or disable...."</code>: This is simply a brief description of what the directive does.</li>
</ol>
(<em>The "missing" parameter in our definition, which is usually set to
</section>
<section id="directive_handler"><title>The directive handler function</title>
<p>
-Now that we've told Apache to expect some directives for our module, it's
-time to make a few functions for handling these. What Apache reads in the
+Now that we've told the server to expect some directives for our module, it's
+time to make a few functions for handling these. What the server reads in the
configuration file(s) is text, and so naturally, what it passes along to
our directive handler is one or more strings, that we ourselves need to
recognize and act upon. You'll notice, that since we set our <code>
<section id="context"><title>Context aware configurations</title>
<section id="context_intro"><title>Introduction to context aware configurations</title>
<p>
-In Apache, different URLs, virtual hosts, directories etc can have very
-different meanings to the user of Apache, and thus different contexts
+In Apache HTTP Server 2.4, different URLs, virtual hosts, directories etc can have very
+different meanings to the user of the server, and thus different contexts
within which modules must operate. For example, let's assume you have this
configuration set up for mod_rewrite:
<example><pre>
<li>Inside <code>/var/www</code>, all requests for <code>http://example.com</code> must go to <code>http://www.example.com</code></li>
<li>Inside <code>/var/www/sub</code>, all requests for <code>foobar</code> must go to <code>index.php?foobar=true</code></li>
</ol>
-If mod_rewrite (or Apache for that matter) wasn't context aware, then
+If mod_rewrite (or the entire server for that matter) wasn't context aware, then
these rewrite rules would just apply to every and any request made,
regardless of where and how they were made, but since the module can pull
-the context specific configuration straight from Apache, it does not need
+the context specific configuration straight from the server, it does not need
to know itself, which of the directives are valid in this context, since
-Apache takes care of this.</p>
+the server takes care of this.</p>
<p>
So how does a module get the specific configuration for the server,
example_config *config = (example_config*) <a href="http://ci.apache.org/projects/httpd/trunk/doxygen/group__APACHE__CORE__CONFIG.html#ga1093a5908a384eacc929b028c79f2a02">ap_get_module_config</a>(<code style='color:#008833'>r->per_dir_config</code>, &example_module);
</pre>
That's it! Of course, a whole lot goes on behind the scenes, which we will
-discuss in this chapter, starting with how Apache came to know what our
+discuss in this chapter, starting with how the server came to know what our
configuration looks like, and how it came to be set up as it is in the
specific context.
</p>
<p>In this chapter, we will be working with a slightly modified version of
our previous context structure. We will set a <code>context</code>
variable that we can use to track which context configuration is being
-used by Apache in various places:
+used by the server in various places:
<!-- BEGIN EXAMPLE CODE -->
<!-- END EXAMPLE CODE -->
-The <code>RSRC_CONF</code> definition told Apache that we would only allow
+The <code>RSRC_CONF</code> definition told the server that we would only allow
this directive in a global server context, but since we are now trying out
a context aware version of our module, we should set this to something
more lenient, namely the value <code>ACCESS_CONF</code>, which lets us use
</p>
</section>
-<section id="context_pool"><title>Using Apache to allocate configuration slots</title>
-<p> A much smarter way to manage your configurations is by letting Apache
+<section id="context_pool"><title>Using the server to allocate configuration slots</title>
+<p> A much smarter way to manage your configurations is by letting the server
help you create them. To do so, we must first start off by changing our
-<em>name tag</em> to let Apache know, that it should assist us in creating
+<em>name tag</em> to let the server know, that it should assist us in creating
and managing our configurations. Since we have chosen the per-directory
(or per-location) context for our module configurations, we'll add a
per-directory creator and merger function reference in our tag:
<section id="context_which"><title>Creating new context configurations</title>
<p>
-Now that we have told Apache to help us create and manage configurations,
+Now that we have told the server to help us create and manage configurations,
our first step is to make a function for creating new, blank
configurations. We do so by creating the function we just referenced in
our name tag as the Per-directory configuration handler:
In this example, it is natural to assume that the directory <code>
/var/www/subdir</code> should inherit the value set for the <code>/var/www
</code> directory, as we did not specify a <code>ExampleEnable</code> nor
-an <code>ExamplePath</code> for this directory. Apache does not presume to
+an <code>ExamplePath</code> for this directory. The server does not presume to
know if this is true, but cleverly does the following:
<ol>
<li>Creates a new configuration for <code>/var/www</code></li>
<section id="summary"><title>Summing up</title>
<p>
-We have now looked at how to create simple modules for Apache and
+We have now looked at how to create simple modules for Apache HTTP Server 2.4 and
configuring them. What you do next is entirely up to you, but it is my
hope that something valuable has come out of reading this documentation.
If you have questions on how to further develop modules, you are welcome