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 7 --> 8<title>Request Processing in the Apache HTTP Server 2.x - 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" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" /> 12<script src="/style/scripts/prettify.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body id="manual-page"><div id="page-header"> 17<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p> 18<p class="apache">Apache HTTP Server Version 2.2</p> 19<img alt="" src="/images/feather.gif" /></div> 20<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 21<div id="path"> 22<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.2</a> > <a href="./">Developer Documentation</a></div><div id="page-content"><div id="preamble"><h1>Request Processing in the Apache HTTP Server 2.x</h1> 23<div class="toplang"> 24<p><span>Available Languages: </span><a href="/en/developer/request.html" title="English"> en </a></p> 25</div> 26 27 <div class="warning"><h3>Warning</h3> 28 <p>Warning - this is a first (fast) draft that needs further 29 revision!</p> 30 </div> 31 32 <p>Several changes in 2.0 and above affect the internal request 33 processing mechanics. Module authors need to be aware of these 34 changes so they may take advantage of the optimizations and 35 security enhancements.</p> 36 37 <p>The first major change is to the subrequest and redirect 38 mechanisms. There were a number of different code paths in 39 the Apache HTTP Server 1.3 to attempt to optimize subrequest 40 or redirect behavior. As patches were introduced to 2.0, these 41 optimizations (and the server behavior) were quickly broken due 42 to this duplication of code. All duplicate code has been folded 43 back into <code>ap_process_request_internal()</code> to prevent 44 the code from falling out of sync again.</p> 45 46 <p>This means that much of the existing code was 'unoptimized'. 47 It is the Apache HTTP Project's first goal to create a robust 48 and correct implementation of the HTTP server RFC. Additional 49 goals include security, scalability and optimization. New 50 methods were sought to optimize the server (beyond the 51 performance of 1.3) without introducing fragile or 52 insecure code.</p> 53</div> 54<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#processing">The Request Processing Cycle</a></li> 55<li><img alt="" src="/images/down.gif" /> <a href="#parsing">The Request Parsing Phase</a></li> 56<li><img alt="" src="/images/down.gif" /> <a href="#security">The Security Phase</a></li> 57<li><img alt="" src="/images/down.gif" /> <a href="#preparation">The Preparation Phase</a></li> 58<li><img alt="" src="/images/down.gif" /> <a href="#handler">The Handler Phase</a></li> 59</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 60<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 61<div class="section"> 62<h2><a name="processing" id="processing">The Request Processing Cycle</a></h2> 63 <p>All requests pass through <code>ap_process_request_internal()</code> 64 in <code>request.c</code>, including subrequests and redirects. If a module 65 doesn't pass generated requests through this code, the author is cautioned 66 that the module may be broken by future changes to request 67 processing.</p> 68 69 <p>To streamline requests, the module author can take advantage 70 of the hooks offered to drop out of the request cycle early, or 71 to bypass core hooks which are irrelevant (and costly in 72 terms of CPU.)</p> 73</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 74<div class="section"> 75<h2><a name="parsing" id="parsing">The Request Parsing Phase</a></h2> 76 <h3><a name="unescape" id="unescape">Unescapes the URL</a></h3> 77 <p>The request's <code>parsed_uri</code> path is unescaped, once and only 78 once, at the beginning of internal request processing.</p> 79 80 <p>This step is bypassed if the proxyreq flag is set, or the 81 <code>parsed_uri.path</code> element is unset. The module has no further 82 control of this one-time unescape operation, either failing to 83 unescape or multiply unescaping the URL leads to security 84 repercussions.</p> 85 86 87 <h3><a name="strip" id="strip">Strips Parent and This Elements from the 88 URI</a></h3> 89 <p>All <code>/../</code> and <code>/./</code> elements are 90 removed by <code>ap_getparents()</code>. This helps to ensure 91 the path is (nearly) absolute before the request processing 92 continues.</p> 93 94 <p>This step cannot be bypassed.</p> 95 96 97 <h3><a name="inital-location-walk" id="inital-location-walk">Initial URI Location Walk</a></h3> 98 <p>Every request is subject to an 99 <code>ap_location_walk()</code> call. This ensures that 100 <code class="directive"><a href="/mod/core.html#location"><Location></a></code> sections 101 are consistently enforced for all requests. If the request is an internal 102 redirect or a sub-request, it may borrow some or all of the processing 103 from the previous or parent request's ap_location_walk, so this step 104 is generally very efficient after processing the main request.</p> 105 106 107 <h3><a name="translate_name" id="translate_name">translate_name</a></h3> 108 <p>Modules can determine the file name, or alter the given URI 109 in this step. For example, <code class="module"><a href="/mod/mod_vhost_alias.html">mod_vhost_alias</a></code> will 110 translate the URI's path into the configured virtual host, 111 <code class="module"><a href="/mod/mod_alias.html">mod_alias</a></code> will translate the path to an alias path, 112 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> 113 114 <p>If all modules <code>DECLINE</code> this phase, an error 500 is 115 returned to the browser, and a "couldn't translate name" error is logged 116 automatically.</p> 117 118 119 <h3><a name="map_to_storage" id="map_to_storage">Hook: map_to_storage</a></h3> 120 <p>After the file or correct URI was determined, the 121 appropriate per-dir configurations are merged together. For 122 example, <code class="module"><a href="/mod/mod_proxy.html">mod_proxy</a></code> compares and merges the appropriate 123 <code class="directive"><a href="/mod/mod_proxy.html#proxy"><Proxy></a></code> sections. 124 If the URI is nothing more than a local (non-proxy) <code>TRACE</code> 125 request, the core handles the request and returns <code>DONE</code>. 126 If no module answers this hook with <code>OK</code> or <code>DONE</code>, 127 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 128 'filename' isn't an absolute, legal filename, a note is set for 129 later termination.</p> 130 131 132 <h3><a name="location-walk" id="location-walk">URI Location Walk</a></h3> 133 <p>Every request is hardened by a second 134 <code>ap_location_walk()</code> call. This reassures that a 135 translated request is still subjected to the configured 136 <code class="directive"><a href="/mod/core.html#location"><Location></a></code> sections. 137 The request again borrows some or all of the processing from its previous 138 <code>location_walk</code> above, so this step is almost always very 139 efficient unless the translated URI mapped to a substantially different 140 path or Virtual Host.</p> 141 142 143 <h3><a name="header_parser" id="header_parser">Hook: header_parser</a></h3> 144 <p>The main request then parses the client's headers. This 145 prepares the remaining request processing steps to better serve 146 the client's request.</p> 147 148</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 149<div class="section"> 150<h2><a name="security" id="security">The Security Phase</a></h2> 151 <p>Needs Documentation. Code is:</p> 152 153 <div class="example"><pre> 154switch (ap_satisfies(r)) { 155case SATISFY_ALL: 156case SATISFY_NOSPEC: 157 if ((access_status = ap_run_access_checker(r)) != 0) { 158 return decl_die(access_status, "check access", r); 159 } 160 161 if (ap_some_auth_required(r)) { 162 if (((access_status = ap_run_check_user_id(r)) != 0) 163 || !ap_auth_type(r)) { 164 return decl_die(access_status, ap_auth_type(r) 165 ? "check user. No user file?" 166 : "perform authentication. AuthType not set!", 167 r); 168 } 169 170 if (((access_status = ap_run_auth_checker(r)) != 0) 171 || !ap_auth_type(r)) { 172 return decl_die(access_status, ap_auth_type(r) 173 ? "check access. No groups file?" 174 : "perform authentication. AuthType not set!", 175 r); 176 } 177 } 178 break; 179 180case SATISFY_ANY: 181 if (((access_status = ap_run_access_checker(r)) != 0)) { 182 if (!ap_some_auth_required(r)) { 183 return decl_die(access_status, "check access", r); 184 } 185 186 if (((access_status = ap_run_check_user_id(r)) != 0) 187 || !ap_auth_type(r)) { 188 return decl_die(access_status, ap_auth_type(r) 189 ? "check user. No user file?" 190 : "perform authentication. AuthType not set!", 191 r); 192 } 193 194 if (((access_status = ap_run_auth_checker(r)) != 0) 195 || !ap_auth_type(r)) { 196 return decl_die(access_status, ap_auth_type(r) 197 ? "check access. No groups file?" 198 : "perform authentication. AuthType not set!", 199 r); 200 } 201 } 202 break; 203}</pre></div> 204</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 205<div class="section"> 206<h2><a name="preparation" id="preparation">The Preparation Phase</a></h2> 207 <h3><a name="type_checker" id="type_checker">Hook: type_checker</a></h3> 208 <p>The modules have an opportunity to test the URI or filename 209 against the target resource, and set mime information for the 210 request. Both <code class="module"><a href="/mod/mod_mime.html">mod_mime</a></code> and 211 <code class="module"><a href="/mod/mod_mime_magic.html">mod_mime_magic</a></code> use this phase to compare the file 212 name or contents against the administrator's configuration and set the 213 content type, language, character set and request handler. Some modules 214 may set up their filters or other request handling parameters at this 215 time.</p> 216 217 <p>If all modules <code>DECLINE</code> this phase, an error 500 is 218 returned to the browser, and a "couldn't find types" error is logged 219 automatically.</p> 220 221 222 <h3><a name="fixups" id="fixups">Hook: fixups</a></h3> 223 <p>Many modules are 'trounced' by some phase above. The fixups 224 phase is used by modules to 'reassert' their ownership or force 225 the request's fields to their appropriate values. It isn't 226 always the cleanest mechanism, but occasionally it's the only 227 option.</p> 228 229</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 230<div class="section"> 231<h2><a name="handler" id="handler">The Handler Phase</a></h2> 232 <p>This phase is <strong>not</strong> part of the processing in 233 <code>ap_process_request_internal()</code>. Many 234 modules prepare one or more subrequests prior to creating any 235 content at all. After the core, or a module calls 236 <code>ap_process_request_internal()</code> it then calls 237 <code>ap_invoke_handler()</code> to generate the request.</p> 238 239 <h3><a name="insert_filter" id="insert_filter">Hook: insert_filter</a></h3> 240 <p>Modules that transform the content in some way can insert 241 their values and override existing filters, such that if the 242 user configured a more advanced filter out-of-order, then the 243 module can move its order as need be. There is no result code, 244 so actions in this hook better be trusted to always succeed.</p> 245 246 247 <h3><a name="hook_handler" id="hook_handler">Hook: handler</a></h3> 248 <p>The module finally has a chance to serve the request in its 249 handler hook. Note that not every prepared request is sent to 250 the handler hook. Many modules, such as <code class="module"><a href="/mod/mod_autoindex.html">mod_autoindex</a></code>, 251 will create subrequests for a given URI, and then never serve the 252 subrequest, but simply lists it for the user. Remember not to 253 put required teardown from the hooks above into this module, 254 but register pool cleanups against the request pool to free 255 resources as required.</p> 256 257</div></div> 258<div class="bottomlang"> 259<p><span>Available Languages: </span><a href="/en/developer/request.html" title="English"> en </a></p> 260</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> 261<script type="text/javascript"><!--//--><![CDATA[//><!-- 262var comments_shortname = 'httpd'; 263var comments_identifier = 'http://httpd.apache.org/docs/2.2/developer/request.html'; 264(function(w, d) { 265 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 266 d.write('<div id="comments_thread"><\/div>'); 267 var s = d.createElement('script'); 268 s.type = 'text/javascript'; 269 s.async = true; 270 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 271 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 272 } 273 else { 274 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 275 } 276})(window, document); 277//--><!]]></script></div><div id="footer"> 278<p class="apache">Copyright 2013 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> 279<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- 280if (typeof(prettyPrint) !== 'undefined') { 281 prettyPrint(); 282} 283//--><!]]></script> 284</body></html>
