From: Daniel Gruno
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
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
@@ -65,7 +65,7 @@ and whys of various function calls.
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.
@@ -105,41 +105,41 @@ module AP_MODULE_DECLARE_DATA example_module=
-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 example_module
. The name
of the module is used primarilly for two things:
-- Letting Apache know how to load the module using the LoadModule
+- Letting the server know how to load the module using the LoadModule
- Setting up a namespace for the module to use in configurations
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 Apache to open up mod_example.so
and look for a module
+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 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.
-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
@@ -147,25 +147,25 @@ 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, 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 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
-Apache to do just that:
+the server to do just that:
AddHandler example-handler .sum
AddHandler
and reply to
-Apache based on the value of this tag.
+the server based on the value of this tag.
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 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:
@@ -222,9 +222,9 @@ the request. We will discuss how to create a handler in the next chapter.
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 Apache has forked)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 Apache has forkedap_hook_post_config
: Place a hook that executes after configuration has been parsed, but before the server has forkedap_hook_translate_name
: Place a hook that executes when a URI needs to be translated into a filename on the server (think mod_rewrite
)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.
text/html
{
/* First off, we need to check if this is a call for the "example-handler" handler.
* If it is, we accept it and do our things, if not, we simply return DECLINED,
- * and Apache will try somewhere else.
+ * and the server will try somewhere else.
*/
if
(
!
r-
>
handler
|
|
strcmp
(
r-
>
handler
,
"
example-handler
"
)
)
return
(
DECLINED)
;
@@ -267,8 +267,8 @@ In C code, our example handler will now look like this:(
r,
"
text/html
"
)
;
ap_rprintf(
r,
"
Hello, world!
"
)
;
- /* Lastly, we must tell Apache that we took care of this request and everything went fine.
- * We do so by simply returning the value OK to Apache.
+ /* Lastly, we must tell the server that we took care of this request and everything went fine.
+ * We do so by simply returning the value OK to the server.
*/
return
OK;
}
@@ -290,7 +290,7 @@ contains all the information you need for your module to fully process any
HTTP request and respond accordingly. Some key elements of the
request_req
structure are:
r->handler
(char*)
: Contains the name of the handler Apache is currently asking to do the handling of this requestr->handler
(char*)
: Contains the name of the handler the server is currently asking to do the handling of this requestr->method
(char*)
: Contains the HTTP method being used, f.x. GET or POSTr->filename
(char*)
: Contains the translated filename the client is requestingr->args
(char*)
: Contains the query string of the request, if anyOK
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 DONE
to let Apache
+module is done, you can return the value DONE
to let the server
know that it should cease all activity on this request and carry on with
the next, without informing other handlers.
DECLINED
: We are not handling this requestOK
: We handled this request and it went wellDONE
: We handled this request and Apache should just close this thread without further processingDONE
: We handled this request and the server should just close this thread without further processing
-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
@@ -452,7 +452,7 @@ apr_pool_t *p, apr_size_t size): Allocates size
number of by
char* apr_pstrdup(
apr_pool_t *p, const char *s)
: Creates a duplicate of the string s
. This is useful for copying constant values so you can edit themchar* apr_psprintf(
-apr_pool_t *p, const char *fmt, ...)
: Similar to sprintf
, except Apache supplies you with an appropriately allocated target variablesprintf
, except the server supplies you with an appropriately allocated target variable
-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:
@@ -671,7 +671,7 @@ out the MD5 or SHA1 digest of files:
- /* Let Apache know that we responded to this request. */
+ /* Let the server know that we responded to this request. */
return
OK;
}
@@ -689,7 +689,7 @@ This version in its entirity can be found here:
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.
example_directives
holds information on what our directives are and how they work.
Since we have three different variables in our module configuration, we
@@ -830,15 +830,15 @@ static const command_rec example_directives[] =
As you can see, each directive needs at least 5 parameters set:
AP_INIT_TAKE1
: This is a macro that tells Apache that this directive takes one and only one argument.
+AP_INIT_TAKE1
: 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 AP_INIT_TAKE2
and so on (refer to httpd_conf.h
for more macros).exampleEnabled
: 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.example_set_enabled
: 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.RSRC_CONF
: This tells Apache where the directive is permissable. We'll go into details on this value in the
-later chapters, but for now, RSRC_CONF
means that Apache will only accept these directives in a server context.RSRC_CONF
: This tells the server where the directive is permissable. We'll go into details on this value in the
+later chapters, but for now, RSRC_CONF
means that the server will only accept these directives in a server context."Enable or disable...."
: This is simply a brief description of what the directive does.
-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
-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:
So how does a module get the specific configuration for the server,
@@ -1077,7 +1077,7 @@ directory or location in question? It does so by making one simple call:
example_config *config = (example_config*) ap_get_module_config( In this chapter, we will be working with a slightly modified version of
our previous context structure. We will set a A much smarter way to manage your configurations is by letting Apache
+ 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
-name tag to let Apache know, that it should assist us in creating
+name tag 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:
@@ -1182,7 +1182,7 @@ module AP_MODULE_DECLARE_DATA example_module
-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:
@@ -1225,7 +1225,7 @@ where you have a parent configuration and a child, such as the following:
In this example, it is natural to assume that the directory
-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
@@ -1038,8 +1038,8 @@ configuration file.
Context aware configurations
Introduction to context aware configurations
@@ -1057,12 +1057,12 @@ mod_rewrite:
/var/www
, all requests for http://example.com
must go to http://www.example.com
/var/www/sub
, all requests for foobar
must go to index.php?foobar=true
r->per_dir_config
, &example_module);
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.
context
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:
@@ -1142,7 +1142,7 @@ a directive required five elements be set:
-The RSRC_CONF
definition told Apache that we would only allow
+The RSRC_CONF
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 ACCESS_CONF
, which lets us use
@@ -1150,10 +1150,10 @@ the directive inside <Directory> and <Location> blocks.
Using Apache to allocate configuration slots
-Using the server to allocate configuration slots
+=
Creating new context configurations
/var/www/subdir
should inherit the value set for the /var/www
directory, as we did not specify a ExampleEnable
nor
-an ExamplePath
for this directory. Apache does not presume to
+an ExamplePath
for this directory. The server does not presume to
know if this is true, but cleverly does the following:
/var/www
=<
Summing up