Request Processing in the Apache HTTP Server 2.x

Available Languages: en

+ +

Warning

Warning - this is a first (fast) draft that needs further + revision!

+ +

Several changes in 2.0 and above affect the internal request + processing mechanics. Module authors need to be aware of these + changes so they may take advantage of the optimizations and + security enhancements.

+ +

The first major change is to the subrequest and redirect + mechanisms. There were a number of different code paths in + the Apache HTTP Server 1.3 to attempt to optimize subrequest + or redirect behavior. As patches were introduced to 2.0, these + optimizations (and the server behavior) were quickly broken due + to this duplication of code. All duplicate code has been folded + back into ap_process_request_internal() to prevent + the code from falling out of sync again.

+ +

This means that much of the existing code was 'unoptimized'. + It is the Apache HTTP Project's first goal to create a robust + and correct implementation of the HTTP server RFC. Additional + goals include security, scalability and optimization. New + methods were sought to optimize the server (beyond the + performance of 1.3) without introducing fragile or + insecure code.

The Request Processing Cycle
The Request Parsing Phase
The Security Phase
The Preparation Phase
The Handler Phase

The Request Processing Cycle

All requests pass through ap_process_request_internal() + in server/request.c, including subrequests and redirects. If a module + doesn't pass generated requests through this code, the author is cautioned + that the module may be broken by future changes to request + processing.

+ +

To streamline requests, the module author can take advantage + of the hooks offered to drop + out of the request cycle early, or to bypass core hooks which are + irrelevant (and costly in terms of CPU.)

The Request Parsing Phase

Unescapes the URL

The request's parsed_uri path is unescaped, once and only + once, at the beginning of internal request processing.

+ +

This step is bypassed if the proxyreq flag is set, or the + parsed_uri.path element is unset. The module has no further + control of this one-time unescape operation, either failing to + unescape or multiply unescaping the URL leads to security + repercussions.

+ + +

Strips Parent and This Elements from the + URI

All /../ and /./ elements are + removed by ap_getparents(), as well as any trailing + /. or /.. element. This helps to ensure + the path is (nearly) absolute before the request processing + continues. (See RFC 1808 section 4 for further discussion.)

+ +

This step cannot be bypassed.

+ + +

Initial URI Location Walk

Every request is subject to an + ap_location_walk() call. This ensures that + <Location> sections + are consistently enforced for all requests. If the request is an internal + redirect or a sub-request, it may borrow some or all of the processing + from the previous or parent request's ap_location_walk, so this step + is generally very efficient after processing the main request.

+ + +

translate_name

Modules can determine the file name, or alter the given URI + in this step. For example, mod_vhost_alias will + translate the URI's path into the configured virtual host, + mod_alias will translate the path to an alias path, + and if the request falls back on the core, the DocumentRoot is prepended to the request resource.

+ +

If all modules DECLINE this phase, an error 500 is + returned to the browser, and a "couldn't translate name" error is logged + automatically.

+ + +

Hook: map_to_storage

After the file or correct URI was determined, the + appropriate per-dir configurations are merged together. For + example, mod_proxy compares and merges the appropriate + <Proxy> sections. + If the URI is nothing more than a local (non-proxy) TRACE + request, the core handles the request and returns DONE. + If no module answers this hook with OK or DONE, + the core will run the request filename against the <Directory> and <Files> sections. If the request + 'filename' isn't an absolute, legal filename, a note is set for + later termination.

+ + +

URI Location Walk

Every request is hardened by a second + ap_location_walk() call. This reassures that a + translated request is still subjected to the configured + <Location> sections. + The request again borrows some or all of the processing from its previous + location_walk above, so this step is almost always very + efficient unless the translated URI mapped to a substantially different + path or Virtual Host.

+ + +

Hook: header_parser

The main request then parses the client's headers. This + prepares the remaining request processing steps to better serve + the client's request.

+ +

The Security Phase

Needs Documentation. Code is:

+ +

if ((access_status = ap_run_access_checker(r)) != 0) {
+    return decl_die(access_status, "check access", r);
+}
+
+if ((access_status = ap_run_check_user_id(r)) != 0) {
+    return decl_die(access_status, "check user", r);
+}
+
+if ((access_status = ap_run_auth_checker(r)) != 0) {
+    return decl_die(access_status, "check authorization", r);
+}

+ +

The Preparation Phase

Hook: type_checker

The modules have an opportunity to test the URI or filename + against the target resource, and set mime information for the + request. Both mod_mime and + mod_mime_magic use this phase to compare the file + name or contents against the administrator's configuration and set the + content type, language, character set and request handler. Some modules + may set up their filters or other request handling parameters at this + time.

+ +

If all modules DECLINE this phase, an error 500 is + returned to the browser, and a "couldn't find types" error is logged + automatically.

+ + +

Hook: fixups

Many modules are 'trounced' by some phase above. The fixups + phase is used by modules to 'reassert' their ownership or force + the request's fields to their appropriate values. It isn't + always the cleanest mechanism, but occasionally it's the only + option.

+ +

The Handler Phase

This phase is not part of the processing in + ap_process_request_internal(). Many + modules prepare one or more subrequests prior to creating any + content at all. After the core, or a module calls + ap_process_request_internal() it then calls + ap_invoke_handler() to generate the request.

+ +

Hook: insert_filter

Modules that transform the content in some way can insert + their values and override existing filters, such that if the + user configured a more advanced filter out-of-order, then the + module can move its order as need be. There is no result code, + so actions in this hook better be trusted to always succeed.

+ + +

Hook: handler

The module finally has a chance to serve the request in its + handler hook. Note that not every prepared request is sent to + the handler hook. Many modules, such as mod_autoindex, + will create subrequests for a given URI, and then never serve the + subrequest, but simply lists it for the user. Remember not to + put required teardown from the hooks above into this module, + but register pool cleanups against the request pool to free + resources as required.

+ +

Request Processing in the Apache HTTP Server 2.x

Warning

See also

The Request Processing Cycle

The Request Parsing Phase

Unescapes the URL

Strips Parent and This Elements from the + URI

Initial URI Location Walk

translate_name

Hook: map_to_storage

URI Location Walk

Hook: header_parser

The Security Phase

The Preparation Phase

Hook: type_checker

Hook: fixups

The Handler Phase

Hook: insert_filter

Hook: handler

Comments