Mercurial > hg > nginx
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->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\.)?(?<domain>.+)$; | |
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&$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> |