294N/A<?
xml version="1.0" encoding="ISO-8859-1"?>
789N/A XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 789N/A This file is generated from xml source: DO NOT EDIT 789N/A XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 789N/A<
title>Request Processing in Apache 2.0 - Apache HTTP Server</
title>
789N/A<
body id="manual-page"><
div id="page-header">
873N/A<
p class="apache">Apache HTTP Server Version 2.1</
p>
789N/A<
div class="up"><
a href="./"><
img title="<-" alt="<-" src="/images/left.gif" /></
a></
div>
789N/A <
div class="warning"><
h3>Warning</
h3>
789N/A <
p>Warning - this is a first (fast) draft that needs further
789N/A <
p>Several changes in Apache 2.0 affect the internal request
789N/A processing mechanics. Module authors need to be aware of these
789N/A changes so they may take advantage of the optimizations and
873N/A security enhancements.</
p>
941N/A <
p>The first major change is to the subrequest and redirect
941N/A mechanisms. There were a number of different code paths in
994N/A Apache 1.3 to attempt to optimize subrequest or redirect
1109N/A behavior. As patches were introduced to 2.0, these
1086N/A optimizations (and the server behavior) were quickly broken due
911N/A to this duplication of code. All duplicate code has been folded
911N/A back into <
code>ap_process_internal_request()</
code> to prevent
873N/A the code from falling out of sync again.</
p>
873N/A <
p>This means that much of the existing code was 'unoptimized'.
789N/A It is the Apache HTTP Project's first goal to create a robust
787N/A and correct implementation of the HTTP server RFC. Additional
294N/A goals include security, scalability and optimization. New
294N/A methods were sought to optimize the server (beyond the
294N/A performance of Apache 1.3) without introducing fragile or
294N/A<
div id="quickview"><
ul id="toc"><
li><
img alt="" src="/images/down.gif" /> <
a href="#processing">The Request Processing Cycle</
a></
li>
294N/A<
li><
img alt="" src="/images/down.gif" /> <
a href="#parsing">The Request Parsing Phase</
a></
li>
869N/A<
li><
img alt="" src="/images/down.gif" /> <
a href="#preparation">The Preparation Phase</
a></
li>
911N/A<
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
789N/A<
h2><
a name="processing" id="processing">The Request Processing Cycle</
a></
h2>
868N/A <
p>All requests pass through <
code>ap_process_request_internal()</
code>
294N/A in <
code>
request.c</
code>, including subrequests and redirects. If a module
294N/A doesn't pass generated requests through this code, the author is cautioned
294N/A that the module may be broken by future changes to request
789N/A <
p>To streamline requests, the module author can take advantage
294N/A of the hooks offered to drop out of the request cycle early, or
1109N/A to bypass core Apache hooks which are irrelevant (and costly in
789N/A</
div><
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
1109N/A<
h2><
a name="parsing" id="parsing">The Request Parsing Phase</
a></
h2>
1109N/A <
h3><
a name="unescape" id="unescape">Unescapes the URL</
a></
h3>
1109N/A <
p>The request's <
code>parsed_uri</
code> path is unescaped, once and only
1109N/A once, at the beginning of internal request processing.</
p>
869N/A <
p>This step is bypassed if the proxyreq flag is set, or the
869N/A control of this one-time unescape operation, either failing to
869N/A unescape or multiply unescaping the URL leads to security
789N/A <
h3><
a name="strip" id="strip">Strips Parent and This Elements from the
789N/A <
p>All <
code>/../</
code> and <
code>/./</
code> elements are
294N/A removed by <
code>ap_getparents()</
code>. This helps to ensure
789N/A the path is (nearly) absolute before the request processing
789N/A <
p>This step cannot be bypassed.</
p>
294N/A <
h3><
a name="inital-location-walk" id="inital-location-walk">Initial URI Location Walk</
a></
h3>
294N/A <
p>Every request is subject to an
294N/A <
code>ap_location_walk()</
code> call. This ensures that
294N/A <
code class="directive"><
a href="/mod/core.html#location"><Location></
a></
code> sections
294N/A are consistently enforced for all requests. If the request is an internal
789N/A redirect or a sub-request, it may borrow some or all of the processing
789N/A from the previous or parent request's ap_location_walk, so this step
789N/A is generally very efficient after processing the main request.</
p>
294N/A <
h3><
a name="translate_name" id="translate_name">translate_name</
a></
h3>
869N/A <
p>Modules can determine the file name, or alter the given URI
789N/A translate the URI's path into the configured virtual host,
789N/A <
code class="module"><
a href="/mod/mod_alias.html">mod_alias</
a></
code> will translate the path to an alias path,
869N/A and if the request falls back on the core, the <
code class="directive"><
a href="/mod/core.html#documentroot">DocumentRoot</
a></
code> is prepended to the request resource.</
p>
869N/A <
p>If all modules <
code>DECLINE</
code> this phase, an error 500 is
869N/A returned to the browser, and a "couldn't translate name" error is logged
949N/A <
h3><
a name="map_to_storage" id="map_to_storage">Hook: map_to_storage</
a></
h3>
789N/A <
p>After the file or correct URI was determined, the
789N/A appropriate per-dir configurations are merged together. For
979N/A example, <
code class="module"><
a href="/mod/mod_proxy.html">mod_proxy</
a></
code> compares and merges the appropriate
789N/A If the URI is nothing more than a local (non-proxy) <
code>TRACE</
code>
787N/A request, the core handles the request and returns <
code>DONE</
code>.
787N/A If no module answers this hook with <
code>OK</
code> or <
code>DONE</
code>,
294N/A the core will run the request filename against the <
code class="directive"><
a href="/mod/core.html#directory"><Directory></
a></
code> and <
code class="directive"><
a href="/mod/core.html#files"><Files></
a></
code> sections. If the request
294N/A 'filename' isn't an absolute, legal filename, a note is set for
294N/A <
h3><
a name="location-walk" id="location-walk">URI Location Walk</
a></
h3>
294N/A <
p>Every request is hardened by a second
789N/A <
code>ap_location_walk()</
code> call. This reassures that a
294N/A translated request is still subjected to the configured
294N/A <
code class="directive"><
a href="/mod/core.html#location"><Location></
a></
code> sections.
294N/A The request again borrows some or all of the processing from its previous
789N/A <
code>location_walk</
code> above, so this step is almost always very
294N/A efficient unless the translated URI mapped to a substantially different
789N/A path or Virtual Host.</
p>
789N/A <
h3><
a name="header_parser" id="header_parser">Hook: header_parser</
a></
h3>
911N/A <
p>The main request then parses the client's headers. This
911N/A prepares the remaining request processing steps to better serve
911N/A the client's request.</
p>
911N/A</
div><
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
911N/A<
h2><
a name="security" id="security">The Security Phase</
a></
h2>
869N/A <
p>Needs Documentation. Code is:</
p>
869N/A <
div class="example"><
pre>
869N/Aswitch (ap_satisfies(r)) {
789N/A if ((access_status = ap_run_access_checker(r)) != 0) {
789N/A return decl_die(access_status, "check access", r);
789N/A if (ap_some_auth_required(r)) {
294N/A if (((access_status = ap_run_check_user_id(r)) != 0)
789N/A return decl_die(access_status, ap_auth_type(r)
294N/A ? "check user. No user file?"
294N/A : "perform authentication. AuthType not set!",
294N/A if (((access_status = ap_run_auth_checker(r)) != 0)
294N/A return decl_die(access_status, ap_auth_type(r)
877N/A ? "check access. No groups file?"
877N/A : "perform authentication. AuthType not set!",
869N/A if (((access_status = ap_run_access_checker(r)) != 0)) {
868N/A if (!ap_some_auth_required(r)) {
789N/A return decl_die(access_status, "check access", r);
911N/A if (((access_status = ap_run_check_user_id(r)) != 0)
911N/A return decl_die(access_status, ap_auth_type(r)
294N/A ? "check user. No user file?"
869N/A : "perform authentication. AuthType not set!",
872N/A if (((access_status = ap_run_auth_checker(r)) != 0)
872N/A return decl_die(access_status, ap_auth_type(r)
869N/A ? "check access. No groups file?"
994N/A : "perform authentication. AuthType not set!",
869N/A</
div><
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
1109N/A<
h2><
a name="preparation" id="preparation">The Preparation Phase</
a></
h2>
1109N/A <
h3><
a name="type_checker" id="type_checker">Hook: type_checker</
a></
h3>
1109N/A <
p>The modules have an opportunity to test the URI or filename
1109N/A against the target resource, and set mime information for the
869N/A name or contents against the administrator's configuration and set the
869N/A content type, language, character set and request handler. Some modules
869N/A may set up their filters or other request handling parameters at this
870N/A <
p>If all modules <
code>DECLINE</
code> this phase, an error 500 is
870N/A returned to the browser, and a "couldn't find types" error is logged
869N/A <
h3><
a name="fixups" id="fixups">Hook: fixups</
a></
h3>
869N/A <
p>Many modules are 'trounced' by some phase above. The fixups
869N/A phase is used by modules to 'reassert' their ownership or force
869N/A the request's fields to their appropriate values. It isn't
869N/A always the cleanest mechanism, but occasionally it's the only
912N/A</
div><
div class="top"><
a href="#page-header"><
img alt="top" src="/images/up.gif" /></
a></
div>
868N/A<
h2><
a name="handler" id="handler">The Handler Phase</
a></
h2>
789N/A <
p>This phase is <
strong>not</
strong> part of the processing in
789N/A <
code>ap_process_request_internal()</
code>. Many
789N/A modules prepare one or more subrequests prior to creating any
789N/A content at all. After the core, or a module calls
789N/A <
code>ap_process_request_internal()</
code> it then calls
877N/A <
code>ap_invoke_handler()</
code> to generate the request.</
p>
877N/A <
h3><
a name="insert_filter" id="insert_filter">Hook: insert_filter</
a></
h3>
877N/A <
p>Modules that transform the content in some way can insert
877N/A their values and override existing filters, such that if the
787N/A user configured a more advanced filter out-of-order, then the
294N/A module can move its order as need be. There is no result code,
789N/A so actions in this hook better be trusted to always succeed.</
p>
789N/A <
h3><
a name="hook_handler" id="hook_handler">Hook: handler</
a></
h3>
789N/A <
p>The module finally has a chance to serve the request in its
789N/A handler hook. Note that not every prepared request is sent to
877N/A will create subrequests for a given URI, and then never serve the
877N/A subrequest, but simply lists it for the user. Remember not to
877N/A put required teardown from the hooks above into this module,
877N/A but register pool cleanups against the request pool to free
789N/A resources as required.</
p>
869N/A<
div class="bottomlang">
