From: Daniel Gruno Date: Sun, 15 Apr 2012 06:56:36 +0000 (+0000) Subject: Merge r1326227 from trunk: X-Git-Tag: 2.4.3~570 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=57323818b9235d796de8284c3c8dd3f721eae0c7;p=apache Merge r1326227 from trunk: Replace instances of "Apache" with the full software name or a simple reference to "the server". git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1326264 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/developer/modguide.xml b/docs/manual/developer/modguide.xml index 8317e4b514..95cae6d83b 100644 --- a/docs/manual/developer/modguide.xml +++ b/docs/manual/developer/modguide.xml @@ -37,7 +37,7 @@ Server 2.4

What we will be discussing in this document

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 @@ -63,7 +63,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.

@@ -103,40 +103,40 @@ 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.

-
Getting started: Hooking into Apache +
Getting started: Hooking into the server
An introduction to hooks

-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 @@ -144,25 +144,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
-What this tells Apache is the following: Whenever we receive a request +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, 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 AddHandler and reply to -Apache based on the value of this tag. +the server based on the value of this tag.

Hooking into httpd @@ -189,13 +189,13 @@ module AP_MODULE_DECLARE_DATA example_module = -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.

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: @@ -219,9 +219,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 forked
    • +
  • ap_hook_post_config: Place a hook that executes after configuration has been parsed, but before the server has forked
  • ap_hook_translate_name: Place a hook that executes when a URI needs to be translated into a filename on the server (think mod_rewrite)

@@ -231,9 +231,9 @@ can create. Some other ways of hooking are:
Building a handler

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.

A simple "Hello, world!" @@ -243,7 +243,7 @@ that does the following: <br/> <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/> @@ -254,7 +254,7 @@ 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> @@ -264,8 +264,8 @@ In C code, our example handler will now look like this:<br/> <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> @@ -287,7 +287,7 @@ contains all the information you need for your module to fully process any 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> @@ -358,11 +358,11 @@ status code, for example: 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/> @@ -370,7 +370,7 @@ the next, without informing other handlers. <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> @@ -429,7 +429,7 @@ the next, without informing other handlers. <section id="memory"><title>Memory management

-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 @@ -450,7 +450,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 them
  • char* apr_psprintf( -apr_pool_t *p, const char *fmt, ...): Similar to sprintf, except Apache supplies you with an appropriately allocated target variable
    • +apr_pool_t *p, const char *fmt, ...)    : Similar to sprintf, except the server supplies you with an appropriately allocated target variable Let's put these functions into an example handler:
    @@ -494,7 +494,7 @@ function to sort it out: 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.

    @@ -513,7 +513,7 @@ md5, we'll produce an MD5 digest, otherwise we'll produce a SHA1 digest.

    -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: @@ -670,7 +670,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; } @@ -688,7 +688,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.

    @@ -781,12 +781,12 @@ When we visit, we'll see our current configuration being spit out by our module.
    -
    Registering directives with Apache +
    Registering directives with the server 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 name tag 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: @@ -805,7 +805,7 @@ module AP_MODULE_DECLARE_DATA example_module = -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 example_directives holds information on what our directives are and how they work. Since we have three different variables in our module configuration, we @@ -829,15 +829,15 @@ static const command_rec example_directives[] =

    As you can see, each directive needs at least 5 parameters set:

      -
    1. AP_INIT_TAKE1: This is a macro that tells Apache that this directive takes one and only one argument. +
    2. 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).
    3. 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.
    4. 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.
      5. -
    5. 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.
      6. +
    6. 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.
    7. "Enable or disable....": This is simply a brief description of what the directive does.
    (The "missing" parameter in our definition, which is usually set to @@ -849,8 +849,8 @@ set them.)
    The directive handler function

    -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 @@ -1037,8 +1037,8 @@ configuration file.

    Context aware configurations
    Introduction to context aware configurations

    -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: 

    @@ -1056,12 +1056,12 @@ mod_rewrite:
 
  • Inside /var/www, all requests for http://example.com must go to http://www.example.com
    • 
 
  • Inside /var/www/sub, all requests for foobar must go to index.php?foobar=true
    • 
 
-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.
    
+the server takes care of this.
    
 
 
    
 So how does a module get the specific configuration for the server, 
@@ -1076,7 +1076,7 @@ directory or location in question? It does so by making one simple call:
 example_config *config = (example_config*) ap_get_module_config(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.

    @@ -1086,7 +1086,7 @@ specific context.

    In this chapter, we will be working with a slightly modified version of our previous context structure. We will set a 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: @@ -1141,7 +1141,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 @@ -1149,10 +1149,10 @@ the directive inside <Directory> and <Location> blocks.

    -
    Using Apache to allocate configuration slots -

    A much smarter way to manage your configurations is by letting Apache +

    Using the server to allocate configuration slots +

    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: @@ -1181,7 +1181,7 @@ module AP_MODULE_DECLARE_DATA example_module =Creating new context configurations

    -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: @@ -1224,7 +1224,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 /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:

    1. Creates a new configuration for /var/www
      2. @@ -1523,7 +1523,7 @@ module AP_MODULE_DECLARE_DATA example_module =<
      Summing up

      -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