Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_core_module.xml @ 958:fd1f8e0a405e
Text review of ngx_http_core_module.
author | Egor Nikitin <yegor.nikitin@gmail.com> |
---|---|
date | Tue, 06 Aug 2013 17:03:33 +0400 |
parents | 7d1d53d4d293 |
children | 95c3c3bbf1ce |
comparison
equal
deleted
inserted
replaced
957:6d9d4bb571a9 | 958:fd1f8e0a405e |
---|---|
29 Enables or disables the use of asynchronous file I/O (AIO) | 29 Enables or disables the use of asynchronous file I/O (AIO) |
30 on FreeBSD and Linux. | 30 on FreeBSD and Linux. |
31 </para> | 31 </para> |
32 | 32 |
33 <para> | 33 <para> |
34 On FreeBSD, AIO is usable starting from FreeBSD 4.3. | 34 On FreeBSD, AIO can be used starting from FreeBSD 4.3. |
35 AIO can either be linked statically into a kernel: | 35 AIO can either be linked statically into a kernel: |
36 <example> | 36 <example> |
37 options VFS_AIO | 37 options VFS_AIO |
38 </example> | 38 </example> |
39 or loaded dynamically as a kernel loadable module: | 39 or loaded dynamically as a kernel loadable module: |
43 </para> | 43 </para> |
44 | 44 |
45 <para> | 45 <para> |
46 In FreeBSD versions 5 and 6, enabling AIO statically, or dynamically | 46 In FreeBSD versions 5 and 6, enabling AIO statically, or dynamically |
47 when booting the kernel, will cause the entire networking subsystem | 47 when booting the kernel, will cause the entire networking subsystem |
48 to use the Giant lock that can impact overall performance negatively. | 48 to use the Giant lock, which can impact overall performance negatively. |
49 This limitation has been removed in FreeBSD 6.4-STABLE in 2009, and in | 49 This limitation has been removed in FreeBSD 6.4-STABLE in 2009, and in |
50 FreeBSD 7. | 50 FreeBSD 7. |
51 However, starting from FreeBSD 5.3 it is possible to enable AIO | 51 However, starting from FreeBSD 5.3 it is possible to enable AIO |
52 without the penalty of running the networking subsystem under a | 52 without the penalty of running the networking subsystem under a |
53 Giant lock—for this to work, the AIO module needs to be loaded | 53 Giant lock—for this to work, the AIO module needs to be loaded |
64 fact that FreeBSD supports asynchronous calls | 64 fact that FreeBSD supports asynchronous calls |
65 <c-func>aio_read</c-func> | 65 <c-func>aio_read</c-func> |
66 and | 66 and |
67 <c-func>aio_write</c-func> | 67 <c-func>aio_write</c-func> |
68 when working with sockets. | 68 when working with sockets. |
69 However, since nginx only uses AIO for disk I/O, no problems should arise. | 69 However, since nginx uses AIO only for disk I/O, no problems should arise. |
70 </note> | 70 </note> |
71 </para> | 71 </para> |
72 | 72 |
73 <para> | 73 <para> |
74 For AIO to work, | 74 For AIO to work, |
92 tcp_nopush on; | 92 tcp_nopush on; |
93 aio sendfile; | 93 aio sendfile; |
94 } | 94 } |
95 </example> | 95 </example> |
96 In this configuration, <c-func>sendfile</c-func> is called with | 96 In this configuration, <c-func>sendfile</c-func> is called with |
97 the <c-def>SF_NODISKIO</c-def> flag which causes it not to | 97 the <c-def>SF_NODISKIO</c-def> flag which causes it not to block on disk I/O, |
98 block on disk I/O and instead report back when the data are not in | 98 but, instead, report back that the data are not in memory. |
99 memory; nginx then initiates an asynchronous data load by reading | 99 nginx then initiates an asynchronous data load by reading one byte. |
100 one byte. | 100 On the first read, the FreeBSD kernel loads the first 128K bytes |
101 The FreeBSD kernel then loads the first 128K bytes | 101 of a file into memory, although next reads will only load data in 16K chunks. |
102 of a file into memory, however next reads will only load data | 102 This can be changed using the |
103 in 16K chunks. | 103 <link id="read_ahead"/> directive. |
104 This can be tuned using the | 104 </para> |
105 <link id="read_ahead"/> | 105 |
106 directive. | 106 <para> |
107 </para> | 107 On Linux, AIO can be used starting from kernel version 2.6.22. |
108 | 108 Also, it is necessary to enable |
109 <para> | |
110 On Linux, AIO is usable starting from kernel version 2.6.22; | |
111 plus, it is also necessary to enable | |
112 <link id="directio"/>, | 109 <link id="directio"/>, |
113 otherwise reading will be blocking: | 110 or otherwise reading will be blocking: |
114 <example> | 111 <example> |
115 location /video/ { | 112 location /video/ { |
116 aio on; | 113 aio on; |
117 directio 512; | 114 directio 512; |
118 output_buffers 1 128k; | 115 output_buffers 1 128k; |
123 <para> | 120 <para> |
124 On Linux, | 121 On Linux, |
125 <link id="directio"/> | 122 <link id="directio"/> |
126 can only be used for reading blocks that are aligned on 512-byte | 123 can only be used for reading blocks that are aligned on 512-byte |
127 boundaries (or 4K for XFS). | 124 boundaries (or 4K for XFS). |
128 Reading of unaligned file’s end is still made in blocking mode. | 125 File’s unaligned end is read in blocking mode. |
129 The same holds true for byte range requests, and for FLV requests | 126 The same holds true for byte range requests and for FLV requests |
130 not from the beginning of a file: reading of unaligned data at the | 127 not from the beginning of a file: reading of unaligned data at the |
131 beginning and end of a file will be blocking. | 128 beginning and end of a file will be blocking. |
132 There is no need to turn off | 129 There is no need to turn off |
133 <link id="sendfile"/> | 130 <link id="sendfile"/> |
134 explicitly as it is turned off automatically when | 131 explicitly, as it is turned off automatically when |
135 <link id="directio"/> | 132 <link id="directio"/> |
136 is used. | 133 is used. |
137 </para> | 134 </para> |
138 | 135 |
139 </directive> | 136 </directive> |
150 <example> | 147 <example> |
151 location /i/ { | 148 location /i/ { |
152 alias /data/w3/images/; | 149 alias /data/w3/images/; |
153 } | 150 } |
154 </example> | 151 </example> |
155 the request of | 152 on request of |
156 “<literal>/i/top.gif</literal>” will be responded | 153 “<literal>/i/top.gif</literal>”, the file |
157 with the file | 154 <path>/data/w3/images/top.gif</path> will be sent. |
158 <path>/data/w3/images/top.gif</path>. | 155 </para> |
159 </para> | 156 |
160 | 157 <para> |
161 <para> | 158 The <value>path</value> value can contain variables, |
162 The <value>path</value> value can contain variables | |
163 except <var>$document_root</var> and <var>$realpath_root</var>. | 159 except <var>$document_root</var> and <var>$realpath_root</var>. |
164 </para> | 160 </para> |
165 | 161 |
166 <para> | 162 <para> |
167 If <literal>alias</literal> is used inside a location defined | 163 If <literal>alias</literal> is used inside a location defined |
203 <context>location</context> | 199 <context>location</context> |
204 | 200 |
205 <para> | 201 <para> |
206 Allows disabling chunked transfer encoding in HTTP/1.1. | 202 Allows disabling chunked transfer encoding in HTTP/1.1. |
207 It may come in handy when using a software failing to support | 203 It may come in handy when using a software failing to support |
208 chunked encoding though the standard requires it. | 204 chunked encoding despite the standard’s requirement. |
209 </para> | 205 </para> |
210 | 206 |
211 </directive> | 207 </directive> |
212 | 208 |
213 | 209 |
219 <context>server</context> | 215 <context>server</context> |
220 <context>location</context> | 216 <context>location</context> |
221 | 217 |
222 <para> | 218 <para> |
223 Sets buffer size for reading client request body. | 219 Sets buffer size for reading client request body. |
224 In case request body is larger than the buffer, | 220 In case the request body is larger than the buffer, |
225 the whole body or only its part is written to a | 221 the whole body or only its part is written to a |
226 <link id="client_body_temp_path">temporary file</link>. | 222 <link id="client_body_temp_path">temporary file</link>. |
227 By default, buffer size is equal to two memory pages. | 223 By default, buffer size is equal to two memory pages. |
228 This is 8K on x86, other 32-bit platforms, and x86-64. | 224 This is 8K on x86, other 32-bit platforms, and x86-64. |
229 It is usually 16K on other 64-bit platforms. | 225 It is usually 16K on other 64-bit platforms. |
295 <context>server</context> | 291 <context>server</context> |
296 <context>location</context> | 292 <context>location</context> |
297 | 293 |
298 <para> | 294 <para> |
299 Defines a directory for storing temporary files holding client request bodies. | 295 Defines a directory for storing temporary files holding client request bodies. |
300 Up to three-level subdirectory hierarchy can be used underneath the specified | 296 Up to three-level subdirectory hierarchy can be used under the specified |
301 directory. | 297 directory. |
302 For example, in the following configuration | 298 For example, in the following configuration |
303 <example> | 299 <example> |
304 client_body_temp_path /spool/nginx/client_temp 1 2; | 300 client_body_temp_path /spool/nginx/client_temp 1 2; |
305 </example> | 301 </example> |
306 a temporary file might look like this: | 302 a path to a temporary file might look like this: |
307 <example> | 303 <example> |
308 /spool/nginx/client_temp/7/45/00000123457 | 304 /spool/nginx/client_temp/7/45/00000123457 |
309 </example> | 305 </example> |
310 </para> | 306 </para> |
311 | 307 |
319 <context>server</context> | 315 <context>server</context> |
320 <context>location</context> | 316 <context>location</context> |
321 | 317 |
322 <para> | 318 <para> |
323 Defines a timeout for reading client request body. | 319 Defines a timeout for reading client request body. |
324 A timeout is only set between two successive read operations, | 320 The timeout is only set for a period between two successive read operations, |
325 not for the transmission of the whole request body. | 321 not for the transmission of the whole request body. |
326 If a client does not transmit anything within this time, | 322 If a client does not transmit anything within this time, the |
327 the client error | |
328 <http-status code="408" text="Request Time-out"/> | 323 <http-status code="408" text="Request Time-out"/> |
329 is returned. | 324 error is returned to the client. |
330 </para> | 325 </para> |
331 | 326 |
332 </directive> | 327 </directive> |
333 | 328 |
334 | 329 |
341 <para> | 336 <para> |
342 Sets buffer size for reading client request header. | 337 Sets buffer size for reading client request header. |
343 For most requests, a buffer of 1K bytes is enough. | 338 For most requests, a buffer of 1K bytes is enough. |
344 However, if a request includes long cookies, or comes from a WAP client, | 339 However, if a request includes long cookies, or comes from a WAP client, |
345 it may not fit into 1K. | 340 it may not fit into 1K. |
346 If a request line, or a request header field do not fit entirely into | 341 If a request line or a request header field does not fit into |
347 this buffer then larger buffers are allocated, configured by the | 342 this buffer then larger buffers, configured by the |
348 <link id="large_client_header_buffers"/> | 343 <link id="large_client_header_buffers"/> directive, |
349 directive. | 344 are allocated. |
350 </para> | 345 </para> |
351 | 346 |
352 </directive> | 347 </directive> |
353 | 348 |
354 | 349 |
358 <context>http</context> | 353 <context>http</context> |
359 <context>server</context> | 354 <context>server</context> |
360 | 355 |
361 <para> | 356 <para> |
362 Defines a timeout for reading client request header. | 357 Defines a timeout for reading client request header. |
363 If a client does not transmit the entire header within this time, | 358 If a client does not transmit the entire header within this time, the |
364 the client error | |
365 <http-status code="408" text="Request Time-out"/> | 359 <http-status code="408" text="Request Time-out"/> |
366 is returned. | 360 error is returned to the client. |
367 </para> | 361 </para> |
368 | 362 |
369 </directive> | 363 </directive> |
370 | 364 |
371 | 365 |
379 <para> | 373 <para> |
380 Sets the maximum allowed size of the client request body, | 374 Sets the maximum allowed size of the client request body, |
381 specified in the | 375 specified in the |
382 <header>Content-Length</header> | 376 <header>Content-Length</header> |
383 request header field. | 377 request header field. |
384 If it exceeds the configured value, the client error | 378 If the size in a request exceeds the configured value, the |
385 <http-status code="413" text="Request Entity Too Large"/> | 379 <http-status code="413" text="Request Entity Too Large"/> |
386 is returned. | 380 error is returned to the client. |
387 Please be aware that | 381 Please be aware that |
388 <!--link doc="/web/upload.xml"-->browsers cannot correctly display | 382 <!--link doc="/web/upload.xml"-->browsers cannot correctly display |
389 this error<!--/link-->. | 383 this error<!--/link-->. |
390 Setting <value>size</value> to 0 disables client | 384 Setting <value>size</value> to 0 disables checking of client |
391 request body size checking. | 385 request body size. |
392 </para> | 386 </para> |
393 | 387 |
394 </directive> | 388 </directive> |
395 | 389 |
396 | 390 |
399 <default>256</default> | 393 <default>256</default> |
400 <context>http</context> | 394 <context>http</context> |
401 <context>server</context> | 395 <context>server</context> |
402 | 396 |
403 <para> | 397 <para> |
404 Allows to fine tune per-connection memory allocations. | 398 Allows accurate tuning of per-connection memory allocations. |
405 This directive has minimal impact on performance, | 399 This directive has minimal impact on performance |
406 and should not generally be used. | 400 and should not generally be used. |
407 </para> | 401 </para> |
408 | 402 |
409 </directive> | 403 </directive> |
410 | 404 |
415 <context>http</context> | 409 <context>http</context> |
416 <context>server</context> | 410 <context>server</context> |
417 <context>location</context> | 411 <context>location</context> |
418 | 412 |
419 <para> | 413 <para> |
420 Defines a default MIME-type of a response. | 414 Defines the default MIME-type of a response. |
421 Mapping of file name extensions to MIME types can be set | 415 Mapping of file name extensions to MIME types can be set |
422 with the <link id="types"/> directive. | 416 with the <link id="types"/> directive. |
423 </para> | 417 </para> |
424 | 418 |
425 </directive> | 419 </directive> |
438 the <c-def>O_DIRECT</c-def> flag (FreeBSD, Linux), | 432 the <c-def>O_DIRECT</c-def> flag (FreeBSD, Linux), |
439 the <c-def>F_NOCACHE</c-def> flag (Mac OS X), | 433 the <c-def>F_NOCACHE</c-def> flag (Mac OS X), |
440 or the <c-func>directio</c-func> function (Solaris), | 434 or the <c-func>directio</c-func> function (Solaris), |
441 when reading files that are larger than or equal to | 435 when reading files that are larger than or equal to |
442 the specified <value>size</value>. | 436 the specified <value>size</value>. |
443 It automatically disables (0.7.15) the use of | 437 The directive automatically disables (0.7.15) the use of |
444 <link id="sendfile"/> | 438 <link id="sendfile"/> |
445 for a given request. | 439 for a given request. |
446 It could be useful for serving large files: | 440 It can be useful for serving large files: |
447 <example> | 441 <example> |
448 directio 4m; | 442 directio 4m; |
449 </example> | 443 </example> |
450 or when using <link id="aio"/> on Linux. | 444 or when using <link id="aio"/> on Linux. |
451 </para> | 445 </para> |
460 <context>server</context> | 454 <context>server</context> |
461 <context>location</context> | 455 <context>location</context> |
462 <appeared-in>0.8.11</appeared-in> | 456 <appeared-in>0.8.11</appeared-in> |
463 | 457 |
464 <para> | 458 <para> |
465 Sets an alignment for | 459 Sets the alignment for |
466 <link id="directio"/>. | 460 <link id="directio"/>. |
467 In most cases, a 512-byte alignment is enough, however, when | 461 In most cases, a 512-byte alignment is enough. |
468 using XFS under Linux, it needs to be increased to 4K. | 462 However, when using XFS under Linux, it needs to be increased to 4K. |
469 </para> | 463 </para> |
470 | 464 |
471 </directive> | 465 </directive> |
472 | 466 |
473 | 467 |
510 <tag-desc> | 504 <tag-desc> |
511 When checking symbolic links | 505 When checking symbolic links |
512 (parameters <literal>on</literal> and <literal>if_not_owner</literal>), | 506 (parameters <literal>on</literal> and <literal>if_not_owner</literal>), |
513 all components of the pathname are normally checked. | 507 all components of the pathname are normally checked. |
514 Checking of symbolic links in the initial part of the pathname | 508 Checking of symbolic links in the initial part of the pathname |
515 may be avoided by also specifying the | 509 may be avoided by specifying additionally the |
516 <literal>from</literal>=<value>part</value> parameter. | 510 <literal>from</literal>=<value>part</value> parameter. |
517 In this case, symbolic links are checked only from | 511 In this case, symbolic links are checked only from |
518 the component of the pathname following the specified initial part. | 512 the pathname component that follows the specified initial part. |
519 If a value is not an initial part of the checked pathname, the whole | 513 If the value is not an initial part of the pathname checked, the whole |
520 pathname is checked as if this parameter was not specified at all. | 514 pathname is checked as if this parameter was not specified at all. |
521 If a value fully matches the file name, | 515 If the value matches the whole file name, |
522 symbolic links are not checked. | 516 symbolic links are not checked. |
523 The parameter value can contain variables. | 517 The parameter value can contain variables. |
524 </tag-desc> | 518 </tag-desc> |
525 | 519 |
526 </list> | 520 </list> |
534 </para> | 528 </para> |
535 | 529 |
536 <para> | 530 <para> |
537 This directive is only available on systems that have the | 531 This directive is only available on systems that have the |
538 <c-func>openat</c-func> and <c-func>fstatat</c-func> interfaces. | 532 <c-func>openat</c-func> and <c-func>fstatat</c-func> interfaces. |
539 This includes modern versions of FreeBSD, Linux, and Solaris. | 533 Such systems include modern versions of FreeBSD, Linux, and Solaris. |
540 </para> | 534 </para> |
541 | 535 |
542 <para> | 536 <para> |
543 Parameters <literal>on</literal> and <literal>if_not_owner</literal> | 537 Parameters <literal>on</literal> and <literal>if_not_owner</literal> |
544 add a processing overhead. | 538 add a processing overhead. |
545 <note> | 539 <note> |
546 On systems that do not support opening directories for search only, | 540 On systems that do not support opening of directories only for search, |
547 the use of these parameters requires that worker processes | 541 to use these parameters it is required that worker processes |
548 have read permissions for all checked directories. | 542 have read permissions for all directories being checked. |
549 </note> | 543 </note> |
550 </para> | 544 </para> |
551 | 545 |
552 <para> | 546 <para> |
553 <note> | 547 <note> |
573 <context>location</context> | 567 <context>location</context> |
574 <context>if in location</context> | 568 <context>if in location</context> |
575 | 569 |
576 <para> | 570 <para> |
577 Defines the URI that will be shown for the specified errors. | 571 Defines the URI that will be shown for the specified errors. |
578 These directives are inherited from the previous level if and | 572 <literal>error_page</literal> directives are inherited from the previous |
579 only if there are no | 573 level only if there are no <literal>error_page</literal> |
580 <literal>error_page</literal> | 574 directives defined on the current level. |
581 directives on | |
582 the current level. | |
583 A <literal>uri</literal> value can contain variables. | 575 A <literal>uri</literal> value can contain variables. |
584 </para> | 576 </para> |
585 | 577 |
586 <para> | 578 <para> |
587 Example: | 579 Example: |
598 error_page 404 =200 /empty.gif; | 590 error_page 404 =200 /empty.gif; |
599 </example> | 591 </example> |
600 </para> | 592 </para> |
601 | 593 |
602 <para> | 594 <para> |
603 If an error response is processed by a proxied server, or a FastCGI server, | 595 If an error response is processed by a proxied server or a FastCGI server, |
604 and the server may return different response codes (e.g., 200, 302, 401 | 596 and the server may return different response codes (e.g., 200, 302, 401 |
605 or 404), it is possible to respond with a returned code: | 597 or 404), it is possible to respond with the code it returns: |
606 <example> | 598 <example> |
607 error_page 404 = /404.php; | 599 error_page 404 = /404.php; |
608 </example> | 600 </example> |
609 </para> | 601 </para> |
610 | 602 |
728 directive). | 720 directive). |
729 </para> | 721 </para> |
730 | 722 |
731 <para> | 723 <para> |
732 A directive can be specified on the <link id="server"/> level | 724 A directive can be specified on the <link id="server"/> level |
733 in a default server. | 725 in the default server. |
734 In this case, its value will cover all virtual servers | 726 In this case, its value will cover all virtual servers |
735 listening on the same address and port. | 727 listening on the same address and port. |
736 </para> | 728 </para> |
737 | 729 |
738 </directive> | 730 </directive> |
815 <para> | 807 <para> |
816 Disables keep-alive connections with misbehaving browsers. | 808 Disables keep-alive connections with misbehaving browsers. |
817 The <value>browser</value> parameters specify which | 809 The <value>browser</value> parameters specify which |
818 browsers will be affected. | 810 browsers will be affected. |
819 The value <literal>msie6</literal> disables keep-alive connections | 811 The value <literal>msie6</literal> disables keep-alive connections |
820 with old versions of MSIE, after seeing a POST request. | 812 with old versions of MSIE, once a POST request is received. |
821 The value <literal>safari</literal> disables keep-alive connections | 813 The value <literal>safari</literal> disables keep-alive connections |
822 with Safari and Safari-like browsers on Mac OS X and Mac OS X-like | 814 with Safari and Safari-like browsers on Mac OS X and Mac OS X-like |
823 operating systems. | 815 operating systems. |
824 The value <literal>none</literal> enables keep-alive connections | 816 The value <literal>none</literal> enables keep-alive connections |
825 with all browsers. | 817 with all browsers. |
841 <context>location</context> | 833 <context>location</context> |
842 <appeared-in>0.8.0</appeared-in> | 834 <appeared-in>0.8.0</appeared-in> |
843 | 835 |
844 <para> | 836 <para> |
845 Sets the maximum number of requests that can be | 837 Sets the maximum number of requests that can be |
846 made through one keep-alive connection. | 838 served through one keep-alive connection. |
847 After this many requests are made, the connection is closed. | 839 After the maximum number of requests are made, the connection is closed. |
848 </para> | 840 </para> |
849 | 841 |
850 </directive> | 842 </directive> |
851 | 843 |
852 | 844 |
860 <context>location</context> | 852 <context>location</context> |
861 | 853 |
862 <para> | 854 <para> |
863 The first parameter sets a timeout during which a keep-alive | 855 The first parameter sets a timeout during which a keep-alive |
864 client connection will stay open on the server side. | 856 client connection will stay open on the server side. |
865 The value of zero disables keep-alive client connections. | 857 The zero value disables keep-alive client connections. |
866 The optional second parameter sets a value in the | 858 The optional second parameter sets a value in the |
867 <header>Keep-Alive: timeout=<value>time</value></header> | 859 <header>Keep-Alive: timeout=<value>time</value></header> |
868 response header field. | 860 response header field. |
869 Two parameters may differ. | 861 Two parameters may differ. |
870 </para> | 862 </para> |
871 | 863 |
872 <para> | 864 <para> |
873 The | 865 The |
874 <header>Keep-Alive: timeout=<value>time</value></header> | 866 <header>Keep-Alive: timeout=<value>time</value></header> |
875 header field is understood by Mozilla and Konqueror. | 867 header field is recognized by Mozilla and Konqueror. |
876 MSIE will close keep-alive connection in about 60 seconds. | 868 MSIE closes keep-alive connections by itself in about 60 seconds. |
877 </para> | 869 </para> |
878 | 870 |
879 </directive> | 871 </directive> |
880 | 872 |
881 | 873 |
885 <context>http</context> | 877 <context>http</context> |
886 <context>server</context> | 878 <context>server</context> |
887 | 879 |
888 <para> | 880 <para> |
889 Sets the maximum <value>number</value> and <value>size</value> of | 881 Sets the maximum <value>number</value> and <value>size</value> of |
890 buffers used when reading large client request header. | 882 buffers used for reading large client request header. |
891 A request line cannot exceed the size of one buffer, or the client error | 883 A request line cannot exceed the size of one buffer, or the |
892 <http-status code="414" text="Request-URI Too Large"/> | 884 <http-status code="414" text="Request-URI Too Large"/> |
893 is returned. | 885 error is returned to the client. |
894 A request header field cannot exceed the size of one buffer as well, or the | 886 A request header field cannot exceed the size of one buffer as well, or the |
895 client error | |
896 <http-status code="400" text="Bad Request"/> | 887 <http-status code="400" text="Bad Request"/> |
897 is returned. | 888 error is returned to the client. |
898 Buffers are allocated only on demand. | 889 Buffers are allocated only on demand. |
899 By default, the buffer size is equal to 8K bytes. | 890 By default, the buffer size is equal to 8K bytes. |
900 If after the end of request processing a connection is transitioned | 891 If after the end of request processing a connection is transitioned |
901 into the keep-alive state, these buffers are freed. | 892 into the keep-alive state, these buffers are released. |
902 </para> | 893 </para> |
903 | 894 |
904 </directive> | 895 </directive> |
905 | 896 |
906 | 897 |
925 <literal>PROPPATCH</literal>, | 916 <literal>PROPPATCH</literal>, |
926 <literal>LOCK</literal>, | 917 <literal>LOCK</literal>, |
927 <literal>UNLOCK</literal>, | 918 <literal>UNLOCK</literal>, |
928 or | 919 or |
929 <literal>PATCH</literal>. | 920 <literal>PATCH</literal>. |
930 Allowing the <literal>GET</literal> method also allows the | 921 Allowing the <literal>GET</literal> method makes the |
931 <literal>HEAD</literal> method. | 922 <literal>HEAD</literal> method also allowed. |
932 Access to other methods can be limited using the | 923 Access to other methods can be limited using the |
933 <link doc="ngx_http_access_module.xml">ngx_http_access_module</link> | 924 <link doc="ngx_http_access_module.xml">ngx_http_access_module</link> |
934 and | 925 and |
935 <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link> | 926 <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link> |
936 modules directives: | 927 modules directives: |
954 <context>server</context> | 945 <context>server</context> |
955 <context>location</context> | 946 <context>location</context> |
956 <context>if in location</context> | 947 <context>if in location</context> |
957 | 948 |
958 <para> | 949 <para> |
959 Rate limits the transmission of a response to a client. | 950 Limits the rate of response transmission to a client. |
960 The <value>rate</value> is specified in bytes per second. | 951 The <value>rate</value> is specified in bytes per second. |
961 The value 0 disables rate limiting. | 952 The value 0 disables rate limiting. |
962 <!-- | 953 <!-- |
963 The smaller the rate, the more accurate will be the limitation. | 954 The smaller the rate, the more accurate will be the limitation. |
964 --> | 955 --> |
965 The limit is set per request, so if a client simultaneously opens | 956 The limit is set per a request, and so if a client simultaneously opens |
966 two connections, an overall rate will be twice as much | 957 two connections, the overall rate will be twice as much |
967 as the specified limit. | 958 as the specified limit. |
968 </para> | 959 </para> |
969 | 960 |
970 <para> | 961 <para> |
971 Rate limit can also be set in the <var>$limit_rate</var> variable. | 962 Rate limit can also be set in the <var>$limit_rate</var> variable. |
982 } | 973 } |
983 </example> | 974 </example> |
984 </para> | 975 </para> |
985 | 976 |
986 <para> | 977 <para> |
987 In addition, rate limit can also be set in the | 978 Rate limit can also be set in the |
988 <header>X-Accel-Limit-Rate</header> header field of a proxied server response. | 979 <header>X-Accel-Limit-Rate</header> header field of a proxied server response. |
989 This ability can be disabled using the | 980 This capability can be disabled using the |
990 <link doc="ngx_http_proxy_module.xml" id="proxy_ignore_headers"/> | 981 <link doc="ngx_http_proxy_module.xml" id="proxy_ignore_headers"/> |
991 and | 982 and |
992 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_ignore_headers"/> | 983 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_ignore_headers"/> |
993 directives. | 984 directives. |
994 </para> | 985 </para> |
1054 </para> | 1045 </para> |
1055 | 1046 |
1056 <para> | 1047 <para> |
1057 The value “<literal>off</literal>” tells nginx to never wait for | 1048 The value “<literal>off</literal>” tells nginx to never wait for |
1058 more data and close the connection immediately. | 1049 more data and close the connection immediately. |
1059 This breaks the protocol and should not be used under normal circumstances. | 1050 This behavior breaks the protocol and should not be used under normal |
1051 circumstances. | |
1060 </para> | 1052 </para> |
1061 | 1053 |
1062 </directive> | 1054 </directive> |
1063 | 1055 |
1064 | 1056 |
1069 <context>server</context> | 1061 <context>server</context> |
1070 <context>location</context> | 1062 <context>location</context> |
1071 | 1063 |
1072 <para> | 1064 <para> |
1073 When <link id="lingering_close"/> is in effect, | 1065 When <link id="lingering_close"/> is in effect, |
1074 this directive specifies a maximum time during which nginx | 1066 this directive specifies the maximum time during which nginx |
1075 will process (read and ignore) additional data coming from a client. | 1067 will process (read and ignore) additional data coming from a client. |
1076 After that, the connection is closed, even if there are more data. | 1068 After that, the connection will be closed, even if there will be |
1069 more data. | |
1077 </para> | 1070 </para> |
1078 | 1071 |
1079 </directive> | 1072 </directive> |
1080 | 1073 |
1081 | 1074 |
1086 <context>server</context> | 1079 <context>server</context> |
1087 <context>location</context> | 1080 <context>location</context> |
1088 | 1081 |
1089 <para> | 1082 <para> |
1090 When <link id="lingering_close"/> is in effect, this directive specifies | 1083 When <link id="lingering_close"/> is in effect, this directive specifies |
1091 a maximum waiting time for more client data to arrive. | 1084 the maximum waiting time for more client data to arrive. |
1092 If data are not received during this time, the connection is closed. | 1085 If data are not received during this time, the connection is closed. |
1093 Otherwise, data are read and ignored, then nginx waits again for more data. | 1086 Otherwise, the data are read and ignored, and nginx starts waiting |
1087 for more data again. | |
1094 The “wait-read-ignore” cycle is repeated, but no longer than specified by the | 1088 The “wait-read-ignore” cycle is repeated, but no longer than specified by the |
1095 <link id="lingering_time"/> directive. | 1089 <link id="lingering_time"/> directive. |
1096 </para> | 1090 </para> |
1097 | 1091 |
1098 </directive> | 1092 </directive> |
1142 <default>*:80 | *:8000</default> | 1136 <default>*:80 | *:8000</default> |
1143 <context>server</context> | 1137 <context>server</context> |
1144 | 1138 |
1145 <para> | 1139 <para> |
1146 Sets an <value>address</value> and a <value>port</value> for IP, | 1140 Sets an <value>address</value> and a <value>port</value> for IP, |
1147 or a <value>path</value> for a UNIX-domain socket, on which | 1141 or a <value>path</value> for a UNIX-domain socket on which |
1148 the server will accept requests. | 1142 the server will accept requests. |
1149 Only one of <value>address</value> or <value>port</value> may be | 1143 Both <value>address</value> and <value>port</value>, |
1150 specified. | 1144 or only <value>address</value> or only <value>port</value> can be specified. |
1151 An <value>address</value> may also be a hostname, for example: | 1145 An <value>address</value> may also be a hostname, for example: |
1152 <example> | 1146 <example> |
1153 listen 127.0.0.1:8000; | 1147 listen 127.0.0.1:8000; |
1154 listen 127.0.0.1; | 1148 listen 127.0.0.1; |
1155 listen 8000; | 1149 listen 8000; |
1171 <para> | 1165 <para> |
1172 If only <value>address</value> is given, the port 80 is used. | 1166 If only <value>address</value> is given, the port 80 is used. |
1173 </para> | 1167 </para> |
1174 | 1168 |
1175 <para> | 1169 <para> |
1176 If directive is not present then either the <literal>*:80</literal> is used | 1170 If the directive is not present then either <literal>*:80</literal> is used |
1177 if nginx runs with superuser privileges, or <literal>*:8000</literal> otherwise. | 1171 if nginx runs with the superuser privileges, or <literal>*:8000</literal> |
1172 otherwise. | |
1178 </para> | 1173 </para> |
1179 | 1174 |
1180 <para> | 1175 <para> |
1181 The <literal>default_server</literal> parameter, if present, | 1176 The <literal>default_server</literal> parameter, if present, |
1182 will cause the server to become the default server for the specified | 1177 will cause the server to become the default server for the specified |
1190 <literal>default</literal>. | 1185 <literal>default</literal>. |
1191 </note> | 1186 </note> |
1192 </para> | 1187 </para> |
1193 | 1188 |
1194 <para> | 1189 <para> |
1195 The <literal>ssl</literal> parameter (0.7.14) allows to specify that all | 1190 The <literal>ssl</literal> parameter (0.7.14) allows specifying that all |
1196 connections accepted on this port should work in SSL mode. | 1191 connections accepted on this port should work in SSL mode. |
1197 This allows for a more compact <link doc="configuring_https_servers.xml" | 1192 This allows for a more compact <link doc="configuring_https_servers.xml" |
1198 id="single_http_https_server">configuration</link> for the server that | 1193 id="single_http_https_server">configuration</link> for the server that |
1199 handles both HTTP and HTTPS requests. | 1194 handles both HTTP and HTTPS requests. |
1200 </para> | 1195 </para> |
1201 | 1196 |
1202 <para> | 1197 <para> |
1203 The <literal>spdy</literal> parameter (1.3.15) allows to accept | 1198 The <literal>spdy</literal> parameter (1.3.15) allows accepting |
1204 <link doc="ngx_http_spdy_module.xml">SPDY</link> connections on this port. | 1199 <link doc="ngx_http_spdy_module.xml">SPDY</link> connections on this port. |
1205 Normally, for this to work the <literal>ssl</literal> parameter should be | 1200 Normally, for this to work the <literal>ssl</literal> parameter should be |
1206 specified as well, but nginx can also be configured to accept SPDY | 1201 specified as well, but nginx can also be configured to accept SPDY |
1207 connections without SSL. | 1202 connections without SSL. |
1208 </para> | 1203 </para> |
1209 | 1204 |
1210 <para> | 1205 <para> |
1211 A <literal>listen</literal> directive | 1206 A <literal>listen</literal> directive |
1212 can have several additional parameters specific to socket-related system calls. | 1207 can have several additional parameters specific to socket-related system calls. |
1213 They can be specified in any | 1208 These parameters can be specified in any |
1214 <literal>listen</literal> directive, but only once for the given | 1209 <literal>listen</literal> directive, but only once for a given |
1215 <value>address</value>:<value>port</value> pair. | 1210 <value>address</value>:<value>port</value> pair. |
1216 <note> | 1211 <note> |
1217 In versions prior to 0.8.21, they could only be | 1212 In versions prior to 0.8.21, they could only be |
1218 specified in the <literal>listen</literal> directive along with the | 1213 specified in the <literal>listen</literal> directive together with the |
1219 <literal>default</literal> parameter. | 1214 <literal>default</literal> parameter. |
1220 </note> | 1215 </note> |
1221 <list type="tag"> | 1216 <list type="tag"> |
1222 | 1217 |
1223 <tag-name> | 1218 <tag-name> |
1224 <literal>setfib</literal>=<value>number</value> | 1219 <literal>setfib</literal>=<value>number</value> |
1225 </tag-name> | 1220 </tag-name> |
1226 <tag-desc> | 1221 <tag-desc> |
1227 this parameter (0.8.44) sets an associated routing table, FIB | 1222 this parameter (0.8.44) sets the associated routing table, FIB |
1228 (the <c-def>SO_SETFIB</c-def> option) for the listening socket. | 1223 (the <c-def>SO_SETFIB</c-def> option) for the listening socket. |
1229 This currently works only on FreeBSD. | 1224 This currently works only on FreeBSD. |
1230 </tag-desc> | 1225 </tag-desc> |
1231 | 1226 |
1232 <tag-name> | 1227 <tag-name> |
1242 | 1237 |
1243 <tag-name> | 1238 <tag-name> |
1244 <literal>rcvbuf</literal>=<value>size</value> | 1239 <literal>rcvbuf</literal>=<value>size</value> |
1245 </tag-name> | 1240 </tag-name> |
1246 <tag-desc> | 1241 <tag-desc> |
1247 sets receive buffer size | 1242 sets the receive buffer size |
1248 (the <c-def>SO_RCVBUF</c-def> option) for the listening socket. | 1243 (the <c-def>SO_RCVBUF</c-def> option) for the listening socket. |
1249 </tag-desc> | 1244 </tag-desc> |
1250 | 1245 |
1251 <tag-name> | 1246 <tag-name> |
1252 <literal>sndbuf</literal>=<value>size</value> | 1247 <literal>sndbuf</literal>=<value>size</value> |
1253 </tag-name> | 1248 </tag-name> |
1254 <tag-desc> | 1249 <tag-desc> |
1255 sets send buffer size | 1250 sets the send buffer size |
1256 (the <c-def>SO_SNDBUF</c-def> option) for the listening socket. | 1251 (the <c-def>SO_SNDBUF</c-def> option) for the listening socket. |
1257 </tag-desc> | 1252 </tag-desc> |
1258 | 1253 |
1259 <tag-name> | 1254 <tag-name> |
1260 <literal>accept_filter</literal>=<value>filter</value> | 1255 <literal>accept_filter</literal>=<value>filter</value> |
1261 </tag-name> | 1256 </tag-name> |
1262 <tag-desc> | 1257 <tag-desc> |
1263 sets the name of accept filter | 1258 sets the name of accept filter |
1264 (the <c-def>SO_ACCEPTFILTER</c-def> option) for the listening socket | 1259 (the <c-def>SO_ACCEPTFILTER</c-def> option) for the listening socket |
1265 that filters incoming connections before presenting them to | 1260 that filters incoming connections before passing them to |
1266 <c-func>accept</c-func>. | 1261 <c-func>accept</c-func>. |
1267 This works only on FreeBSD and NetBSD 5.0+. | 1262 This works only on FreeBSD and NetBSD 5.0+. |
1268 Acceptable values are | 1263 Possible values are |
1269 <link url="http://man.freebsd.org/accf_data">dataready</link> | 1264 <link url="http://man.freebsd.org/accf_data">dataready</link> |
1270 and | 1265 and |
1271 <link url="http://man.freebsd.org/accf_http">httpready</link>. | 1266 <link url="http://man.freebsd.org/accf_http">httpready</link>. |
1272 </tag-desc> | 1267 </tag-desc> |
1273 | 1268 |
1283 <literal>bind</literal> | 1278 <literal>bind</literal> |
1284 </tag-name> | 1279 </tag-name> |
1285 <tag-desc> | 1280 <tag-desc> |
1286 instructs to make a separate <c-func>bind</c-func> call for a given | 1281 instructs to make a separate <c-func>bind</c-func> call for a given |
1287 <value>address</value>:<value>port</value> pair. | 1282 <value>address</value>:<value>port</value> pair. |
1288 This is because nginx will <c-func>bind</c-func> only to | 1283 This is useful because if there are several <literal>listen</literal> |
1289 <literal>*:</literal><value>port</value> | 1284 directives with the same port but different addresses, and one of the |
1290 if there are several <literal>listen</literal> directives with | |
1291 the same port but different addresses, and one of the | |
1292 <literal>listen</literal> directives listens on all addresses | 1285 <literal>listen</literal> directives listens on all addresses |
1293 for the given port (<literal>*:</literal><value>port</value>). | 1286 for the given port (<literal>*:</literal><value>port</value>), nginx |
1294 It should be noted that in this case a <c-func>getsockname</c-func> | 1287 will <c-func>bind</c-func> only to <literal>*:</literal><value>port</value>. |
1295 system call will be made to determine an address that accepted a | 1288 It should be noted that in this case the address that accepted the |
1296 connection. | 1289 connection is determined by a <c-func>getsockname</c-func> system call. |
1297 If parameters <literal>backlog</literal>, <literal>rcvbuf</literal>, | 1290 If the <literal>backlog</literal>, <literal>rcvbuf</literal>, |
1298 <literal>sndbuf</literal>, <literal>accept_filter</literal>, | 1291 <literal>sndbuf</literal>, <literal>accept_filter</literal>, |
1299 <literal>deferred</literal>, or <literal>so_keepalive</literal> | 1292 <literal>deferred</literal>, or <literal>so_keepalive</literal> parameters |
1300 are used then for a given | 1293 are used then for a given |
1301 <value>address</value>:<value>port</value> pair | 1294 <value>address</value>:<value>port</value> pair |
1302 a separate <c-func>bind</c-func> call will always be made. | 1295 a separate <c-func>bind</c-func> call will always be made. |
1303 </tag-desc> | 1296 </tag-desc> |
1304 | 1297 |
1306 <literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal> | 1299 <literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal> |
1307 </tag-name> | 1300 </tag-name> |
1308 <tag-desc> | 1301 <tag-desc> |
1309 this parameter (0.7.42) determines | 1302 this parameter (0.7.42) determines |
1310 (via the <c-def>IPV6_V6ONLY</c-def> socket option) | 1303 (via the <c-def>IPV6_V6ONLY</c-def> socket option) |
1311 whether IPv6 socket listening on a wildcard address <literal>[::]</literal> | 1304 whether an IPv6 socket listening on a wildcard address <literal>[::]</literal> |
1312 will accept only IPv6 connections, or both IPv6 and IPv4 connections. | 1305 will accept only IPv6 connections or both IPv6 and IPv4 connections. |
1313 This parameter is turned on by default. | 1306 This parameter is turned on by default. |
1314 It can only be set once on start. | 1307 It can only be set once on start. |
1315 <note> | 1308 <note> |
1316 Prior to version 1.3.4, | 1309 Prior to version 1.3.4, |
1317 if this parameter was omitted then the operating system’s settings were | 1310 if this parameter was omitted then the operating system’s settings were |
1325 <tag-desc> | 1318 <tag-desc> |
1326 this parameter (1.1.11) configures the “TCP keepalive” behavior | 1319 this parameter (1.1.11) configures the “TCP keepalive” behavior |
1327 for the listening socket. | 1320 for the listening socket. |
1328 If this parameter is omitted then the operating system’s settings will be | 1321 If this parameter is omitted then the operating system’s settings will be |
1329 in effect for the socket. | 1322 in effect for the socket. |
1330 If set to the value “<literal>on</literal>”, the <c-def>SO_KEEPALIVE</c-def> | 1323 If it is set to the value “<literal>on</literal>”, the |
1331 socket option is turned on for the socket. | 1324 <c-def>SO_KEEPALIVE</c-def> option is turned on for the socket. |
1332 If set to the value “<literal>off</literal>”, the <c-def>SO_KEEPALIVE</c-def> | 1325 If it is set to the value “<literal>off</literal>”, the |
1333 socket option is turned off for the socket. | 1326 <c-def>SO_KEEPALIVE</c-def> option is turned off for the socket. |
1334 Some operating systems support tuning TCP keepalive parameters on a per-socket | 1327 Some operating systems support setting of TCP keepalive parameters on |
1335 basis using the <c-def>TCP_KEEPIDLE</c-def>, <c-def>TCP_KEEPINTVL</c-def>, | 1328 a per-socket basis using the <c-def>TCP_KEEPIDLE</c-def>, |
1336 and <c-def>TCP_KEEPCNT</c-def> socket options. | 1329 <c-def>TCP_KEEPINTVL</c-def>, and <c-def>TCP_KEEPCNT</c-def> socket options. |
1337 On such systems (currently, Linux 2.4+, NetBSD 5+, and | 1330 On such systems (currently, Linux 2.4+, NetBSD 5+, and |
1338 FreeBSD 9.0-STABLE) they can be configured | 1331 FreeBSD 9.0-STABLE), they can be configured |
1339 using the <value>keepidle</value>, <value>keepintvl</value>, and | 1332 using the <value>keepidle</value>, <value>keepintvl</value>, and |
1340 <value>keepcnt</value> parameters. | 1333 <value>keepcnt</value> parameters. |
1341 One or two parameters may be omitted, in which case the system default setting | 1334 One or two parameters may be omitted, in which case the system default setting |
1342 for the corresponding socket option will be in effect. | 1335 for the corresponding socket option will be in effect. |
1343 For example, | 1336 For example, |
1344 <example>so_keepalive=30m::10</example> | 1337 <example>so_keepalive=30m::10</example> |
1345 will set idle timeout (<c-def>TCP_KEEPIDLE</c-def>) to 30 minutes, | 1338 will set the idle timeout (<c-def>TCP_KEEPIDLE</c-def>) to 30 minutes, |
1346 leave probe interval (<c-def>TCP_KEEPINTVL</c-def>) at its system default, | 1339 leave the probe interval (<c-def>TCP_KEEPINTVL</c-def>) at its system default, |
1347 and set probes count (<c-def>TCP_KEEPCNT</c-def>) to 10 probes. | 1340 and set the probes count (<c-def>TCP_KEEPCNT</c-def>) to 10 probes. |
1348 </tag-desc> | 1341 </tag-desc> |
1349 | 1342 |
1350 </list> | 1343 </list> |
1351 </para> | 1344 </para> |
1352 | 1345 |
1371 <default/> | 1364 <default/> |
1372 <context>server</context> | 1365 <context>server</context> |
1373 <context>location</context> | 1366 <context>location</context> |
1374 | 1367 |
1375 <para> | 1368 <para> |
1376 Sets a configuration based on a request URI. | 1369 Sets configuration depending on a request URI. |
1377 </para> | 1370 </para> |
1378 | 1371 |
1379 <para> | 1372 <para> |
1380 The matching is performed against a normalized URI, | 1373 The matching is performed against a normalized URI, |
1381 after decoding a text encoded in the “<literal>%XX</literal>” form, | 1374 after decoding the text encoded in the “<literal>%XX</literal>” form, |
1382 resolving references to relative path components “<literal>.</literal>” | 1375 resolving references to relative path components “<literal>.</literal>” |
1383 and “<literal>..</literal>”, and possible | 1376 and “<literal>..</literal>”, and possible |
1384 <link id="merge_slashes">compression</link> of two or more | 1377 <link id="merge_slashes">compression</link> of two or more |
1385 adjacent slashes into a single slash. | 1378 adjacent slashes into a single slash. |
1386 </para> | 1379 </para> |
1387 | 1380 |
1388 <para> | 1381 <para> |
1389 A location can either be defined by a prefix string, or by a regular expression. | 1382 A location can either be defined by a prefix string, or by a regular expression. |
1390 Regular expressions are specified by prepending them with the | 1383 Regular expressions are specified with the preceding |
1391 “<literal>~*</literal>” modifier (for case-insensitive matching), or with the | 1384 “<literal>~*</literal>” modifier (for case-insensitive matching), or the |
1392 “<literal>~</literal>” modifier (for case-sensitive matching). | 1385 “<literal>~</literal>” modifier (for case-sensitive matching). |
1393 To find a location matching a given request, nginx first checks | 1386 To find location matching a given request, nginx first checks |
1394 locations defined using the prefix strings (prefix locations). | 1387 locations defined using the prefix strings (prefix locations). |
1395 Among them, the most specific one is searched. | 1388 Among them, the location with the longest matching |
1389 prefix is selected and remembered. | |
1396 Then regular expressions are checked, in the order of their appearance | 1390 Then regular expressions are checked, in the order of their appearance |
1397 in a configuration file. | 1391 in the configuration file. |
1398 A search of regular expressions terminates on the first match, | 1392 The search of regular expressions terminates on the first match, |
1399 and the corresponding configuration is used. | 1393 and the corresponding configuration is used. |
1400 If no match with a regular expression is found then a | 1394 If no match with a regular expression is found then the |
1401 configuration of the most specific prefix location is used. | 1395 configuration of the prefix location remembered earlier is used. |
1402 </para> | 1396 </para> |
1403 | 1397 |
1404 <para> | 1398 <para> |
1405 Locations can be nested, with some exceptions mentioned below. | 1399 <literal>location</literal> blocks can be nested, with some exceptions |
1400 mentioned below. | |
1406 </para> | 1401 </para> |
1407 | 1402 |
1408 <para> | 1403 <para> |
1409 For case-insensitive operating systems such as Mac OS X and Cygwin, | 1404 For case-insensitive operating systems such as Mac OS X and Cygwin, |
1410 matching with prefix strings ignores a case (0.7.7). | 1405 matching with prefix strings ignores a case (0.7.7). |
1415 Regular expressions can contain captures (0.7.40) that can later | 1410 Regular expressions can contain captures (0.7.40) that can later |
1416 be used in other directives. | 1411 be used in other directives. |
1417 </para> | 1412 </para> |
1418 | 1413 |
1419 <para> | 1414 <para> |
1420 If the most specific prefix location has the “<literal>^~</literal>” modifier | 1415 If the longest matching prefix location has the “<literal>^~</literal>” modifier |
1421 then regular expressions are not checked. | 1416 then regular expressions are not checked. |
1422 </para> | 1417 </para> |
1423 | 1418 |
1424 <para> | 1419 <para> |
1425 Also, using the “<literal>=</literal>” modifier it is possible to define | 1420 Also, using the “<literal>=</literal>” modifier it is possible to define |
1440 not checked. | 1435 not checked. |
1441 </note> | 1436 </note> |
1442 </para> | 1437 </para> |
1443 | 1438 |
1444 <para> | 1439 <para> |
1445 Let’s illustrate the above by example: | 1440 Let’s illustrate the above by an example: |
1446 <example> | 1441 <example> |
1447 location = / { | 1442 location = / { |
1448 [ configuration A ] | 1443 [ configuration A ] |
1449 } | 1444 } |
1450 | 1445 |
1489 <link doc="ngx_http_memcached_module.xml" id="memcached_pass"/>, | 1484 <link doc="ngx_http_memcached_module.xml" id="memcached_pass"/>, |
1490 then in response to a request with URI equal to this string, | 1485 then in response to a request with URI equal to this string, |
1491 but without the trailing slash, | 1486 but without the trailing slash, |
1492 a permanent redirect with the code 301 will be returned to the requested URI | 1487 a permanent redirect with the code 301 will be returned to the requested URI |
1493 with the slash appended. | 1488 with the slash appended. |
1494 If this is undesired, an exact match of the URI and location could be | 1489 If this is not desired, an exact match of the URI and location could be |
1495 defined like this: | 1490 defined like this: |
1496 <example> | 1491 <example> |
1497 location /user/ { | 1492 location /user/ { |
1498 proxy_pass http://user.example.com; | 1493 proxy_pass http://user.example.com; |
1499 } | 1494 } |
1517 <context>http</context> | 1512 <context>http</context> |
1518 <context>server</context> | 1513 <context>server</context> |
1519 <context>location</context> | 1514 <context>location</context> |
1520 | 1515 |
1521 <para> | 1516 <para> |
1522 Enables or disables logging of errors about not found files into the | 1517 Enables or disables logging of errors about not found files into |
1523 <link doc="../ngx_core_module.xml" id="error_log"/>. | 1518 <link doc="../ngx_core_module.xml" id="error_log"/>. |
1524 </para> | 1519 </para> |
1525 | 1520 |
1526 </directive> | 1521 </directive> |
1527 | 1522 |
1532 <context>http</context> | 1527 <context>http</context> |
1533 <context>server</context> | 1528 <context>server</context> |
1534 <context>location</context> | 1529 <context>location</context> |
1535 | 1530 |
1536 <para> | 1531 <para> |
1537 Enables or disables logging of subrequests into the | 1532 Enables or disables logging of subrequests into |
1538 <link doc="ngx_http_log_module.xml" id="access_log"/>. | 1533 <link doc="ngx_http_log_module.xml" id="access_log"/>. |
1539 </para> | 1534 </para> |
1540 | 1535 |
1541 </directive> | 1536 </directive> |
1542 | 1537 |
1551 | 1546 |
1552 <para> | 1547 <para> |
1553 Limits the maximum allowed number of ranges in byte-range requests. | 1548 Limits the maximum allowed number of ranges in byte-range requests. |
1554 Requests that exceed the limit are processed as if there were no | 1549 Requests that exceed the limit are processed as if there were no |
1555 byte ranges specified. | 1550 byte ranges specified. |
1556 By default, there is no limit. | 1551 By default, the number of ranges is not limited. |
1557 The value of zero disables the byte-range support completely. | 1552 The zero value disables the byte-range support completely. |
1558 </para> | 1553 </para> |
1559 | 1554 |
1560 </directive> | 1555 </directive> |
1561 | 1556 |
1562 | 1557 |
1570 Enables or disables compression of two or more adjacent slashes | 1565 Enables or disables compression of two or more adjacent slashes |
1571 in a URI into a single slash. | 1566 in a URI into a single slash. |
1572 </para> | 1567 </para> |
1573 | 1568 |
1574 <para> | 1569 <para> |
1575 Note that compression is essential for the correct prefix string | 1570 Note that compression is essential for the correct matching of prefix string |
1576 and regular expressions location matching. | 1571 and regular expression locations. |
1577 Without it, the “<literal>//scripts/one.php</literal>” request would not match | 1572 Without it, the “<literal>//scripts/one.php</literal>” request would not match |
1578 <example> | 1573 <example> |
1579 location /scripts/ { | 1574 location /scripts/ { |
1580 ... | 1575 ... |
1581 } | 1576 } |
1582 </example> | 1577 </example> |
1583 and might be processed as a static file, | 1578 and might be processed as a static file. |
1584 so it gets converted to “<literal>/scripts/one.php</literal>”. | 1579 So it gets converted to “<literal>/scripts/one.php</literal>”. |
1585 </para> | 1580 </para> |
1586 | 1581 |
1587 <para> | 1582 <para> |
1588 Turning the compression <literal>off</literal> can become necessary if a URI | 1583 Turning the compression <literal>off</literal> can become necessary if a URI |
1589 contains base64-encoded names, since base64 uses the “<literal>/</literal>” | 1584 contains base64-encoded names, since base64 uses the “<literal>/</literal>” |
1590 character internally. | 1585 character internally. |
1591 However, for security considerations, it is better to avoid turning off | 1586 However, for security considerations, it is better to avoid turning |
1592 the compression. | 1587 the compression off. |
1593 </para> | 1588 </para> |
1594 | 1589 |
1595 <para> | 1590 <para> |
1596 A directive can be specified on the <link id="server"/> level | 1591 A directive can be specified on the <link id="server"/> level |
1597 in a default server. | 1592 in the default server. |
1598 In this case, its value will cover all virtual servers | 1593 In this case, its value will apply to all virtual servers |
1599 listening on the same address and port. | 1594 listening on the same address and port. |
1600 </para> | 1595 </para> |
1601 | 1596 |
1602 </directive> | 1597 </directive> |
1603 | 1598 |
1608 <context>http</context> | 1603 <context>http</context> |
1609 <context>server</context> | 1604 <context>server</context> |
1610 <context>location</context> | 1605 <context>location</context> |
1611 | 1606 |
1612 <para> | 1607 <para> |
1613 Enables or disables adding of comments to responses with status | 1608 Enables or disables adding comments to responses for MSIE clients with status |
1614 greater than 400 for MSIE clients, to pad the response size to 512 bytes. | 1609 greater than 400 to increase the response size to 512 bytes. |
1615 </para> | 1610 </para> |
1616 | 1611 |
1617 </directive> | 1612 </directive> |
1618 | 1613 |
1619 | 1614 |
1623 <context>http</context> | 1618 <context>http</context> |
1624 <context>server</context> | 1619 <context>server</context> |
1625 <context>location</context> | 1620 <context>location</context> |
1626 | 1621 |
1627 <para> | 1622 <para> |
1628 Enables or disables issuing refreshes instead of redirects, for MSIE clients. | 1623 Enables or disables issuing refreshes instead of redirects for MSIE clients. |
1629 </para> | 1624 </para> |
1630 | 1625 |
1631 </directive> | 1626 </directive> |
1632 | 1627 |
1633 | 1628 |
1648 <listitem> | 1643 <listitem> |
1649 open file descriptors, their sizes and modification times; | 1644 open file descriptors, their sizes and modification times; |
1650 </listitem> | 1645 </listitem> |
1651 | 1646 |
1652 <listitem> | 1647 <listitem> |
1653 directory lookups; | 1648 information on existence of directories; |
1654 </listitem> | 1649 </listitem> |
1655 | 1650 |
1656 <listitem> | 1651 <listitem> |
1657 file lookup errors, such as “file not found”, “no read permission”, | 1652 file lookup errors, such as “file not found”, “no read permission”, |
1658 and so on. | 1653 and so on. |
1673 <tag-name> | 1668 <tag-name> |
1674 <literal>max</literal> | 1669 <literal>max</literal> |
1675 </tag-name> | 1670 </tag-name> |
1676 <tag-desc> | 1671 <tag-desc> |
1677 sets the maximum number of elements in the cache; | 1672 sets the maximum number of elements in the cache; |
1678 on cache overflow the least recently used (LRU) elements get removed; | 1673 on cache overflow the least recently used (LRU) elements are removed; |
1679 </tag-desc> | 1674 </tag-desc> |
1680 | 1675 |
1681 <tag-name> | 1676 <tag-name> |
1682 <literal>inactive</literal> | 1677 <literal>inactive</literal> |
1683 </tag-name> | 1678 </tag-name> |
1684 <tag-desc> | 1679 <tag-desc> |
1685 defines a time, after which an element gets removed from the cache | 1680 defines a time after which an element is removed from the cache |
1686 if there were no accesses to it during this time; | 1681 if it has not been accessed during this time; |
1687 by default, it is 60 seconds; | 1682 by default, it is 60 seconds; |
1688 </tag-desc> | 1683 </tag-desc> |
1689 | 1684 |
1690 <tag-name> | 1685 <tag-name> |
1691 <literal>off</literal> | 1686 <literal>off</literal> |
1762 <context>location</context> | 1757 <context>location</context> |
1763 | 1758 |
1764 <para> | 1759 <para> |
1765 Sets the minimum <value>number</value> of file accesses during | 1760 Sets the minimum <value>number</value> of file accesses during |
1766 the period configured by the <literal>inactive</literal> parameter | 1761 the period configured by the <literal>inactive</literal> parameter |
1767 of the <link id="open_file_cache"/> directive, | 1762 of the <link id="open_file_cache"/> directive, required for a file |
1768 after which a file descriptor will remain open in the cache. | 1763 descriptor to remain open in the cache. |
1769 </para> | 1764 </para> |
1770 | 1765 |
1771 </directive> | 1766 </directive> |
1772 | 1767 |
1773 | 1768 |
1798 <default>off</default> | 1793 <default>off</default> |
1799 <context>http</context> | 1794 <context>http</context> |
1800 <context>server</context> | 1795 <context>server</context> |
1801 | 1796 |
1802 <para> | 1797 <para> |
1803 This directive is made obsolete by the | 1798 This directive is obsolete. |
1804 <link id="server_name_in_redirect"/> directive. | 1799 The <link id="server_name_in_redirect"/> directive should be used instead. |
1805 </para> | 1800 </para> |
1806 | 1801 |
1807 <!-- | 1802 <!-- |
1808 <para> | 1803 <para> |
1809 Enables or disables optimization of hostname checking in name-based | 1804 Enables or disables optimization of hostname checking in name-based |
1831 <para> | 1826 <para> |
1832 Enables or disables specifying the port in redirects issued by nginx. | 1827 Enables or disables specifying the port in redirects issued by nginx. |
1833 </para> | 1828 </para> |
1834 | 1829 |
1835 <para> | 1830 <para> |
1836 The use of a primary server name in redirects is controlled by | 1831 The use of the primary server name in redirects is controlled by |
1837 the <link id="server_name_in_redirect"/> directive. | 1832 the <link id="server_name_in_redirect"/> directive. |
1838 </para> | 1833 </para> |
1839 | 1834 |
1840 </directive> | 1835 </directive> |
1841 | 1836 |
1846 <context>http</context> | 1841 <context>http</context> |
1847 <context>server</context> | 1842 <context>server</context> |
1848 <context>location</context> | 1843 <context>location</context> |
1849 | 1844 |
1850 <para> | 1845 <para> |
1851 If possible, the output of client data will be postponed until | 1846 If possible, the transmission of client data will be postponed until |
1852 nginx has at least <value>size</value> bytes of data to send. | 1847 nginx has at least <value>size</value> bytes of data to send. |
1853 Value of zero disables postponing. | 1848 The zero value disables postponing data transmission. |
1854 </para> | 1849 </para> |
1855 | 1850 |
1856 </directive> | 1851 </directive> |
1857 | 1852 |
1858 | 1853 |
1862 <context>http</context> | 1857 <context>http</context> |
1863 <context>server</context> | 1858 <context>server</context> |
1864 <context>location</context> | 1859 <context>location</context> |
1865 | 1860 |
1866 <para> | 1861 <para> |
1867 Sets the amount of pre-reading when working with files, in the kernel. | 1862 Sets the amount of pre-reading for the kernel when working with file. |
1868 </para> | 1863 </para> |
1869 | 1864 |
1870 <para> | 1865 <para> |
1871 On Linux, the | 1866 On Linux, the |
1872 <literal>posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)</literal> | 1867 <literal>posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)</literal> |
1873 system call is used, so the <value>size</value> parameter is ignored. | 1868 system call is used, and so the <value>size</value> parameter is ignored. |
1874 </para> | 1869 </para> |
1875 | 1870 |
1876 <para> | 1871 <para> |
1877 On FreeBSD, the | 1872 On FreeBSD, the |
1878 <literal>fcntl(O_READAHEAD,</literal> | 1873 <literal>fcntl(O_READAHEAD,</literal> |
1879 <value>size</value><literal>)</literal> | 1874 <value>size</value><literal>)</literal> |
1880 system call is used, supported in FreeBSD 9.0-CURRENT. | 1875 system call, supported since FreeBSD 9.0-CURRENT, is used. |
1881 FreeBSD 7 needs to be | 1876 FreeBSD 7 has to be |
1882 <link url="http://sysoev.ru/freebsd/patch.readahead.txt">patched</link>. | 1877 <link url="http://sysoev.ru/freebsd/patch.readahead.txt">patched</link>. |
1883 </para> | 1878 </para> |
1884 | 1879 |
1885 </directive> | 1880 </directive> |
1886 | 1881 |
1894 | 1889 |
1895 <para> | 1890 <para> |
1896 Enables or disables doing several redirects using the | 1891 Enables or disables doing several redirects using the |
1897 <link id="error_page"/> | 1892 <link id="error_page"/> |
1898 directive. | 1893 directive. |
1899 There is a <link id="internal">limit</link> on a number of such redirects. | 1894 The number of such redirects is <link id="internal">limited</link>. |
1900 </para> | 1895 </para> |
1901 | 1896 |
1902 </directive> | 1897 </directive> |
1903 | 1898 |
1904 | 1899 |
1907 <default>4k</default> | 1902 <default>4k</default> |
1908 <context>http</context> | 1903 <context>http</context> |
1909 <context>server</context> | 1904 <context>server</context> |
1910 | 1905 |
1911 <para> | 1906 <para> |
1912 Allows to fine tune per-request memory allocations. | 1907 Allows accurate tuning of per-request memory allocations. |
1913 This directive has minimal impact on performance, | 1908 This directive has minimal impact on performance |
1914 and should not generally be used. | 1909 and should not generally be used. |
1915 </para> | 1910 </para> |
1916 | 1911 |
1917 </directive> | 1912 </directive> |
1918 | 1913 |
1923 <context>http</context> | 1918 <context>http</context> |
1924 <context>server</context> | 1919 <context>server</context> |
1925 <context>location</context> | 1920 <context>location</context> |
1926 | 1921 |
1927 <para> | 1922 <para> |
1928 Enables or disables resetting of timed out connections. | 1923 Enables or disables resetting timed out connections. |
1929 The reset is performed as follows: before closing a socket, the | 1924 The reset is performed as follows. |
1925 Before closing a socket, the | |
1930 <c-def>SO_LINGER</c-def> | 1926 <c-def>SO_LINGER</c-def> |
1931 option is set on it with a timeout value of 0. | 1927 option is set on it with a timeout value of 0. |
1932 When the socket is closed, a client is sent TCP RST, and all memory | 1928 When the socket is closed, TCP RST is sent to the client, and all memory |
1933 occupied by this socket is freed. | 1929 occupied by this socket is released. |
1934 This avoids keeping of an already closed socket with filled buffers | 1930 This helps avoid keeping an already closed socket with filled buffers |
1935 for a long time, in a FIN_WAIT1 state. | 1931 in a FIN_WAIT1 state for a long time. |
1936 </para> | 1932 </para> |
1937 | 1933 |
1938 <para> | 1934 <para> |
1939 It should be noted that timed out keep-alive connections are still | 1935 It should be noted that timed out keep-alive connections are |
1940 closed normally. | 1936 closed normally. |
1941 </para> | 1937 </para> |
1942 | 1938 |
1943 </directive> | 1939 </directive> |
1944 | 1940 |
1966 Before version 1.1.7, only a single name server could be configured. | 1962 Before version 1.1.7, only a single name server could be configured. |
1967 Specifying name servers using IPv6 addresses is supported | 1963 Specifying name servers using IPv6 addresses is supported |
1968 starting from versions 1.3.1 and 1.2.2. | 1964 starting from versions 1.3.1 and 1.2.2. |
1969 </note> | 1965 </note> |
1970 By default, nginx caches answers using the TTL value of a response. | 1966 By default, nginx caches answers using the TTL value of a response. |
1971 An optional <literal>valid</literal> parameter allows to override it: | 1967 An optional <literal>valid</literal> parameter allows overriding it: |
1972 <example> | 1968 <example> |
1973 resolver 127.0.0.1 [::1]:5353 valid=30s; | 1969 resolver 127.0.0.1 [::1]:5353 valid=30s; |
1974 </example> | 1970 </example> |
1975 <note> | 1971 <note> |
1976 Before version 1.1.9, tuning of caching time was not possible, | 1972 Before version 1.1.9, tuning of caching time was not possible, |
2012 <example> | 2008 <example> |
2013 location /i/ { | 2009 location /i/ { |
2014 root /data/w3; | 2010 root /data/w3; |
2015 } | 2011 } |
2016 </example> | 2012 </example> |
2017 “<literal>/i/top.gif</literal>” will be responded | 2013 The <path>/data/w3/i/top.gif</path> file will be sent in response to |
2018 with the file | 2014 the “<literal>/i/top.gif</literal>” request. |
2019 <path>/data/w3/i/top.gif</path>. | 2015 </para> |
2020 </para> | 2016 |
2021 | 2017 <para> |
2022 <para> | 2018 The <value>path</value> value can contain variables, |
2023 The <value>path</value> value can contain variables | |
2024 except <var>$document_root</var> and <var>$realpath_root</var>. | 2019 except <var>$document_root</var> and <var>$realpath_root</var>. |
2025 </para> | 2020 </para> |
2026 | 2021 |
2027 <para> | 2022 <para> |
2028 A path to the file is constructed by merely adding a URI to the value | 2023 A path to the file is constructed by merely adding a URI to the value |
2029 of the <literal>root</literal> directive. | 2024 of the <literal>root</literal> directive. |
2030 If a URI need to be modified, the | 2025 If a URI has to be modified, the |
2031 <link id="alias"/> directive should be used. | 2026 <link id="alias"/> directive should be used. |
2032 </para> | 2027 </para> |
2033 | 2028 |
2034 </directive> | 2029 </directive> |
2035 | 2030 |
2040 <context>http</context> | 2035 <context>http</context> |
2041 <context>server</context> | 2036 <context>server</context> |
2042 <context>location</context> | 2037 <context>location</context> |
2043 | 2038 |
2044 <para> | 2039 <para> |
2045 Allows access if <literal>all</literal> or <literal>any</literal> of the | 2040 Allows access if both (<literal>all</literal>) or at least one |
2041 (<literal>any</literal>) of the | |
2046 <link doc="ngx_http_access_module.xml">ngx_http_access_module</link> | 2042 <link doc="ngx_http_access_module.xml">ngx_http_access_module</link> |
2047 or <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link> | 2043 or <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link> |
2048 modules grant access. | 2044 modules allow access. |
2049 </para> | 2045 </para> |
2050 | 2046 |
2051 <para> | 2047 <para> |
2052 Example: | 2048 Example: |
2053 <example> | 2049 <example> |
2087 <context>http</context> | 2083 <context>http</context> |
2088 <context>server</context> | 2084 <context>server</context> |
2089 <context>location</context> | 2085 <context>location</context> |
2090 | 2086 |
2091 <para> | 2087 <para> |
2092 If set to a non-zero value, nginx will try to minimize the number | 2088 If the directive is set to a non-zero value, nginx will try to minimize |
2093 of send operations on client sockets by using either | 2089 the number of send operations on client sockets by using either |
2094 <c-def>NOTE_LOWAT</c-def> flag of the | 2090 <c-def>NOTE_LOWAT</c-def> flag of the |
2095 <link doc="../events.xml" id="kqueue"/> method, | 2091 <link doc="../events.xml" id="kqueue"/> method |
2096 or the <c-def>SO_SNDLOWAT</c-def> socket option, | 2092 or the <c-def>SO_SNDLOWAT</c-def> socket option. |
2097 with the specified <value>size</value>. | 2093 In both cases the specified <value>size</value> is used. |
2098 </para> | 2094 </para> |
2099 | 2095 |
2100 <para> | 2096 <para> |
2101 This directive is ignored on Linux, Solaris, and Windows. | 2097 This directive is ignored on Linux, Solaris, and Windows. |
2102 </para> | 2098 </para> |
2148 <context>location</context> | 2144 <context>location</context> |
2149 | 2145 |
2150 <para> | 2146 <para> |
2151 When set to a non-zero value, limits the amount of data that can be | 2147 When set to a non-zero value, limits the amount of data that can be |
2152 transferred in a single <c-func>sendfile</c-func> call. | 2148 transferred in a single <c-func>sendfile</c-func> call. |
2153 Without the limit, one fast connection may seize the worker process. | 2149 Without the limit, one fast connection may seize the worker process entirely. |
2154 </para> | 2150 </para> |
2155 | 2151 |
2156 </directive> | 2152 </directive> |
2157 | 2153 |
2158 | 2154 |
2160 <syntax block="yes"/> | 2156 <syntax block="yes"/> |
2161 <default/> | 2157 <default/> |
2162 <context>http</context> | 2158 <context>http</context> |
2163 | 2159 |
2164 <para> | 2160 <para> |
2165 Sets a configuration for the virtual server. | 2161 Sets configuration for a virtual server. |
2166 There is no clean separation between IP-based (based on the IP address) | 2162 There is no clear separation between IP-based (based on the IP address) |
2167 and name-based (based on the <header>Host</header> request header field) | 2163 and name-based (based on the <header>Host</header> request header field) |
2168 virtual servers. | 2164 virtual servers. |
2169 Instead, the <link id="listen"/> directives describe all | 2165 Instead, the <link id="listen"/> directives describe all |
2170 addresses and ports that should accept connections for a server, and the | 2166 addresses and ports that should accept connections for the server, and the |
2171 <link id="server_name"/> directive lists all server names. | 2167 <link id="server_name"/> directive lists all server names. |
2172 Example configurations are provided in the | 2168 Example configurations are provided in the |
2173 “<link doc="request_processing.xml"/>” document. | 2169 “<link doc="request_processing.xml"/>” document. |
2174 </para> | 2170 </para> |
2175 | 2171 |
2180 <syntax><value>name</value> ...</syntax> | 2176 <syntax><value>name</value> ...</syntax> |
2181 <default>""</default> | 2177 <default>""</default> |
2182 <context>server</context> | 2178 <context>server</context> |
2183 | 2179 |
2184 <para> | 2180 <para> |
2185 Sets names of the virtual server, for example: | 2181 Sets names of a virtual server, for example: |
2186 <example> | 2182 <example> |
2187 server { | 2183 server { |
2188 server_name example.com www.example.com; | 2184 server_name example.com www.example.com; |
2189 } | 2185 } |
2190 </example> | 2186 </example> |
2194 The first name becomes the primary server name. | 2190 The first name becomes the primary server name. |
2195 </para> | 2191 </para> |
2196 | 2192 |
2197 <para> | 2193 <para> |
2198 Server names can include an asterisk (“<literal>*</literal>”) | 2194 Server names can include an asterisk (“<literal>*</literal>”) |
2199 to replace the first or last part of a name: | 2195 replacing the first or last part of a name: |
2200 <example> | 2196 <example> |
2201 server { | 2197 server { |
2202 server_name example.com *.example.com www.example.*; | 2198 server_name example.com *.example.com www.example.*; |
2203 } | 2199 } |
2204 </example> | 2200 </example> |
2205 Such names are called wildcard names. | 2201 Such names are called wildcard names. |
2206 </para> | 2202 </para> |
2207 | 2203 |
2208 <para> | 2204 <para> |
2209 The first two of the above mentioned names can be combined: | 2205 The first two of the names mentioned above can be combined in one: |
2210 <example> | 2206 <example> |
2211 server { | 2207 server { |
2212 server_name .example.com; | 2208 server_name .example.com; |
2213 } | 2209 } |
2214 </example> | 2210 </example> |
2215 </para> | 2211 </para> |
2216 | 2212 |
2217 <para> | 2213 <para> |
2218 It is also possible to use regular expressions in server names, | 2214 It is also possible to use regular expressions in server names, |
2219 prepending the name with a tilde (“<literal>~</literal>”): | 2215 preceeding the name with a tilde (“<literal>~</literal>”): |
2220 <example> | 2216 <example> |
2221 server { | 2217 server { |
2222 server_name www.example.com ~^www\d+\.example\.com$; | 2218 server_name www.example.com ~^www\d+\.example\.com$; |
2223 } | 2219 } |
2224 </example> | 2220 </example> |
2267 } | 2263 } |
2268 </example> | 2264 </example> |
2269 </para> | 2265 </para> |
2270 | 2266 |
2271 <para> | 2267 <para> |
2272 If the parameter equals “<var>$hostname</var>” (0.9.4), the | 2268 If the directive’s parameter is set to “<var>$hostname</var>” (0.9.4), the |
2273 machine’s hostname is substituted. | 2269 machine’s hostname is inserted. |
2274 </para> | 2270 </para> |
2275 | 2271 |
2276 <para> | 2272 <para> |
2277 It is also possible to specify an empty server name (0.7.11): | 2273 It is also possible to specify an empty server name (0.7.11): |
2278 <example> | 2274 <example> |
2279 server { | 2275 server { |
2280 server_name www.example.com ""; | 2276 server_name www.example.com ""; |
2281 } | 2277 } |
2282 </example> | 2278 </example> |
2283 It allows this server to process requests without the <header>Host</header> | 2279 It allows this server to process requests without the <header>Host</header> |
2284 header field, instead of the default server for the given address:port pair. | 2280 header field — instead of the default server — for the given address:port pair. |
2285 This is the default setting. | 2281 This is the default setting. |
2286 <note> | 2282 <note> |
2287 Before 0.8.48, the machine’s hostname was used by default. | 2283 Before 0.8.48, the machine’s hostname was used by default. |
2288 </note> | 2284 </note> |
2289 </para> | 2285 </para> |
2290 | 2286 |
2291 <para> | 2287 <para> |
2292 When searching for a virtual server by name, | 2288 During searching for a virtual server by name, |
2293 if name matches more than one of the specified variants, | 2289 if the name matches more than one of the specified variants, |
2294 e.g. both wildcard name and regular expression match, the first matching | 2290 (e.g. both a wildcard name and regular expression match), the first matching |
2295 variant will be chosen, in the following order of precedence: | 2291 variant will be chosen, in the following order of priority: |
2296 <list type="enum"> | 2292 <list type="enum"> |
2297 | 2293 |
2298 <listitem> | 2294 <listitem> |
2299 exact name | 2295 the exact name |
2300 </listitem> | 2296 </listitem> |
2301 | 2297 |
2302 <listitem> | 2298 <listitem> |
2303 longest wildcard name starting with an asterisk, | 2299 the longest wildcard name starting with an asterisk, |
2304 e.g. “<literal>*.example.com</literal>” | 2300 e.g. “<literal>*.example.com</literal>” |
2305 </listitem> | 2301 </listitem> |
2306 | 2302 |
2307 <listitem> | 2303 <listitem> |
2308 longest wildcard name ending with an asterisk, | 2304 the longest wildcard name ending with an asterisk, |
2309 e.g. “<literal>mail.*</literal>” | 2305 e.g. “<literal>mail.*</literal>” |
2310 </listitem> | 2306 </listitem> |
2311 | 2307 |
2312 <listitem> | 2308 <listitem> |
2313 first matching regular expression | 2309 the first matching regular expression |
2314 (in order of appearance in a configuration file) | 2310 (in order of appearance in the configuration file) |
2315 </listitem> | 2311 </listitem> |
2316 | 2312 |
2317 </list> | 2313 </list> |
2318 </para> | 2314 </para> |
2319 | 2315 |
2334 | 2330 |
2335 <para> | 2331 <para> |
2336 Enables or disables the use of the primary server name, specified by the | 2332 Enables or disables the use of the primary server name, specified by the |
2337 <link id="server_name"/> | 2333 <link id="server_name"/> |
2338 directive, in redirects issued by nginx. | 2334 directive, in redirects issued by nginx. |
2339 When disabled, the name from the <header>Host</header> request header field | 2335 When the use of the primary server name is disabled, the name from the |
2340 is used. | 2336 <header>Host</header> request header field is used. |
2341 If this field is not present, an IP address of the server is used. | 2337 If this field is not present, the IP address of the server is used. |
2342 </para> | 2338 </para> |
2343 | 2339 |
2344 <para> | 2340 <para> |
2345 The use of a port in redirects is controlled by | 2341 The use of a port in redirects is controlled by |
2346 the <link id="port_in_redirect"/> directive. | 2342 the <link id="port_in_redirect"/> directive. |
2354 <default>32|64|128</default> | 2350 <default>32|64|128</default> |
2355 <context>http</context> | 2351 <context>http</context> |
2356 | 2352 |
2357 <para> | 2353 <para> |
2358 Sets the bucket size for the server names hash tables. | 2354 Sets the bucket size for the server names hash tables. |
2359 Default value depends on the size of the processor’s cache line. | 2355 The default value depends on the size of the processor’s cache line. |
2360 Details of setting up hash tables are provided in a separate | 2356 Details of setting up hash tables are provided in a separate |
2361 <link doc="../hash.xml">document</link>. | 2357 <link doc="../hash.xml">document</link>. |
2362 </para> | 2358 </para> |
2363 | 2359 |
2364 </directive> | 2360 </directive> |
2384 <context>http</context> | 2380 <context>http</context> |
2385 <context>server</context> | 2381 <context>server</context> |
2386 <context>location</context> | 2382 <context>location</context> |
2387 | 2383 |
2388 <para> | 2384 <para> |
2389 Enables or disables emitting of nginx version in error messages and in the | 2385 Enables or disables emitting nginx version in error messages and in the |
2390 <header>Server</header> response header field. | 2386 <header>Server</header> response header field. |
2391 </para> | 2387 </para> |
2392 | 2388 |
2393 </directive> | 2389 </directive> |
2394 | 2390 |
2418 | 2414 |
2419 <para> | 2415 <para> |
2420 Enables or disables the use of | 2416 Enables or disables the use of |
2421 the <c-def>TCP_NOPUSH</c-def> socket option on FreeBSD | 2417 the <c-def>TCP_NOPUSH</c-def> socket option on FreeBSD |
2422 or the <c-def>TCP_CORK</c-def> socket option on Linux. | 2418 or the <c-def>TCP_CORK</c-def> socket option on Linux. |
2423 Options are enabled only when <link id="sendfile"/> is used. | 2419 The options are enabled only when <link id="sendfile"/> is used. |
2424 Enabling the option allows to | 2420 Enabling the option allows |
2425 <list type="bullet"> | 2421 <list type="bullet"> |
2426 | 2422 |
2427 <listitem> | 2423 <listitem> |
2428 send the response header and the beginning of a file in one packet, | 2424 sending the response header and the beginning of a file in one packet, |
2429 on Linux and FreeBSD 4.*; | 2425 on Linux and FreeBSD 4.*; |
2430 </listitem> | 2426 </listitem> |
2431 | 2427 |
2432 <listitem> | 2428 <listitem> |
2433 send a file in full packets. | 2429 sending a file in full packets. |
2434 </listitem> | 2430 </listitem> |
2435 | 2431 |
2436 </list> | 2432 </list> |
2437 </para> | 2433 </para> |
2438 | 2434 |
2445 <default/> | 2441 <default/> |
2446 <context>server</context> | 2442 <context>server</context> |
2447 <context>location</context> | 2443 <context>location</context> |
2448 | 2444 |
2449 <para> | 2445 <para> |
2450 Checks the existence of files in the specified order, and uses | 2446 Checks the existence of files in the specified order and uses |
2451 the first found file for request processing; the processing | 2447 the first found file for request processing; the processing |
2452 is performed in the current context. | 2448 is performed in the current context. |
2453 A path to the file is constructed from the | 2449 The path to a file is constructed from the |
2454 <value>file</value> parameter | 2450 <value>file</value> parameter |
2455 according to the | 2451 according to the |
2456 <link id="root"/> and <link id="alias"/> directives. | 2452 <link id="root"/> and <link id="alias"/> directives. |
2457 It is possible to check the directory existence by specifying | 2453 It is possible to check directory’s existence by specifying |
2458 a slash at the end of a name, e.g. “<literal>$uri/</literal>”. | 2454 a slash at the end of a name, e.g. “<literal>$uri/</literal>”. |
2459 If none of the files were found, an internal redirect to the | 2455 If none of the files were found, an internal redirect to the |
2460 <value>uri</value> specified by the last parameter is made. | 2456 <value>uri</value> specified in the last parameter is made. |
2461 For example: | 2457 For example: |
2462 <example> | 2458 <example> |
2463 location /images/ { | 2459 location /images/ { |
2464 try_files $uri /images/default.gif; | 2460 try_files $uri /images/default.gif; |
2465 } | 2461 } |
2468 expires 30s; | 2464 expires 30s; |
2469 } | 2465 } |
2470 </example> | 2466 </example> |
2471 The last parameter can also point to a named location, | 2467 The last parameter can also point to a named location, |
2472 as shown in examples below. | 2468 as shown in examples below. |
2473 As of version 0.7.51, the last parameter can also be a | 2469 Starting from version 0.7.51, the last parameter can also be a |
2474 <value>code</value>: | 2470 <value>code</value>: |
2475 <example> | 2471 <example> |
2476 location / { | 2472 location / { |
2477 try_files $uri $uri/index.html $uri.html =404; | 2473 try_files $uri $uri/index.html $uri.html =404; |
2478 } | 2474 } |
2479 </example> | 2475 </example> |
2480 </para> | 2476 </para> |
2481 | 2477 |
2482 <para> | 2478 <para> |
2483 Example when proxying Mongrel: | 2479 Example in proxying Mongrel: |
2484 <example> | 2480 <example> |
2485 location / { | 2481 location / { |
2486 try_files /system/maintenance.html | 2482 try_files /system/maintenance.html |
2487 $uri $uri/index.html $uri.html | 2483 $uri $uri/index.html $uri.html |
2488 @mongrel; | 2484 @mongrel; |
2592 <context>location</context> | 2588 <context>location</context> |
2593 | 2589 |
2594 <para> | 2590 <para> |
2595 Maps file name extensions to MIME types of responses. | 2591 Maps file name extensions to MIME types of responses. |
2596 Extensions are case-insensitive. | 2592 Extensions are case-insensitive. |
2597 Several extensions can map to one type, for example: | 2593 Several extensions can be mapped to one type, for example: |
2598 <example> | 2594 <example> |
2599 types { | 2595 types { |
2600 application/octet-stream bin exe dll; | 2596 application/octet-stream bin exe dll; |
2601 application/octet-stream deb; | 2597 application/octet-stream deb; |
2602 application/octet-stream dmg; | 2598 application/octet-stream dmg; |
2610 </para> | 2606 </para> |
2611 | 2607 |
2612 <para> | 2608 <para> |
2613 To make a particular location emit the | 2609 To make a particular location emit the |
2614 “<literal>application/octet-stream</literal>” | 2610 “<literal>application/octet-stream</literal>” |
2615 MIME type for all requests, try the following: | 2611 MIME type for all requests, the following configuration can be used: |
2616 <example> | 2612 <example> |
2617 location /download/ { | 2613 location /download/ { |
2618 types { } | 2614 types { } |
2619 default_type application/octet-stream; | 2615 default_type application/octet-stream; |
2620 } | 2616 } |
2631 <context>server</context> | 2627 <context>server</context> |
2632 <context>location</context> | 2628 <context>location</context> |
2633 | 2629 |
2634 <para> | 2630 <para> |
2635 Sets the bucket size for the types hash tables. | 2631 Sets the bucket size for the types hash tables. |
2636 Default value depends on the size of the processor’s cache line. | 2632 The default value depends on the size of the processor’s cache line. |
2637 Details of setting up hash tables are provided in a separate | 2633 Details of setting up hash tables are provided in a separate |
2638 <link doc="../hash.xml">document</link>. | 2634 <link doc="../hash.xml">document</link>. |
2639 </para> | 2635 </para> |
2640 | 2636 |
2641 </directive> | 2637 </directive> |
2663 <context>http</context> | 2659 <context>http</context> |
2664 <context>server</context> | 2660 <context>server</context> |
2665 | 2661 |
2666 <para> | 2662 <para> |
2667 Enables or disables the use of underscores in client request header fields. | 2663 Enables or disables the use of underscores in client request header fields. |
2668 When disabled, request header fields whose names contain underscores are | 2664 When the use of underscores is disabled, request header fields whose names |
2669 marked as invalid and are subject to the <link id="ignore_invalid_headers"/> | 2665 contain underscores are |
2670 directive. | 2666 marked as invalid and become subject to the |
2667 <link id="ignore_invalid_headers"/> directive. | |
2671 </para> | 2668 </para> |
2672 | 2669 |
2673 <para> | 2670 <para> |
2674 A directive can be specified on the <link id="server"/> level | 2671 A directive can be specified on the <link id="server"/> level |
2675 in a default server. | 2672 in a default server. |
2676 In this case, its value will cover all virtual servers | 2673 In this case, its value will apply to all virtual servers |
2677 listening on the same address and port. | 2674 listening on the same address and port. |
2678 </para> | 2675 </para> |
2679 | 2676 |
2680 </directive> | 2677 </directive> |
2681 | 2678 |
2711 | 2708 |
2712 | 2709 |
2713 <section id="variables" name="Embedded Variables"> | 2710 <section id="variables" name="Embedded Variables"> |
2714 | 2711 |
2715 <para> | 2712 <para> |
2716 The module <literal>ngx_http_core_module</literal> supports embedded variables | 2713 The <literal>ngx_http_core_module</literal> module supports embedded variables |
2717 with names matching those of the Apache Server. | 2714 with names matching the Apache Server variables. |
2718 First of all, these are variables representing client request header | 2715 First of all, these are variables representing client request header |
2719 fields, such as <var>$http_user_agent</var>, <var>$http_cookie</var>, | 2716 fields, such as <var>$http_user_agent</var>, <var>$http_cookie</var>, |
2720 and so on. | 2717 and so on. |
2721 It also supports other variables: | 2718 Also there are other variables: |
2722 <list type="tag"> | 2719 <list type="tag"> |
2723 | 2720 |
2724 <tag-name id="var_arg_"><var>$arg_</var><value>name</value></tag-name> | 2721 <tag-name id="var_arg_"><var>$arg_</var><value>name</value></tag-name> |
2725 <tag-desc> | 2722 <tag-desc> |
2726 argument <value>name</value> in the request line | 2723 argument <value>name</value> in the request line |
2818 or an empty string otherwise | 2815 or an empty string otherwise |
2819 </tag-desc> | 2816 </tag-desc> |
2820 | 2817 |
2821 <tag-name id="var_limit_rate"><var>$limit_rate</var></tag-name> | 2818 <tag-name id="var_limit_rate"><var>$limit_rate</var></tag-name> |
2822 <tag-desc> | 2819 <tag-desc> |
2823 setting this variable allows for response rate limiting; | 2820 setting this variable enables response rate limiting; |
2824 see <link id="limit_rate"/> | 2821 see <link id="limit_rate"/> |
2825 </tag-desc> | 2822 </tag-desc> |
2826 | 2823 |
2827 <tag-name id="var_msec"><var>$msec</var></tag-name> | 2824 <tag-name id="var_msec"><var>$msec</var></tag-name> |
2828 <tag-desc> | 2825 <tag-desc> |
2829 current time in seconds with a milliseconds resolution (1.3.9, 1.2.6) | 2826 current time in seconds with the milliseconds resolution (1.3.9, 1.2.6) |
2830 </tag-desc> | 2827 </tag-desc> |
2831 | 2828 |
2832 <tag-name id="var_nginx_version"><var>$nginx_version</var></tag-name> | 2829 <tag-name id="var_nginx_version"><var>$nginx_version</var></tag-name> |
2833 <tag-desc> | 2830 <tag-desc> |
2834 nginx version | 2831 nginx version |
2894 <tag-name id="var_request_body_file"><var>$request_body_file</var></tag-name> | 2891 <tag-name id="var_request_body_file"><var>$request_body_file</var></tag-name> |
2895 <tag-desc> | 2892 <tag-desc> |
2896 name of a temporary file with the request body | 2893 name of a temporary file with the request body |
2897 <para> | 2894 <para> |
2898 At the end of processing, the file needs to be removed. | 2895 At the end of processing, the file needs to be removed. |
2899 To always write a request body to a file, | 2896 To always write the request body to a file, |
2900 <link id="client_body_in_file_only"/> needs to be enabled. | 2897 <link id="client_body_in_file_only"/> needs to be enabled. |
2901 When passing the name of a temporary file in a proxied request, | 2898 When the name of a temporary file is passed in a proxied request |
2902 or in a request to a FastCGI server, | 2899 or in a request to a FastCGI server, |
2903 passing of the request body should be disabled by the | 2900 passing the request body should be disabled by the |
2904 <link doc="ngx_http_proxy_module.xml" id="proxy_pass_request_body"> | 2901 <link doc="ngx_http_proxy_module.xml" id="proxy_pass_request_body"> |
2905 proxy_pass_request_body off</link> | 2902 proxy_pass_request_body off</link> |
2906 and | 2903 and |
2907 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass_request_body"> | 2904 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass_request_body"> |
2908 fastcgi_pass_request_body off</link> | 2905 fastcgi_pass_request_body off</link> |