1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
5 This file is generated from xml source: DO NOT EDIT
6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8 <title>Request Processing in Apache 2.0 - Apache HTTP Server</title>
9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
13 <body id="manual-page"><div id="page-header">
14 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
15 <p class="apache">Apache HTTP Server Version 2.0</p>
16 <img alt="" src="../images/feather.gif" /></div>
17 <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
19 <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.0</a> > <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>Request Processing in Apache 2.0</h1>
21 <p><span>Available Languages: </span><a href="../en/developer/request.html" title="English"> en </a></p>
24 <div class="warning"><h3>Warning</h3>
25 <p>Warning - this is a first (fast) draft that needs further
29 <p>Several changes in Apache 2.0 affect the internal request
30 processing mechanics. Module authors need to be aware of these
31 changes so they may take advantage of the optimizations and
32 security enhancements.</p>
34 <p>The first major change is to the subrequest and redirect
35 mechanisms. There were a number of different code paths in
36 Apache 1.3 to attempt to optimize subrequest or redirect
37 behavior. As patches were introduced to 2.0, these
38 optimizations (and the server behavior) were quickly broken due
39 to this duplication of code. All duplicate code has been folded
40 back into <code>ap_process_request_internal()</code> to prevent
41 the code from falling out of sync again.</p>
43 <p>This means that much of the existing code was 'unoptimized'.
44 It is the Apache HTTP Project's first goal to create a robust
45 and correct implementation of the HTTP server RFC. Additional
46 goals include security, scalability and optimization. New
47 methods were sought to optimize the server (beyond the
48 performance of Apache 1.3) without introducing fragile or
51 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#processing">The Request Processing Cycle</a></li>
52 <li><img alt="" src="../images/down.gif" /> <a href="#parsing">The Request Parsing Phase</a></li>
53 <li><img alt="" src="../images/down.gif" /> <a href="#security">The Security Phase</a></li>
54 <li><img alt="" src="../images/down.gif" /> <a href="#preparation">The Preparation Phase</a></li>
55 <li><img alt="" src="../images/down.gif" /> <a href="#handler">The Handler Phase</a></li>
57 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
59 <h2><a name="processing" id="processing">The Request Processing Cycle</a></h2>
60 <p>All requests pass through <code>ap_process_request_internal()</code>
61 in <code>request.c</code>, including subrequests and redirects. If a module
62 doesn't pass generated requests through this code, the author is cautioned
63 that the module may be broken by future changes to request
66 <p>To streamline requests, the module author can take advantage
67 of the hooks offered to drop out of the request cycle early, or
68 to bypass core Apache hooks which are irrelevant (and costly in
70 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
72 <h2><a name="parsing" id="parsing">The Request Parsing Phase</a></h2>
73 <h3><a name="unescape" id="unescape">Unescapes the URL</a></h3>
74 <p>The request's <code>parsed_uri</code> path is unescaped, once and only
75 once, at the beginning of internal request processing.</p>
77 <p>This step is bypassed if the proxyreq flag is set, or the
78 <code>parsed_uri.path</code> element is unset. The module has no further
79 control of this one-time unescape operation, either failing to
80 unescape or multiply unescaping the URL leads to security
84 <h3><a name="strip" id="strip">Strips Parent and This Elements from the
86 <p>All <code>/../</code> and <code>/./</code> elements are
87 removed by <code>ap_getparents()</code>. This helps to ensure
88 the path is (nearly) absolute before the request processing
91 <p>This step cannot be bypassed.</p>
94 <h3><a name="inital-location-walk" id="inital-location-walk">Initial URI Location Walk</a></h3>
95 <p>Every request is subject to an
96 <code>ap_location_walk()</code> call. This ensures that
97 <code class="directive"><a href="../mod/core.html#location"><Location></a></code> sections
98 are consistently enforced for all requests. If the request is an internal
99 redirect or a sub-request, it may borrow some or all of the processing
100 from the previous or parent request's ap_location_walk, so this step
101 is generally very efficient after processing the main request.</p>
104 <h3><a name="translate_name" id="translate_name">translate_name</a></h3>
105 <p>Modules can determine the file name, or alter the given URI
106 in this step. For example, <code class="module"><a href="../mod/mod_vhost_alias.html">mod_vhost_alias</a></code> will
107 translate the URI's path into the configured virtual host,
108 <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> will translate the path to an alias path,
109 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>
111 <p>If all modules <code>DECLINE</code> this phase, an error 500 is
112 returned to the browser, and a "couldn't translate name" error is logged
116 <h3><a name="map_to_storage" id="map_to_storage">Hook: map_to_storage</a></h3>
117 <p>After the file or correct URI was determined, the
118 appropriate per-dir configurations are merged together. For
119 example, <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> compares and merges the appropriate
120 <code class="directive"><a href="../mod/mod_proxy.html#proxy"><Proxy></a></code> sections.
121 If the URI is nothing more than a local (non-proxy) <code>TRACE</code>
122 request, the core handles the request and returns <code>DONE</code>.
123 If no module answers this hook with <code>OK</code> or <code>DONE</code>,
124 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
125 'filename' isn't an absolute, legal filename, a note is set for
126 later termination.</p>
129 <h3><a name="location-walk" id="location-walk">URI Location Walk</a></h3>
130 <p>Every request is hardened by a second
131 <code>ap_location_walk()</code> call. This reassures that a
132 translated request is still subjected to the configured
133 <code class="directive"><a href="../mod/core.html#location"><Location></a></code> sections.
134 The request again borrows some or all of the processing from its previous
135 <code>location_walk</code> above, so this step is almost always very
136 efficient unless the translated URI mapped to a substantially different
137 path or Virtual Host.</p>
140 <h3><a name="header_parser" id="header_parser">Hook: header_parser</a></h3>
141 <p>The main request then parses the client's headers. This
142 prepares the remaining request processing steps to better serve
143 the client's request.</p>
145 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
146 <div class="section">
147 <h2><a name="security" id="security">The Security Phase</a></h2>
148 <p>Needs Documentation. Code is:</p>
150 <div class="example"><pre>
151 switch (ap_satisfies(r)) {
154 if ((access_status = ap_run_access_checker(r)) != 0) {
155 return decl_die(access_status, "check access", r);
158 if (ap_some_auth_required(r)) {
159 if (((access_status = ap_run_check_user_id(r)) != 0)
160 || !ap_auth_type(r)) {
161 return decl_die(access_status, ap_auth_type(r)
162 ? "check user. No user file?"
163 : "perform authentication. AuthType not set!",
167 if (((access_status = ap_run_auth_checker(r)) != 0)
168 || !ap_auth_type(r)) {
169 return decl_die(access_status, ap_auth_type(r)
170 ? "check access. No groups file?"
171 : "perform authentication. AuthType not set!",
178 if (((access_status = ap_run_access_checker(r)) != 0)) {
179 if (!ap_some_auth_required(r)) {
180 return decl_die(access_status, "check access", r);
183 if (((access_status = ap_run_check_user_id(r)) != 0)
184 || !ap_auth_type(r)) {
185 return decl_die(access_status, ap_auth_type(r)
186 ? "check user. No user file?"
187 : "perform authentication. AuthType not set!",
191 if (((access_status = ap_run_auth_checker(r)) != 0)
192 || !ap_auth_type(r)) {
193 return decl_die(access_status, ap_auth_type(r)
194 ? "check access. No groups file?"
195 : "perform authentication. AuthType not set!",
201 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
202 <div class="section">
203 <h2><a name="preparation" id="preparation">The Preparation Phase</a></h2>
204 <h3><a name="type_checker" id="type_checker">Hook: type_checker</a></h3>
205 <p>The modules have an opportunity to test the URI or filename
206 against the target resource, and set mime information for the
207 request. Both <code class="module"><a href="../mod/mod_mime.html">mod_mime</a></code> and
208 <code class="module"><a href="../mod/mod_mime_magic.html">mod_mime_magic</a></code> use this phase to compare the file
209 name or contents against the administrator's configuration and set the
210 content type, language, character set and request handler. Some modules
211 may set up their filters or other request handling parameters at this
214 <p>If all modules <code>DECLINE</code> this phase, an error 500 is
215 returned to the browser, and a "couldn't find types" error is logged
219 <h3><a name="fixups" id="fixups">Hook: fixups</a></h3>
220 <p>Many modules are 'trounced' by some phase above. The fixups
221 phase is used by modules to 'reassert' their ownership or force
222 the request's fields to their appropriate values. It isn't
223 always the cleanest mechanism, but occasionally it's the only
226 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
227 <div class="section">
228 <h2><a name="handler" id="handler">The Handler Phase</a></h2>
229 <p>This phase is <strong>not</strong> part of the processing in
230 <code>ap_process_request_internal()</code>. Many
231 modules prepare one or more subrequests prior to creating any
232 content at all. After the core, or a module calls
233 <code>ap_process_request_internal()</code> it then calls
234 <code>ap_invoke_handler()</code> to generate the request.</p>
236 <h3><a name="insert_filter" id="insert_filter">Hook: insert_filter</a></h3>
237 <p>Modules that transform the content in some way can insert
238 their values and override existing filters, such that if the
239 user configured a more advanced filter out-of-order, then the
240 module can move its order as need be. There is no result code,
241 so actions in this hook better be trusted to always succeed.</p>
244 <h3><a name="hook_handler" id="hook_handler">Hook: handler</a></h3>
245 <p>The module finally has a chance to serve the request in its
246 handler hook. Note that not every prepared request is sent to
247 the handler hook. Many modules, such as <code class="module"><a href="../mod/mod_autoindex.html">mod_autoindex</a></code>,
248 will create subrequests for a given URI, and then never serve the
249 subrequest, but simply lists it for the user. Remember not to
250 put required teardown from the hooks above into this module,
251 but register pool cleanups against the request pool to free
252 resources as required.</p>
255 <div class="bottomlang">
256 <p><span>Available Languages: </span><a href="../en/developer/request.html" title="English"> en </a></p>
257 </div><div id="footer">
258 <p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
259 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>