Mercurial > hg > nginx-site
comparison xml/en/docs/http/request_processing.xml @ 521:3481a91d46ab
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’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’s header line | 38 In this configuration nginx tests only the request’s header field |
40 “Host” 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 “Host” 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—which is nginx’s standard default behaviour. | 44 one—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’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 “Host” | 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’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&page=1 | 222 /index.php?user=john&page=1 |
226 /index.php?page=1&user=john | 223 /index.php?page=1&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&something+else&user=john | 227 /index.php?page=1&something+else&user=john |
233 </programlisting> | 228 </programlisting> |
234 </para> | 229 |
235 | 230 </para> |
236 <para> | 231 |
237 Now let’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 /data/www</literal>” the request | 242 Using the directive “<literal>root /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 /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> |