comparison docs/html/http/ngx_http_core_module.html @ 4069:4dbdfd985863

Regenerate HTML for the previous revision.
author Ruslan Ermilov <ru@nginx.com>
date Mon, 05 Sep 2011 09:40:50 +0000
parents fc808f006ff4
children cf09c4826ab3
comparison
equal deleted inserted replaced
4068:22364b1f61c9 4069:4dbdfd985863
1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>ngx_http_core_module</title></head><body><center><h4>Directives</h4></center><a name="client_body_buffer_size"></a><center><h4>client_body_buffer_size</h4></center>syntax: client_body_buffer_size <i>size</i><br>default: client_body_buffer_size 8k/16k<br>context: http, server, location<br><p> 1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"><title>HTTP Core Module</title></head><body><a name="directives"></a><center><h4>Directives</h4></center><hr><a name="aio"></a><strong>syntax</strong>:
2 Directive sets client request body buffer size. 2 <code>aio
3 If the request body is larger than the buffer, 3 <code>on</code> |
4 then the whole body or some its part is written to temporary file. 4 <code>off</code> |
5 By default buffer size is equal to 2 memory page sizes. 5 <code>sendfile</code></code><br><strong>default</strong>:
6 <code>aio off</code><br><strong>context</strong>:
7 <code>http</code>, <code>server</code>, <code>location</code><br><strong>appeared in version</strong>:
8 0.8.11<p>
9 Enables or disables the use of asynchronous file I/O (AIO)
10 on FreeBSD and Linux.
11 </p><p>
12 On FreeBSD, AIO is usable used starting from FreeBSD 4.3.
13 AIO can either be linked statically into a kernel:
14 <blockquote><pre>
15 options VFS_AIO
16 </pre></blockquote>
17 or loaded dynamically as a kernel loadable module:
18 <blockquote><pre>
19 kldload aio
20 </pre></blockquote></p><p>
21 In FreeBSD versions 5 and 6, enabling AIO statically, or dynamically
22 when booting the kernel, will cause the entire networking subsystem
23 to use the Giant lock that can impact overall performance negatively.
24 This limitation has been removed in FreeBSD 6.4-STABLE in 2009, and in
25 FreeBSD 7.
26 However, starting from FreeBSD 5.3, it's possible to enable AIO
27 without the penalty of running the networking subsystem under a
28 Giant lock - for this to work, the AIO module needs to be loaded
29 after the kernel has booted.
30 In this case, the following message will appear in
31 <code>/var/log/messages</code><blockquote><pre>
32 WARNING: Network stack Giant-free, but aio requires Giant.
33 Consider adding 'options NET_WITH_GIANT' or setting debug.mpsafenet=0
34 </pre></blockquote>
35 and can safely be ignored.
36
37 The requirement to use the Giant lock with AIO is related to the
38 fact that FreeBSD supports asynchronous calls
39 <code>aio_read()</code>
40 and
41 <code>aio_write()</code>
42 when working with sockets.
43 However, since nginx only uses AIO for disk I/O, no problems should arise.
44 </p><p>
45 For AIO to work,
46 <a href="#sendfile">sendfile</a>
47 needs to be disabled:
48 <blockquote><pre>
49 location /video/ {
50 sendfile off;
51 aio on;
52 output_buffers 1 64k;
53 }
54 </pre></blockquote></p><p>
55 In addition, starting from FreeBSD 5.2.1 and nginx 0.8.12, AIO can
56 also be used to pre-load data for <code>sendfile()</code>:
57 <blockquote><pre>
58 location /video/ {
59 sendfile on;
60 tcp_nopush on;
61 aio sendfile;
62 }
63 </pre></blockquote>
64 In this configuration, <code>sendfile()</code> is called with
65 the <code>SF_NODISKIO</code> flag which causes it not to
66 block on disk I/O and instead report back when the data are not in
67 memory; nginx then initiates an asynchronous data load by reading
68 one byte. The FreeBSD kernel then loads the first 128K bytes
69 of a file into memory, however next reads will only load data
70 in 16K chunks. This can be tuned using the
71 <a href="#read_ahead">read_ahead</a>
72 directive.
73 </p><p>
74 On Linux, AIO is usable starting from kernel version 2.6.22;
75 plus, it is also necessary to enable
76 <a href="#directio">directio</a>,
77 otherwise reading will be blocking:
78 <blockquote><pre>
79 location /video/ {
80 aio on;
81 directio 512;
82 output_buffers 1 128k;
83 }
84 </pre></blockquote></p><p>
85 On Linux,
86 <a href="#directio">directio</a>
87 can only be used for reading blocks that are aligned on 512-byte
88 boundaries (or 4K for XFS).
89 Reading of unaligned file's tail is still made in blocking mode.
90 The same holds true for byte range requests, and for FLV requests
91 not from the beginning of a file: reading of unaligned data at the
92 beginning and end of a file will be blocking.
93 There is no need to turn off
94 <a href="#sendfile">sendfile</a>
95 explicitly as it is turned off automatically when
96 <a href="#directio">directio</a>
97 is used.
98 </p><hr><a name="alias"></a><strong>syntax</strong>:
99 <code>alias <code><i>path</i></code></code><br><strong>default</strong>:
100 <strong>none</strong><br><strong>context</strong>:
101 <code>location</code><br><p>
102 Defines a replacement for the specified location.
103 For example, with the following configuration
104 <blockquote><pre>
105 location /i/ {
106 alias /data/w3/images/;
107 }
108 </pre></blockquote>
109 the request of "/i/top.gif" will be responded
110 with the file "/data/w3/images/top.gif".
111 </p><p>
112 The <code><i>path</i></code> value can contain variables.
113 </p><p>
114 If <code>alias</code> is used inside a location defined
115 with a regular expression then such regular expression should
116 contain captures and <code>alias</code> should refer to
117 these captures (0.7.40), for example:
118 <blockquote><pre>
119 location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ {
120 alias /data/w3/images/$1;
121 }
122 </pre></blockquote></p><p>
123 When location matches the last part of the directive's value:
124 <blockquote><pre>
125 location /images/ {
126 alias /data/w3/images/;
127 }
128 </pre></blockquote>
129 it's better to use the
130 <a href="#root">root</a>
131 directive instead:
132 <blockquote><pre>
133 location /images/ {
134 root /data/w3;
135 }
136 </pre></blockquote></p><hr><a name="client_body_in_file_only"></a><strong>syntax</strong>:
137 <code>client_body_in_file_only
138 <code>on</code> |
139 <code>clean</code> |
140 <code>off</code></code><br><strong>default</strong>:
141 <code>client_body_in_file_only off</code><br><strong>context</strong>:
142 <code>http</code>, <code>server</code>, <code>location</code><br><p>
143 Determines whether nginx should save the entire client request body
144 into a file.
145 This directive can be used during debugging, or when using the
146 <code>$request_body_file</code>
147 variable, or the
148 <u>$r-&gt;request_body_file</u>
149 method of the
150 <u>http_perl</u> module.
151 </p><p>
152 When set to the value <code>on</code>, temporary files are not
153 removed after request processing.
154 </p><p>
155 The value <code>clean</code> will cause the temporary files
156 left after request processing to be removed.
157 </p><hr><a name="client_body_in_single_buffer"></a><strong>syntax</strong>:
158 <code>client_body_in_single_buffer <code>on</code> | <code>off</code></code><br><strong>default</strong>:
159 <code>client_body_in_single_buffer off</code><br><strong>context</strong>:
160 <code>http</code>, <code>server</code>, <code>location</code><br><p>
161 Determines whether nginx should save the entire client request body
162 in a single buffer.
163 The directive is recommended when using the
164 <code>$request_body</code>
165 variable, to save the number of copy operations involved.
166 </p><hr><a name="client_body_buffer_size"></a><strong>syntax</strong>:
167 <code>client_body_buffer_size <code><i>size</i></code></code><br><strong>default</strong>:
168 <code>client_body_buffer_size 8k/16k</code><br><strong>context</strong>:
169 <code>http</code>, <code>server</code>, <code>location</code><br><p>
170 Sets buffer size for reading client request body.
171 In case request body is larger than the buffer,
172 the whole body or only its part is written to a temporary file.
173
174 By default, buffer size is equal to two memory pages.
6 This is 8K on x86, other 32-bit platforms, and x86-64. 175 This is 8K on x86, other 32-bit platforms, and x86-64.
7 It is usually 16K on other 64-bit platforms. 176 It is usually 16K on other 64-bit platforms.
8 </p><a name="sendfile"></a><center><h4>sendfile</h4></center>syntax: sendfile <i>[on|off]</i><br>default: sendfile off<br>context: http, server, location<br><p> 177 </p><hr><a name="client_body_temp_path"></a><strong>syntax</strong>:
9 Directive enables or disables sendfile() usage. 178 <code>client_body_temp_path
10 </p></body></html> 179 <code><i>path</i></code>
180 [<code><i>level1</i></code>
181 [<code><i>level2</i></code>
182 [<code><i>level3</i></code>]]]
183 </code><br><strong>default</strong>:
184 <code>client_body_temp_path client_body_temp</code><br><strong>context</strong>:
185 <code>http</code>, <code>server</code>, <code>location</code><br><p>
186 Defines a directory for storing temporary files holding client request bodies.
187 Up to three-level subdirectory hierarchy can be used underneath the specified
188 directory.
189 For example, in the following configuration
190 <blockquote><pre>
191 client_body_temp_path /spool/nginx/client_temp 1 2;
192 </pre></blockquote>
193 a temporary file might look like this:
194 <blockquote><pre>
195 /spool/nginx/client_temp/7/45/00000123457
196 </pre></blockquote></p><hr><a name="client_body_timeout"></a><strong>syntax</strong>:
197 <code>client_body_timeout <code><i>time</i></code></code><br><strong>default</strong>:
198 <code>client_body_timeout 60</code><br><strong>context</strong>:
199 <code>http</code>, <code>server</code>, <code>location</code><br><p>
200 Defines a timeout for reading client request body.
201 A timeout is only set between two successive read operations,
202 not for the transmission of the whole request body.
203 If a client does not transmit anything within this time,
204 the error
205 <i>"Request time out"</i> (408)
206 is returned.
207 </p><hr><a name="client_header_buffer_size"></a><strong>syntax</strong>:
208 <code>client_header_buffer_size <code><i>size</i></code></code><br><strong>default</strong>:
209 <code>client_header_buffer_size 1k</code><br><strong>context</strong>:
210 <code>http</code>, <code>server</code><br><p>
211 Sets buffer size for reading client request header.
212 For most requests, a buffer of 1K bytes is enough.
213 However, if a request includes long cookies, or comes from a WAP client,
214 it may not fit into 1K.
215 If a request line, or a request header line do not fit entirely into
216 this buffer then larger buffers are allocated, configured by the
217 <a href="#large_client_header_buffers">large_client_header_buffers</a>
218 directive.
219 </p><hr><a name="client_header_timeout"></a><strong>syntax</strong>:
220 <code>client_header_timeout <code><i>time</i></code></code><br><strong>default</strong>:
221 <code>client_header_timeout 60</code><br><strong>context</strong>:
222 <code>http</code>, <code>server</code><br><p>
223 Defines a timeout for reading client request header.
224 If a client does not transmit the entire header within this time,
225 the error
226 <i>"Request time out"</i> (408)
227 is returned.
228 </p><hr><a name="client_max_body_size"></a><strong>syntax</strong>:
229 <code>client_max_body_size <code><i>size</i></code></code><br><strong>default</strong>:
230 <code>client_max_body_size 1m</code><br><strong>context</strong>:
231 <code>http</code>, <code>server</code>, <code>location</code><br><p>
232 Sets the maximum allowed size of the client request body,
233 specified in the
234 <code>Content-Length</code>
235 request header line.
236 If <code><i>size</i></code> is greater than the configured value, the
237 <i>"Request Entity Too Large"</i> (413)
238 error is returned to a client.
239 Please be aware that
240 <u>browsers cannot correctly display
241 this error</u>.
242 </p><hr><a name="default_type"></a><strong>syntax</strong>:
243 <code>default_type <code><i>mime-type</i></code></code><br><strong>default</strong>:
244 <code>default_type text/plain</code><br><strong>context</strong>:
245 <code>http</code>, <code>server</code>, <code>location</code><br><p>
246 Defines a default MIME-type of a response.
247 </p><hr><a name="directio"></a><strong>syntax</strong>:
248 <code>directio <code><i>size</i></code> | <code>off</code></code><br><strong>default</strong>:
249 <code>directio off</code><br><strong>context</strong>:
250 <code>http</code>, <code>server</code>, <code>location</code><br><strong>appeared in version</strong>:
251 0.7.7<p>
252 Enables the use of
253 the <code>O_DIRECT</code> flag (FreeBSD, Linux),
254 the <code>F_NOCACHE</code> flag (Mac OS X),
255 or the <code>directio()</code> function (Solaris),
256 when reading files that are larger than the specified <code><i>size</i></code>.
257 It automatically disables (0.7.15) the use of
258 <a href="#sendfile">sendfile</a>
259 for a given request.
260 It could be useful for serving large files:
261 <blockquote><pre>
262 directio 4m;
263 </pre></blockquote>
264 or when using <a href="#aio">aio</a> on Linux.
265 </p><hr><a name="directio_alignment"></a><strong>syntax</strong>:
266 <code>directio_alignment <code><i>size</i></code></code><br><strong>default</strong>:
267 <code>directio_alignment 512</code><br><strong>context</strong>:
268 <code>http</code>, <code>server</code>, <code>location</code><br><strong>appeared in version</strong>:
269 0.8.11<p>
270 Sets an alignment for
271 <a href="#directio">directio</a>.
272 In most cases, a 512-byte alignment is enough, however, when
273 using XFS under Linux, it needs to be increased to 4K.
274 </p><hr><a name="error_page"></a><strong>syntax</strong>:
275 <code>error_page
276 <code><i>code ...</i></code>
277 [<code>=</code>[<code><i>response</i></code>]]
278 <code><i>uri</i></code></code><br><strong>default</strong>:
279 <strong>none</strong><br><strong>context</strong>:
280 <code>http</code>, <code>server</code>, <code>location</code>, <code>if in location</code><br><p>
281 Defines the URI that will be shown for the specified errors.
282 These directives are inherited from the previous level if and
283 only if there are no <code>error_page</code> directives on
284 the current level.
285 A URI value can contain variables.
286 </p><p>
287 Example usage:
288 <blockquote><pre>
289 error_page 404 /404.html;
290 error_page 502 503 504 /50x.html;
291 error_page 403 http://example.com/forbidden.html;
292 </pre></blockquote></p><p>
293 Furthermore, it is possible to change the response code to another, for example:
294 <blockquote><pre>
295 error_page 404 =200 /empty.gif;
296 </pre></blockquote></p><p>
297 If an error response is processed by a proxied server, or a FastCGI-server,
298 and the server may return different response codes (e.g., 200, 302, 401
299 or 404), it is possible to respond with a returned code:
300 <blockquote><pre>
301 error_page 404 = /404.php;
302 </pre></blockquote></p><p>
303 If there is no need to change URI during redirection it is possible to redirect
304 error processing into a named location:
305 <blockquote><pre>
306 location / {
307 error_page 404 = @fallback;
308 }
309
310 location @fallback {
311 proxy_pass http://backend;
312 }
313 </pre></blockquote></p><hr><a name="if_modified_since"></a><strong>syntax</strong>:
314 <code>if_modified_since
315 <code>off</code> |
316 <code>exact</code> |
317 <code>before</code></code><br><strong>default</strong>:
318 <code>if_modified_since exact</code><br><strong>context</strong>:
319 <code>http</code>, <code>server</code>, <code>location</code><br><strong>appeared in version</strong>:
320 0.7.24<p>
321 Specifies how to compare modification time of a response
322 with the time in the
323 <code>If-Modified-Since</code>
324 request header:
325
326 <ul><li><code>off</code> - the
327 <code>If-Modified-Since</code> request header is ignored (0.7.34);
328 </li><li><code>exact</code> - exact match;
329 </li><li><code>before</code> - modification time of a response is
330 less than or equal to the time in the <code>If-Modified-Since</code>
331 request header.
332 </li></ul></p><hr><a name="internal"></a><strong>syntax</strong>:
333 <code>internal</code><br><strong>default</strong>:
334 <strong>none</strong><br><strong>context</strong>:
335 <code>location</code><br><p>
336 Specifies that a given location can only be used for internal requests.
337 For external requests, the <i>"Not found"</i> (404)
338 error is returned.
339 Internal requests are the following:
340
341 <ul><li>
342 requests redirected by the <a href="#error_page">error_page</a> directive;
343 </li><li>
344 subrequests formed by the
345 <code>include virtual</code>
346 command of the
347 <u>http_ssi</u> module;
348 </li><li>
349 requests changed by the
350 <u>rewrite</u>
351 directive of the
352 <u>http_rewrite</u> module.
353 </li></ul></p><p>
354 Example usage:
355 <blockquote><pre>
356 error_page 404 /404.html;
357
358 location /404.html {
359 internal;
360 }
361 </pre></blockquote></p><hr><a name="keepalive_requests"></a><strong>syntax</strong>:
362 <code>keepalive_requests <code><i>number</i></code></code><br><strong>default</strong>:
363 <code>keepalive_requests 100</code><br><strong>context</strong>:
364 <code>http</code>, <code>server</code>, <code>location</code><br><strong>appeared in version</strong>:
365 0.8.0<p>
366 Sets the maximum number of requests that can be
367 made through one keep-alive connection.
368 </p><hr><a name="keepalive_timeout"></a><strong>syntax</strong>:
369 <code>keepalive_timeout
370 <code><i>time</i></code>
371 [<code><i>time</i></code>]
372 </code><br><strong>default</strong>:
373 <code>keepalive_timeout 75</code><br><strong>context</strong>:
374 <code>http</code>, <code>server</code>, <code>location</code><br><p>
375 The first argument sets a timeout during which a keep-alive
376 client connection will stay open on the server side.
377 The optional second argument sets a value in the
378 "<code>Keep-Alive: timeout=</code><code><i>time</i></code>"
379 response header.
380 Two arguments may differ.
381 </p><p>
382 The
383 "<code>Keep-Alive: timeout=</code>"
384 is understood by Mozilla and Konqueror.
385 MSIE will close keep-alive connection in about 60 seconds.
386 </p><hr><a name="large_client_header_buffers"></a><strong>syntax</strong>:
387 <code>large_client_header_buffers <code><i>number size</i></code></code><br><strong>default</strong>:
388 <code>large_client_header_buffers 4 4k/8k</code><br><strong>context</strong>:
389 <code>http</code>, <code>server</code><br><p>
390 Sets the maximum <code><i>number</i></code> and <code><i>size</i></code> of
391 buffers used when reading large client request headers.
392 A request line cannot exceed the size of one buffer, or the
393 <i>"Request URI too large"</i> (414)
394 error is returned.
395 A request header line cannot exceed the size of one buffer as well, or the
396 <i>"Bad request"</i> (400)
397 error is returned.
398 Buffers are allocated only on demand.
399 By default, the buffer size is equal to one memory page size.
400 It is either 4K or 8K, platform dependent.
401 If after the end of request processing a connection is transitioned
402 into the keep-alive state, these buffers are freed.
403 </p><hr><a name="limit_except"></a><strong>syntax</strong>:
404 <code>limit_except <code><i>method</i></code> ... { ... }</code><br><strong>default</strong>:
405 <strong>none</strong><br><strong>context</strong>:
406 <code>location</code><br><p>
407 Limits allowed HTTP methods inside a location.
408 The GET method also implies the HEAD method.
409 Access to other methods can be limited using the
410 <u>http_access</u>
411 and
412 <u>http_auth_basic</u>
413 modules directives:
414 <blockquote><pre>
415 limit_except GET {
416 allow 192.168.1.0/32;
417 deny all;
418 }
419 </pre></blockquote>
420 Please note that this will limit access to all methods
421 <strong>except</strong> GET and HEAD.
422 </p><hr><a name="limit_rate"></a><strong>syntax</strong>:
423 <code>limit_rate <code><i>rate</i></code></code><br><strong>default</strong>:
424 <strong>none</strong><br><strong>context</strong>:
425 <code>http</code>, <code>server</code>, <code>location</code>, <code>if in location</code><br><p>
426 Rate limits the transmission of a response to a client.
427 The <code><i>rate</i></code> is specified in bytes per second.
428
429 The limit is per connection, so if a single client opens 2 connections,
430 an overall rate will be 2x more than specified.
431 </p><p>
432 This directive is not applicable if one wants to rate limit
433 a group of clients on the
434 <a href="#server">server</a>
435 level.
436 If that is the case, the desired limit can be specified in the
437 <code>$limit_rate</code>
438 variable:
439 <blockquote><pre>
440 server {
441
442 if ($slow) {
443 set $limit_rate 4k;
444 }
445
446 ...
447 }
448 </pre></blockquote></p><hr><a name="limit_rate_after"></a><strong>syntax</strong>:
449 <code>limit_rate_after <code><i>size</i></code></code><br><strong>default</strong>:
450 <strong>none</strong><br><strong>context</strong>:
451 <code>http</code>, <code>server</code>, <code>location</code>, <code>if in location</code><br><strong>appeared in version</strong>:
452 0.8.0<p>
453 Sets the initial amount after which the further transmission
454 of a response to a client will be rate limited.
455 </p><p>
456 Example:
457 <blockquote><pre>
458 location /flv/ {
459 flv;
460 limit_rate_after 500k;
461 limit_rate 50k;
462 }
463 </pre></blockquote></p><hr><a name="listen"></a><strong>syntax</strong>:
464 <code>listen
465 <code><i>address</i></code>[:<code><i>port</i></code>]
466 [<code>default</code> | <code>default_server</code>
467 [<code>backlog</code>=<code><i>number</i></code>]
468 [<code>rcvbuf</code>=<code><i>size</i></code>]
469 [<code>sndbuf</code>=<code><i>size</i></code>]
470 [<code>accept_filter</code>=<code><i>filter</i></code>]
471 [<code>deferred</code>]
472 [<code>bind</code>]
473 [<code>ipv6only</code>=<code>on</code>|<code>off</code>]
474 [<code>ssl</code>]]
475 </code><br><code>       </code><code>listen
476 <code><i>port</i></code>
477 [<code>default</code> | <code>default_server</code>
478 [<code>backlog</code>=<code><i>number</i></code>]
479 [<code>rcvbuf</code>=<code><i>size</i></code>]
480 [<code>sndbuf</code>=<code><i>size</i></code>]
481 [<code>accept_filter</code>=<code><i>filter</i></code>]
482 [<code>deferred</code>]
483 [<code>bind</code>]
484 [<code>ipv6only</code>=<code>on</code>|<code>off</code>]
485 [<code>ssl</code>]]
486 </code><br><strong>default</strong>:
487 <code>listen *:80 | *:8000</code><br><strong>context</strong>:
488 <code>server</code><br><p>
489 Sets an <code><i>address</i></code> and a <code><i>port</i></code>, on which
490 the server will accept requests.
491 Only one of <code><i>address</i></code> or <code><i>port</i></code> can be
492 specified.
493 An <code><i>address</i></code> may also be a hostname, for example:
494 <blockquote><pre>
495 listen 127.0.0.1:8000;
496 listen 127.0.0.1;
497 listen 8000;
498 listen *:8000;
499 listen localhost:8000;
500 </pre></blockquote>
501 IPv6 addresses (0.7.36) are specified in square brackets:
502 <blockquote><pre>
503 listen [::]:8000;
504 listen [fe80::1];
505 </pre></blockquote></p><p>
506 If only <code><i>address</i></code> is given, the port 80 is used.
507 </p><p>
508 If directive is not present then either the <code>*:80</code> is used
509 if nginx runs with superuser privileges, or <code>*:8000</code> otherwise.
510 </p><p>
511 The <code>default</code> parameter, if present,
512 will cause the server to become the default server for the specified
513 <code><i>address</i></code>:<code><i>port</i></code> pair.
514 If none of the directives have the <code>default</code>
515 parameter then the first server with the
516 <code><i>address</i></code>:<code><i>port</i></code> pair will be
517 the default server for this pair.
518 Starting from version 0.8.21 it is possible to use the
519 <code>default_server</code>
520 parameter.
521 </p><p>
522 A <code>listen</code> directive which has the <code>default</code>
523 parameter can have several additional parameters specific to system calls
524 <code>listen()</code> and <code>bind()</code>.
525 Starting from version 0.8.21, these parameters can be specified in any
526 <code>listen</code> directive, but only once for the given
527 <code><i>address</i></code>:<code><i>port</i></code> pair.
528 <ul><li><code>backlog</code>=<code><i>number</i></code> -
529 sets the <code>backlog</code> parameter in the
530 <code>listen()</code> call.
531 By default, <code>backlog</code> equals -1 on FreeBSD
532 and 511 on other platforms.
533 </li><li><code>rcvbuf</code>=<code><i>size</i></code> -
534 sets the <code>SO_RCVBUF</code> parameter for the listening socket.
535 </li><li><code>sndbuf</code>=<code><i>size</i></code> -
536 sets the <code>SO_SNDBUF</code> parameter for the listening socket.
537 </li><li><code>accept_filter</code>=<code><i>filter</i></code> -
538 sets the name of the accept filter.
539 This works only on FreeBSD, acceptable values are <code>dataready</code>
540 and <code>httpready</code>.
541 On receiving <code>SIGHUP</code> signal, an accept filter can only be
542 changed in recent versions of FreeBSD, starting from 6.0, 5.4-STABLE
543 and 4.11-STABLE.
544 </li><li><code>deferred</code> -
545 instructs to use a deferred <code>accept()</code> on Linux
546 using the <code>TCP_DEFER_ACCEPT</code> option.
547 </li><li><code>bind</code> -
548 specifies to make a separate <code>bind()</code> call for a given
549 <code><i>address</i></code>:<code><i>port</i></code> pair.
550 This is because nginx will only <code>bind()</code> to
551 <code>*</code>:<code><i>port</i></code>
552 if there are several <code>listen</code> directives with
553 the same port and different addresses, and one of the
554 <code>listen</code> directives listens on all addresses
555 for the given port (<code>*</code>:<code><i>port</i></code>).
556 It should be noted that in this case a <code>getsockname()</code>
557 system call will be made to determine an address that accepted a
558 connection.
559 If parameters <code>backlog</code>, <code>rcvbuf</code>,
560 <code>sndbuf</code>, <code>accept_filter</code>, or
561 <code>deferred</code> are used then for a given
562 <code><i>address</i></code>:<code><i>port</i></code> pair
563 a separate <code>bind()</code> call will always be made.
564 </li><li><code>ipv6only</code>=<code>on</code>|<code>off</code> -
565 this parameter (0.7.42) sets the value of the <code>IPV6_V6ONLY</code>
566 parameter for the listening socket.
567 This parameter can only be set once on start.
568 </li><li><code>ssl</code> -
569 this parameter (0.7.14) does not relate to system calls
570 <code>listen()</code> and <code>bind()</code>, but allows to
571 specify that all connections accepted on this port should work in
572 the SSL mode.
573 This allows for a more compact configuration for the server operating
574 in both HTTP and HTTPS modes simultaneously.
575 <blockquote><pre>
576 listen 80;
577 listen 443 default ssl;
578 </pre></blockquote></li></ul></p><p>
579 Example:
580 <blockquote><pre>
581 listen 127.0.0.1 default accept_filter=dataready backlog=1024;
582 </pre></blockquote></p><hr><a name="location"></a><strong>syntax</strong>:
583 <code>location [
584 <code>=</code> |
585 <code>~</code> |
586 <code>~*</code> |
587 <code>^~</code> |
588 <code>@</code>
589 ] <code><i>uri</i></code>
590 { ... }</code><br><strong>default</strong>:
591 <strong>none</strong><br><strong>context</strong>:
592 <code>server</code><br><p>
593 Sets a configuration based on a request URI.
594 A location can either be defined by a prefix string, or by a regular expression.
595 Regular expressions are specified by prepending them with the
596 "<code>~*</code>" prefix (for case-insensitive matching), or with the
597 "<code>~</code>" prefix (for case-sensitive matching).
598 To find a location matching a given request, nginx first checks
599 locations defined using the prefix strings (prefix locations).
600 Amongst them, the most specific one is searched.
601 Then regular expressions are checked, in the order of their appearance
602 in a configuration file.
603 A search terminates on the first match, and its corresponding
604 configuration is used.
605 If no match with a regular expression location is found then a
606 configuration of the most specific prefix location is used.
607 </p><p>
608 For case-insensitive operating systems such as Mac OS X and Cygwin,
609 the string matching ignores a case (0.7.7).
610 However, comparison is limited to one-byte locales.
611 </p><p>
612 Regular expressions can contain captures (0.7.40) that can later
613 be used in other directives.
614 </p><p>
615 If the most specific prefix location has the "<code>^~</code>" prefix
616 then regular expressions are not checked.
617 </p><p>
618 Also, using the "<code>=</code>" prefix it's possible to define
619 an exact match of URI and location.
620 If an exact match is found, the search terminates.
621 For example, if a "<code>/</code>" request happens frequently,
622 defining "<code>location = /</code>" will speed up the processing
623 of these requests, as search terminates right after the first
624 comparison.
625 </p><p>
626 In versions from 0.7.1 to 0.8.41, if a request matched the prefix
627 location without the "<code>=</code>" and "<code>^~</code>"
628 prefixes, the search also terminated and regular expressions were
629 not checked.
630 </p><p>
631 Let's illustrate the above by an example:
632 <blockquote><pre>
633 location = / {
634 [ configuration A ]
635 }
636
637 location / {
638 [ configuration B ]
639 }
640
641 location ^~ /images/ {
642 [ configuration C ]
643 }
644
645 location ~* \.(gif|jpg|jpeg)$ {
646 [ configuration D ]
647 }
648 </pre></blockquote>
649 The "<code>/</code>" request will match configuration A,
650 the "<code>/documents/document.html</code>" request - configuration B,
651 the "<code>/images/1.gif</code>" request - configuration C, and
652 the "<code>/documents/1.jpg</code>" request - configuration D.
653 </p><p>
654 The "<code>@</code>" prefix defines a named location.
655 Such a location isn't used for a regular request processing, but instead
656 used for request redirection.
657 </p><hr><a name="log_not_found"></a><strong>syntax</strong>:
658 <code>log_not_found <code>on</code> | <code>off</code></code><br><strong>default</strong>:
659 <code>log_not_found on</code><br><strong>context</strong>:
660 <code>http</code>, <code>server</code>, <code>location</code><br><p>
661 Enables or disables logging of errors about not found files into the
662 <u>error_log</u>.
663 </p><hr><a name="log_subrequest"></a><strong>syntax</strong>:
664 <code>log_subrequest <code>on</code> | <code>off</code></code><br><strong>default</strong>:
665 <code>log_subrequest off</code><br><strong>context</strong>:
666 <code>http</code>, <code>server</code>, <code>location</code><br><p>
667 Enables or disables logging of subrequests into the
668 <u>access_log</u>.
669 </p><hr><a name="merge_slashes"></a><strong>syntax</strong>:
670 <code>merge_slashes <code>on</code> | <code>off</code></code><br><strong>default</strong>:
671 <code>merge_slashes on</code><br><strong>context</strong>:
672 <code>http</code>, <code>server</code><br><p>
673 Enables or disables compression of two or more adjacent slashes
674 in a URI into a single slash.
675 </p><p>
676 Note that compression is essential for the correct prefix string
677 and regular expressions location matching.
678 Without it, the "<code>//scripts/one.php</code>" request would not match
679 <blockquote><pre>
680 location /scripts/ {
681 ...
682 }
683 </pre></blockquote>
684 and might be processed as a static file,
685 so it gets converted to "<code>/scripts/one.php</code>".
686 </p><p>
687 Turning the compression <code>off</code> can become necessary if a URI
688 contains base64-encoded names, since base64 uses the "/" character internally.
689 However, for security considerations, it's better to avoid turning off
690 the compression.
691 </p><p>
692 If a directive is specified on the
693 <a href="#server">server</a>
694 level, which is also a default server, its value will cover
695 all virtual servers listening on the same address and port.
696 </p><hr><a name="msie_padding"></a><strong>syntax</strong>:
697 <code>msie_padding <code>on</code> | <code>off</code></code><br><strong>default</strong>:
698 <code>msie_padding on</code><br><strong>context</strong>:
699 <code>http</code>, <code>server</code>, <code>location</code><br><p>
700 Enables or disables adding of comments to responses with status
701 greater than 400 for MSIE clients, to pad the response size to 512 bytes.
702 </p><hr><a name="msie_refresh"></a><strong>syntax</strong>:
703 <code>msie_refresh <code>on</code> | <code>off</code></code><br><strong>default</strong>:
704 <code>msie_refresh off</code><br><strong>context</strong>:
705 <code>http</code>, <code>server</code>, <code>location</code><br><p>
706 Enables or disables issuing refreshes instead of redirects, for MSIE clients.
707 </p><hr><a name="open_file_cache"></a><strong>syntax</strong>:
708 <code>open_file_cache
709 <code>max</code>=<code><i>N</i></code>
710 [<code>inactive</code>=<code><i>time</i></code>] |
711 <code>off</code></code><br><strong>default</strong>:
712 <code>open_file_cache off</code><br><strong>context</strong>:
713 <code>http</code>, <code>server</code>, <code>location</code><br><p>
714 Configures a cache that can store:
715 <ul><li>
716 open file descriptors, their sizes and modification times;
717 </li><li>
718 directory lookups;
719 </li><li>
720 file lookup errors, such as "file not found", "no read permission",
721 and so on.
722 Caching of errors should be enabled separately by the
723 <a href="#open_file_cache_errors">open_file_cache_errors</a>
724 directive.
725 </li></ul></p><p>
726 The directive has the following parameters:
727 <ul><li><code>max</code> -
728 sets the maximum number of elements in the cache;
729 on cache overflow the least recently used (LRU) elements get removed;
730 </li><li><code>inactive</code> -
731 defines a time, after which the element gets removed from the cache
732 if there were no accesses to it during this time;
733 by default, it is 60 seconds;
734 </li><li><code>off</code> - disables the cache.
735 </li></ul></p><p>
736 Example:
737 <blockquote><pre>
738 open_file_cache max=1000 inactive=20s;
739 open_file_cache_valid 30s;
740 open_file_cache_min_uses 2;
741 open_file_cache_errors on;</pre></blockquote></p><hr><a name="open_file_cache_errors"></a><strong>syntax</strong>:
742 <code>open_file_cache_errors <code>on</code> | <code>off</code></code><br><strong>default</strong>:
743 <code>open_file_cache_errors off</code><br><strong>context</strong>:
744 <code>http</code>, <code>server</code>, <code>location</code><br><p>
745 Enables or disables caching of file lookup errors by the
746 <a href="#open_file_cache">open_file_cache</a>.
747 </p><hr><a name="open_file_cache_min_uses"></a><strong>syntax</strong>:
748 <code>open_file_cache_min_uses <code><i>number</i></code></code><br><strong>default</strong>:
749 <code>open_file_cache_min_uses 1</code><br><strong>context</strong>:
750 <code>http</code>, <code>server</code>, <code>location</code><br><p>
751 Sets the minimum <code><i>number</i></code> of file accesses during
752 the period configured by the <code>inactive</code> parameter
753 of the <a href="#open_file_cache">open_file_cache</a> directive,
754 after which a file descriptor will remain open in the cache.
755 </p><hr><a name="open_file_cache_valid"></a><strong>syntax</strong>:
756 <code>open_file_cache_valid <code><i>time</i></code></code><br><strong>default</strong>:
757 <code>open_file_cache_valid 60</code><br><strong>context</strong>:
758 <code>http</code>, <code>server</code>, <code>location</code><br><p>
759 Sets a time after which
760 <a href="#open_file_cache">open_file_cache</a>
761 elements should be validated.
762 </p><hr><a name="optimize_server_names"></a><strong>syntax</strong>:
763 <code>optimize_server_names <code>on</code> | <code>off</code></code><br><strong>default</strong>:
764 <code>optimize_server_names on</code><br><strong>context</strong>:
765 <code>http</code>, <code>server</code><br><p>
766 This directive is obsolete.
767 </p><p>
768 Enables or disables optimization of hostname checking in name-based
769 virtual servers.
770 In particular, the checking affects hostnames used in redirects.
771 If optimization is enabled, and all name-based servers listening on
772 the same address:port pair have identical configuration, then
773 names are not checked during request processing, and the first
774 server name is used in redirects.
775 In case redirects should use hostnames sent by clients,
776 optimization needs to be disabled.
777 </p><hr><a name="port_in_redirect"></a><strong>syntax</strong>:
778 <code>port_in_redirect <code>on</code> | <code>off</code></code><br><strong>default</strong>:
779 <code>port_in_redirect on</code><br><strong>context</strong>:
780 <code>http</code>, <code>server</code>, <code>location</code><br><p>
781 Enables or disables specifying the port in redirects issued by nginx.
782 </p><hr><a name="read_ahead"></a><strong>syntax</strong>:
783 <code>read_ahead <code><i>size</i></code></code><br><strong>default</strong>:
784 <code>read_ahead 0</code><br><strong>context</strong>:
785 <code>http</code>, <code>server</code>, <code>location</code><br><p>
786 Sets the amount of pre-reading when working with files, in the kernel.
787 </p><p>
788 On Linux, the
789 <code>posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)</code>
790 system call is used, so the <code><i>size</i></code> argument is ignored.
791 </p><p>
792 On FreeBSD, the
793 <code>fcntl(O_READAHEAD,</code><code><i>size</i></code><code>)</code>
794 system call is used, supported in FreeBSD 9.0-CURRENT.
795 FreeBSD 7 needs to be
796 <u>patched</u>.
797 </p><hr><a name="recursive_error_pages"></a><strong>syntax</strong>:
798 <code>recursive_error_pages <code>on</code> | <code>off</code></code><br><strong>default</strong>:
799 <code>recursive_error_pages off</code><br><strong>context</strong>:
800 <code>http</code>, <code>server</code>, <code>location</code><br><p>
801 Enables or disables doing several redirects using the
802 <a href="#error_page">error_page</a>
803 directive.
804 </p><hr><a name="reset_timedout_connection"></a><strong>syntax</strong>:
805 <code>reset_timedout_connection <code>on</code> | <code>off</code></code><br><strong>default</strong>:
806 <code>reset_timedout_connection off</code><br><strong>context</strong>:
807 <code>http</code>, <code>server</code>, <code>location</code><br><p>
808 Enables or disables resetting of timed out connections.
809 The reset is performed as follows: before closing a socket, the
810 <code>SO_LINGER</code>
811 option is set on it with a timeout value of 0.
812 When the socket is closed, a client is sent TCP RST, and all memory
813 occupied by this socket is freed.
814 This avoids keeping of an already closed socket with filled buffers
815 for a long time, in a FIN_WAIT1 state.
816 </p><p>
817 It should be noted that timed out keep-alive connections are still
818 closed normally.
819 </p><hr><a name="resolver"></a><strong>syntax</strong>:
820 <code>resolver <code><i>address</i></code></code><br><strong>default</strong>:
821 <strong>none</strong><br><strong>context</strong>:
822 <code>http</code>, <code>server</code>, <code>location</code><br><p>
823 Sets the <code><i>address</i></code> of a name server, for example:
824 <blockquote><pre>
825 resolver 127.0.0.1;
826 </pre></blockquote></p><hr><a name="resolver_timeout"></a><strong>syntax</strong>:
827 <code>resolver_timeout <code><i>time</i></code></code><br><strong>default</strong>:
828 <code>resolver_timeout 30s</code><br><strong>context</strong>:
829 <code>http</code>, <code>server</code>, <code>location</code><br><p>
830 Sets a timeout for name resolution, for example:
831 <blockquote><pre>
832 resolver_timeout 5s;
833 </pre></blockquote></p><hr><a name="root"></a><strong>syntax</strong>:
834 <code>root <code><i>path</i></code></code><br><strong>default</strong>:
835 <code>root html</code><br><strong>context</strong>:
836 <code>http</code>, <code>server</code>, <code>location</code>, <code>if in location</code><br><p>
837 Sets the root directory for requests.
838 For example, with the following configuration
839 <blockquote><pre>
840 location /i/ {
841 root /data/w3;
842 }
843 </pre></blockquote>
844 the request of "/i/top.gif" will be responded
845 with the file "/data/w3/images/top.gif".
846 </p><p>
847 The <code><i>path</i></code> value can contain variables.
848 </p><p>
849 A path to the file is constructed by merely adding a URI to the value
850 of the <code>root</code> directive.
851 If a URI need to be modified, the
852 <a href="#alias">alias</a> directive should be used.
853 </p><hr><a name="satisfy"></a><strong>syntax</strong>:
854 <code>satisfy <code>all</code> | <code>any</code></code><br><strong>default</strong>:
855 <code>satisfy all</code><br><strong>context</strong>:
856 <code>location</code><br><p>
857 Allows access if any of the
858 <u>http_access</u>
859 or <u>http_auth_basic</u>
860 modules grant access.
861 <blockquote><pre>
862 location / {
863 satisfy any;
864
865 allow 192.168.1.0/32;
866 deny all;
867
868 auth_basic "closed site";
869 auth_basic_user_file conf/htpasswd;
870 }
871 </pre></blockquote></p><hr><a name="satisfy_any"></a><strong>syntax</strong>:
872 <code>satisfy_any <code>on</code> | <code>off</code></code><br><strong>default</strong>:
873 <code>satisfy_any off</code><br><strong>context</strong>:
874 <code>location</code><br><p>
875 This directive was renamed to the <a href="#satisfy">satisfy</a> directive.
876 </p><hr><a name="send_timeout"></a><strong>syntax</strong>:
877 <code>send_timeout <code><i>time</i></code></code><br><strong>default</strong>:
878 <code>send_timeout 60</code><br><strong>context</strong>:
879 <code>http</code>, <code>server</code>, <code>location</code><br><p>
880 Sets a timeout for transmitting a response to the client.
881 A timeout is only set between two successive write operations,
882 not for the transmission of the whole response.
883 If a client does not receive anything within this time,
884 a connection is closed.
885 </p><hr><a name="sendfile"></a><strong>syntax</strong>:
886 <code>sendfile <code>on</code> | <code>off</code></code><br><strong>default</strong>:
887 <code>sendfile off</code><br><strong>context</strong>:
888 <code>http</code>, <code>server</code>, <code>location</code><br><p>
889 Enables or disables the use of
890 <code>sendfile()</code>.
891 </p><hr><a name="server"></a><strong>syntax</strong>:
892 <code>server { ... }</code><br><strong>default</strong>:
893 <strong>none</strong><br><strong>context</strong>:
894 <code>http</code><br><p>
895 Sets a configuration for the virtual server.
896 There is no clean separation between IP-based (based on the IP address)
897 and name-based (based on the <code>Host</code> header string)
898 virtual servers.
899 Instead, the <a href="#listen">listen</a> directives describe all
900 addresses and ports that should accept connections for a server, and the
901 <a href="#server_name">server_name</a> directive lists all server names.
902 An example configuration is provided in the
903 <u>
904 Setting Up Virtual Servers</u> document.
905 </p><hr><a name="server_name"></a><strong>syntax</strong>:
906 <code>server_name <code><i>name ...</i></code></code><br><strong>default</strong>:
907 <code>server_name hostname</code><br><strong>context</strong>:
908 <code>server</code><br><p>
909 Sets names of the virtual server, for example:
910 <blockquote><pre>
911 server {
912 server_name example.com www.example.com;
913 }
914 </pre></blockquote></p><p>
915 The first name becomes a primary server name.
916 By default, the machine's hostname is used.
917 Server names can include an asterisk ("<code>*</code>")
918 to replace the first or last part of a name:
919 <blockquote><pre>
920 server {
921 server_name example.com *.example.com www.example.*;
922 }
923 </pre></blockquote></p><p>
924 The first two of the above mentioned names can be combined:
925 <blockquote><pre>
926 server {
927 server_name .example.com;
928 }
929 </pre></blockquote></p><p>
930 It is also possible to use regular expressions in server names,
931 prepending the name with a tilde ("<code>~</code>"):
932 <blockquote><pre>
933 server {
934 server_name www.example.com ~^www\d+\.example\.com$;
935 }
936 </pre></blockquote></p><p>
937 Regular expressions can contain captures (0.7.40) that can later
938 be used in other directives:
939 <blockquote><pre>
940 server {
941 server_name ~^(www\.)?(.+)$;
942
943 location / {
944 root /sites/$2;
945 }
946 }
947
948 server {
949 server_name _;
950
951 location / {
952 root /sites/default;
953 }
954 }
955 </pre></blockquote></p><p>
956 Starting from version 0.8.25, named captures in regular expressions create
957 variables that can later be used in other directives:
958 <blockquote><pre>
959 server {
960 server_name ~^(www\.)?(?&lt;domain&gt;.+)$;
961
962 location / {
963 root /sites/$domain;
964 }
965 }
966
967 server {
968 server_name _;
969
970 location / {
971 root /sites/default;
972 }
973 }
974 </pre></blockquote></p><p>
975 Starting from version 0.7.11, it is possible to specify an empty name "":
976 <blockquote><pre>
977 server {
978 server_name www.example.com "";
979 }
980 </pre></blockquote>
981 It allows this server to process requests without the <code>Host</code>
982 header, instead of the default server for the given address:port pair.
983 </p><p>
984 The name checking order is as follows:
985 <ol><li>
986 full names
987 </li><li>
988 names with the prefix mask - *.example.com
989 </li><li>
990 names with the suffix mask - mail.*
991 </li><li>
992 regular expressions
993 </li></ol></p><hr><a name="server_name_in_redirect"></a><strong>syntax</strong>:
994 <code>server_name_in_redirect <code>on</code> | <code>off</code></code><br><strong>default</strong>:
995 <code>server_name_in_redirect on</code><br><strong>context</strong>:
996 <code>http</code>, <code>server</code>, <code>location</code><br><p>
997 Enables or disables the use of the primary server name, specified by the
998 <a href="#server_name">server_name</a>
999 directive, in redirects issued by nginx.
1000 When disabled, the name from the <code>Host</code> request header string
1001 is used.
1002 If there's no such a string, an IP address of the server is used.
1003 </p><hr><a name="server_names_hash_max_size"></a><strong>syntax</strong>:
1004 <code>server_names_hash_max_size <code><i>size</i></code></code><br><strong>default</strong>:
1005 <code>server_names_hash_max_size 512</code><br><strong>context</strong>:
1006 <code>http</code><br><p>
1007 Sets the maximum <code><i>size</i></code> of the server names hash tables.
1008 For more information, please refer to
1009 <u>Setting Up Hashes</u>.
1010 </p><hr><a name="server_names_hash_bucket_size"></a><strong>syntax</strong>:
1011 <code>server_names_hash_bucket_size <code><i>size</i></code></code><br><strong>default</strong>:
1012 <code>server_names_hash_bucket_size 32/64/128</code><br><strong>context</strong>:
1013 <code>http</code><br><p>
1014 Sets the bucket size for the server names hash tables.
1015 Default value depends on the size of the processor's cache line.
1016 For more information, please refer to
1017 <u>Setting Up Hashes</u>.
1018 </p><hr><a name="server_tokens"></a><strong>syntax</strong>:
1019 <code>server_tokens <code>on</code> | <code>off</code></code><br><strong>default</strong>:
1020 <code>server_tokens on</code><br><strong>context</strong>:
1021 <code>http</code>, <code>server</code>, <code>location</code><br><p>
1022 Enables or disables emitting of nginx version in error messages and in the
1023 <code>Server</code> response header string.
1024 </p><hr><a name="tcp_nodelay"></a><strong>syntax</strong>:
1025 <code>tcp_nodelay <code>on</code> | <code>off</code></code><br><strong>default</strong>:
1026 <code>tcp_nodelay on</code><br><strong>context</strong>:
1027 <code>http</code>, <code>server</code>, <code>location</code><br><p>
1028 Enables or disables the use of the <code>TCP_NODELAY</code> option.
1029 The option is enabled only when a connection is transitioned into the
1030 keep-alive state.
1031 </p><hr><a name="tcp_nopush"></a><strong>syntax</strong>:
1032 <code>tcp_nopush <code>on</code> | <code>off</code></code><br><strong>default</strong>:
1033 <code>tcp_nopush off</code><br><strong>context</strong>:
1034 <code>http</code>, <code>server</code>, <code>location</code><br><p>
1035 Enables or disables the use of
1036 the <code>TCP_NOPUSH</code> socket option on FreeBSD
1037 or the <code>TCP_CORK</code> socket option on Linux.
1038 Opitons are enables only when <a href="#sendfile">sendfile</a> is used.
1039 Enabling the option allows to
1040 <ul><li>
1041 send the response header and the beginning of a file in one packet,
1042 on Linux and FreeBSD 4.*;
1043 </li><li>
1044 send a file in full packets.
1045 </li></ul></p><hr><a name="try_files"></a><strong>syntax</strong>:
1046 <code>try_files <code><i>file ... uri</i></code></code><br><code>       </code><code>try_files <code><i>file ...</i></code> =<code><i>code</i></code></code><br><strong>default</strong>:
1047 <strong>none</strong><br><strong>context</strong>:
1048 <code>location</code><br><p>
1049 Checks the existence of files in the specified order, and uses
1050 the first found file for request processing; the processing
1051 is performed in this location's context.
1052 It is possible to check the directory existence by specifying
1053 the slash at the end of a name, e.g. "<code>$uri/</code>".
1054 If none of the files were found, an internal redirect to the
1055 <code><i>uri</i></code> specified by the last argument is made.
1056 As of version 0.7.51, the last argument can also be a
1057 <code><i>code</i></code>:
1058 <blockquote><pre>
1059 location / {
1060 try_files $uri $uri/index.html $uri.html =404;
1061 }
1062 </pre></blockquote></p><p>
1063 Example when proxying Mongrel:
1064 <blockquote><pre>
1065 location / {
1066 try_files /system/maintenance.html
1067 $uri $uri/index.html $uri.html
1068 @mongrel;
1069 }
1070
1071 location @mongrel {
1072 proxy_pass http://mongrel;
1073 }
1074 </pre></blockquote></p><p>
1075 Example for Drupal/FastCGI:
1076 <blockquote><pre>
1077 location / {
1078 try_files $uri $uri/ @drupal;
1079 }
1080
1081 location ~ \.php$ {
1082 try_files $uri @drupal;
1083
1084 fastcgi_pass ...;
1085
1086 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
1087 fastcgi_param SCRIPT_NAME $fastcgi_script_name;
1088 fastcgi_param QUERY_STRING $args;
1089
1090 ... other fastcgi_param's
1091 }
1092
1093 location @drupal {
1094 fastcgi_pass ...;
1095
1096 fastcgi_param SCRIPT_FILENAME /path/to/index.php;
1097 fastcgi_param SCRIPT_NAME /index.php;
1098 fastcgi_param QUERY_STRING q=$uri&amp;$args;
1099
1100 ... other fastcgi_param's
1101 }
1102 </pre></blockquote>
1103 In the following example,
1104 <blockquote><pre>
1105 location / {
1106 try_files $uri $uri/ @drupal;
1107 }
1108 </pre></blockquote>
1109 the <code>try_files</code> directive is equivalent to
1110 <blockquote><pre>
1111 location / {
1112 error_page 404 = @drupal;
1113 log_not_found off;
1114 }
1115 </pre></blockquote>
1116 And here,
1117 <blockquote><pre>
1118 location ~ \.php$ {
1119 try_files $uri @drupal;
1120
1121 fastcgi_pass ...;
1122
1123 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
1124
1125 ...
1126 }
1127 </pre></blockquote><code>try_files</code> checks the existence of the PHP file
1128 before passing the request to the FastCGI server.
1129 </p><p>
1130 Example for Wordpress and Joomla:
1131 <blockquote><pre>
1132 location / {
1133 try_files $uri $uri/ @wordpress;
1134 }
1135
1136 location ~ \.php$ {
1137 try_files $uri @wordpress;
1138
1139 fastcgi_pass ...;
1140
1141 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
1142 ... other fastcgi_param's
1143 }
1144
1145 location @wordpress {
1146 fastcgi_pass ...;
1147
1148 fastcgi_param SCRIPT_FILENAME /path/to/index.php;
1149 ... other fastcgi_param's
1150 }
1151 </pre></blockquote></p></body></html>