Mercurial > hg > nginx-site

comparison xml/en/docs/http/request_processing.xml @ 521:3481a91d46ab

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Minor revision in preparation for translation.
author Ruslan Ermilov <ru@nginx.com>
date Thu, 24 May 2012 12:24:25 +0000
parents 9913f1d51c07
children be54c443235a
comparison
equal deleted inserted replaced
520:c5150ea6dd02 521:3481a91d46ab
4 link="/en/docs/http/request_processing.html" 4 link="/en/docs/http/request_processing.html"
5 lang="en" 5 lang="en"
6 author="Igor Sysoev" 6 author="Igor Sysoev"
7 editor="Brian Mercer"> 7 editor="Brian Mercer">
8 8
9
10 <section name="Name-based virtual servers"> 9 <section name="Name-based virtual servers">
11 10
12 <para> 11 <para>
13 nginx first decides which <i>server</i> should process the request. 12 nginx first decides which <i>server</i> should process the request.
14 Let&rsquo;s start with a simple configuration 13 Let’s start with a simple configuration
15 where all three virtual servers listen on port *:80: 14 where all three virtual servers listen on port *:80:
16 15 <programlisting>
17 <programlisting> 16 server {
18 server { 17 listen 80;
19 listen 80; 18 server_name example.org www.example.org;
20 server_name example.org www.example.org; 19 ...
21 ... 20 }
22 } 21
23 22 server {
24 server { 23 listen 80;
25 listen 80; 24 server_name example.net www.example.net;
26 server_name example.net www.example.net; 25 ...
27 ... 26 }
28 } 27
29 28 server {
30 server { 29 listen 80;
31 listen 80; 30 server_name example.com www.example.com;
32 server_name example.com www.example.com; 31 ...
33 ... 32 }
34 } 33 </programlisting>
35 </programlisting> 34
36 </para> 35 </para>
37 36
38 <para> 37 <para>
39 In this configuration nginx tests only the request&rsquo;s header line 38 In this configuration nginx tests only the request’s header field
40 &ldquo;Host&rdquo; to determine which server the request should be routed to. 39 <header>Host</header> to determine which server the request should be routed to.
41 If the &ldquo;Host&rdquo; header line does not match any server name, 40 If its value does not match any server name,
42 or the request does not contain this line at all, 41 or the request does not contain this header field at all,
43 then nginx will route the request to the default server. 42 then nginx will route the request to the default server for this port.
44 In the configuration above, the default server is the first 43 In the configuration above, the default server is the first
45 one&mdash;which is nginx&rsquo;s standard default behaviour. 44 one&mdash;which is nginx’s standard default behaviour.
46 If you do not want the first server listed to be the default server, 45 It can also be set explicitly which server should be default,
47 you may set it explicitly with the <literal>default_server</literal> parameter 46 with the <literal>default_server</literal> parameter
48 in the <link doc="ngx_http_core_module.xml" id="listen"/> directive: 47 in the <link doc="ngx_http_core_module.xml" id="listen"/> directive:
49 48 <programlisting>
50 <programlisting> 49 server {
51 server { 50 listen 80 <b>default_server</b>;
52 listen 80 <b>default_server</b>; 51 server_name example.net www.example.net;
53 server_name example.net www.example.net;
54 ... 52 ...
55 } 53 }
56 </programlisting> 54 </programlisting>
57 55
58 <note> 56 <note>
59 The <literal>default_server</literal> parameter has been available since 57 The <literal>default_server</literal> parameter has been available since
60 version 0.8.21. 58 version 0.8.21.
61 In earlier versions the <literal>default</literal> parameter should be used 59 In earlier versions the <literal>default</literal> parameter should be used
62 instead. 60 instead.
63 </note> 61 </note>
64
65 Note that the default server is a property of the listen port 62 Note that the default server is a property of the listen port
66 and not of the server name. More about this later. 63 and not of the server name.
64 More about this later.
67 </para> 65 </para>
68 66
69 </section> 67 </section>
70 68
71 69
72 <section id="how_to_prevent_undefined_server_names" 70 <section id="how_to_prevent_undefined_server_names"
73 name="How to prevent processing requests with undefined server names"> 71 name="How to prevent processing requests with undefined server names">
74 72
75 <para> 73 <para>
76 If you do not want to process requests without the <header>Host</header> 74 If requests without the <header>Host</header> header field should not be
77 header line, you may define a server that just drops the requests: 75 allowed, a server that just drops the requests can be defined:
78 76 <programlisting>
79 <programlisting> 77 server {
80 server { 78 listen 80;
81 listen 80; 79 server_name "";
82 server_name ""; 80 return 444;
83 return 444; 81 }
84 } 82 </programlisting>
85 </programlisting> 83 Here, the server name is set to an empty string that will match
86 84 requests without the <header>Host</header> header field,
87 Here, the server name is set to an empty string which will match
88 requests without the <header>Host</header> header line,
89 and a special nginx’s non-standard code 444 85 and a special nginx’s non-standard code 444
90 is returned that closes the connection. 86 is returned that closes the connection.
87 <note>
91 Since version 0.8.48, this is the default setting for the 88 Since version 0.8.48, this is the default setting for the
92 server name, so the <literal>server_name ""</literal> can be omitted. 89 server name, so the <literal>server_name ""</literal> can be omitted.
93 In earlier versions, the machine's <i>hostname</i> was used as 90 In earlier versions, the machine’s <i>hostname</i> was used as
94 a default server name. 91 a default server name.
92 </note>
95 </para> 93 </para>
96 94
97 </section> 95 </section>
98 96
99 97
100 <section id="mixed_name_ip_based_servers" 98 <section id="mixed_name_ip_based_servers"
101 name="Mixed name-based and IP-based virtual servers"> 99 name="Mixed name-based and IP-based virtual servers">
102 100
103 <para> 101 <para>
104 Let&rsquo;s look at a more complex configuration 102 Let’s look at a more complex configuration
105 where some virtual servers listen on different addresses: 103 where some virtual servers listen on different addresses:
106 104 <programlisting>
107 <programlisting> 105 server {
108 server { 106 listen 192.168.1.1:80;
109 listen 192.168.1.1:80; 107 server_name example.org www.example.org;
110 server_name example.org www.example.org; 108 ...
111 ... 109 }
112 } 110
113 111 server {
114 server { 112 listen 192.168.1.1:80;
115 listen 192.168.1.1:80; 113 server_name example.net www.example.net;
116 server_name example.net www.example.net; 114 ...
117 ... 115 }
118 } 116
119 117 server {
120 server { 118 listen 192.168.1.2:80;
121 listen 192.168.1.2:80; 119 server_name example.com www.example.com;
122 server_name example.com www.example.com; 120 ...
123 ... 121 }
124 } 122 </programlisting>
125 </programlisting>
126
127 In this configuration, nginx first tests the IP address and port 123 In this configuration, nginx first tests the IP address and port
128 of the request against the 124 of the request against the
129 <link doc="ngx_http_core_module.xml" id="listen"/> directives 125 <link doc="ngx_http_core_module.xml" id="listen"/> directives
130 of the 126 of the
131 <link doc="ngx_http_core_module.xml" id="server"/> blocks. 127 <link doc="ngx_http_core_module.xml" id="server"/> blocks.
132 It then tests the &ldquo;Host&rdquo; 128 It then tests the <header>Host</header>
133 header line of the request against the 129 header field of the request against the
134 <link doc="ngx_http_core_module.xml" id="server_name"/> 130 <link doc="ngx_http_core_module.xml" id="server_name"/>
135 entries of the 131 entries of the
136 <link doc="ngx_http_core_module.xml" id="server"/> 132 <link doc="ngx_http_core_module.xml" id="server"/>
137 blocks that matched 133 blocks that matched
138 the IP address and port. 134 the IP address and port.
139
140 If the server name is not found, the request will be processed by 135 If the server name is not found, the request will be processed by
141 the default server. 136 the default server.
142 For example, a request for <url>www.example.com</url> received on 137 For example, a request for <url>www.example.com</url> received on
143 the 192.168.1.1:80 port will be handled by the default server 138 the 192.168.1.1:80 port will be handled by the default server
144 of the 192.168.1.1:80 port, i.e., by the first server, 139 of the 192.168.1.1:80 port, i.e., by the first server,
145 since there is no <url>www.example.com</url> defined for this port. 140 since there is no <url>www.example.com</url> defined for this port.
146 </para> 141 </para>
147 142
148 <para> 143 <para>
149 As already stated, a default server is a property of the listen port 144 As already stated, a default server is a property of the listen port,
150 and different default servers may be defined for different listen ports: 145 and different default servers may be defined for different ports:
151 146 <programlisting>
152 <programlisting> 147 server {
153 server { 148 listen 192.168.1.1:80;
154 listen 192.168.1.1:80; 149 server_name example.org www.example.org;
155 server_name example.org www.example.org; 150 ...
156 ... 151 }
157 } 152
158 153 server {
159 server { 154 listen 192.168.1.1:80 <b>default_server</b>;
160 listen 192.168.1.1:80 default_server; 155 server_name example.net www.example.net;
161 server_name example.net www.example.net; 156 ...
162 ... 157 }
163 } 158
164 159 server {
165 server { 160 listen 192.168.1.2:80 <b>default_server</b>;
166 listen 192.168.1.2:80 default_server; 161 server_name example.com www.example.com;
167 server_name example.com www.example.com; 162 ...
168 ... 163 }
169 } 164 </programlisting>
170 </programlisting> 165
171 </para> 166 </para>
172 167
173 </section> 168 </section>
174 169
175 170
176 <section id="simple_php_site_configuration" 171 <section id="simple_php_site_configuration"
177 name="A simple PHP site configuration"> 172 name="A simple PHP site configuration">
178 173
179 <para> 174 <para>
180 Now let&rsquo;s look at how nginx chooses a <i>location</i> to process a request 175 Now let’s look at how nginx chooses a <i>location</i> to process a request
181 for a typical, simple PHP site: 176 for a typical, simple PHP site:
182 177 <programlisting>
183 <programlisting> 178 server {
184 server { 179 listen 80;
185 listen 80; 180 server_name example.org www.example.org;
186 server_name example.org www.example.org; 181 root /data/www;
187 root /data/www;
188 182
189 location / { 183 location / {
190 index index.html index.php; 184 index index.html index.php;
191 } 185 }
192 186
193 location ~* \.(gif|jpg|png)$ { 187 location ~* \.(gif|jpg|png)$ {
194 expires 30d; 188 expires 30d;
195 } 189 }
196 190
197 location ~ \.php$ { 191 location ~ \.php$ {
198 fastcgi_pass localhost:9000; 192 fastcgi_pass localhost:9000;
199 fastcgi_param SCRIPT_FILENAME 193 fastcgi_param SCRIPT_FILENAME
200 $document_root$fastcgi_script_name; 194 $document_root$fastcgi_script_name;
201 include fastcgi_params; 195 include fastcgi_params;
202 } 196 }
203 } 197 }
204 </programlisting> 198 </programlisting>
205 </para> 199
206 200 </para>
207 <para> 201
208 nginx first searches for the most specific location given by literal strings 202 <para>
209 regardless of the listed order. In the configuration above 203 nginx first searches for the most specific prefix location given by
210 the only literal location is “<literal>/</literal>” and since it matches 204 literal strings regardless of the listed order.
205 In the configuration above
206 the only prefix location is “<literal>/</literal>” and since it matches
211 any request it will be used as a last resort. 207 any request it will be used as a last resort.
212 Then nginx checks locations given by 208 Then nginx checks locations given by
213 regular expression in the order listed in the configuration file. 209 regular expression in the order listed in the configuration file.
214 The first matching expression stops the search and nginx will use this 210 The first matching expression stops the search and nginx will use this
215 location. If no regular expression matches a request, then nginx uses 211 location.
216 the most specific literal location found earlier. 212 If no regular expression matches a request, then nginx uses
217 </para> 213 the most specific prefix location found earlier.
218 214 </para>
219 <para> 215
220 Note that locations of all types test only a request URI part without a query 216 <para>
221 string. This is done because arguments in the query string may be given in 217 Note that locations of all types test only a URI part of request line
218 without arguments.
219 This is done because arguments in the query string may be given in
222 several ways, for example: 220 several ways, for example:
223
224 <programlisting> 221 <programlisting>
225 /index.php?user=john&amp;page=1 222 /index.php?user=john&amp;page=1
226 /index.php?page=1&amp;user=john 223 /index.php?page=1&amp;user=john
227 </programlisting> 224 </programlisting>
228
229 Besides, anyone may request anything in the query string: 225 Besides, anyone may request anything in the query string:
230
231 <programlisting> 226 <programlisting>
232 /index.php?page=1&amp;something+else&amp;user=john 227 /index.php?page=1&amp;something+else&amp;user=john
233 </programlisting> 228 </programlisting>
234 </para> 229
235 230 </para>
236 <para> 231
237 Now let&rsquo;s look at how requests would be processed 232 <para>
233 Now let’s look at how requests would be processed
238 in the configuration above: 234 in the configuration above:
239 235 <list type="bullet" compact="no">
240 <list type="bullet"> 236
241 237 <listitem>
242 <listitem> 238 A request “<literal>/logo.gif</literal>” is matched by the prefix location
243 <para>
244 A request “<literal>/logo.gif</literal>” is matched by the literal location
245 “<literal>/</literal>” first and then by the regular expression 239 “<literal>/</literal>” first and then by the regular expression
246 “<literal>\.(gif|jpg|png)$</literal>”, 240 “<literal>\.(gif|jpg|png)$</literal>”,
247 therefore, it is handled by the latter location. 241 therefore, it is handled by the latter location.
248 Using the directive “<literal>root&nbsp;/data/www</literal>” the request 242 Using the directive “<literal>root&nbsp;/data/www</literal>” the request
249 is mapped to a file <path>/data/www/logo.gif</path>, and the file 243 is mapped to the file <path>/data/www/logo.gif</path>, and the file
250 is sent to the client. 244 is sent to the client.
251 </para> 245 </listitem>
252 </listitem> 246
253 247 <listitem>
254 <listitem> 248 A request “<literal>/index.php</literal>” is also matched by the prefix location
255 <para>
256 A request “<literal>/index.php</literal>” is also matched by the literal location
257 “<literal>/</literal>” first and then by the regular expression 249 “<literal>/</literal>” first and then by the regular expression
258 “<literal>\.(php)$</literal>”. Therefore, it is handled by the latter location 250 “<literal>\.(php)$</literal>”.
251 Therefore, it is handled by the latter location
259 and the request is passed to a FastCGI server listening on localhost:9000. 252 and the request is passed to a FastCGI server listening on localhost:9000.
260 The 253 The
261 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_param"/> 254 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_param"/>
262 directive sets the FastCGI parameter 255 directive sets the FastCGI parameter
263 SCRIPT_FILENAME to “<literal>/data/www/index.php</literal>”, 256 <literal>SCRIPT_FILENAME</literal> to “<literal>/data/www/index.php</literal>”,
264 and the FastCGI server executes the file. 257 and the FastCGI server executes the file.
265 The variable $document_root is equal to 258 The variable <var>$document_root</var> is equal to
266 the value of the 259 the value of the
267 <link doc="ngx_http_core_module.xml" id="root"/> 260 <link doc="ngx_http_core_module.xml" id="root"/>
268 directive and 261 directive and the variable <var>$fastcgi_script_name</var> is equal to
269 the variable $fastcgi_script_name is equal to the request URI, 262 the request URI, i.e. “<literal>/index.php</literal>”.
270 i.e. “<literal>/index.php</literal>”. 263 </listitem>
271 </para> 264
272 </listitem> 265 <listitem>
273 266 A request “<literal>/about.html</literal>” is matched by the prefix location
274 <listitem>
275 <para>
276 A request “<literal>/about.html</literal>” is matched by the literal location
277 “<literal>/</literal>” only, therefore, it is handled in this location. 267 “<literal>/</literal>” only, therefore, it is handled in this location.
278 Using the directive “<literal>root /data/www</literal>” the request is mapped 268 Using the directive “<literal>root /data/www</literal>” the request is mapped
279 to the file <path>/data/www/about.html</path>, and the file is sent 269 to the file <path>/data/www/about.html</path>, and the file is sent
280 to the client. 270 to the client.
281 </para> 271 </listitem>
282 </listitem> 272
283 273 <listitem>
284 <listitem>
285 <para>
286 Handling a request “<literal>/</literal>” is more complex. 274 Handling a request “<literal>/</literal>” is more complex.
287 It is matched by the literal location “<literal>/</literal>” only, 275 It is matched by the prefix location “<literal>/</literal>” only,
288 therefore, it is handled by this location. 276 therefore, it is handled by this location.
289 Then the 277 Then the
290 <link doc="ngx_http_index_module.xml" id="index"/> 278 <link doc="ngx_http_index_module.xml" id="index"/>
291 directive tests for the existence 279 directive tests for the existence
292 of an index file according to its parameters and 280 of index files according to its parameters and
293 the “<literal>root&nbsp;/data/www</literal>” directive. 281 the “<literal>root /data/www</literal>” directive.
294 If a file <path>/data/www/index.php</path> exists, 282 If the file <path>/data/www/index.html</path> does not exist,
283 and the file <path>/data/www/index.php</path> exists,
295 then the directive does an internal redirect to “<literal>/index.php</literal>”, 284 then the directive does an internal redirect to “<literal>/index.php</literal>”,
296 and nginx searches the locations again 285 and nginx searches the locations again
297 as if the request had been sent by a client. 286 as if the request had been sent by a client.
298 As we saw before, the redirected request will eventually be handled 287 As we saw before, the redirected request will eventually be handled
299 by the FastCGI server. 288 by the FastCGI server.
300 </para>
301 </listitem> 289 </listitem>
302 290
303 </list> 291 </list>
292
304 </para> 293 </para>
305 294
306 </section> 295 </section>
307 296
308 </article> 297 </article>