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 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
7 This file is generated from xml source: DO NOT EDIT
8 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
10 <title>Request Processing in the Apache HTTP Server 2.x - Apache HTTP Server Version 2.5</title>
11 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
12 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
13 <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" />
14 <script src="../style/scripts/prettify.min.js" type="text/javascript">
17 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
18 <body id="manual-page"><div id="page-header">
19 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.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>
20 <p class="apache">Apache HTTP Server Version 2.5</p>
21 <img alt="" src="../images/feather.png" /></div>
22 <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
24 <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.5</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>
26 <p><span>Available Languages: </span><a href="../en/developer/request.html" title="English"> en </a></p>
29 <div class="warning"><h3>Warning</h3>
30 <p>Warning - this is a first (fast) draft that needs further
34 <p>Several changes in 2.0 and above affect the internal request
35 processing mechanics. Module authors need to be aware of these
36 changes so they may take advantage of the optimizations and
37 security enhancements.</p>
39 <p>The first major change is to the subrequest and redirect
40 mechanisms. There were a number of different code paths in
41 the Apache HTTP Server 1.3 to attempt to optimize subrequest
42 or redirect behavior. As patches were introduced to 2.0, these
43 optimizations (and the server behavior) were quickly broken due
44 to this duplication of code. All duplicate code has been folded
45 back into <code>ap_process_request_internal()</code> to prevent
46 the code from falling out of sync again.</p>
48 <p>This means that much of the existing code was 'unoptimized'.
49 It is the Apache HTTP Project's first goal to create a robust
50 and correct implementation of the HTTP server RFC. Additional
51 goals include security, scalability and optimization. New
52 methods were sought to optimize the server (beyond the
53 performance of 1.3) without introducing fragile or
56 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#processing">The Request Processing Cycle</a></li>
57 <li><img alt="" src="../images/down.gif" /> <a href="#parsing">The Request Parsing Phase</a></li>
58 <li><img alt="" src="../images/down.gif" /> <a href="#security">The Security Phase</a></li>
59 <li><img alt="" src="../images/down.gif" /> <a href="#preparation">The Preparation Phase</a></li>
60 <li><img alt="" src="../images/down.gif" /> <a href="#handler">The Handler Phase</a></li>
61 </ul><h3>See also</h3><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
62 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
64 <h2><a name="processing" id="processing">The Request Processing Cycle</a></h2>
65 <p>All requests pass through <code>ap_process_request_internal()</code>
66 in <code>server/request.c</code>, including subrequests and redirects. If a module
67 doesn't pass generated requests through this code, the author is cautioned
68 that the module may be broken by future changes to request
71 <p>To streamline requests, the module author can take advantage
72 of the <a href="./modguide.html#hooking">hooks offered</a> to drop
73 out of the request cycle early, or to bypass core hooks which are
74 irrelevant (and costly in terms of CPU.)</p>
75 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
77 <h2><a name="parsing" id="parsing">The Request Parsing Phase</a></h2>
78 <h3><a name="unescape" id="unescape">Unescapes the URL</a></h3>
79 <p>The request's <code>parsed_uri</code> path is unescaped, once and only
80 once, at the beginning of internal request processing.</p>
82 <p>This step is bypassed if the proxyreq flag is set, or the
83 <code>parsed_uri.path</code> element is unset. The module has no further
84 control of this one-time unescape operation, either failing to
85 unescape or multiply unescaping the URL leads to security
89 <h3><a name="strip" id="strip">Strips Parent and This Elements from the
91 <p>All <code>/../</code> and <code>/./</code> elements are
92 removed by <code>ap_getparents()</code>. This helps to ensure
93 the path is (nearly) absolute before the request processing
96 <p>This step cannot be bypassed.</p>
99 <h3><a name="inital-location-walk" id="inital-location-walk">Initial URI Location Walk</a></h3>
100 <p>Every request is subject to an
101 <code>ap_location_walk()</code> call. This ensures that
102 <code class="directive"><a href="../mod/core.html#location"><Location></a></code> sections
103 are consistently enforced for all requests. If the request is an internal
104 redirect or a sub-request, it may borrow some or all of the processing
105 from the previous or parent request's ap_location_walk, so this step
106 is generally very efficient after processing the main request.</p>
109 <h3><a name="translate_name" id="translate_name">translate_name</a></h3>
110 <p>Modules can determine the file name, or alter the given URI
111 in this step. For example, <code class="module"><a href="../mod/mod_vhost_alias.html">mod_vhost_alias</a></code> will
112 translate the URI's path into the configured virtual host,
113 <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> will translate the path to an alias path,
114 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>
116 <p>If all modules <code>DECLINE</code> this phase, an error 500 is
117 returned to the browser, and a "couldn't translate name" error is logged
121 <h3><a name="map_to_storage" id="map_to_storage">Hook: map_to_storage</a></h3>
122 <p>After the file or correct URI was determined, the
123 appropriate per-dir configurations are merged together. For
124 example, <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> compares and merges the appropriate
125 <code class="directive"><a href="../mod/mod_proxy.html#proxy"><Proxy></a></code> sections.
126 If the URI is nothing more than a local (non-proxy) <code>TRACE</code>
127 request, the core handles the request and returns <code>DONE</code>.
128 If no module answers this hook with <code>OK</code> or <code>DONE</code>,
129 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
130 'filename' isn't an absolute, legal filename, a note is set for
131 later termination.</p>
134 <h3><a name="location-walk" id="location-walk">URI Location Walk</a></h3>
135 <p>Every request is hardened by a second
136 <code>ap_location_walk()</code> call. This reassures that a
137 translated request is still subjected to the configured
138 <code class="directive"><a href="../mod/core.html#location"><Location></a></code> sections.
139 The request again borrows some or all of the processing from its previous
140 <code>location_walk</code> above, so this step is almost always very
141 efficient unless the translated URI mapped to a substantially different
142 path or Virtual Host.</p>
145 <h3><a name="header_parser" id="header_parser">Hook: header_parser</a></h3>
146 <p>The main request then parses the client's headers. This
147 prepares the remaining request processing steps to better serve
148 the client's request.</p>
150 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
151 <div class="section">
152 <h2><a name="security" id="security">The Security Phase</a></h2>
153 <p>Needs Documentation. Code is:</p>
155 <pre class="prettyprint lang-c">if ((access_status = ap_run_access_checker(r)) != 0) {
156 return decl_die(access_status, "check access", r);
159 if ((access_status = ap_run_check_user_id(r)) != 0) {
160 return decl_die(access_status, "check user", r);
163 if ((access_status = ap_run_auth_checker(r)) != 0) {
164 return decl_die(access_status, "check authorization", r);
167 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
168 <div class="section">
169 <h2><a name="preparation" id="preparation">The Preparation Phase</a></h2>
170 <h3><a name="type_checker" id="type_checker">Hook: type_checker</a></h3>
171 <p>The modules have an opportunity to test the URI or filename
172 against the target resource, and set mime information for the
173 request. Both <code class="module"><a href="../mod/mod_mime.html">mod_mime</a></code> and
174 <code class="module"><a href="../mod/mod_mime_magic.html">mod_mime_magic</a></code> use this phase to compare the file
175 name or contents against the administrator's configuration and set the
176 content type, language, character set and request handler. Some modules
177 may set up their filters or other request handling parameters at this
180 <p>If all modules <code>DECLINE</code> this phase, an error 500 is
181 returned to the browser, and a "couldn't find types" error is logged
185 <h3><a name="fixups" id="fixups">Hook: fixups</a></h3>
186 <p>Many modules are 'trounced' by some phase above. The fixups
187 phase is used by modules to 'reassert' their ownership or force
188 the request's fields to their appropriate values. It isn't
189 always the cleanest mechanism, but occasionally it's the only
192 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
193 <div class="section">
194 <h2><a name="handler" id="handler">The Handler Phase</a></h2>
195 <p>This phase is <strong>not</strong> part of the processing in
196 <code>ap_process_request_internal()</code>. Many
197 modules prepare one or more subrequests prior to creating any
198 content at all. After the core, or a module calls
199 <code>ap_process_request_internal()</code> it then calls
200 <code>ap_invoke_handler()</code> to generate the request.</p>
202 <h3><a name="insert_filter" id="insert_filter">Hook: insert_filter</a></h3>
203 <p>Modules that transform the content in some way can insert
204 their values and override existing filters, such that if the
205 user configured a more advanced filter out-of-order, then the
206 module can move its order as need be. There is no result code,
207 so actions in this hook better be trusted to always succeed.</p>
210 <h3><a name="hook_handler" id="hook_handler">Hook: handler</a></h3>
211 <p>The module finally has a chance to serve the request in its
212 handler hook. Note that not every prepared request is sent to
213 the handler hook. Many modules, such as <code class="module"><a href="../mod/mod_autoindex.html">mod_autoindex</a></code>,
214 will create subrequests for a given URI, and then never serve the
215 subrequest, but simply lists it for the user. Remember not to
216 put required teardown from the hooks above into this module,
217 but register pool cleanups against the request pool to free
218 resources as required.</p>
221 <div class="bottomlang">
222 <p><span>Available Languages: </span><a href="../en/developer/request.html" title="English"> en </a></p>
223 </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>
224 <script type="text/javascript"><!--//--><![CDATA[//><!--
225 var comments_shortname = 'httpd';
226 var comments_identifier = 'http://httpd.apache.org/docs/trunk/developer/request.html';
228 if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
229 d.write('<div id="comments_thread"><\/div>');
230 var s = d.createElement('script');
231 s.type = 'text/javascript';
233 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
234 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
237 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
239 })(window, document);
240 //--><!]]></script></div><div id="footer">
241 <p class="apache">Copyright 2016 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>
242 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.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[//><!--
243 if (typeof(prettyPrint) !== 'undefined') {