Mercurial > hg > nginx-quic
comparison docs/html/http/ngx_http_core_module.html @ 4080:a1e1b348bfaf
Regenerate after previous commit.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Tue, 06 Sep 2011 13:43:04 +0000 |
parents | cf09c4826ab3 |
children | b7c944d1a5a8 |
comparison
equal
deleted
inserted
replaced
4079:9755cb2a39b2 | 4080:a1e1b348bfaf |
---|---|
7 <code>http</code>, <code>server</code>, <code>location</code><br><strong>appeared in version</strong>: | 7 <code>http</code>, <code>server</code>, <code>location</code><br><strong>appeared in version</strong>: |
8 0.8.11<p> | 8 0.8.11<p> |
9 Enables or disables the use of asynchronous file I/O (AIO) | 9 Enables or disables the use of asynchronous file I/O (AIO) |
10 on FreeBSD and Linux. | 10 on FreeBSD and Linux. |
11 </p><p> | 11 </p><p> |
12 On FreeBSD, AIO is usable used starting from FreeBSD 4.3. | 12 On FreeBSD, AIO is usable starting from FreeBSD 4.3. |
13 AIO can either be linked statically into a kernel: | 13 AIO can either be linked statically into a kernel: |
14 <blockquote><pre> | 14 <blockquote><pre> |
15 options VFS_AIO | 15 options VFS_AIO |
16 </pre></blockquote> | 16 </pre></blockquote> |
17 or loaded dynamically as a kernel loadable module: | 17 or loaded dynamically as a kernel loadable module: |
19 kldload aio | 19 kldload aio |
20 </pre></blockquote></p><p> | 20 </pre></blockquote></p><p> |
21 In FreeBSD versions 5 and 6, enabling AIO statically, or dynamically | 21 In FreeBSD versions 5 and 6, enabling AIO statically, or dynamically |
22 when booting the kernel, will cause the entire networking subsystem | 22 when booting the kernel, will cause the entire networking subsystem |
23 to use the Giant lock that can impact overall performance negatively. | 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 | 24 This limitation has been removed in FreeBSD 6.4-STABLE in 2009, and in |
25 FreeBSD 7. | 25 FreeBSD 7. |
26 However, starting from FreeBSD 5.3, it's possible to enable AIO | 26 However, starting from FreeBSD 5.3 it is possible to enable AIO |
27 without the penalty of running the networking subsystem under a | 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 | 28 Giant lock - for this to work, the AIO module needs to be loaded |
29 after the kernel has booted. | 29 after the kernel has booted. |
30 In this case, the following message will appear in | 30 In this case, the following message will appear in |
31 <code>/var/log/messages</code><blockquote><pre> | 31 <code>/var/log/messages</code><blockquote><pre> |
44 </p><p> | 44 </p><p> |
45 For AIO to work, | 45 For AIO to work, |
46 <a href="#sendfile">sendfile</a> | 46 <a href="#sendfile">sendfile</a> |
47 needs to be disabled: | 47 needs to be disabled: |
48 <blockquote><pre> | 48 <blockquote><pre> |
49 location /video/ { | 49 location /video/ { |
50 sendfile off; | 50 sendfile off; |
51 aio on; | 51 aio on; |
52 output_buffers 1 64k; | 52 output_buffers 1 64k; |
53 } | 53 } |
54 </pre></blockquote></p><p> | 54 </pre></blockquote></p><p> |
55 In addition, starting from FreeBSD 5.2.1 and nginx 0.8.12, AIO can | 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>: | 56 also be used to pre-load data for <code>sendfile()</code>: |
57 <blockquote><pre> | 57 <blockquote><pre> |
58 location /video/ { | 58 location /video/ { |
59 sendfile on; | 59 sendfile on; |
60 tcp_nopush on; | 60 tcp_nopush on; |
61 aio sendfile; | 61 aio sendfile; |
62 } | 62 } |
63 </pre></blockquote> | 63 </pre></blockquote> |
64 In this configuration, <code>sendfile()</code> is called with | 64 In this configuration, <code>sendfile()</code> is called with |
65 the <code>SF_NODISKIO</code> flag which causes it not to | 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 | 66 block on disk I/O and instead report back when the data are not in |
74 On Linux, AIO is usable starting from kernel version 2.6.22; | 74 On Linux, AIO is usable starting from kernel version 2.6.22; |
75 plus, it is also necessary to enable | 75 plus, it is also necessary to enable |
76 <a href="#directio">directio</a>, | 76 <a href="#directio">directio</a>, |
77 otherwise reading will be blocking: | 77 otherwise reading will be blocking: |
78 <blockquote><pre> | 78 <blockquote><pre> |
79 location /video/ { | 79 location /video/ { |
80 aio on; | 80 aio on; |
81 directio 512; | 81 directio 512; |
82 output_buffers 1 128k; | 82 output_buffers 1 128k; |
83 } | 83 } |
84 </pre></blockquote></p><p> | 84 </pre></blockquote></p><p> |
85 On Linux, | 85 On Linux, |
86 <a href="#directio">directio</a> | 86 <a href="#directio">directio</a> |
87 can only be used for reading blocks that are aligned on 512-byte | 87 can only be used for reading blocks that are aligned on 512-byte |
88 boundaries (or 4K for XFS). | 88 boundaries (or 4K for XFS). |
89 Reading of unaligned file's tail is still made in blocking mode. | 89 Reading of unaligned file's end is still made in blocking mode. |
90 The same holds true for byte range requests, and for FLV requests | 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 | 91 not from the beginning of a file: reading of unaligned data at the |
92 beginning and end of a file will be blocking. | 92 beginning and end of a file will be blocking. |
93 There is no need to turn off | 93 There is no need to turn off |
94 <a href="#sendfile">sendfile</a> | 94 <a href="#sendfile">sendfile</a> |
100 <strong>none</strong><br><strong>context</strong>: | 100 <strong>none</strong><br><strong>context</strong>: |
101 <code>location</code><br><p> | 101 <code>location</code><br><p> |
102 Defines a replacement for the specified location. | 102 Defines a replacement for the specified location. |
103 For example, with the following configuration | 103 For example, with the following configuration |
104 <blockquote><pre> | 104 <blockquote><pre> |
105 location /i/ { | 105 location /i/ { |
106 alias /data/w3/images/; | 106 alias /data/w3/images/; |
107 } | 107 } |
108 </pre></blockquote> | 108 </pre></blockquote> |
109 the request of "/i/top.gif" will be responded | 109 the request of |
110 with the file "/data/w3/images/top.gif". | 110 “<code>/i/top.gif</code>” will be responded |
111 with the file | |
112 “<code>/data/w3/images/top.gif</code>”. | |
111 </p><p> | 113 </p><p> |
112 The <code><i>path</i></code> value can contain variables. | 114 The <code><i>path</i></code> value can contain variables. |
113 </p><p> | 115 </p><p> |
114 If <code>alias</code> is used inside a location defined | 116 If <code>alias</code> is used inside a location defined |
115 with a regular expression then such regular expression should | 117 with a regular expression then such regular expression should |
116 contain captures and <code>alias</code> should refer to | 118 contain captures and <code>alias</code> should refer to |
117 these captures (0.7.40), for example: | 119 these captures (0.7.40), for example: |
118 <blockquote><pre> | 120 <blockquote><pre> |
119 location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ { | 121 location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ { |
120 alias /data/w3/images/$1; | 122 alias /data/w3/images/$1; |
121 } | 123 } |
122 </pre></blockquote></p><p> | 124 </pre></blockquote></p><p> |
123 When location matches the last part of the directive's value: | 125 When location matches the last part of the directive's value: |
124 <blockquote><pre> | 126 <blockquote><pre> |
125 location /images/ { | 127 location /images/ { |
126 alias /data/w3/images/; | 128 alias /data/w3/images/; |
127 } | 129 } |
128 </pre></blockquote> | 130 </pre></blockquote> |
129 it's better to use the | 131 it is better to use the |
130 <a href="#root">root</a> | 132 <a href="#root">root</a> |
131 directive instead: | 133 directive instead: |
132 <blockquote><pre> | 134 <blockquote><pre> |
133 location /images/ { | 135 location /images/ { |
134 root /data/w3; | 136 root /data/w3; |
135 } | 137 } |
136 </pre></blockquote></p><hr><a name="client_body_in_file_only"></a><strong>syntax</strong>: | 138 </pre></blockquote></p><hr><a name="client_body_in_file_only"></a><strong>syntax</strong>: |
137 <code>client_body_in_file_only | 139 <code>client_body_in_file_only |
138 <code>on</code> | | 140 <code>on</code> | |
139 <code>clean</code> | | 141 <code>clean</code> | |
186 Defines a directory for storing temporary files holding client request bodies. | 188 Defines a directory for storing temporary files holding client request bodies. |
187 Up to three-level subdirectory hierarchy can be used underneath the specified | 189 Up to three-level subdirectory hierarchy can be used underneath the specified |
188 directory. | 190 directory. |
189 For example, in the following configuration | 191 For example, in the following configuration |
190 <blockquote><pre> | 192 <blockquote><pre> |
191 client_body_temp_path /spool/nginx/client_temp 1 2; | 193 client_body_temp_path /spool/nginx/client_temp 1 2; |
192 </pre></blockquote> | 194 </pre></blockquote> |
193 a temporary file might look like this: | 195 a temporary file might look like this: |
194 <blockquote><pre> | 196 <blockquote><pre> |
195 /spool/nginx/client_temp/7/45/00000123457 | 197 /spool/nginx/client_temp/7/45/00000123457 |
196 </pre></blockquote></p><hr><a name="client_body_timeout"></a><strong>syntax</strong>: | 198 </pre></blockquote></p><hr><a name="client_body_timeout"></a><strong>syntax</strong>: |
210 <code>http</code>, <code>server</code><br><p> | 212 <code>http</code>, <code>server</code><br><p> |
211 Sets buffer size for reading client request header. | 213 Sets buffer size for reading client request header. |
212 For most requests, a buffer of 1K bytes is enough. | 214 For most requests, a buffer of 1K bytes is enough. |
213 However, if a request includes long cookies, or comes from a WAP client, | 215 However, if a request includes long cookies, or comes from a WAP client, |
214 it may not fit into 1K. | 216 it may not fit into 1K. |
215 If a request line, or a request header line do not fit entirely into | 217 If a request line, or a request header field do not fit entirely into |
216 this buffer then larger buffers are allocated, configured by the | 218 this buffer then larger buffers are allocated, configured by the |
217 <a href="#large_client_header_buffers">large_client_header_buffers</a> | 219 <a href="#large_client_header_buffers">large_client_header_buffers</a> |
218 directive. | 220 directive. |
219 </p><hr><a name="client_header_timeout"></a><strong>syntax</strong>: | 221 </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>: | 222 <code>client_header_timeout <code><i>time</i></code></code><br><strong>default</strong>: |
230 <code>client_max_body_size 1m</code><br><strong>context</strong>: | 232 <code>client_max_body_size 1m</code><br><strong>context</strong>: |
231 <code>http</code>, <code>server</code>, <code>location</code><br><p> | 233 <code>http</code>, <code>server</code>, <code>location</code><br><p> |
232 Sets the maximum allowed size of the client request body, | 234 Sets the maximum allowed size of the client request body, |
233 specified in the | 235 specified in the |
234 <code>Content-Length</code> | 236 <code>Content-Length</code> |
235 request header line. | 237 request header field. |
236 If <code><i>size</i></code> is greater than the configured value, the | 238 If <code><i>size</i></code> is greater than the configured value, the |
237 <i>"Request Entity Too Large"</i> (413) | 239 <i>"Request Entity Too Large"</i> (413) |
238 error is returned to a client. | 240 error is returned to a client. |
239 Please be aware that | 241 Please be aware that |
240 <u>browsers cannot correctly display | 242 <u>browsers cannot correctly display |
257 It automatically disables (0.7.15) the use of | 259 It automatically disables (0.7.15) the use of |
258 <a href="#sendfile">sendfile</a> | 260 <a href="#sendfile">sendfile</a> |
259 for a given request. | 261 for a given request. |
260 It could be useful for serving large files: | 262 It could be useful for serving large files: |
261 <blockquote><pre> | 263 <blockquote><pre> |
262 directio 4m; | 264 directio 4m; |
263 </pre></blockquote> | 265 </pre></blockquote> |
264 or when using <a href="#aio">aio</a> on Linux. | 266 or when using <a href="#aio">aio</a> on Linux. |
265 </p><hr><a name="directio_alignment"></a><strong>syntax</strong>: | 267 </p><hr><a name="directio_alignment"></a><strong>syntax</strong>: |
266 <code>directio_alignment <code><i>size</i></code></code><br><strong>default</strong>: | 268 <code>directio_alignment <code><i>size</i></code></code><br><strong>default</strong>: |
267 <code>directio_alignment 512</code><br><strong>context</strong>: | 269 <code>directio_alignment 512</code><br><strong>context</strong>: |
271 <a href="#directio">directio</a>. | 273 <a href="#directio">directio</a>. |
272 In most cases, a 512-byte alignment is enough, however, when | 274 In most cases, a 512-byte alignment is enough, however, when |
273 using XFS under Linux, it needs to be increased to 4K. | 275 using XFS under Linux, it needs to be increased to 4K. |
274 </p><hr><a name="error_page"></a><strong>syntax</strong>: | 276 </p><hr><a name="error_page"></a><strong>syntax</strong>: |
275 <code>error_page | 277 <code>error_page |
276 <code><i>code ...</i></code> | 278 <code><i>code</i></code> ... |
277 [<code>=</code>[<code><i>response</i></code>]] | 279 [<code>=</code>[<code><i>response</i></code>]] |
278 <code><i>uri</i></code></code><br><strong>default</strong>: | 280 <code><i>uri</i></code></code><br><strong>default</strong>: |
279 <strong>none</strong><br><strong>context</strong>: | 281 <strong>none</strong><br><strong>context</strong>: |
280 <code>http</code>, <code>server</code>, <code>location</code>, <code>if in location</code><br><p> | 282 <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. | 283 Defines the URI that will be shown for the specified errors. |
282 These directives are inherited from the previous level if and | 284 These directives are inherited from the previous level if and |
283 only if there are no <code>error_page</code> directives on | 285 only if there are no |
286 <u>error_page</u> | |
287 directives on | |
284 the current level. | 288 the current level. |
285 A URI value can contain variables. | 289 A URI value can contain variables. |
286 </p><p> | 290 </p><p> |
287 Example usage: | 291 Example: |
288 <blockquote><pre> | 292 <blockquote><pre> |
289 error_page 404 /404.html; | 293 error_page 404 /404.html; |
290 error_page 502 503 504 /50x.html; | 294 error_page 502 503 504 /50x.html; |
291 error_page 403 http://example.com/forbidden.html; | 295 error_page 403 http://example.com/forbidden.html; |
292 </pre></blockquote></p><p> | 296 </pre></blockquote></p><p> |
293 Furthermore, it is possible to change the response code to another, for example: | 297 Furthermore, it is possible to change the response code to another, for example: |
294 <blockquote><pre> | 298 <blockquote><pre> |
295 error_page 404 =200 /empty.gif; | 299 error_page 404 =200 /empty.gif; |
296 </pre></blockquote></p><p> | 300 </pre></blockquote></p><p> |
297 If an error response is processed by a proxied server, or a FastCGI-server, | 301 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 | 302 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: | 303 or 404), it is possible to respond with a returned code: |
300 <blockquote><pre> | 304 <blockquote><pre> |
301 error_page 404 = /404.php; | 305 error_page 404 = /404.php; |
302 </pre></blockquote></p><p> | 306 </pre></blockquote></p><p> |
303 If there is no need to change URI during redirection it is possible to redirect | 307 If there is no need to change URI during redirection it is possible to redirect |
304 error processing into a named location: | 308 error processing into a named location: |
305 <blockquote><pre> | 309 <blockquote><pre> |
306 location / { | 310 location / { |
307 error_page 404 = @fallback; | 311 error_page 404 = @fallback; |
308 } | 312 } |
309 | 313 |
310 location @fallback { | 314 location @fallback { |
311 proxy_pass http://backend; | 315 proxy_pass http://backend; |
312 } | 316 } |
313 </pre></blockquote></p><hr><a name="if_modified_since"></a><strong>syntax</strong>: | 317 </pre></blockquote></p><hr><a name="if_modified_since"></a><strong>syntax</strong>: |
314 <code>if_modified_since | 318 <code>if_modified_since |
315 <code>off</code> | | 319 <code>off</code> | |
316 <code>exact</code> | | 320 <code>exact</code> | |
321 Specifies how to compare modification time of a response | 325 Specifies how to compare modification time of a response |
322 with the time in the | 326 with the time in the |
323 <code>If-Modified-Since</code> | 327 <code>If-Modified-Since</code> |
324 request header: | 328 request header: |
325 | 329 |
326 <ul><li><code>off</code> - the | 330 <dl compact><dt><code>off</code></dt><dd> |
331 the | |
327 <code>If-Modified-Since</code> request header is ignored (0.7.34); | 332 <code>If-Modified-Since</code> request header is ignored (0.7.34); |
328 </li><li><code>exact</code> - exact match; | 333 </dd><dt><code>exact</code></dt><dd> |
329 </li><li><code>before</code> - modification time of a response is | 334 exact match; |
335 </dd><dt><code>before</code></dt><dd> | |
336 modification time of a response is | |
330 less than or equal to the time in the <code>If-Modified-Since</code> | 337 less than or equal to the time in the <code>If-Modified-Since</code> |
331 request header. | 338 request header. |
332 </li></ul></p><hr><a name="internal"></a><strong>syntax</strong>: | 339 </dd></dl></p><hr><a name="internal"></a><strong>syntax</strong>: |
333 <code>internal</code><br><strong>default</strong>: | 340 <code>internal</code><br><strong>default</strong>: |
334 <strong>none</strong><br><strong>context</strong>: | 341 <strong>none</strong><br><strong>context</strong>: |
335 <code>location</code><br><p> | 342 <code>location</code><br><p> |
336 Specifies that a given location can only be used for internal requests. | 343 Specifies that a given location can only be used for internal requests. |
337 For external requests, the <i>"Not found"</i> (404) | 344 For external requests, the <i>"Not found"</i> (404) |
349 requests changed by the | 356 requests changed by the |
350 <u>rewrite</u> | 357 <u>rewrite</u> |
351 directive of the | 358 directive of the |
352 <u>http_rewrite</u> module. | 359 <u>http_rewrite</u> module. |
353 </li></ul></p><p> | 360 </li></ul></p><p> |
354 Example usage: | 361 Example: |
355 <blockquote><pre> | 362 <blockquote><pre> |
356 error_page 404 /404.html; | 363 error_page 404 /404.html; |
357 | 364 |
358 location /404.html { | 365 location /404.html { |
359 internal; | 366 internal; |
360 } | 367 } |
361 </pre></blockquote></p><hr><a name="keepalive_requests"></a><strong>syntax</strong>: | 368 </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>: | 369 <code>keepalive_requests <code><i>number</i></code></code><br><strong>default</strong>: |
363 <code>keepalive_requests 100</code><br><strong>context</strong>: | 370 <code>keepalive_requests 100</code><br><strong>context</strong>: |
373 <code>keepalive_timeout 75</code><br><strong>context</strong>: | 380 <code>keepalive_timeout 75</code><br><strong>context</strong>: |
374 <code>http</code>, <code>server</code>, <code>location</code><br><p> | 381 <code>http</code>, <code>server</code>, <code>location</code><br><p> |
375 The first argument sets a timeout during which a keep-alive | 382 The first argument sets a timeout during which a keep-alive |
376 client connection will stay open on the server side. | 383 client connection will stay open on the server side. |
377 The optional second argument sets a value in the | 384 The optional second argument sets a value in the |
378 "<code>Keep-Alive: timeout=</code><code><i>time</i></code>" | 385 “<code>Keep-Alive: timeout=<code><i>time</i></code></code>” |
379 response header. | 386 response header. |
380 Two arguments may differ. | 387 Two arguments may differ. |
381 </p><p> | 388 </p><p> |
382 The | 389 The |
383 "<code>Keep-Alive: timeout=</code>" | 390 “<code>Keep-Alive: timeout=</code>” |
384 is understood by Mozilla and Konqueror. | 391 is understood by Mozilla and Konqueror. |
385 MSIE will close keep-alive connection in about 60 seconds. | 392 MSIE will close keep-alive connection in about 60 seconds. |
386 </p><hr><a name="large_client_header_buffers"></a><strong>syntax</strong>: | 393 </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>: | 394 <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>: | 395 <code>large_client_header_buffers 4 4k/8k</code><br><strong>context</strong>: |
390 Sets the maximum <code><i>number</i></code> and <code><i>size</i></code> of | 397 Sets the maximum <code><i>number</i></code> and <code><i>size</i></code> of |
391 buffers used when reading large client request headers. | 398 buffers used when reading large client request headers. |
392 A request line cannot exceed the size of one buffer, or the | 399 A request line cannot exceed the size of one buffer, or the |
393 <i>"Request URI too large"</i> (414) | 400 <i>"Request URI too large"</i> (414) |
394 error is returned. | 401 error is returned. |
395 A request header line cannot exceed the size of one buffer as well, or the | 402 A request header field cannot exceed the size of one buffer as well, or the |
396 <i>"Bad request"</i> (400) | 403 <i>"Bad request"</i> (400) |
397 error is returned. | 404 error is returned. |
398 Buffers are allocated only on demand. | 405 Buffers are allocated only on demand. |
399 By default, the buffer size is equal to one memory page size. | 406 By default, the buffer size is equal to one memory page size. |
400 It is either 4K or 8K, platform dependent. | 407 It is either 4K or 8K, platform dependent. |
410 <u>http_access</u> | 417 <u>http_access</u> |
411 and | 418 and |
412 <u>http_auth_basic</u> | 419 <u>http_auth_basic</u> |
413 modules directives: | 420 modules directives: |
414 <blockquote><pre> | 421 <blockquote><pre> |
415 limit_except GET { | 422 limit_except GET { |
416 allow 192.168.1.0/32; | 423 allow 192.168.1.0/32; |
417 deny all; | 424 deny all; |
418 } | 425 } |
419 </pre></blockquote> | 426 </pre></blockquote> |
420 Please note that this will limit access to all methods | 427 Please note that this will limit access to all methods |
421 <strong>except</strong> GET and HEAD. | 428 <strong>except</strong> GET and HEAD. |
422 </p><hr><a name="limit_rate"></a><strong>syntax</strong>: | 429 </p><hr><a name="limit_rate"></a><strong>syntax</strong>: |
438 variable: | 445 variable: |
439 <blockquote><pre> | 446 <blockquote><pre> |
440 server { | 447 server { |
441 | 448 |
442 if ($slow) { | 449 if ($slow) { |
443 set $limit_rate 4k; | 450 set $limit_rate 4k; |
444 } | 451 } |
445 | 452 |
446 ... | 453 ... |
447 } | 454 } |
448 </pre></blockquote></p><hr><a name="limit_rate_after"></a><strong>syntax</strong>: | 455 </pre></blockquote></p><hr><a name="limit_rate_after"></a><strong>syntax</strong>: |
455 </p><p> | 462 </p><p> |
456 Example: | 463 Example: |
457 <blockquote><pre> | 464 <blockquote><pre> |
458 location /flv/ { | 465 location /flv/ { |
459 flv; | 466 flv; |
460 limit_rate_after 500k; | 467 limit_rate_after 500k; |
461 limit_rate 50k; | 468 limit_rate 50k; |
462 } | 469 } |
463 </pre></blockquote></p><hr><a name="listen"></a><strong>syntax</strong>: | 470 </pre></blockquote></p><hr><a name="listen"></a><strong>syntax</strong>: |
464 <code>listen | 471 <code>listen |
465 <code><i>address</i></code>[:<code><i>port</i></code>] | 472 <code><i>address</i></code>[:<code><i>port</i></code>] |
466 [<code>default</code> | <code>default_server</code> | 473 [<code>default</code> | <code>default_server</code> |
490 the server will accept requests. | 497 the server will accept requests. |
491 Only one of <code><i>address</i></code> or <code><i>port</i></code> can be | 498 Only one of <code><i>address</i></code> or <code><i>port</i></code> can be |
492 specified. | 499 specified. |
493 An <code><i>address</i></code> may also be a hostname, for example: | 500 An <code><i>address</i></code> may also be a hostname, for example: |
494 <blockquote><pre> | 501 <blockquote><pre> |
495 listen 127.0.0.1:8000; | 502 listen 127.0.0.1:8000; |
496 listen 127.0.0.1; | 503 listen 127.0.0.1; |
497 listen 8000; | 504 listen 8000; |
498 listen *:8000; | 505 listen *:8000; |
499 listen localhost:8000; | 506 listen localhost:8000; |
500 </pre></blockquote> | 507 </pre></blockquote> |
501 IPv6 addresses (0.7.36) are specified in square brackets: | 508 IPv6 addresses (0.7.36) are specified in square brackets: |
502 <blockquote><pre> | 509 <blockquote><pre> |
503 listen [::]:8000; | 510 listen [::]:8000; |
504 listen [fe80::1]; | 511 listen [fe80::1]; |
505 </pre></blockquote></p><p> | 512 </pre></blockquote></p><p> |
506 If only <code><i>address</i></code> is given, the port 80 is used. | 513 If only <code><i>address</i></code> is given, the port 80 is used. |
507 </p><p> | 514 </p><p> |
508 If directive is not present then either the <code>*:80</code> is used | 515 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. | 516 if nginx runs with superuser privileges, or <code>*:8000</code> otherwise. |
523 parameter can have several additional parameters specific to system calls | 530 parameter can have several additional parameters specific to system calls |
524 <code>listen()</code> and <code>bind()</code>. | 531 <code>listen()</code> and <code>bind()</code>. |
525 Starting from version 0.8.21, these parameters can be specified in any | 532 Starting from version 0.8.21, these parameters can be specified in any |
526 <code>listen</code> directive, but only once for the given | 533 <code>listen</code> directive, but only once for the given |
527 <code><i>address</i></code>:<code><i>port</i></code> pair. | 534 <code><i>address</i></code>:<code><i>port</i></code> pair. |
528 <ul><li><code>backlog</code>=<code><i>number</i></code> - | 535 <dl compact><dt><code>backlog</code>=<code><i>number</i></code></dt><dd> |
529 sets the <code>backlog</code> parameter in the | 536 sets the <code>backlog</code> parameter in the |
530 <code>listen()</code> call. | 537 <code>listen()</code> call. |
531 By default, <code>backlog</code> equals -1 on FreeBSD | 538 By default, <code>backlog</code> equals -1 on FreeBSD |
532 and 511 on other platforms. | 539 and 511 on other platforms. |
533 </li><li><code>rcvbuf</code>=<code><i>size</i></code> - | 540 </dd><dt><code>rcvbuf</code>=<code><i>size</i></code></dt><dd> |
534 sets the <code>SO_RCVBUF</code> parameter for the listening socket. | 541 sets the <code>SO_RCVBUF</code> parameter for the listening socket. |
535 </li><li><code>sndbuf</code>=<code><i>size</i></code> - | 542 </dd><dt><code>sndbuf</code>=<code><i>size</i></code></dt><dd> |
536 sets the <code>SO_SNDBUF</code> parameter for the listening socket. | 543 sets the <code>SO_SNDBUF</code> parameter for the listening socket. |
537 </li><li><code>accept_filter</code>=<code><i>filter</i></code> - | 544 </dd><dt><code>accept_filter</code>=<code><i>filter</i></code></dt><dd> |
538 sets the name of the accept filter. | 545 sets the name of the accept filter. |
539 This works only on FreeBSD, acceptable values are <code>dataready</code> | 546 This works only on FreeBSD, acceptable values are <code>dataready</code> |
540 and <code>httpready</code>. | 547 and <code>httpready</code>. |
541 On receiving <code>SIGHUP</code> signal, an accept filter can only be | 548 On receipt of the <code>SIGHUP</code> signal, an accept filter can only be |
542 changed in recent versions of FreeBSD, starting from 6.0, 5.4-STABLE | 549 changed in recent versions of FreeBSD, starting from 6.0, 5.4-STABLE |
543 and 4.11-STABLE. | 550 and 4.11-STABLE. |
544 </li><li><code>deferred</code> - | 551 </dd><dt><code>deferred</code></dt><dd> |
545 instructs to use a deferred <code>accept()</code> on Linux | 552 instructs to use a deferred <code>accept()</code> on Linux |
546 using the <code>TCP_DEFER_ACCEPT</code> option. | 553 using the <code>TCP_DEFER_ACCEPT</code> option. |
547 </li><li><code>bind</code> - | 554 </dd><dt><code>bind</code></dt><dd> |
548 specifies to make a separate <code>bind()</code> call for a given | 555 specifies to make a separate <code>bind()</code> call for a given |
549 <code><i>address</i></code>:<code><i>port</i></code> pair. | 556 <code><i>address</i></code>:<code><i>port</i></code> pair. |
550 This is because nginx will only <code>bind()</code> to | 557 This is because nginx will only <code>bind()</code> to |
551 <code>*</code>:<code><i>port</i></code> | 558 <code>*</code>:<code><i>port</i></code> |
552 if there are several <code>listen</code> directives with | 559 if there are several <code>listen</code> directives with |
553 the same port and different addresses, and one of the | 560 the same port but different addresses, and one of the |
554 <code>listen</code> directives listens on all addresses | 561 <code>listen</code> directives listens on all addresses |
555 for the given port (<code>*</code>:<code><i>port</i></code>). | 562 for the given port (<code>*</code>:<code><i>port</i></code>). |
556 It should be noted that in this case a <code>getsockname()</code> | 563 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 | 564 system call will be made to determine an address that accepted a |
558 connection. | 565 connection. |
559 If parameters <code>backlog</code>, <code>rcvbuf</code>, | 566 If parameters <code>backlog</code>, <code>rcvbuf</code>, |
560 <code>sndbuf</code>, <code>accept_filter</code>, or | 567 <code>sndbuf</code>, <code>accept_filter</code>, or |
561 <code>deferred</code> are used then for a given | 568 <code>deferred</code> are used then for a given |
562 <code><i>address</i></code>:<code><i>port</i></code> pair | 569 <code><i>address</i></code>:<code><i>port</i></code> pair |
563 a separate <code>bind()</code> call will always be made. | 570 a separate <code>bind()</code> call will always be made. |
564 </li><li><code>ipv6only</code>=<code>on</code>|<code>off</code> - | 571 </dd><dt><code>ipv6only</code>=<code>on</code>|<code>off</code></dt><dd> |
565 this parameter (0.7.42) sets the value of the <code>IPV6_V6ONLY</code> | 572 this parameter (0.7.42) sets the value of the <code>IPV6_V6ONLY</code> |
566 parameter for the listening socket. | 573 parameter for the listening socket. |
567 This parameter can only be set once on start. | 574 This parameter can only be set once on start. |
568 </li><li><code>ssl</code> - | 575 </dd><dt><code>ssl</code></dt><dd> |
569 this parameter (0.7.14) does not relate to system calls | 576 this parameter (0.7.14) does not relate to system calls |
570 <code>listen()</code> and <code>bind()</code>, but allows to | 577 <code>listen()</code> and <code>bind()</code>, but allows to |
571 specify that all connections accepted on this port should work in | 578 specify that all connections accepted on this port should work in |
572 the SSL mode. | 579 the SSL mode. |
573 This allows for a more compact configuration for the server operating | 580 This allows for a more compact configuration for the server operating |
574 in both HTTP and HTTPS modes simultaneously. | 581 in both HTTP and HTTPS modes simultaneously. |
575 <blockquote><pre> | 582 <blockquote><pre> |
576 listen 80; | 583 listen 80; |
577 listen 443 default ssl; | 584 listen 443 default ssl; |
578 </pre></blockquote></li></ul></p><p> | 585 </pre></blockquote></dd></dl></p><p> |
579 Example: | 586 Example: |
580 <blockquote><pre> | 587 <blockquote><pre> |
581 listen 127.0.0.1 default accept_filter=dataready backlog=1024; | 588 listen 127.0.0.1 default accept_filter=dataready backlog=1024; |
582 </pre></blockquote></p><hr><a name="location"></a><strong>syntax</strong>: | 589 </pre></blockquote></p><hr><a name="location"></a><strong>syntax</strong>: |
583 <code>location [ | 590 <code>location [ |
584 <code>=</code> | | 591 <code>=</code> | |
585 <code>~</code> | | 592 <code>~</code> | |
586 <code>~*</code> | | 593 <code>~*</code> | |
591 <strong>none</strong><br><strong>context</strong>: | 598 <strong>none</strong><br><strong>context</strong>: |
592 <code>server</code><br><p> | 599 <code>server</code><br><p> |
593 Sets a configuration based on a request URI. | 600 Sets a configuration based on a request URI. |
594 A location can either be defined by a prefix string, or by a regular expression. | 601 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 | 602 Regular expressions are specified by prepending them with the |
596 "<code>~*</code>" prefix (for case-insensitive matching), or with the | 603 “<code>~*</code>” prefix (for case-insensitive matching), or with the |
597 "<code>~</code>" prefix (for case-sensitive matching). | 604 “<code>~</code>” prefix (for case-sensitive matching). |
598 To find a location matching a given request, nginx first checks | 605 To find a location matching a given request, nginx first checks |
599 locations defined using the prefix strings (prefix locations). | 606 locations defined using the prefix strings (prefix locations). |
600 Amongst them, the most specific one is searched. | 607 Amongst them, the most specific one is searched. |
601 Then regular expressions are checked, in the order of their appearance | 608 Then regular expressions are checked, in the order of their appearance |
602 in a configuration file. | 609 in a configuration file. |
610 However, comparison is limited to one-byte locales. | 617 However, comparison is limited to one-byte locales. |
611 </p><p> | 618 </p><p> |
612 Regular expressions can contain captures (0.7.40) that can later | 619 Regular expressions can contain captures (0.7.40) that can later |
613 be used in other directives. | 620 be used in other directives. |
614 </p><p> | 621 </p><p> |
615 If the most specific prefix location has the "<code>^~</code>" prefix | 622 If the most specific prefix location has the “<code>^~</code>” prefix |
616 then regular expressions are not checked. | 623 then regular expressions are not checked. |
617 </p><p> | 624 </p><p> |
618 Also, using the "<code>=</code>" prefix it's possible to define | 625 Also, using the “<code>=</code>” prefix it is possible to define |
619 an exact match of URI and location. | 626 an exact match of URI and location. |
620 If an exact match is found, the search terminates. | 627 If an exact match is found, the search terminates. |
621 For example, if a "<code>/</code>" request happens frequently, | 628 For example, if a “<code>/</code>” request happens frequently, |
622 defining "<code>location = /</code>" will speed up the processing | 629 defining “<code>location = /</code>” will speed up the processing |
623 of these requests, as search terminates right after the first | 630 of these requests, as search terminates right after the first |
624 comparison. | 631 comparison. |
625 </p><p> | 632 </p><p> |
626 In versions from 0.7.1 to 0.8.41, if a request matched the prefix | 633 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>" | 634 location without the “<code>=</code>” and “<code>^~</code>” |
628 prefixes, the search also terminated and regular expressions were | 635 prefixes, the search also terminated and regular expressions were |
629 not checked. | 636 not checked. |
630 </p><p> | 637 </p><p> |
631 Let's illustrate the above by an example: | 638 Let's illustrate the above by example: |
632 <blockquote><pre> | 639 <blockquote><pre> |
633 location = / { | 640 location = / { |
634 [ configuration A ] | 641 [ configuration A ] |
635 } | 642 } |
636 | 643 |
637 location / { | 644 location / { |
638 [ configuration B ] | 645 [ configuration B ] |
639 } | 646 } |
640 | 647 |
641 location ^~ /images/ { | 648 location ^~ /images/ { |
642 [ configuration C ] | 649 [ configuration C ] |
644 | 651 |
645 location ~* \.(gif|jpg|jpeg)$ { | 652 location ~* \.(gif|jpg|jpeg)$ { |
646 [ configuration D ] | 653 [ configuration D ] |
647 } | 654 } |
648 </pre></blockquote> | 655 </pre></blockquote> |
649 The "<code>/</code>" request will match configuration A, | 656 The “<code>/</code>” request will match configuration A, |
650 the "<code>/documents/document.html</code>" request - configuration B, | 657 the “<code>/documents/document.html</code>” request will match |
651 the "<code>/images/1.gif</code>" request - configuration C, and | 658 configuration B, |
652 the "<code>/documents/1.jpg</code>" request - configuration D. | 659 the “<code>/images/1.gif</code>” request will match configuration C, and |
653 </p><p> | 660 the “<code>/documents/1.jpg</code>” request will match configuration D. |
654 The "<code>@</code>" prefix defines a named location. | 661 </p><p> |
655 Such a location isn't used for a regular request processing, but instead | 662 The “<code>@</code>” prefix defines a named location. |
663 Such a location is not used for a regular request processing, but instead | |
656 used for request redirection. | 664 used for request redirection. |
657 </p><hr><a name="log_not_found"></a><strong>syntax</strong>: | 665 </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>: | 666 <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>: | 667 <code>log_not_found on</code><br><strong>context</strong>: |
660 <code>http</code>, <code>server</code>, <code>location</code><br><p> | 668 <code>http</code>, <code>server</code>, <code>location</code><br><p> |
673 Enables or disables compression of two or more adjacent slashes | 681 Enables or disables compression of two or more adjacent slashes |
674 in a URI into a single slash. | 682 in a URI into a single slash. |
675 </p><p> | 683 </p><p> |
676 Note that compression is essential for the correct prefix string | 684 Note that compression is essential for the correct prefix string |
677 and regular expressions location matching. | 685 and regular expressions location matching. |
678 Without it, the "<code>//scripts/one.php</code>" request would not match | 686 Without it, the “<code>//scripts/one.php</code>” request would not match |
679 <blockquote><pre> | 687 <blockquote><pre> |
680 location /scripts/ { | 688 location /scripts/ { |
681 ... | 689 ... |
682 } | 690 } |
683 </pre></blockquote> | 691 </pre></blockquote> |
684 and might be processed as a static file, | 692 and might be processed as a static file, |
685 so it gets converted to "<code>/scripts/one.php</code>". | 693 so it gets converted to “<code>/scripts/one.php</code>”. |
686 </p><p> | 694 </p><p> |
687 Turning the compression <code>off</code> can become necessary if a URI | 695 Turning the compression <code>off</code> can become necessary if a URI |
688 contains base64-encoded names, since base64 uses the "/" character internally. | 696 contains base64-encoded names, since base64 uses the "/" character internally. |
689 However, for security considerations, it's better to avoid turning off | 697 However, for security considerations, it is better to avoid turning off |
690 the compression. | 698 the compression. |
691 </p><p> | 699 </p><p> |
692 If a directive is specified on the | 700 If a directive is specified on the |
693 <a href="#server">server</a> | 701 <a href="#server">server</a> |
694 level, which is also a default server, its value will cover | 702 level, which is also a default server, its value will cover |
722 Caching of errors should be enabled separately by the | 730 Caching of errors should be enabled separately by the |
723 <a href="#open_file_cache_errors">open_file_cache_errors</a> | 731 <a href="#open_file_cache_errors">open_file_cache_errors</a> |
724 directive. | 732 directive. |
725 </li></ul></p><p> | 733 </li></ul></p><p> |
726 The directive has the following parameters: | 734 The directive has the following parameters: |
727 <ul><li><code>max</code> - | 735 <dl compact><dt><code>max</code></dt><dd> |
728 sets the maximum number of elements in the cache; | 736 sets the maximum number of elements in the cache; |
729 on cache overflow the least recently used (LRU) elements get removed; | 737 on cache overflow the least recently used (LRU) elements get removed; |
730 </li><li><code>inactive</code> - | 738 </dd><dt><code>inactive</code></dt><dd> |
731 defines a time, after which the element gets removed from the cache | 739 defines a time, after which the element gets removed from the cache |
732 if there were no accesses to it during this time; | 740 if there were no accesses to it during this time; |
733 by default, it is 60 seconds; | 741 by default, it is 60 seconds; |
734 </li><li><code>off</code> - disables the cache. | 742 </dd><dt><code>off</code></dt><dd> |
735 </li></ul></p><p> | 743 disables the cache. |
744 </dd></dl></p><p> | |
736 Example: | 745 Example: |
737 <blockquote><pre> | 746 <blockquote><pre> |
738 open_file_cache max=1000 inactive=20s; | 747 open_file_cache max=1000 inactive=20s; |
739 open_file_cache_valid 30s; | 748 open_file_cache_valid 30s; |
740 open_file_cache_min_uses 2; | 749 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>: | 750 open_file_cache_errors on; |
751 </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>: | 752 <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>: | 753 <code>open_file_cache_errors off</code><br><strong>context</strong>: |
744 <code>http</code>, <code>server</code>, <code>location</code><br><p> | 754 <code>http</code>, <code>server</code>, <code>location</code><br><p> |
745 Enables or disables caching of file lookup errors by the | 755 Enables or disables caching of file lookup errors by the |
746 <a href="#open_file_cache">open_file_cache</a>. | 756 <a href="#open_file_cache">open_file_cache</a>. |
779 <code>port_in_redirect on</code><br><strong>context</strong>: | 789 <code>port_in_redirect on</code><br><strong>context</strong>: |
780 <code>http</code>, <code>server</code>, <code>location</code><br><p> | 790 <code>http</code>, <code>server</code>, <code>location</code><br><p> |
781 Enables or disables specifying the port in redirects issued by nginx. | 791 Enables or disables specifying the port in redirects issued by nginx. |
782 </p><hr><a name="read_ahead"></a><strong>syntax</strong>: | 792 </p><hr><a name="read_ahead"></a><strong>syntax</strong>: |
783 <code>read_ahead <code><i>size</i></code></code><br><strong>default</strong>: | 793 <code>read_ahead <code><i>size</i></code></code><br><strong>default</strong>: |
784 <code>read_ahead 0</code><br><strong>context</strong>: | 794 <code>read_ahead 0</code><br><strong>context</strong>: |
785 <code>http</code>, <code>server</code>, <code>location</code><br><p> | 795 <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. | 796 Sets the amount of pre-reading when working with files, in the kernel. |
787 </p><p> | 797 </p><p> |
788 On Linux, the | 798 On Linux, the |
789 <code>posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)</code> | 799 <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. | 800 system call is used, so the <code><i>size</i></code> argument is ignored. |
791 </p><p> | 801 </p><p> |
792 On FreeBSD, the | 802 On FreeBSD, the |
793 <code>fcntl(O_READAHEAD,</code><code><i>size</i></code><code>)</code> | 803 <code>fcntl(O_READAHEAD,</code><code><i>size</i></code><code>)</code> |
794 system call is used, supported in FreeBSD 9.0-CURRENT. | 804 system call is used, supported in FreeBSD 9.0-CURRENT. |
795 FreeBSD 7 needs to be | 805 FreeBSD 7 needs to be |
796 <u>patched</u>. | 806 <u>patched</u>. |
797 </p><hr><a name="recursive_error_pages"></a><strong>syntax</strong>: | 807 </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>: | 808 <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>: | 809 <code>recursive_error_pages off</code><br><strong>context</strong>: |
800 <code>http</code>, <code>server</code>, <code>location</code><br><p> | 810 <code>http</code>, <code>server</code>, <code>location</code><br><p> |
801 Enables or disables doing several redirects using the | 811 Enables or disables doing several redirects using the |
802 <a href="#error_page">error_page</a> | 812 <a href="#error_page">error_page</a> |
803 directive. | 813 directive. |
804 </p><hr><a name="reset_timedout_connection"></a><strong>syntax</strong>: | 814 </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>: | 815 <code>reset_timedout_connection |
816 <code>on</code> | <code>off</code></code><br><strong>default</strong>: | |
806 <code>reset_timedout_connection off</code><br><strong>context</strong>: | 817 <code>reset_timedout_connection off</code><br><strong>context</strong>: |
807 <code>http</code>, <code>server</code>, <code>location</code><br><p> | 818 <code>http</code>, <code>server</code>, <code>location</code><br><p> |
808 Enables or disables resetting of timed out connections. | 819 Enables or disables resetting of timed out connections. |
809 The reset is performed as follows: before closing a socket, the | 820 The reset is performed as follows: before closing a socket, the |
810 <code>SO_LINGER</code> | 821 <code>SO_LINGER</code> |
820 <code>resolver <code><i>address</i></code></code><br><strong>default</strong>: | 831 <code>resolver <code><i>address</i></code></code><br><strong>default</strong>: |
821 <strong>none</strong><br><strong>context</strong>: | 832 <strong>none</strong><br><strong>context</strong>: |
822 <code>http</code>, <code>server</code>, <code>location</code><br><p> | 833 <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: | 834 Sets the <code><i>address</i></code> of a name server, for example: |
824 <blockquote><pre> | 835 <blockquote><pre> |
825 resolver 127.0.0.1; | 836 resolver 127.0.0.1; |
826 </pre></blockquote></p><hr><a name="resolver_timeout"></a><strong>syntax</strong>: | 837 </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>: | 838 <code>resolver_timeout <code><i>time</i></code></code><br><strong>default</strong>: |
828 <code>resolver_timeout 30s</code><br><strong>context</strong>: | 839 <code>resolver_timeout 30s</code><br><strong>context</strong>: |
829 <code>http</code>, <code>server</code>, <code>location</code><br><p> | 840 <code>http</code>, <code>server</code>, <code>location</code><br><p> |
830 Sets a timeout for name resolution, for example: | 841 Sets a timeout for name resolution, for example: |
831 <blockquote><pre> | 842 <blockquote><pre> |
832 resolver_timeout 5s; | 843 resolver_timeout 5s; |
833 </pre></blockquote></p><hr><a name="root"></a><strong>syntax</strong>: | 844 </pre></blockquote></p><hr><a name="root"></a><strong>syntax</strong>: |
834 <code>root <code><i>path</i></code></code><br><strong>default</strong>: | 845 <code>root <code><i>path</i></code></code><br><strong>default</strong>: |
835 <code>root html</code><br><strong>context</strong>: | 846 <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> | 847 <code>http</code>, <code>server</code>, <code>location</code>, <code>if in location</code><br><p> |
837 Sets the root directory for requests. | 848 Sets the root directory for requests. |
838 For example, with the following configuration | 849 For example, with the following configuration |
839 <blockquote><pre> | 850 <blockquote><pre> |
840 location /i/ { | 851 location /i/ { |
841 root /data/w3; | 852 root /data/w3; |
842 } | 853 } |
843 </pre></blockquote> | 854 </pre></blockquote>“<code>/i/top.gif</code>” will be responded |
844 the request of "/i/top.gif" will be responded | 855 with the file |
845 with the file "/data/w3/images/top.gif". | 856 “<code>/data/w3/i/top.gif</code>”. |
846 </p><p> | 857 </p><p> |
847 The <code><i>path</i></code> value can contain variables. | 858 The <code><i>path</i></code> value can contain variables. |
848 </p><p> | 859 </p><p> |
849 A path to the file is constructed by merely adding a URI to the value | 860 A path to the file is constructed by merely adding a URI to the value |
850 of the <code>root</code> directive. | 861 of the <code>root</code> directive. |
858 <u>http_access</u> | 869 <u>http_access</u> |
859 or <u>http_auth_basic</u> | 870 or <u>http_auth_basic</u> |
860 modules grant access. | 871 modules grant access. |
861 <blockquote><pre> | 872 <blockquote><pre> |
862 location / { | 873 location / { |
863 satisfy any; | 874 satisfy any; |
864 | 875 |
865 allow 192.168.1.0/32; | 876 allow 192.168.1.0/32; |
866 deny all; | 877 deny all; |
867 | 878 |
868 auth_basic "closed site"; | 879 auth_basic "closed site"; |
869 auth_basic_user_file conf/htpasswd; | 880 auth_basic_user_file conf/htpasswd; |
870 } | 881 } |
871 </pre></blockquote></p><hr><a name="satisfy_any"></a><strong>syntax</strong>: | 882 </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>: | 883 <code>satisfy_any <code>on</code> | <code>off</code></code><br><strong>default</strong>: |
873 <code>satisfy_any off</code><br><strong>context</strong>: | 884 <code>satisfy_any off</code><br><strong>context</strong>: |
874 <code>location</code><br><p> | 885 <code>location</code><br><p> |
892 <code>server { ... }</code><br><strong>default</strong>: | 903 <code>server { ... }</code><br><strong>default</strong>: |
893 <strong>none</strong><br><strong>context</strong>: | 904 <strong>none</strong><br><strong>context</strong>: |
894 <code>http</code><br><p> | 905 <code>http</code><br><p> |
895 Sets a configuration for the virtual server. | 906 Sets a configuration for the virtual server. |
896 There is no clean separation between IP-based (based on the IP address) | 907 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) | 908 and name-based (based on the <code>Host</code> request header field) |
898 virtual servers. | 909 virtual servers. |
899 Instead, the <a href="#listen">listen</a> directives describe all | 910 Instead, the <a href="#listen">listen</a> directives describe all |
900 addresses and ports that should accept connections for a server, and the | 911 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. | 912 <a href="#server_name">server_name</a> directive lists all server names. |
902 An example configuration is provided in the | 913 An example configuration is provided in the |
903 <u> | 914 <u> |
904 Setting Up Virtual Servers</u> document. | 915 Setting Up Virtual Servers</u> document. |
905 </p><hr><a name="server_name"></a><strong>syntax</strong>: | 916 </p><hr><a name="server_name"></a><strong>syntax</strong>: |
906 <code>server_name <code><i>name ...</i></code></code><br><strong>default</strong>: | 917 <code>server_name <code><i>name</i></code> ...</code><br><strong>default</strong>: |
907 <code>server_name hostname</code><br><strong>context</strong>: | 918 <code>server_name hostname</code><br><strong>context</strong>: |
908 <code>server</code><br><p> | 919 <code>server</code><br><p> |
909 Sets names of the virtual server, for example: | 920 Sets names of the virtual server, for example: |
910 <blockquote><pre> | 921 <blockquote><pre> |
911 server { | 922 server { |
912 server_name example.com www.example.com; | 923 server_name example.com www.example.com; |
913 } | 924 } |
914 </pre></blockquote></p><p> | 925 </pre></blockquote></p><p> |
915 The first name becomes a primary server name. | 926 The first name becomes a primary server name. |
916 By default, the machine's hostname is used. | 927 By default, the machine's hostname is used. |
917 Server names can include an asterisk ("<code>*</code>") | 928 Server names can include an asterisk (“<code>*</code>”) |
918 to replace the first or last part of a name: | 929 to replace the first or last part of a name: |
919 <blockquote><pre> | 930 <blockquote><pre> |
920 server { | 931 server { |
921 server_name example.com *.example.com www.example.*; | 932 server_name example.com *.example.com www.example.*; |
922 } | 933 } |
923 </pre></blockquote></p><p> | 934 </pre></blockquote></p><p> |
924 The first two of the above mentioned names can be combined: | 935 The first two of the above mentioned names can be combined: |
925 <blockquote><pre> | 936 <blockquote><pre> |
926 server { | 937 server { |
927 server_name .example.com; | 938 server_name .example.com; |
928 } | 939 } |
929 </pre></blockquote></p><p> | 940 </pre></blockquote></p><p> |
930 It is also possible to use regular expressions in server names, | 941 It is also possible to use regular expressions in server names, |
931 prepending the name with a tilde ("<code>~</code>"): | 942 prepending the name with a tilde (“<code>~</code>”): |
932 <blockquote><pre> | 943 <blockquote><pre> |
933 server { | 944 server { |
934 server_name www.example.com ~^www\d+\.example\.com$; | 945 server_name www.example.com ~^www\d+\.example\.com$; |
935 } | 946 } |
936 </pre></blockquote></p><p> | 947 </pre></blockquote></p><p> |
937 Regular expressions can contain captures (0.7.40) that can later | 948 Regular expressions can contain captures (0.7.40) that can later |
938 be used in other directives: | 949 be used in other directives: |
939 <blockquote><pre> | 950 <blockquote><pre> |
940 server { | 951 server { |
941 server_name ~^(www\.)?(.+)$; | 952 server_name ~^(www\.)?(.+)$; |
942 | 953 |
943 location / { | 954 location / { |
944 root /sites/$2; | 955 root /sites/$2; |
945 } | 956 } |
946 } | 957 } |
947 | 958 |
948 server { | 959 server { |
949 server_name _; | 960 server_name _; |
950 | 961 |
951 location / { | 962 location / { |
952 root /sites/default; | 963 root /sites/default; |
953 } | 964 } |
954 } | 965 } |
955 </pre></blockquote></p><p> | 966 </pre></blockquote></p><p> |
956 Starting from version 0.8.25, named captures in regular expressions create | 967 Starting from version 0.8.25, named captures in regular expressions create |
957 variables that can later be used in other directives: | 968 variables that can later be used in other directives: |
958 <blockquote><pre> | 969 <blockquote><pre> |
959 server { | 970 server { |
960 server_name ~^(www\.)?(?<domain>.+)$; | 971 server_name ~^(www\.)?(?<domain>.+)$; |
961 | 972 |
962 location / { | 973 location / { |
963 root /sites/$domain; | 974 root /sites/$domain; |
964 } | 975 } |
965 } | 976 } |
966 | 977 |
967 server { | 978 server { |
968 server_name _; | 979 server_name _; |
969 | 980 |
970 location / { | 981 location / { |
971 root /sites/default; | 982 root /sites/default; |
972 } | 983 } |
973 } | 984 } |
974 </pre></blockquote></p><p> | 985 </pre></blockquote></p><p> |
975 Starting from version 0.7.11, it is possible to specify an empty name "": | 986 Starting from version 0.7.11, it is possible to specify an empty name: |
976 <blockquote><pre> | 987 <blockquote><pre> |
977 server { | 988 server { |
978 server_name www.example.com ""; | 989 server_name www.example.com ""; |
979 } | 990 } |
980 </pre></blockquote> | 991 </pre></blockquote> |
981 It allows this server to process requests without the <code>Host</code> | 992 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. | 993 header, instead of the default server for the given address:port pair. |
983 </p><p> | 994 </p><p> |
984 The name checking order is as follows: | 995 The name checking order is as follows: |
985 <ol><li> | 996 <ol><li> |
986 full names | 997 full names |
987 </li><li> | 998 </li><li> |
988 names with the prefix mask - *.example.com | 999 names with the prefix mask, e.g. “<code>*.example.com</code>”</li><li> |
989 </li><li> | 1000 names with the suffix mask, e.g. “<code>mail.*</code>”</li><li> |
990 names with the suffix mask - mail.* | |
991 </li><li> | |
992 regular expressions | 1001 regular expressions |
993 </li></ol></p><hr><a name="server_name_in_redirect"></a><strong>syntax</strong>: | 1002 </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>: | 1003 <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>: | 1004 <code>server_name_in_redirect on</code><br><strong>context</strong>: |
996 <code>http</code>, <code>server</code>, <code>location</code><br><p> | 1005 <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 | 1006 Enables or disables the use of the primary server name, specified by the |
998 <a href="#server_name">server_name</a> | 1007 <a href="#server_name">server_name</a> |
999 directive, in redirects issued by nginx. | 1008 directive, in redirects issued by nginx. |
1000 When disabled, the name from the <code>Host</code> request header string | 1009 When disabled, the name from the <code>Host</code> request header field |
1001 is used. | 1010 is used. |
1002 If there's no such a string, an IP address of the server is used. | 1011 If this field is not present, an IP address of the server is used. |
1003 </p><hr><a name="server_names_hash_max_size"></a><strong>syntax</strong>: | 1012 </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>: | 1013 <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>: | 1014 <code>server_names_hash_max_size 512</code><br><strong>context</strong>: |
1006 <code>http</code><br><p> | 1015 <code>http</code><br><p> |
1007 Sets the maximum <code><i>size</i></code> of the server names hash tables. | 1016 Sets the maximum <code><i>size</i></code> of the server names hash tables. |
1018 </p><hr><a name="server_tokens"></a><strong>syntax</strong>: | 1027 </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>: | 1028 <code>server_tokens <code>on</code> | <code>off</code></code><br><strong>default</strong>: |
1020 <code>server_tokens on</code><br><strong>context</strong>: | 1029 <code>server_tokens on</code><br><strong>context</strong>: |
1021 <code>http</code>, <code>server</code>, <code>location</code><br><p> | 1030 <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 | 1031 Enables or disables emitting of nginx version in error messages and in the |
1023 <code>Server</code> response header string. | 1032 <code>Server</code> response header field. |
1024 </p><hr><a name="tcp_nodelay"></a><strong>syntax</strong>: | 1033 </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>: | 1034 <code>tcp_nodelay <code>on</code> | <code>off</code></code><br><strong>default</strong>: |
1026 <code>tcp_nodelay on</code><br><strong>context</strong>: | 1035 <code>tcp_nodelay on</code><br><strong>context</strong>: |
1027 <code>http</code>, <code>server</code>, <code>location</code><br><p> | 1036 <code>http</code>, <code>server</code>, <code>location</code><br><p> |
1028 Enables or disables the use of the <code>TCP_NODELAY</code> option. | 1037 Enables or disables the use of the <code>TCP_NODELAY</code> option. |
1041 send the response header and the beginning of a file in one packet, | 1050 send the response header and the beginning of a file in one packet, |
1042 on Linux and FreeBSD 4.*; | 1051 on Linux and FreeBSD 4.*; |
1043 </li><li> | 1052 </li><li> |
1044 send a file in full packets. | 1053 send a file in full packets. |
1045 </li></ul></p><hr><a name="try_files"></a><strong>syntax</strong>: | 1054 </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>: | 1055 <code>try_files |
1056 <code><i>file</i></code> ... | |
1057 <code><i>uri</i></code></code><br><code> </code><code>try_files | |
1058 <code><i>file</i></code> ... | |
1059 =<code><i>code</i></code></code><br><strong>default</strong>: | |
1047 <strong>none</strong><br><strong>context</strong>: | 1060 <strong>none</strong><br><strong>context</strong>: |
1048 <code>location</code><br><p> | 1061 <code>location</code><br><p> |
1049 Checks the existence of files in the specified order, and uses | 1062 Checks the existence of files in the specified order, and uses |
1050 the first found file for request processing; the processing | 1063 the first found file for request processing; the processing |
1051 is performed in this location's context. | 1064 is performed in this location's context. |
1052 It is possible to check the directory existence by specifying | 1065 It is possible to check the directory existence by specifying |
1053 the slash at the end of a name, e.g. "<code>$uri/</code>". | 1066 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 | 1067 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. | 1068 <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 | 1069 As of version 0.7.51, the last argument can also be a |
1057 <code><i>code</i></code>: | 1070 <code><i>code</i></code>: |
1058 <blockquote><pre> | 1071 <blockquote><pre> |
1059 location / { | 1072 location / { |
1060 try_files $uri $uri/index.html $uri.html =404; | 1073 try_files $uri $uri/index.html $uri.html =404; |
1061 } | 1074 } |
1062 </pre></blockquote></p><p> | 1075 </pre></blockquote></p><p> |
1063 Example when proxying Mongrel: | 1076 Example when proxying Mongrel: |
1064 <blockquote><pre> | 1077 <blockquote><pre> |
1065 location / { | 1078 location / { |
1066 try_files /system/maintenance.html | 1079 try_files /system/maintenance.html |
1067 $uri $uri/index.html $uri.html | 1080 $uri $uri/index.html $uri.html |
1068 @mongrel; | 1081 @mongrel; |
1069 } | 1082 } |
1070 | 1083 |
1071 location @mongrel { | 1084 location @mongrel { |
1072 proxy_pass http://mongrel; | 1085 proxy_pass http://mongrel; |
1073 } | 1086 } |
1074 </pre></blockquote></p><p> | 1087 </pre></blockquote></p><p> |
1075 Example for Drupal/FastCGI: | 1088 Example for Drupal/FastCGI: |
1076 <blockquote><pre> | 1089 <blockquote><pre> |
1077 location / { | 1090 location / { |
1078 try_files $uri $uri/ @drupal; | 1091 try_files $uri $uri/ @drupal; |
1079 } | 1092 } |
1080 | 1093 |
1081 location ~ \.php$ { | 1094 location ~ \.php$ { |
1082 try_files $uri @drupal; | 1095 try_files $uri @drupal; |
1083 | 1096 |
1084 fastcgi_pass ...; | 1097 fastcgi_pass ...; |
1085 | 1098 |
1086 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; | 1099 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; |
1087 fastcgi_param SCRIPT_NAME $fastcgi_script_name; | 1100 fastcgi_param SCRIPT_NAME $fastcgi_script_name; |
1088 fastcgi_param QUERY_STRING $args; | 1101 fastcgi_param QUERY_STRING $args; |
1089 | 1102 |
1090 ... other fastcgi_param's | 1103 ... other fastcgi_param's |
1091 } | 1104 } |
1092 | 1105 |
1093 location @drupal { | 1106 location @drupal { |
1094 fastcgi_pass ...; | 1107 fastcgi_pass ...; |
1095 | 1108 |
1096 fastcgi_param SCRIPT_FILENAME /path/to/index.php; | 1109 fastcgi_param SCRIPT_FILENAME /path/to/index.php; |
1097 fastcgi_param SCRIPT_NAME /index.php; | 1110 fastcgi_param SCRIPT_NAME /index.php; |
1098 fastcgi_param QUERY_STRING q=$uri&$args; | 1111 fastcgi_param QUERY_STRING q=$uri&$args; |
1099 | 1112 |
1100 ... other fastcgi_param's | 1113 ... other fastcgi_param's |
1101 } | 1114 } |
1102 </pre></blockquote> | 1115 </pre></blockquote> |
1103 In the following example, | 1116 In the following example, |
1104 <blockquote><pre> | 1117 <blockquote><pre> |
1105 location / { | 1118 location / { |
1106 try_files $uri $uri/ @drupal; | 1119 try_files $uri $uri/ @drupal; |
1107 } | 1120 } |
1108 </pre></blockquote> | 1121 </pre></blockquote> |
1109 the <code>try_files</code> directive is equivalent to | 1122 the <code>try_files</code> directive is equivalent to |
1110 <blockquote><pre> | 1123 <blockquote><pre> |
1111 location / { | 1124 location / { |
1112 error_page 404 = @drupal; | 1125 error_page 404 = @drupal; |
1113 log_not_found off; | 1126 log_not_found off; |
1114 } | 1127 } |
1115 </pre></blockquote> | 1128 </pre></blockquote> |
1116 And here, | 1129 And here, |
1117 <blockquote><pre> | 1130 <blockquote><pre> |
1118 location ~ \.php$ { | 1131 location ~ \.php$ { |
1119 try_files $uri @drupal; | 1132 try_files $uri @drupal; |
1120 | 1133 |
1121 fastcgi_pass ...; | 1134 fastcgi_pass ...; |
1122 | 1135 |
1123 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; | 1136 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; |
1124 | 1137 |
1125 ... | 1138 ... |
1126 } | 1139 } |
1127 </pre></blockquote><code>try_files</code> checks the existence of the PHP file | 1140 </pre></blockquote><code>try_files</code> checks the existence of the PHP file |
1128 before passing the request to the FastCGI server. | 1141 before passing the request to the FastCGI server. |
1129 </p><p> | 1142 </p><p> |
1130 Example for Wordpress and Joomla: | 1143 Example for Wordpress and Joomla: |
1131 <blockquote><pre> | 1144 <blockquote><pre> |
1132 location / { | 1145 location / { |
1133 try_files $uri $uri/ @wordpress; | 1146 try_files $uri $uri/ @wordpress; |
1134 } | 1147 } |
1135 | 1148 |
1136 location ~ \.php$ { | 1149 location ~ \.php$ { |
1137 try_files $uri @wordpress; | 1150 try_files $uri @wordpress; |
1138 | 1151 |
1139 fastcgi_pass ...; | 1152 fastcgi_pass ...; |
1140 | 1153 |
1141 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; | 1154 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; |
1142 ... other fastcgi_param's | 1155 ... other fastcgi_param's |
1143 } | 1156 } |
1144 | 1157 |
1145 location @wordpress { | 1158 location @wordpress { |
1146 fastcgi_pass ...; | 1159 fastcgi_pass ...; |
1147 | 1160 |
1148 fastcgi_param SCRIPT_FILENAME /path/to/index.php; | 1161 fastcgi_param SCRIPT_FILENAME /path/to/index.php; |
1149 ... other fastcgi_param's | 1162 ... other fastcgi_param's |
1150 } | 1163 } |
1151 </pre></blockquote></p><hr><a name="types"></a><strong>syntax</strong>: | 1164 </pre></blockquote></p><hr><a name="types"></a><strong>syntax</strong>: |
1152 <code>types { ... }</code><br><strong>default</strong>: | 1165 <code>types { ... }</code><br><strong>default</strong>: |
1153 <code>see below</code><br><strong>context</strong>: | 1166 <code>see below</code><br><strong>context</strong>: |
1155 Maps file name extensions to MIME types of responses. | 1168 Maps file name extensions to MIME types of responses. |
1156 Several extensions can map to one type. | 1169 Several extensions can map to one type. |
1157 The following mappings are configured by default: | 1170 The following mappings are configured by default: |
1158 <blockquote><pre> | 1171 <blockquote><pre> |
1159 types { | 1172 types { |
1160 text/html html; | 1173 text/html html; |
1161 image/gif gif; | 1174 image/gif gif; |
1162 image/jpeg jpg; | 1175 image/jpeg jpg; |
1163 } | 1176 } |
1164 </pre></blockquote></p><p> | 1177 </pre></blockquote></p><p> |
1165 A sufficiently full mapping table is distributed with nginx in the | 1178 A sufficiently full mapping table is distributed with nginx in the |
1166 <code>conf/mime.types</code> file. | 1179 <code>conf/mime.types</code> file. |
1167 </p><p> | 1180 </p><p> |
1168 To make a particular location emit the "<code>application/octet-stream</code>" | 1181 To make a particular location emit the |
1182 “<code>application/octet-stream</code>” | |
1169 MIME type for all requests, try the following: | 1183 MIME type for all requests, try the following: |
1170 <blockquote><pre> | 1184 <blockquote><pre> |
1171 location /download/ { | 1185 location /download/ { |
1172 types { } | 1186 types { } |
1173 default_type application/octet-stream; | 1187 default_type application/octet-stream; |
1174 } | 1188 } |
1175 </pre></blockquote></p><hr><a name="underscores_in_headers"></a><strong>syntax</strong>: | 1189 </pre></blockquote></p><hr><a name="underscores_in_headers"></a><strong>syntax</strong>: |
1176 <code>underscores_in_headers <code>on</code> | <code>off</code></code><br><strong>default</strong>: | 1190 <code>underscores_in_headers <code>on</code> | <code>off</code></code><br><strong>default</strong>: |
1177 <code>underscores_in_headers off</code><br><strong>context</strong>: | 1191 <code>underscores_in_headers off</code><br><strong>context</strong>: |
1178 <code>http</code>, <code>server</code><br><p> | 1192 <code>http</code>, <code>server</code><br><p> |
1179 Enables or disables the use of underscores in client request header strings. | 1193 Enables or disables the use of underscores in client request header fields. |
1180 </p></body></html> | 1194 </p><a name="variables"></a><center><h4>Embedded Variables</h4></center><p> |
1195 The http_core module supports embedded variables with names matching | |
1196 those of the Apache Server. | |
1197 First of all, these are variables representing client request header | |
1198 fields, such as, <code>$http_user_agent</code>, <code>$http_cookie</code>, | |
1199 and so on. | |
1200 It also supports other variables: | |
1201 <dl compact><dt><code>$args</code></dt><dd> | |
1202 arguments in the request line | |
1203 </dd><dt><code>$arg_</code><code><i>name</i></code></dt><dd> | |
1204 argument <code><i>name</i></code> in the request line | |
1205 </dd><dt><code>$binary_remote_addr</code></dt><dd> | |
1206 client address in a binary form, value's length is always 4 bytes | |
1207 </dd><dt><code>$content_length</code></dt><dd><code>Content-Length</code> request header field | |
1208 </dd><dt><code>$content_type</code></dt><dd><code>Content-Type</code> request header field | |
1209 </dd><dt><code>$cookie_</code><code><i>name</i></code></dt><dd> | |
1210 the <code><i>name</i></code> cookie | |
1211 </dd><dt><code>$document_root</code></dt><dd><a href="#root">root</a> directive's value for the current request | |
1212 </dd><dt><code>$document_uri</code></dt><dd> | |
1213 same as <code>$uri</code></dd><dt><code>$host</code></dt><dd><code>Host</code> request header field, | |
1214 or the server name matching a request if this field is not present | |
1215 </dd><dt><code>$hostname</code></dt><dd> | |
1216 host name | |
1217 </dd><dt><code>$http_</code><code><i>name</i></code></dt><dd> | |
1218 the <code><i>name</i></code> request header field | |
1219 </dd><dt><code>$is_args</code></dt><dd>“<code>?</code>” if a request line has arguments, | |
1220 or an empty string otherwise | |
1221 </dd><dt><code>$limit_rate</code></dt><dd> | |
1222 allows for connection rate limiting | |
1223 </dd><dt><code>$pid</code></dt><dd> | |
1224 PID of the worker process | |
1225 </dd><dt><code>$request_method</code></dt><dd> | |
1226 request method, usually | |
1227 “<code>GET</code>” or “<code>POST</code>”</dd><dt><code>$remote_addr</code></dt><dd> | |
1228 client address | |
1229 </dd><dt><code>$remote_port</code></dt><dd> | |
1230 client port | |
1231 </dd><dt><code>$remote_user</code></dt><dd> | |
1232 user name supplied with the Basic authentication | |
1233 </dd><dt><code>$realpath_root</code></dt><dd><a href="#root">root</a> directive's value | |
1234 for the current request, with all symbolic links resolved to real paths | |
1235 </dd><dt><code>$request_filename</code></dt><dd> | |
1236 file path for the current query, based on the | |
1237 <a href="#root">root</a> and <a href="#alias">alias</a> | |
1238 directives, and the request URI | |
1239 </dd><dt><code>$request_body</code></dt><dd> | |
1240 request body | |
1241 <p> | |
1242 The variable's value is made available in locations | |
1243 processed by the | |
1244 <u>proxy_pass</u> | |
1245 and | |
1246 <u>fastcgi_pass</u> | |
1247 directives. | |
1248 </p></dd><dt><code>$request_body_file</code></dt><dd> | |
1249 name of a temporary file with the request body | |
1250 <p> | |
1251 At the end of processing, the file needs to be removed. | |
1252 To always write a request body to a file, | |
1253 <a href="#client_body_in_file_only">client_body_in_file_only on</a> | |
1254 needs be specified. | |
1255 When passing the name of a temporary file in a proxied request, | |
1256 or in a request to a FastCGI server, | |
1257 passing of the request body should be disabled by the | |
1258 <u>proxy_pass_request_body</u> | |
1259 and | |
1260 <u>fastcgi_pass_request_body</u> | |
1261 directives, respectively. | |
1262 </p></dd><dt><code>$request_uri</code></dt><dd> | |
1263 full original request URI (with arguments) | |
1264 </dd><dt><code>$query_string</code></dt><dd> | |
1265 same as <code>$args</code></dd><dt><code>$scheme</code></dt><dd> | |
1266 request scheme, “<code>http</code>” or “<code>https</code>>”</dd><dt><code>$server_protocol</code></dt><dd> | |
1267 request protocol, usually | |
1268 “<code>HTTP/1.0</code>” | |
1269 or | |
1270 “<code>HTTP/1.1</code>”</dd><dt><code>$server_addr</code></dt><dd> | |
1271 an address of the server which accepted a request | |
1272 <p> | |
1273 Computing a value of this variable usually requires one system call. | |
1274 To avoid a system call, the <code>listen</code> directives | |
1275 must specify addresses and use the <code>bind</code> parameter | |
1276 </p></dd><dt><code>$server_name</code></dt><dd> | |
1277 name of the server which accepted a request | |
1278 </dd><dt><code>$server_port</code></dt><dd> | |
1279 port of the server which accepted a request | |
1280 </dd><dt><code>$uri</code></dt><dd> | |
1281 current URI in request | |
1282 <p> | |
1283 It may differ from an original, e.g. when doing internal redirects, | |
1284 or when using index files. | |
1285 </p></dd></dl></p></body></html> |