Mercurial > hg > nginx

comparison docs/xml/http/ngx_http_core_module.xml @ 4079:9755cb2a39b2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Finished initial translation of the Core and HTTP Core modules.
author Ruslan Ermilov <ru@nginx.com>
date Tue, 06 Sep 2011 13:42:40 +0000
parents d0d832a3b1df
children 44c1953c266c
comparison
equal deleted inserted replaced
4078:e922cc1755fa 4079:9755cb2a39b2
21 Enables or disables the use of asynchronous file I/O (AIO) 21 Enables or disables the use of asynchronous file I/O (AIO)
22 on FreeBSD and Linux. 22 on FreeBSD and Linux.
23 </para> 23 </para>
24 24
25 <para> 25 <para>
26 On FreeBSD, AIO is usable used starting from FreeBSD 4.3. 26 On FreeBSD, AIO is usable starting from FreeBSD&nbsp;4.3.
27 AIO can either be linked statically into a kernel: 27 AIO can either be linked statically into a kernel:
28 <example> 28 <example>
29 options VFS_AIO 29 options VFS_AIO
30 </example> 30 </example>
31 or loaded dynamically as a kernel loadable module: 31 or loaded dynamically as a kernel loadable module:
36 36
37 <para> 37 <para>
38 In FreeBSD versions 5 and 6, enabling AIO statically, or dynamically 38 In FreeBSD versions 5 and 6, enabling AIO statically, or dynamically
39 when booting the kernel, will cause the entire networking subsystem 39 when booting the kernel, will cause the entire networking subsystem
40 to use the Giant lock that can impact overall performance negatively. 40 to use the Giant lock that can impact overall performance negatively.
41 This limitation has been removed in FreeBSD 6.4-STABLE in 2009, and in 41 This limitation has been removed in FreeBSD&nbsp;6.4-STABLE in 2009, and in
42 FreeBSD 7. 42 FreeBSD&nbsp;7.
43 However, starting from FreeBSD 5.3, it's possible to enable AIO 43 However, starting from FreeBSD&nbsp;5.3 it is possible to enable AIO
44 without the penalty of running the networking subsystem under a 44 without the penalty of running the networking subsystem under a
45 Giant lock&mdash;for this to work, the AIO module needs to be loaded 45 Giant lock&mdash;for this to work, the AIO module needs to be loaded
46 after the kernel has booted. 46 after the kernel has booted.
47 In this case, the following message will appear in 47 In this case, the following message will appear in
48 <code>/var/log/messages</code> 48 <pathname>/var/log/messages</pathname>
49 <example> 49 <example>
50 WARNING: Network stack Giant-free, but aio requires Giant. 50 WARNING: Network stack Giant-free, but aio requires Giant.
51 Consider adding 'options NET_WITH_GIANT' or setting debug.mpsafenet=0 51 Consider adding 'options NET_WITH_GIANT' or setting debug.mpsafenet=0
52 </example> 52 </example>
53 and can safely be ignored. 53 and can safely be ignored.
65 <para> 65 <para>
66 For AIO to work, 66 For AIO to work,
67 <link id="sendfile">sendfile</link> 67 <link id="sendfile">sendfile</link>
68 needs to be disabled: 68 needs to be disabled:
69 <example> 69 <example>
70 location /video/ { 70 location /video/ {
71 sendfile off; 71 sendfile off;
72 aio on; 72 aio on;
73 output_buffers 1 64k; 73 output_buffers 1 64k;
74 } 74 }
75 </example> 75 </example>
76 </para> 76 </para>
77 77
78 <para> 78 <para>
79 In addition, starting from FreeBSD 5.2.1 and nginx 0.8.12, AIO can 79 In addition, starting from FreeBSD&nbsp;5.2.1 and nginx&nbsp;0.8.12, AIO can
80 also be used to pre-load data for <c-func>sendfile</c-func>: 80 also be used to pre-load data for <c-func>sendfile</c-func>:
81 <example> 81 <example>
82 location /video/ { 82 location /video/ {
83 sendfile on; 83 sendfile on;
84 tcp_nopush on; 84 tcp_nopush on;
85 aio sendfile; 85 aio sendfile;
86 } 86 }
87 </example> 87 </example>
88 In this configuration, <c-func>sendfile</c-func> is called with 88 In this configuration, <c-func>sendfile</c-func> is called with
89 the <c-def>SF_NODISKIO</c-def> flag which causes it not to 89 the <c-def>SF_NODISKIO</c-def> flag which causes it not to
90 block on disk I/O and instead report back when the data are not in 90 block on disk I/O and instead report back when the data are not in
100 On Linux, AIO is usable starting from kernel version 2.6.22; 100 On Linux, AIO is usable starting from kernel version 2.6.22;
101 plus, it is also necessary to enable 101 plus, it is also necessary to enable
102 <link id="directio">directio</link>, 102 <link id="directio">directio</link>,
103 otherwise reading will be blocking: 103 otherwise reading will be blocking:
104 <example> 104 <example>
105 location /video/ { 105 location /video/ {
106 aio on; 106 aio on;
107 directio 512; 107 directio 512;
108 output_buffers 1 128k; 108 output_buffers 1 128k;
109 } 109 }
110 </example> 110 </example>
111 </para> 111 </para>
112 112
113 <para> 113 <para>
114 On Linux, 114 On Linux,
115 <link id="directio">directio</link> 115 <link id="directio">directio</link>
116 can only be used for reading blocks that are aligned on 512-byte 116 can only be used for reading blocks that are aligned on 512-byte
117 boundaries (or 4K for XFS). 117 boundaries (or 4K for XFS).
118 Reading of unaligned file's tail is still made in blocking mode. 118 Reading of unaligned file's end is still made in blocking mode.
119 The same holds true for byte range requests, and for FLV requests 119 The same holds true for byte range requests, and for FLV requests
120 not from the beginning of a file: reading of unaligned data at the 120 not from the beginning of a file: reading of unaligned data at the
121 beginning and end of a file will be blocking. 121 beginning and end of a file will be blocking.
122 There is no need to turn off 122 There is no need to turn off
123 <link id="sendfile">sendfile</link> 123 <link id="sendfile">sendfile</link>
136 136
137 <para> 137 <para>
138 Defines a replacement for the specified location. 138 Defines a replacement for the specified location.
139 For example, with the following configuration 139 For example, with the following configuration
140 <example> 140 <example>
141 location /i/ { 141 location /i/ {
142 alias /data/w3/images/; 142 alias /data/w3/images/;
143 } 143 }
144 </example> 144 </example>
145 the request of "/i/top.gif" will be responded 145 the request of
146 with the file "/data/w3/images/top.gif". 146 <dq><code>/i/top.gif</code></dq> will be responded
147 with the file
148 <dq><pathname>/data/w3/images/top.gif</pathname></dq>.
147 </para> 149 </para>
148 150
149 <para> 151 <para>
150 The <argument>path</argument> value can contain variables. 152 The <argument>path</argument> value can contain variables.
151 </para> 153 </para>
155 with a regular expression then such regular expression should 157 with a regular expression then such regular expression should
156 contain captures and <command>alias</command> should refer to 158 contain captures and <command>alias</command> should refer to
157 these captures (0.7.40), for example: 159 these captures (0.7.40), for example:
158 <example> 160 <example>
159 location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ { 161 location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ {
160 alias /data/w3/images/$1; 162 alias /data/w3/images/$1;
161 } 163 }
162 </example> 164 </example>
163 </para> 165 </para>
164 166
165 <para> 167 <para>
166 When location matches the last part of the directive's value: 168 When location matches the last part of the directive's value:
167 <example> 169 <example>
168 location /images/ { 170 location /images/ {
169 alias /data/w3/images/; 171 alias /data/w3/images/;
170 } 172 }
171 </example> 173 </example>
172 it's better to use the 174 it is better to use the
173 <link id="root">root</link> 175 <link id="root">root</link>
174 directive instead: 176 directive instead:
175 <example> 177 <example>
176 location /images/ { 178 location /images/ {
177 root /data/w3; 179 root /data/w3;
178 } 180 }
179 </example> 181 </example>
180 </para> 182 </para>
181 183
182 </directive> 184 </directive>
203 method of the 205 method of the
204 <link doc="ngx_http_perl_module.xml">http_perl</link> module. 206 <link doc="ngx_http_perl_module.xml">http_perl</link> module.
205 </para> 207 </para>
206 208
207 <para> 209 <para>
208 When set to the value <code>on</code>, temporary files are not 210 When set to the value <value>on</value>, temporary files are not
209 removed after request processing. 211 removed after request processing.
210 </para> 212 </para>
211 213
212 <para> 214 <para>
213 The value <code>clean</code> will cause the temporary files 215 The value <value>clean</value> will cause the temporary files
214 left after request processing to be removed. 216 left after request processing to be removed.
215 </para> 217 </para>
216 218
217 </directive> 219 </directive>
218 220
273 Defines a directory for storing temporary files holding client request bodies. 275 Defines a directory for storing temporary files holding client request bodies.
274 Up to three-level subdirectory hierarchy can be used underneath the specified 276 Up to three-level subdirectory hierarchy can be used underneath the specified
275 directory. 277 directory.
276 For example, in the following configuration 278 For example, in the following configuration
277 <example> 279 <example>
278 client_body_temp_path /spool/nginx/client_temp 1 2; 280 client_body_temp_path /spool/nginx/client_temp 1 2;
279 </example> 281 </example>
280 a temporary file might look like this: 282 a temporary file might look like this:
281 <example> 283 <example>
282 /spool/nginx/client_temp/7/45/00000123457 284 /spool/nginx/client_temp/7/45/00000123457
283 </example> 285 </example>
315 <para> 317 <para>
316 Sets buffer size for reading client request header. 318 Sets buffer size for reading client request header.
317 For most requests, a buffer of 1K bytes is enough. 319 For most requests, a buffer of 1K bytes is enough.
318 However, if a request includes long cookies, or comes from a WAP client, 320 However, if a request includes long cookies, or comes from a WAP client,
319 it may not fit into 1K. 321 it may not fit into 1K.
320 If a request line, or a request header line do not fit entirely into 322 If a request line, or a request header field do not fit entirely into
321 this buffer then larger buffers are allocated, configured by the 323 this buffer then larger buffers are allocated, configured by the
322 <link id="large_client_header_buffers">large_client_header_buffers</link> 324 <link id="large_client_header_buffers">large_client_header_buffers</link>
323 directive. 325 directive.
324 </para> 326 </para>
325 327
352 354
353 <para> 355 <para>
354 Sets the maximum allowed size of the client request body, 356 Sets the maximum allowed size of the client request body,
355 specified in the 357 specified in the
356 <header>Content-Length</header> 358 <header>Content-Length</header>
357 request header line. 359 request header field.
358 If <argument>size</argument> is greater than the configured value, the 360 If <argument>size</argument> is greater than the configured value, the
359 <http-error code="413" text="Request Entity Too Large"/> 361 <http-error code="413" text="Request Entity Too Large"/>
360 error is returned to a client. 362 error is returned to a client.
361 Please be aware that 363 Please be aware that
362 <link doc="/web/upload.xml">browsers cannot correctly display 364 <link doc="/web/upload.xml">browsers cannot correctly display
396 It automatically disables (0.7.15) the use of 398 It automatically disables (0.7.15) the use of
397 <link id="sendfile">sendfile</link> 399 <link id="sendfile">sendfile</link>
398 for a given request. 400 for a given request.
399 It could be useful for serving large files: 401 It could be useful for serving large files:
400 <example> 402 <example>
401 directio 4m; 403 directio 4m;
402 </example> 404 </example>
403 or when using <link id="aio">aio</link> on Linux. 405 or when using <link id="aio">aio</link> on Linux.
404 </para> 406 </para>
405 407
406 </directive> 408 </directive>
423 </directive> 425 </directive>
424 426
425 427
426 <directive name="error_page"> 428 <directive name="error_page">
427 <syntax>error_page 429 <syntax>error_page
428 <argument>code ...</argument> 430 <argument>code</argument> ...
429 [<value>=</value>[<argument>response</argument>]] 431 [<value>=</value>[<argument>response</argument>]]
430 <argument>uri</argument> 432 <argument>uri</argument>
431 </syntax> 433 </syntax>
432 <default/> 434 <default/>
433 <context>http</context> 435 <context>http</context>
436 <context>if in location</context> 438 <context>if in location</context>
437 439
438 <para> 440 <para>
439 Defines the URI that will be shown for the specified errors. 441 Defines the URI that will be shown for the specified errors.
440 These directives are inherited from the previous level if and 442 These directives are inherited from the previous level if and
441 only if there are no <code>error_page</code> directives on 443 only if there are no
444 <link doc="../core_module.xml" id="error_page">error_page</link>
445 directives on
442 the current level. 446 the current level.
443 A URI value can contain variables. 447 A URI value can contain variables.
444 </para> 448 </para>
445 449
446 <para> 450 <para>
447 Example usage: 451 Example:
448 <example> 452 <example>
449 error_page 404 /404.html; 453 error_page 404 /404.html;
450 error_page 502 503 504 /50x.html; 454 error_page 502 503 504 /50x.html;
451 error_page 403 http://example.com/forbidden.html; 455 error_page 403 http://example.com/forbidden.html;
452 </example> 456 </example>
453 </para> 457 </para>
454 458
455 <para> 459 <para>
456 Furthermore, it is possible to change the response code to another, for example: 460 Furthermore, it is possible to change the response code to another, for example:
457 <example> 461 <example>
458 error_page 404 =200 /empty.gif; 462 error_page 404 =200 /empty.gif;
459 </example> 463 </example>
460 </para> 464 </para>
461 465
462 <para> 466 <para>
463 If an error response is processed by a proxied server, or a FastCGI-server, 467 If an error response is processed by a proxied server, or a FastCGI server,
464 and the server may return different response codes (e.g., 200, 302, 401 468 and the server may return different response codes (e.g., 200, 302, 401
465 or 404), it is possible to respond with a returned code: 469 or 404), it is possible to respond with a returned code:
466 <example> 470 <example>
467 error_page 404 = /404.php; 471 error_page 404 = /404.php;
468 </example> 472 </example>
469 </para> 473 </para>
470 474
471 <para> 475 <para>
472 If there is no need to change URI during redirection it is possible to redirect 476 If there is no need to change URI during redirection it is possible to redirect
473 error processing into a named location: 477 error processing into a named location:
474 <example> 478 <example>
475 location / { 479 location / {
476 error_page 404 = @fallback; 480 error_page 404 = @fallback;
477 } 481 }
478 482
479 location @fallback { 483 location @fallback {
480 proxy_pass http://backend; 484 proxy_pass http://backend;
481 } 485 }
482 </example> 486 </example>
483 </para> 487 </para>
484 488
485 </directive> 489 </directive>
500 Specifies how to compare modification time of a response 504 Specifies how to compare modification time of a response
501 with the time in the 505 with the time in the
502 <header>If-Modified-Since</header> 506 <header>If-Modified-Since</header>
503 request header: 507 request header:
504 508
505 <list type="bullet"> 509 <list type="tag">
506 510
507 <listitem> 511 <tag-name><value>off</value></tag-name>
508 <value>off</value>&mdash;the 512 <tag-desc>
513 the
509 <header>If-Modified-Since</header> request header is ignored (0.7.34); 514 <header>If-Modified-Since</header> request header is ignored (0.7.34);
510 </listitem> 515 </tag-desc>
511 516
512 <listitem> 517 <tag-name><value>exact</value></tag-name>
513 <value>exact</value>&mdash;exact match; 518 <tag-desc>
514 </listitem> 519 exact match;
515 520 </tag-desc>
516 <listitem> 521
517 <value>before</value>&mdash;modification time of a response is 522 <tag-name><value>before</value></tag-name>
523 <tag-desc>
524 modification time of a response is
518 less than or equal to the time in the <header>If-Modified-Since</header> 525 less than or equal to the time in the <header>If-Modified-Since</header>
519 request header. 526 request header.
520 </listitem> 527 </tag-desc>
521 528
522 </list> 529 </list>
523 </para> 530 </para>
524 531
525 </directive> 532 </directive>
558 565
559 </list> 566 </list>
560 </para> 567 </para>
561 568
562 <para> 569 <para>
563 Example usage: 570 Example:
564 <example> 571 <example>
565 error_page 404 /404.html; 572 error_page 404 /404.html;
566 573
567 location /404.html { 574 location /404.html {
568 internal; 575 internal;
569 } 576 }
570 </example> 577 </example>
571 </para> 578 </para>
572 579
600 607
601 <para> 608 <para>
602 The first argument sets a timeout during which a keep-alive 609 The first argument sets a timeout during which a keep-alive
603 client connection will stay open on the server side. 610 client connection will stay open on the server side.
604 The optional second argument sets a value in the 611 The optional second argument sets a value in the
605 "<header>Keep-Alive: timeout=</header><argument>time</argument>" 612 <dq><header>Keep-Alive: timeout=<argument>time</argument></header></dq>
606 response header. 613 response header.
607 Two arguments may differ. 614 Two arguments may differ.
608 </para> 615 </para>
609 616
610 <para> 617 <para>
611 The 618 The
612 "<header>Keep-Alive: timeout=</header>" 619 <dq><header>Keep-Alive: timeout=</header></dq>
613 is understood by Mozilla and Konqueror. 620 is understood by Mozilla and Konqueror.
614 MSIE will close keep-alive connection in about 60 seconds. 621 MSIE will close keep-alive connection in about 60 seconds.
615 </para> 622 </para>
616 623
617 </directive> 624 </directive>
627 Sets the maximum <argument>number</argument> and <argument>size</argument> of 634 Sets the maximum <argument>number</argument> and <argument>size</argument> of
628 buffers used when reading large client request headers. 635 buffers used when reading large client request headers.
629 A request line cannot exceed the size of one buffer, or the 636 A request line cannot exceed the size of one buffer, or the
630 <http-error code="414" text="Request URI too large"/> 637 <http-error code="414" text="Request URI too large"/>
631 error is returned. 638 error is returned.
632 A request header line cannot exceed the size of one buffer as well, or the 639 A request header field cannot exceed the size of one buffer as well, or the
633 <http-error code="400" text="Bad request"/> 640 <http-error code="400" text="Bad request"/>
634 error is returned. 641 error is returned.
635 Buffers are allocated only on demand. 642 Buffers are allocated only on demand.
636 By default, the buffer size is equal to one memory page size. 643 By default, the buffer size is equal to one memory page size.
637 It is either 4K or 8K, platform dependent. 644 It is either 4K or 8K, platform dependent.
654 <link doc="ngx_http_access_module.xml">http_access</link> 661 <link doc="ngx_http_access_module.xml">http_access</link>
655 and 662 and
656 <link doc="ngx_http_auth_basic_module.xml">http_auth_basic</link> 663 <link doc="ngx_http_auth_basic_module.xml">http_auth_basic</link>
657 modules directives: 664 modules directives:
658 <example> 665 <example>
659 limit_except GET { 666 limit_except GET {
660 allow 192.168.1.0/32; 667 allow 192.168.1.0/32;
661 deny all; 668 deny all;
662 } 669 }
663 </example> 670 </example>
664 Please note that this will limit access to all methods 671 Please note that this will limit access to all methods
665 <emphasis>except</emphasis> GET and HEAD. 672 <emphasis>except</emphasis> GET and HEAD.
666 </para> 673 </para>
696 variable: 703 variable:
697 <example> 704 <example>
698 server { 705 server {
699 706
700 if ($slow) { 707 if ($slow) {
701 set $limit_rate 4k; 708 set $limit_rate 4k;
702 } 709 }
703 710
704 ... 711 ...
705 } 712 }
706 </example> 713 </example>
725 <para> 732 <para>
726 Example: 733 Example:
727 <example> 734 <example>
728 location /flv/ { 735 location /flv/ {
729 flv; 736 flv;
730 limit_rate_after 500k; 737 limit_rate_after 500k;
731 limit_rate 50k; 738 limit_rate 50k;
732 } 739 }
733 </example> 740 </example>
734 </para> 741 </para>
735 742
736 </directive> 743 </directive>
769 the server will accept requests. 776 the server will accept requests.
770 Only one of <argument>address</argument> or <argument>port</argument> can be 777 Only one of <argument>address</argument> or <argument>port</argument> can be
771 specified. 778 specified.
772 An <argument>address</argument> may also be a hostname, for example: 779 An <argument>address</argument> may also be a hostname, for example:
773 <example> 780 <example>
774 listen 127.0.0.1:8000; 781 listen 127.0.0.1:8000;
775 listen 127.0.0.1; 782 listen 127.0.0.1;
776 listen 8000; 783 listen 8000;
777 listen *:8000; 784 listen *:8000;
778 listen localhost:8000; 785 listen localhost:8000;
779 </example> 786 </example>
780 IPv6 addresses (0.7.36) are specified in square brackets: 787 IPv6 addresses (0.7.36) are specified in square brackets:
781 <example> 788 <example>
782 listen [::]:8000; 789 listen [::]:8000;
783 listen [fe80::1]; 790 listen [fe80::1];
784 </example> 791 </example>
785 </para> 792 </para>
786 793
787 <para> 794 <para>
788 If only <argument>address</argument> is given, the port 80 is used. 795 If only <argument>address</argument> is given, the port 80 is used.
811 parameter can have several additional parameters specific to system calls 818 parameter can have several additional parameters specific to system calls
812 <c-func>listen</c-func> and <c-func>bind</c-func>. 819 <c-func>listen</c-func> and <c-func>bind</c-func>.
813 Starting from version 0.8.21, these parameters can be specified in any 820 Starting from version 0.8.21, these parameters can be specified in any
814 <code>listen</code> directive, but only once for the given 821 <code>listen</code> directive, but only once for the given
815 <argument>address</argument>:<argument>port</argument> pair. 822 <argument>address</argument>:<argument>port</argument> pair.
816 <list type="bullet"> 823 <list type="tag">
817 824
818 <listitem> 825 <tag-name>
819 <parameter>backlog</parameter>=<argument>number</argument>&mdash; 826 <parameter>backlog</parameter>=<argument>number</argument>
827 </tag-name>
828 <tag-desc>
820 sets the <parameter>backlog</parameter> parameter in the 829 sets the <parameter>backlog</parameter> parameter in the
821 <c-func>listen</c-func> call. 830 <c-func>listen</c-func> call.
822 By default, <parameter>backlog</parameter> equals -1 on FreeBSD 831 By default, <parameter>backlog</parameter> equals -1 on FreeBSD
823 and 511 on other platforms. 832 and 511 on other platforms.
824 </listitem> 833 </tag-desc>
825 834
826 <listitem> 835 <tag-name>
827 <parameter>rcvbuf</parameter>=<argument>size</argument>&mdash; 836 <parameter>rcvbuf</parameter>=<argument>size</argument>
837 </tag-name>
838 <tag-desc>
828 sets the <c-def>SO_RCVBUF</c-def> parameter for the listening socket. 839 sets the <c-def>SO_RCVBUF</c-def> parameter for the listening socket.
829 </listitem> 840 </tag-desc>
830 841
831 <listitem> 842 <tag-name>
832 <parameter>sndbuf</parameter>=<argument>size</argument>&mdash; 843 <parameter>sndbuf</parameter>=<argument>size</argument>
844 </tag-name>
845 <tag-desc>
833 sets the <c-def>SO_SNDBUF</c-def> parameter for the listening socket. 846 sets the <c-def>SO_SNDBUF</c-def> parameter for the listening socket.
834 </listitem> 847 </tag-desc>
835 848
836 <listitem> 849 <tag-name>
837 <parameter>accept_filter</parameter>=<argument>filter</argument>&mdash; 850 <parameter>accept_filter</parameter>=<argument>filter</argument>
851 </tag-name>
852 <tag-desc>
838 sets the name of the accept filter. 853 sets the name of the accept filter.
839 This works only on FreeBSD, acceptable values are <value>dataready</value> 854 This works only on FreeBSD, acceptable values are <value>dataready</value>
840 and <value>httpready</value>. 855 and <value>httpready</value>.
841 On receiving <c-def>SIGHUP</c-def> signal, an accept filter can only be 856 On receipt of the <c-def>SIGHUP</c-def> signal, an accept filter can only be
842 changed in recent versions of FreeBSD, starting from 6.0, 5.4-STABLE 857 changed in recent versions of FreeBSD, starting from 6.0, 5.4-STABLE
843 and 4.11-STABLE. 858 and 4.11-STABLE.
844 </listitem> 859 </tag-desc>
845 860
846 <listitem> 861 <tag-name>
847 <parameter>deferred</parameter>&mdash; 862 <parameter>deferred</parameter>
863 </tag-name>
864 <tag-desc>
848 instructs to use a deferred <c-func>accept</c-func> on Linux 865 instructs to use a deferred <c-func>accept</c-func> on Linux
849 using the <c-def>TCP_DEFER_ACCEPT</c-def> option. 866 using the <c-def>TCP_DEFER_ACCEPT</c-def> option.
850 </listitem> 867 </tag-desc>
851 868
852 <listitem> 869 <tag-name>
853 <parameter>bind</parameter>&mdash; 870 <parameter>bind</parameter>
871 </tag-name>
872 <tag-desc>
854 specifies to make a separate <c-func>bind</c-func> call for a given 873 specifies to make a separate <c-func>bind</c-func> call for a given
855 <argument>address</argument>:<argument>port</argument> pair. 874 <argument>address</argument>:<argument>port</argument> pair.
856 This is because nginx will only <c-func>bind</c-func> to 875 This is because nginx will only <c-func>bind</c-func> to
857 <code>*</code>:<argument>port</argument> 876 <code>*</code>:<argument>port</argument>
858 if there are several <code>listen</code> directives with 877 if there are several <code>listen</code> directives with
859 the same port and different addresses, and one of the 878 the same port but different addresses, and one of the
860 <code>listen</code> directives listens on all addresses 879 <code>listen</code> directives listens on all addresses
861 for the given port (<code>*</code>:<argument>port</argument>). 880 for the given port (<code>*</code>:<argument>port</argument>).
862 It should be noted that in this case a <c-func>getsockname</c-func> 881 It should be noted that in this case a <c-func>getsockname</c-func>
863 system call will be made to determine an address that accepted a 882 system call will be made to determine an address that accepted a
864 connection. 883 connection.
865 If parameters <parameter>backlog</parameter>, <parameter>rcvbuf</parameter>, 884 If parameters <parameter>backlog</parameter>, <parameter>rcvbuf</parameter>,
866 <parameter>sndbuf</parameter>, <parameter>accept_filter</parameter>, or 885 <parameter>sndbuf</parameter>, <parameter>accept_filter</parameter>, or
867 <parameter>deferred</parameter> are used then for a given 886 <parameter>deferred</parameter> are used then for a given
868 <argument>address</argument>:<argument>port</argument> pair 887 <argument>address</argument>:<argument>port</argument> pair
869 a separate <c-func>bind</c-func> call will always be made. 888 a separate <c-func>bind</c-func> call will always be made.
870 </listitem> 889 </tag-desc>
871 890
872 <listitem> 891 <tag-name>
873 <parameter>ipv6only</parameter>=<value>on</value>|<value>off</value>&mdash; 892 <parameter>ipv6only</parameter>=<value>on</value>|<value>off</value>
893 </tag-name>
894 <tag-desc>
874 this parameter (0.7.42) sets the value of the <c-def>IPV6_V6ONLY</c-def> 895 this parameter (0.7.42) sets the value of the <c-def>IPV6_V6ONLY</c-def>
875 parameter for the listening socket. 896 parameter for the listening socket.
876 This parameter can only be set once on start. 897 This parameter can only be set once on start.
877 </listitem> 898 </tag-desc>
878 899
879 <listitem> 900 <tag-name>
880 <parameter>ssl</parameter>&mdash; 901 <parameter>ssl</parameter>
902 </tag-name>
903 <tag-desc>
881 this parameter (0.7.14) does not relate to system calls 904 this parameter (0.7.14) does not relate to system calls
882 <c-func>listen</c-func> and <c-func>bind</c-func>, but allows to 905 <c-func>listen</c-func> and <c-func>bind</c-func>, but allows to
883 specify that all connections accepted on this port should work in 906 specify that all connections accepted on this port should work in
884 the SSL mode. 907 the SSL mode.
885 This allows for a more compact configuration for the server operating 908 This allows for a more compact configuration for the server operating
886 in both HTTP and HTTPS modes simultaneously. 909 in both HTTP and HTTPS modes simultaneously.
887 <example> 910 <example>
888 listen 80; 911 listen 80;
889 listen 443 default ssl; 912 listen 443 default ssl;
890 </example> 913 </example>
891 </listitem> 914 </tag-desc>
892 915
893 </list> 916 </list>
894 </para> 917 </para>
895 918
896 <para> 919 <para>
897 Example: 920 Example:
898 <example> 921 <example>
899 listen 127.0.0.1 default accept_filter=dataready backlog=1024; 922 listen 127.0.0.1 default accept_filter=dataready backlog=1024;
900 </example> 923 </example>
901 </para> 924 </para>
902 925
903 </directive> 926 </directive>
904 927
920 943
921 <para> 944 <para>
922 Sets a configuration based on a request URI. 945 Sets a configuration based on a request URI.
923 A location can either be defined by a prefix string, or by a regular expression. 946 A location can either be defined by a prefix string, or by a regular expression.
924 Regular expressions are specified by prepending them with the 947 Regular expressions are specified by prepending them with the
925 "<value>~*</value>" prefix (for case-insensitive matching), or with the 948 <dq><value>~*</value></dq> prefix (for case-insensitive matching), or with the
926 "<value>~</value>" prefix (for case-sensitive matching). 949 <dq><value>~</value></dq> prefix (for case-sensitive matching).
927 To find a location matching a given request, nginx first checks 950 To find a location matching a given request, nginx first checks
928 locations defined using the prefix strings (prefix locations). 951 locations defined using the prefix strings (prefix locations).
929 Amongst them, the most specific one is searched. 952 Amongst them, the most specific one is searched.
930 Then regular expressions are checked, in the order of their appearance 953 Then regular expressions are checked, in the order of their appearance
931 in a configuration file. 954 in a configuration file.
945 Regular expressions can contain captures (0.7.40) that can later 968 Regular expressions can contain captures (0.7.40) that can later
946 be used in other directives. 969 be used in other directives.
947 </para> 970 </para>
948 971
949 <para> 972 <para>
950 If the most specific prefix location has the "<value>^~</value>" prefix 973 If the most specific prefix location has the <dq><value>^~</value></dq> prefix
951 then regular expressions are not checked. 974 then regular expressions are not checked.
952 </para> 975 </para>
953 976
954 <para> 977 <para>
955 Also, using the "<value>=</value>" prefix it's possible to define 978 Also, using the <dq><value>=</value></dq> prefix it is possible to define
956 an exact match of URI and location. 979 an exact match of URI and location.
957 If an exact match is found, the search terminates. 980 If an exact match is found, the search terminates.
958 For example, if a "<code>/</code>" request happens frequently, 981 For example, if a <dq><code>/</code></dq> request happens frequently,
959 defining "<code>location = /</code>" will speed up the processing 982 defining <dq><code>location = /</code></dq> will speed up the processing
960 of these requests, as search terminates right after the first 983 of these requests, as search terminates right after the first
961 comparison. 984 comparison.
962 </para> 985 </para>
963 986
964 <para> 987 <para>
965 In versions from 0.7.1 to 0.8.41, if a request matched the prefix 988 In versions from 0.7.1 to 0.8.41, if a request matched the prefix
966 location without the "<value>=</value>" and "<value>^~</value>" 989 location without the <dq><value>=</value></dq> and <dq><value>^~</value></dq>
967 prefixes, the search also terminated and regular expressions were 990 prefixes, the search also terminated and regular expressions were
968 not checked. 991 not checked.
969 </para> 992 </para>
970 993
971 <para> 994 <para>
972 Let's illustrate the above by an example: 995 Let's illustrate the above by example:
973 <example> 996 <example>
974 location = / { 997 location = / {
975 [ configuration A ] 998 [ configuration A ]
976 } 999 }
977 1000
978 location / { 1001 location / {
979 [ configuration B ] 1002 [ configuration B ]
980 } 1003 }
981 1004
982 location ^~ /images/ { 1005 location ^~ /images/ {
983 [ configuration C ] 1006 [ configuration C ]
985 1008
986 location ~* \.(gif|jpg|jpeg)$ { 1009 location ~* \.(gif|jpg|jpeg)$ {
987 [ configuration D ] 1010 [ configuration D ]
988 } 1011 }
989 </example> 1012 </example>
990 The "<code>/</code>" request will match configuration A, 1013 The <dq><code>/</code></dq> request will match configuration A,
991 the "<code>/documents/document.html</code>" request&mdash;configuration B, 1014 the <dq><code>/documents/document.html</code></dq> request will match
992 the "<code>/images/1.gif</code>" request&mdash;configuration C, and 1015 configuration B,
993 the "<code>/documents/1.jpg</code>" request&mdash;configuration D. 1016 the <dq><code>/images/1.gif</code></dq> request will match configuration C, and
994 </para> 1017 the <dq><code>/documents/1.jpg</code></dq> request will match configuration D.
995 1018 </para>
996 <para> 1019
997 The "<code>@</code>" prefix defines a named location. 1020 <para>
998 Such a location isn't used for a regular request processing, but instead 1021 The <dq><value>@</value></dq> prefix defines a named location.
1022 Such a location is not used for a regular request processing, but instead
999 used for request redirection. 1023 used for request redirection.
1000 </para> 1024 </para>
1001 1025
1002 <!-- 1026 <!--
1003 <migration from="Apache" directive="Location" /> 1027 <migration from="Apache" directive="Location" />
1048 </para> 1072 </para>
1049 1073
1050 <para> 1074 <para>
1051 Note that compression is essential for the correct prefix string 1075 Note that compression is essential for the correct prefix string
1052 and regular expressions location matching. 1076 and regular expressions location matching.
1053 Without it, the "<code>//scripts/one.php</code>" request would not match 1077 Without it, the <dq><code>//scripts/one.php</code></dq> request would not match
1054 <example> 1078 <example>
1055 location /scripts/ { 1079 location /scripts/ {
1056 ... 1080 ...
1057 } 1081 }
1058 </example> 1082 </example>
1059 and might be processed as a static file, 1083 and might be processed as a static file,
1060 so it gets converted to "<code>/scripts/one.php</code>". 1084 so it gets converted to <dq><code>/scripts/one.php</code></dq>.
1061 </para> 1085 </para>
1062 1086
1063 <para> 1087 <para>
1064 Turning the compression <value>off</value> can become necessary if a URI 1088 Turning the compression <value>off</value> can become necessary if a URI
1065 contains base64-encoded names, since base64 uses the "/" character internally. 1089 contains base64-encoded names, since base64 uses the "/" character internally.
1066 However, for security considerations, it's better to avoid turning off 1090 However, for security considerations, it is better to avoid turning off
1067 the compression. 1091 the compression.
1068 </para> 1092 </para>
1069 1093
1070 <para> 1094 <para>
1071 If a directive is specified on the 1095 If a directive is specified on the
1140 </list> 1164 </list>
1141 </para> 1165 </para>
1142 1166
1143 <para> 1167 <para>
1144 The directive has the following parameters: 1168 The directive has the following parameters:
1145 <list type="bullet"> 1169 <list type="tag">
1146 1170
1147 <listitem> 1171 <tag-name>
1148 <parameter>max</parameter>&mdash; 1172 <parameter>max</parameter>
1173 </tag-name>
1174 <tag-desc>
1149 sets the maximum number of elements in the cache; 1175 sets the maximum number of elements in the cache;
1150 on cache overflow the least recently used (LRU) elements get removed; 1176 on cache overflow the least recently used (LRU) elements get removed;
1151 </listitem> 1177 </tag-desc>
1152 1178
1153 <listitem> 1179 <tag-name>
1154 <parameter>inactive</parameter>&mdash; 1180 <parameter>inactive</parameter>
1181 </tag-name>
1182 <tag-desc>
1155 defines a time, after which the element gets removed from the cache 1183 defines a time, after which the element gets removed from the cache
1156 if there were no accesses to it during this time; 1184 if there were no accesses to it during this time;
1157 by default, it is 60 seconds; 1185 by default, it is 60 seconds;
1158 </listitem> 1186 </tag-desc>
1159 1187
1160 <listitem> 1188 <tag-name>
1161 <value>off</value>&mdash;disables the cache. 1189 <value>off</value>
1162 </listitem> 1190 </tag-name>
1191 <tag-desc>
1192 disables the cache.
1193 </tag-desc>
1163 1194
1164 </list> 1195 </list>
1165 </para> 1196 </para>
1166 1197
1167 <para> 1198 <para>
1168 Example: 1199 Example:
1169 <example> 1200 <example>
1170 open_file_cache max=1000 inactive=20s; 1201 open_file_cache max=1000 inactive=20s;
1171 open_file_cache_valid 30s; 1202 open_file_cache_valid 30s;
1172 open_file_cache_min_uses 2; 1203 open_file_cache_min_uses 2;
1173 open_file_cache_errors on;<!-- open_file_cache_events on; --> 1204 open_file_cache_errors on;
1205 <!--
1206 open_file_cache_events on;
1207 -->
1174 </example> 1208 </example>
1175 </para> 1209 </para>
1176 1210
1177 </directive> 1211 </directive>
1178 1212
1296 </directive> 1330 </directive>
1297 1331
1298 1332
1299 <directive name="read_ahead"> 1333 <directive name="read_ahead">
1300 <syntax>read_ahead <argument>size</argument></syntax> 1334 <syntax>read_ahead <argument>size</argument></syntax>
1301 <default>read_ahead 0</default> 1335 <default>read_ahead 0</default>
1302 <context>http</context> 1336 <context>http</context>
1303 <context>server</context> 1337 <context>server</context>
1304 <context>location</context> 1338 <context>location</context>
1305 1339
1306 <para> 1340 <para>
1314 </para> 1348 </para>
1315 1349
1316 <para> 1350 <para>
1317 On FreeBSD, the 1351 On FreeBSD, the
1318 <code>fcntl(O_READAHEAD,</code><argument>size</argument><code>)</code> 1352 <code>fcntl(O_READAHEAD,</code><argument>size</argument><code>)</code>
1319 system call is used, supported in FreeBSD 9.0-CURRENT. 1353 system call is used, supported in FreeBSD&nbsp;9.0-CURRENT.
1320 FreeBSD&nbsp;7 needs to be 1354 FreeBSD&nbsp;7 needs to be
1321 <link doc="http://sysoev.ru/freebsd/patch.readahead.txt">patched</link>. 1355 <link doc="http://sysoev.ru/freebsd/patch.readahead.txt">patched</link>.
1322 </para> 1356 </para>
1323 1357
1324 </directive> 1358 </directive>
1339 1373
1340 </directive> 1374 </directive>
1341 1375
1342 1376
1343 <directive name="reset_timedout_connection"> 1377 <directive name="reset_timedout_connection">
1344 <syntax>reset_timedout_connection <value>on</value> | <value>off</value></syntax> 1378 <syntax>reset_timedout_connection
1379 <value>on</value> | <value>off</value></syntax>
1345 <default>reset_timedout_connection off</default> 1380 <default>reset_timedout_connection off</default>
1346 <context>http</context> 1381 <context>http</context>
1347 <context>server</context> 1382 <context>server</context>
1348 <context>location</context> 1383 <context>location</context>
1349 1384
1374 <context>location</context> 1409 <context>location</context>
1375 1410
1376 <para> 1411 <para>
1377 Sets the <argument>address</argument> of a name server, for example: 1412 Sets the <argument>address</argument> of a name server, for example:
1378 <example> 1413 <example>
1379 resolver 127.0.0.1; 1414 resolver 127.0.0.1;
1380 </example> 1415 </example>
1381 </para> 1416 </para>
1382 1417
1383 </directive> 1418 </directive>
1384 1419
1391 <context>location</context> 1426 <context>location</context>
1392 1427
1393 <para> 1428 <para>
1394 Sets a timeout for name resolution, for example: 1429 Sets a timeout for name resolution, for example:
1395 <example> 1430 <example>
1396 resolver_timeout 5s; 1431 resolver_timeout 5s;
1397 </example> 1432 </example>
1398 </para> 1433 </para>
1399 1434
1400 </directive> 1435 </directive>
1401 1436
1410 1445
1411 <para> 1446 <para>
1412 Sets the root directory for requests. 1447 Sets the root directory for requests.
1413 For example, with the following configuration 1448 For example, with the following configuration
1414 <example> 1449 <example>
1415 location /i/ { 1450 location /i/ {
1416 root /data/w3; 1451 root /data/w3;
1417 } 1452 }
1418 </example> 1453 </example>
1419 the request of "/i/top.gif" will be responded 1454 <dq><code>/i/top.gif</code></dq> will be responded
1420 with the file "/data/w3/images/top.gif". 1455 with the file
1456 <dq><pathname>/data/w3/i/top.gif</pathname></dq>.
1421 </para> 1457 </para>
1422 1458
1423 <para> 1459 <para>
1424 The <argument>path</argument> value can contain variables. 1460 The <argument>path</argument> value can contain variables.
1425 </para> 1461 </para>
1444 <link doc="ngx_http_access_module.xml">http_access</link> 1480 <link doc="ngx_http_access_module.xml">http_access</link>
1445 or <link doc="ngx_http_auth_basic_module.xml">http_auth_basic</link> 1481 or <link doc="ngx_http_auth_basic_module.xml">http_auth_basic</link>
1446 modules grant access. 1482 modules grant access.
1447 <example> 1483 <example>
1448 location / { 1484 location / {
1449 satisfy any; 1485 satisfy any;
1450 1486
1451 allow 192.168.1.0/32; 1487 allow 192.168.1.0/32;
1452 deny all; 1488 deny all;
1453 1489
1454 auth_basic "closed site"; 1490 auth_basic "closed site";
1455 auth_basic_user_file conf/htpasswd; 1491 auth_basic_user_file conf/htpasswd;
1456 } 1492 }
1457 </example> 1493 </example>
1458 </para> 1494 </para>
1459 1495
1460 </directive> 1496 </directive>
1512 <context>http</context> 1548 <context>http</context>
1513 1549
1514 <para> 1550 <para>
1515 Sets a configuration for the virtual server. 1551 Sets a configuration for the virtual server.
1516 There is no clean separation between IP-based (based on the IP address) 1552 There is no clean separation between IP-based (based on the IP address)
1517 and name-based (based on the <header>Host</header> header string) 1553 and name-based (based on the <header>Host</header> request header field)
1518 virtual servers. 1554 virtual servers.
1519 Instead, the <link id="listen">listen</link> directives describe all 1555 Instead, the <link id="listen">listen</link> directives describe all
1520 addresses and ports that should accept connections for a server, and the 1556 addresses and ports that should accept connections for a server, and the
1521 <link id="server_name">server_name</link> directive lists all server names. 1557 <link id="server_name">server_name</link> directive lists all server names.
1522 An example configuration is provided in the 1558 An example configuration is provided in the
1526 1562
1527 </directive> 1563 </directive>
1528 1564
1529 1565
1530 <directive name="server_name"> 1566 <directive name="server_name">
1531 <syntax>server_name <argument>name ...</argument></syntax> 1567 <syntax>server_name <argument>name</argument> ...</syntax>
1532 <default>server_name hostname</default> 1568 <default>server_name hostname</default>
1533 <context>server</context> 1569 <context>server</context>
1534 1570
1535 <para> 1571 <para>
1536 Sets names of the virtual server, for example: 1572 Sets names of the virtual server, for example:
1537 <example> 1573 <example>
1538 server { 1574 server {
1539 server_name example.com www.example.com; 1575 server_name example.com www.example.com;
1540 } 1576 }
1541 </example> 1577 </example>
1542 </para> 1578 </para>
1543 1579
1544 <para> 1580 <para>
1545 The first name becomes a primary server name. 1581 The first name becomes a primary server name.
1546 By default, the machine's hostname is used. 1582 By default, the machine's hostname is used.
1547 Server names can include an asterisk ("<code>*</code>") 1583 Server names can include an asterisk (<dq><code>*</code></dq>)
1548 to replace the first or last part of a name: 1584 to replace the first or last part of a name:
1549 <example> 1585 <example>
1550 server { 1586 server {
1551 server_name example.com *.example.com www.example.*; 1587 server_name example.com *.example.com www.example.*;
1552 } 1588 }
1553 </example> 1589 </example>
1554 </para> 1590 </para>
1555 1591
1556 <para> 1592 <para>
1557 The first two of the above mentioned names can be combined: 1593 The first two of the above mentioned names can be combined:
1558 <example> 1594 <example>
1559 server { 1595 server {
1560 server_name .example.com; 1596 server_name .example.com;
1561 } 1597 }
1562 </example> 1598 </example>
1563 </para> 1599 </para>
1564 1600
1565 <para> 1601 <para>
1566 It is also possible to use regular expressions in server names, 1602 It is also possible to use regular expressions in server names,
1567 prepending the name with a tilde ("<code>~</code>"): 1603 prepending the name with a tilde (<dq><code>~</code></dq>):
1568 <example> 1604 <example>
1569 server { 1605 server {
1570 server_name www.example.com ~^www\d+\.example\.com$; 1606 server_name www.example.com ~^www\d+\.example\.com$;
1571 } 1607 }
1572 </example> 1608 </example>
1573 </para> 1609 </para>
1574 1610
1575 <para> 1611 <para>
1576 Regular expressions can contain captures (0.7.40) that can later 1612 Regular expressions can contain captures (0.7.40) that can later
1577 be used in other directives: 1613 be used in other directives:
1578 <example> 1614 <example>
1579 server { 1615 server {
1580 server_name ~^(www\.)?(.+)$; 1616 server_name ~^(www\.)?(.+)$;
1581 1617
1582 location / { 1618 location / {
1583 root /sites/$2; 1619 root /sites/$2;
1584 } 1620 }
1585 } 1621 }
1586 1622
1587 server { 1623 server {
1588 server_name _; 1624 server_name _;
1589 1625
1590 location / { 1626 location / {
1591 root /sites/default; 1627 root /sites/default;
1592 } 1628 }
1593 } 1629 }
1594 </example> 1630 </example>
1595 </para> 1631 </para>
1596 1632
1597 <para> 1633 <para>
1598 Starting from version 0.8.25, named captures in regular expressions create 1634 Starting from version 0.8.25, named captures in regular expressions create
1599 variables that can later be used in other directives: 1635 variables that can later be used in other directives:
1600 <example> 1636 <example>
1601 server { 1637 server {
1602 server_name ~^(www\.)?(?&lt;domain&gt;.+)$; 1638 server_name ~^(www\.)?(?&lt;domain&gt;.+)$;
1603 1639
1604 location / { 1640 location / {
1605 root /sites/$domain; 1641 root /sites/$domain;
1606 } 1642 }
1607 } 1643 }
1608 1644
1609 server { 1645 server {
1610 server_name _; 1646 server_name _;
1611 1647
1612 location / { 1648 location / {
1613 root /sites/default; 1649 root /sites/default;
1614 } 1650 }
1615 } 1651 }
1616 </example> 1652 </example>
1617 </para> 1653 </para>
1618 1654
1619 <para> 1655 <para>
1620 Starting from version 0.7.11, it is possible to specify an empty name "": 1656 Starting from version 0.7.11, it is possible to specify an empty name:
1621 <example> 1657 <example>
1622 server { 1658 server {
1623 server_name www.example.com ""; 1659 server_name www.example.com "";
1624 } 1660 }
1625 </example> 1661 </example>
1626 It allows this server to process requests without the <header>Host</header> 1662 It allows this server to process requests without the <header>Host</header>
1627 header, instead of the default server for the given address:port pair. 1663 header, instead of the default server for the given address:port pair.
1628 </para> 1664 </para>
1634 <listitem> 1670 <listitem>
1635 full names 1671 full names
1636 </listitem> 1672 </listitem>
1637 1673
1638 <listitem> 1674 <listitem>
1639 names with the prefix mask&mdash;*.example.com 1675 names with the prefix mask, e.g. <dq><code>*.example.com</code></dq>
1640 </listitem> 1676 </listitem>
1641 1677
1642 <listitem> 1678 <listitem>
1643 names with the suffix mask&mdash;mail.* 1679 names with the suffix mask, e.g. <dq><code>mail.*</code></dq>
1644 </listitem> 1680 </listitem>
1645 1681
1646 <listitem> 1682 <listitem>
1647 regular expressions 1683 regular expressions
1648 </listitem> 1684 </listitem>
1662 1698
1663 <para> 1699 <para>
1664 Enables or disables the use of the primary server name, specified by the 1700 Enables or disables the use of the primary server name, specified by the
1665 <link id="server_name">server_name</link> 1701 <link id="server_name">server_name</link>
1666 directive, in redirects issued by nginx. 1702 directive, in redirects issued by nginx.
1667 When disabled, the name from the <header>Host</header> request header string 1703 When disabled, the name from the <header>Host</header> request header field
1668 is used. 1704 is used.
1669 If there's no such a string, an IP address of the server is used. 1705 If this field is not present, an IP address of the server is used.
1670 </para> 1706 </para>
1671 1707
1672 </directive> 1708 </directive>
1673 1709
1674 1710
1708 <context>server</context> 1744 <context>server</context>
1709 <context>location</context> 1745 <context>location</context>
1710 1746
1711 <para> 1747 <para>
1712 Enables or disables emitting of nginx version in error messages and in the 1748 Enables or disables emitting of nginx version in error messages and in the
1713 <header>Server</header> response header string. 1749 <header>Server</header> response header field.
1714 </para> 1750 </para>
1715 1751
1716 </directive> 1752 </directive>
1717 1753
1718 1754
1761 1797
1762 </directive> 1798 </directive>
1763 1799
1764 1800
1765 <directive name="try_files"> 1801 <directive name="try_files">
1766 <syntax>try_files <argument>file ... uri</argument></syntax> 1802 <syntax>try_files
1767 <syntax>try_files <argument>file ...</argument> =<argument>code</argument></syntax> 1803 <argument>file</argument> ...
1804 <argument>uri</argument>
1805 </syntax>
1806 <syntax>try_files
1807 <argument>file</argument> ...
1808 =<argument>code</argument>
1809 </syntax>
1768 <default/> 1810 <default/>
1769 <context>location</context> 1811 <context>location</context>
1770 1812
1771 <para> 1813 <para>
1772 Checks the existence of files in the specified order, and uses 1814 Checks the existence of files in the specified order, and uses
1773 the first found file for request processing; the processing 1815 the first found file for request processing; the processing
1774 is performed in this location's context. 1816 is performed in this location's context.
1775 It is possible to check the directory existence by specifying 1817 It is possible to check the directory existence by specifying
1776 the slash at the end of a name, e.g. "<code>$uri/</code>". 1818 the slash at the end of a name, e.g. <dq><code>$uri/</code></dq>.
1777 If none of the files were found, an internal redirect to the 1819 If none of the files were found, an internal redirect to the
1778 <argument>uri</argument> specified by the last argument is made. 1820 <argument>uri</argument> specified by the last argument is made.
1779 As of version 0.7.51, the last argument can also be a 1821 As of version 0.7.51, the last argument can also be a
1780 <argument>code</argument>: 1822 <argument>code</argument>:
1781 <example> 1823 <example>
1782 location / { 1824 location / {
1783 try_files $uri $uri/index.html $uri.html =404; 1825 try_files $uri $uri/index.html $uri.html =404;
1784 } 1826 }
1785 </example> 1827 </example>
1786 </para> 1828 </para>
1787 1829
1788 <para> 1830 <para>
1789 Example when proxying Mongrel: 1831 Example when proxying Mongrel:
1790 <example> 1832 <example>
1791 location / { 1833 location / {
1792 try_files /system/maintenance.html 1834 try_files /system/maintenance.html
1793 $uri $uri/index.html $uri.html 1835 $uri $uri/index.html $uri.html
1794 @mongrel; 1836 @mongrel;
1795 } 1837 }
1796 1838
1797 location @mongrel { 1839 location @mongrel {
1798 proxy_pass http://mongrel; 1840 proxy_pass http://mongrel;
1799 } 1841 }
1800 </example> 1842 </example>
1801 </para> 1843 </para>
1802 1844
1803 <para> 1845 <para>
1804 Example for Drupal/FastCGI: 1846 Example for Drupal/FastCGI:
1805 <example> 1847 <example>
1806 location / { 1848 location / {
1807 try_files $uri $uri/ @drupal; 1849 try_files $uri $uri/ @drupal;
1808 } 1850 }
1809 1851
1810 location ~ \.php$ { 1852 location ~ \.php$ {
1811 try_files $uri @drupal; 1853 try_files $uri @drupal;
1812 1854
1813 fastcgi_pass ...; 1855 fastcgi_pass ...;
1814 1856
1815 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; 1857 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
1816 fastcgi_param SCRIPT_NAME $fastcgi_script_name; 1858 fastcgi_param SCRIPT_NAME $fastcgi_script_name;
1817 fastcgi_param QUERY_STRING $args; 1859 fastcgi_param QUERY_STRING $args;
1818 1860
1819 ... other fastcgi_param's 1861 ... other fastcgi_param's
1820 } 1862 }
1821 1863
1822 location @drupal { 1864 location @drupal {
1823 fastcgi_pass ...; 1865 fastcgi_pass ...;
1824 1866
1825 fastcgi_param SCRIPT_FILENAME /path/to/index.php; 1867 fastcgi_param SCRIPT_FILENAME /path/to/index.php;
1826 fastcgi_param SCRIPT_NAME /index.php; 1868 fastcgi_param SCRIPT_NAME /index.php;
1827 fastcgi_param QUERY_STRING q=$uri&amp;$args; 1869 fastcgi_param QUERY_STRING q=$uri&amp;$args;
1828 1870
1829 ... other fastcgi_param's 1871 ... other fastcgi_param's
1830 } 1872 }
1831 </example> 1873 </example>
1832 In the following example, 1874 In the following example,
1833 <example> 1875 <example>
1834 location / { 1876 location / {
1835 try_files $uri $uri/ @drupal; 1877 try_files $uri $uri/ @drupal;
1836 } 1878 }
1837 </example> 1879 </example>
1838 the <command>try_files</command> directive is equivalent to 1880 the <command>try_files</command> directive is equivalent to
1839 <example> 1881 <example>
1840 location / { 1882 location / {
1841 error_page 404 = @drupal; 1883 error_page 404 = @drupal;
1842 log_not_found off; 1884 log_not_found off;
1843 } 1885 }
1844 </example> 1886 </example>
1845 And here, 1887 And here,
1846 <example> 1888 <example>
1847 location ~ \.php$ { 1889 location ~ \.php$ {
1848 try_files $uri @drupal; 1890 try_files $uri @drupal;
1849 1891
1850 fastcgi_pass ...; 1892 fastcgi_pass ...;
1851 1893
1852 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; 1894 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
1853 1895
1854 ... 1896 ...
1855 } 1897 }
1856 </example> 1898 </example>
1857 <command>try_files</command> checks the existence of the PHP file 1899 <command>try_files</command> checks the existence of the PHP file
1860 1902
1861 <para> 1903 <para>
1862 Example for Wordpress and Joomla: 1904 Example for Wordpress and Joomla:
1863 <example> 1905 <example>
1864 location / { 1906 location / {
1865 try_files $uri $uri/ @wordpress; 1907 try_files $uri $uri/ @wordpress;
1866 } 1908 }
1867 1909
1868 location ~ \.php$ { 1910 location ~ \.php$ {
1869 try_files $uri @wordpress; 1911 try_files $uri @wordpress;
1870 1912
1871 fastcgi_pass ...; 1913 fastcgi_pass ...;
1872 1914
1873 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; 1915 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
1874 ... other fastcgi_param's 1916 ... other fastcgi_param's
1875 } 1917 }
1876 1918
1877 location @wordpress { 1919 location @wordpress {
1878 fastcgi_pass ...; 1920 fastcgi_pass ...;
1879 1921
1880 fastcgi_param SCRIPT_FILENAME /path/to/index.php; 1922 fastcgi_param SCRIPT_FILENAME /path/to/index.php;
1881 ... other fastcgi_param's 1923 ... other fastcgi_param's
1882 } 1924 }
1883 </example> 1925 </example>
1884 </para> 1926 </para>
1885 1927
1897 Maps file name extensions to MIME types of responses. 1939 Maps file name extensions to MIME types of responses.
1898 Several extensions can map to one type. 1940 Several extensions can map to one type.
1899 The following mappings are configured by default: 1941 The following mappings are configured by default:
1900 <example> 1942 <example>
1901 types { 1943 types {
1902 text/html html; 1944 text/html html;
1903 image/gif gif; 1945 image/gif gif;
1904 image/jpeg jpg; 1946 image/jpeg jpg;
1905 } 1947 }
1906 </example> 1948 </example>
1907 </para> 1949 </para>
1908 1950
1909 <para> 1951 <para>
1910 A sufficiently full mapping table is distributed with nginx in the 1952 A sufficiently full mapping table is distributed with nginx in the
1911 <code>conf/mime.types</code> file. 1953 <pathname>conf/mime.types</pathname> file.
1912 </para> 1954 </para>
1913 1955
1914 <para> 1956 <para>
1915 To make a particular location emit the "<code>application/octet-stream</code>" 1957 To make a particular location emit the
1958 <dq><code>application/octet-stream</code></dq>
1916 MIME type for all requests, try the following: 1959 MIME type for all requests, try the following:
1917 <example> 1960 <example>
1918 location /download/ { 1961 location /download/ {
1919 types { } 1962 types { }
1920 default_type application/octet-stream; 1963 default_type application/octet-stream;
1921 } 1964 }
1922 </example> 1965 </example>
1923 </para> 1966 </para>
1924 1967
1925 </directive> 1968 </directive>
1930 <default>underscores_in_headers off</default> 1973 <default>underscores_in_headers off</default>
1931 <context>http</context> 1974 <context>http</context>
1932 <context>server</context> 1975 <context>server</context>
1933 1976
1934 <para> 1977 <para>
1935 Enables or disables the use of underscores in client request header strings. 1978 Enables or disables the use of underscores in client request header fields.
1936 </para> 1979 </para>
1937 1980
1938 </directive> 1981 </directive>
1939 1982
1940 </section> 1983 </section>
1941 1984
1985 <section id="variables" name="Embedded Variables">
1986
1987 <para>
1988 The http_core module supports embedded variables with names matching
1989 those of the Apache Server.
1990 First of all, these are variables representing client request header
1991 fields, such as, <var>$http_user_agent</var>, <var>$http_cookie</var>,
1992 and so on.
1993 It also supports other variables:
1994 <list type="tag">
1995
1996 <tag-name><var>$args</var></tag-name>
1997 <tag-desc>
1998 arguments in the request line
1999 </tag-desc>
2000
2001 <tag-name><var>$arg_</var><argument>name</argument></tag-name>
2002 <tag-desc>
2003 argument <argument>name</argument> in the request line
2004 </tag-desc>
2005
2006 <tag-name><var>$binary_remote_addr</var></tag-name>
2007 <tag-desc>
2008 client address in a binary form, value's length is always 4 bytes
2009 </tag-desc>
2010
2011 <tag-name><var>$content_length</var></tag-name>
2012 <tag-desc>
2013 <header>Content-Length</header> request header field
2014 </tag-desc>
2015
2016 <tag-name><var>$content_type</var></tag-name>
2017 <tag-desc>
2018 <header>Content-Type</header> request header field
2019 </tag-desc>
2020
2021 <tag-name><var>$cookie_</var><argument>name</argument></tag-name>
2022 <tag-desc>
2023 the <argument>name</argument> cookie
2024 </tag-desc>
2025
2026 <tag-name><var>$document_root</var></tag-name>
2027 <tag-desc>
2028 <link id="root">root</link> directive's value for the current request
2029 </tag-desc>
2030
2031 <tag-name><var>$document_uri</var></tag-name>
2032 <tag-desc>
2033 same as <var>$uri</var>
2034 </tag-desc>
2035
2036 <tag-name><var>$host</var></tag-name>
2037 <tag-desc>
2038 <header>Host</header> request header field,
2039 or the server name matching a request if this field is not present
2040 </tag-desc>
2041
2042 <tag-name><var>$hostname</var></tag-name>
2043 <tag-desc>
2044 host name
2045 </tag-desc>
2046
2047 <tag-name><var>$http_</var><argument>name</argument></tag-name>
2048 <tag-desc>
2049 the <argument>name</argument> request header field
2050 </tag-desc>
2051
2052 <tag-name><var>$is_args</var></tag-name>
2053 <tag-desc>
2054 <dq><code>?</code></dq> if a request line has arguments,
2055 or an empty string otherwise
2056 </tag-desc>
2057
2058 <tag-name><var>$limit_rate</var></tag-name>
2059 <tag-desc>
2060 allows for connection rate limiting
2061 </tag-desc>
2062
2063 <tag-name><var>$pid</var></tag-name>
2064 <tag-desc>
2065 PID of the worker process
2066 </tag-desc>
2067
2068 <tag-name><var>$request_method</var></tag-name>
2069 <tag-desc>
2070 request method, usually
2071 <dq><code>GET</code></dq> or <dq><code>POST</code></dq>
2072 </tag-desc>
2073
2074 <tag-name><var>$remote_addr</var></tag-name>
2075 <tag-desc>
2076 client address
2077 </tag-desc>
2078
2079 <tag-name><var>$remote_port</var></tag-name>
2080 <tag-desc>
2081 client port
2082 </tag-desc>
2083
2084 <tag-name><var>$remote_user</var></tag-name>
2085 <tag-desc>
2086 user name supplied with the Basic authentication
2087 </tag-desc>
2088
2089 <tag-name><var>$realpath_root</var></tag-name>
2090 <tag-desc>
2091 <link id="root">root</link> directive's value
2092 for the current request, with all symbolic links resolved to real paths
2093 </tag-desc>
2094
2095 <tag-name><var>$request_filename</var></tag-name>
2096 <tag-desc>
2097 file path for the current query, based on the
2098 <link id="root">root</link> and <link id="alias">alias</link>
2099 directives, and the request URI
2100 </tag-desc>
2101
2102 <tag-name><var>$request_body</var></tag-name>
2103 <tag-desc>
2104 request body
2105 <para>
2106 The variable's value is made available in locations
2107 processed by the
2108 <link doc="ngx_http_proxy_module.xml" id="proxy_pass">proxy_pass</link>
2109 and
2110 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass">fastcgi_pass</link>
2111 directives.
2112 </para>
2113 </tag-desc>
2114
2115 <tag-name><var>$request_body_file</var></tag-name>
2116 <tag-desc>
2117 name of a temporary file with the request body
2118 <para>
2119 At the end of processing, the file needs to be removed.
2120 To always write a request body to a file,
2121 <link id="client_body_in_file_only">client_body_in_file_only on</link>
2122 needs be specified.
2123 When passing the name of a temporary file in a proxied request,
2124 or in a request to a FastCGI server,
2125 passing of the request body should be disabled by the
2126 <link doc="ngx_http_proxy_module.xml"
2127 id="proxy_pass_request_body">proxy_pass_request_body</link>
2128 and
2129 <link doc="ngx_http_fastcgi_module.xml"
2130 id="fastcgi_pass_request_body">fastcgi_pass_request_body</link>
2131 directives, respectively.
2132 </para>
2133 </tag-desc>
2134
2135 <tag-name><var>$request_uri</var></tag-name>
2136 <tag-desc>
2137 full original request URI (with arguments)
2138 </tag-desc>
2139
2140 <tag-name><var>$query_string</var></tag-name>
2141 <tag-desc>
2142 same as <var>$args</var>
2143 </tag-desc>
2144
2145 <tag-name><var>$scheme</var></tag-name>
2146 <tag-desc>
2147 request scheme, <dq><code>http</code></dq> or <dq><code>https</code>></dq>
2148 </tag-desc>
2149
2150 <tag-name><var>$server_protocol</var></tag-name>
2151 <tag-desc>
2152 request protocol, usually
2153 <dq><code>HTTP/1.0</code></dq>
2154 or
2155 <dq><code>HTTP/1.1</code></dq>
2156 </tag-desc>
2157
2158 <tag-name><var>$server_addr</var></tag-name>
2159 <tag-desc>
2160 an address of the server which accepted a request
2161 <para>
2162 Computing a value of this variable usually requires one system call.
2163 To avoid a system call, the <command>listen</command> directives
2164 must specify addresses and use the <parameter>bind</parameter> parameter
2165 </para>
2166 </tag-desc>
2167
2168 <tag-name><var>$server_name</var></tag-name>
2169 <tag-desc>
2170 name of the server which accepted a request
2171 </tag-desc>
2172
2173 <tag-name><var>$server_port</var></tag-name>
2174 <tag-desc>
2175 port of the server which accepted a request
2176 </tag-desc>
2177
2178 <tag-name><var>$uri</var></tag-name>
2179 <tag-desc>
2180 current URI in request
2181 <para>
2182 It may differ from an original, e.g. when doing internal redirects,
2183 or when using index files.
2184 </para>
2185 </tag-desc>
2186
2187 </list>
2188 </para>
2189
2190 </section>
2191
1942 </module> 2192 </module>