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