Mercurial > hg > nginx-site

comparison xml/en/docs/http/request_processing.xml @ 0:61e04fc01027

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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&rsquo;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&rsquo;s header line
40 &ldquo;Host&rdquo; to determine which server the request should be routed to.
41 If the &ldquo;Host&rdquo; 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&mdash;which is nginx&rsquo;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 &ldquo;Host&rdquo;
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 &ldquo;_&rdquo;
88 as the server name and returned nginx&rsquo;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&rsquo;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 &ldquo;Host&rdquo;
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&rsquo;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&amp;page=1
217 /index.php?page=1&amp;user=john
218 </programlisting>
219
220 Besides, anyone may request anything in the query string:
221
222 <programlisting>
223 /index.php?page=1&amp;something+else&amp;user=john
224 </programlisting>
225 </para>
226
227 <para>
228 Now let&rsquo;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&nbsp;/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&nbsp;/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>