| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta name="generator" content="HTML Tidy, see www.w3.org" /> |
| |
| <title>Request Processing in Apache 2.0</title> |
| </head> |
| <!-- Background white, links blue (unvisited), navy (visited), red (active) --> |
| |
| <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" |
| vlink="#000080" alink="#FF0000"> |
| <!--#include virtual="header.html" --> |
| |
| <h1>Request Processing in Apache 2.0</h1> |
| |
| <p>Warning - this is a first (fast) draft that needs further |
| revision!</p> |
| |
| <p>Several changes in Apache 2.0 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.</p> |
| |
| <p>The first major change is to the subrequest and redirect |
| mechanisms. There were a number of different code paths in |
| Apache 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 <code>ap_process_internal_request()</code> to prevent |
| the code from falling out of sync again.</p> |
| |
| <p>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 Apache 1.3) without introducing fragile or |
| insecure code.</p> |
| |
| <h2>The Request Processing Cycle</h2> |
| |
| <p>All requests pass through |
| <code>ap_process_request_internal()</code> in 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.</p> |
| |
| <p>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 Apache hooks which are irrelevant (and costly in |
| terms of CPU.)</p> |
| |
| <h2>The Request Parsing Phase</h2> |
| |
| <h3>Unescapes the URL</h3> |
| |
| <p>The request's parsed_uri path is unescaped, once and only |
| once, at the beginning of internal request processing.</p> |
| |
| <p>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 |
| reprecussions.</p> |
| |
| <h3>Strips Parent and This Elements from the URI</h3> |
| |
| <p>All <code>/../</code> and <code>/./</code> elements are |
| removed by <code>ap_getparents()</code>. This helps to ensure |
| the path is (nearly) absolute before the request processing |
| continues.</p> |
| |
| <p>This step cannot be bypassed.</p> |
| |
| <h3>Initial URI Location Walk</h3> |
| |
| <p>Every request is subject to an |
| <code>ap_location_walk()</code> 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.</p> |
| |
| <h3>Hook: translate_name</h3> |
| |
| <p>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.</p> |
| |
| <p>If all modules DECLINE this phase, an error 500 is returned |
| to the browser, and a "couldn't translate name" error is logged |
| automatically.</p> |
| |
| <h3>Hook: map_to_storage</h3> |
| |
| <p>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.</p> |
| |
| <h3>Initial URI Location Walk</h3> |
| |
| <p>Every request is hardened by a second |
| <code>ap_location_walk()</code> 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 it's 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.</p> |
| |
| <h3>Hook: header_parser</h3> |
| |
| <p>The main request then parses the client's headers. This |
| prepares the remaining request processing steps to better serve |
| the client's request.</p> |
| |
| <h2>The Security Phase</h2> |
| |
| <p>Needs Documentation. Code is;</p> |
| <pre> |
| switch (ap_satisfies(r)) { |
| case SATISFY_ALL: |
| case SATISFY_NOSPEC: |
| if ((access_status = ap_run_access_checker(r)) != 0) { |
| return decl_die(access_status, "check access", r); |
| } |
| if (ap_some_auth_required(r)) { |
| if (((access_status = ap_run_check_user_id(r)) != 0) || !ap_auth_type(r)) { |
| return decl_die(access_status, ap_auth_type(r) |
| ? "check user. No user file?" |
| : "perform authentication. AuthType not set!", r); |
| } |
| if (((access_status = ap_run_auth_checker(r)) != 0) || !ap_auth_type(r)) { |
| return decl_die(access_status, ap_auth_type(r) |
| ? "check access. No groups file?" |
| : "perform authentication. AuthType not set!", r); |
| } |
| } |
| break; |
| case SATISFY_ANY: |
| if (((access_status = ap_run_access_checker(r)) != 0) || !ap_auth_type(r)) { |
| if (!ap_some_auth_required(r)) { |
| return decl_die(access_status, ap_auth_type(r) |
| ? "check access" |
| : "perform authentication. AuthType not set!", r); |
| } |
| if (((access_status = ap_run_check_user_id(r)) != 0) || !ap_auth_type(r)) { |
| return decl_die(access_status, ap_auth_type(r) |
| ? "check user. No user file?" |
| : "perform authentication. AuthType not set!", r); |
| } |
| if (((access_status = ap_run_auth_checker(r)) != 0) || !ap_auth_type(r)) { |
| return decl_die(access_status, ap_auth_type(r) |
| ? "check access. No groups file?" |
| : "perform authentication. AuthType not set!", r); |
| } |
| } |
| break; |
| } |
| </pre> |
| |
| <h2>The Preparation Phase</h2> |
| |
| <h3>Hook: type_checker</h3> |
| |
| <p>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.</p> |
| |
| <p>If all modules DECLINE this phase, an error 500 is returned |
| to the browser, and a "couldn't find types" error is logged |
| automatically.</p> |
| |
| <h3>Hook: fixups</h3> |
| |
| <p>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.</p> |
| |
| <h3>Hook: insert_filter</h3> |
| |
| <p>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 it's order as need be.</p> |
| |
| <h2>The Handler Phase</h2> |
| |
| <p>This phase is <strong><em>not</em></strong> part of the |
| processing in <code>ap_process_request_internal()</code>. Many |
| modules prepare one or more subrequests prior to creating any |
| content at all. After the core, or a module calls |
| <code>ap_process_request_internal()</code> it then calls |
| <code>ap_invoke_handler()</code> to generate the request.</p> |
| |
| <h3>Hook: handler</h3> |
| |
| <p>The module finally has a chance to serve the request in it's |
| 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.</p> |
| <!--#include virtual="footer.html" --> |
| </body> |
| </html> |
| |