Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_core_module.xml @ 271:4c6d2c614d2c
Cleaned up XML tag mess:
- all of <parameter> and <code>, and some of <dirname>, <value>,
and <command> were replaced by <literal>;
- the rest of <dirname> were replaced by links;
- <argument> were replaced by <value>;
- <value> is now rendered in HTML in italic;
- <literal> and <path> can now contain <value>.
Cleaned up terminology mess:
- directives take "parameters".
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Fri, 23 Dec 2011 17:29:59 +0000 |
parents | 945d7299c26c |
children | 4a0fe9283dc7 |
comparison
equal
deleted
inserted
replaced
270:945d7299c26c | 271:4c6d2c614d2c |
---|---|
8 | 8 |
9 <section id="directives" name="Directives"> | 9 <section id="directives" name="Directives"> |
10 | 10 |
11 <directive name="aio"> | 11 <directive name="aio"> |
12 <syntax> | 12 <syntax> |
13 <value>on</value> | | 13 <literal>on</literal> | |
14 <value>off</value> | | 14 <literal>off</literal> | |
15 <value>sendfile</value></syntax> | 15 <literal>sendfile</literal></syntax> |
16 <default>off</default> | 16 <default>off</default> |
17 <context>http</context> | 17 <context>http</context> |
18 <context>server</context> | 18 <context>server</context> |
19 <context>location</context> | 19 <context>location</context> |
20 <appeared-in>0.8.11</appeared-in> | 20 <appeared-in>0.8.11</appeared-in> |
130 | 130 |
131 </directive> | 131 </directive> |
132 | 132 |
133 | 133 |
134 <directive name="alias"> | 134 <directive name="alias"> |
135 <syntax><argument>path</argument></syntax> | 135 <syntax><value>path</value></syntax> |
136 <default/> | 136 <default/> |
137 <context>location</context> | 137 <context>location</context> |
138 | 138 |
139 <para> | 139 <para> |
140 Defines a replacement for the specified location. | 140 Defines a replacement for the specified location. |
143 location /i/ { | 143 location /i/ { |
144 alias /data/w3/images/; | 144 alias /data/w3/images/; |
145 } | 145 } |
146 </example> | 146 </example> |
147 the request of | 147 the request of |
148 “<code>/i/top.gif</code>” will be responded | 148 “<literal>/i/top.gif</literal>” will be responded |
149 with the file | 149 with the file |
150 <path>/data/w3/images/top.gif</path>. | 150 <path>/data/w3/images/top.gif</path>. |
151 </para> | 151 </para> |
152 | 152 |
153 <para> | 153 <para> |
154 The <argument>path</argument> value can contain variables | 154 The <value>path</value> value can contain variables |
155 except <var>$document_root</var> and <var>$realpath_root</var>. | 155 except <var>$document_root</var> and <var>$realpath_root</var>. |
156 </para> | 156 </para> |
157 | 157 |
158 <para> | 158 <para> |
159 If <code>alias</code> is used inside a location defined | 159 If <literal>alias</literal> is used inside a location defined |
160 with a regular expression then such regular expression should | 160 with a regular expression then such regular expression should |
161 contain captures and <code>alias</code> should refer to | 161 contain captures and <literal>alias</literal> should refer to |
162 these captures (0.7.40), for example: | 162 these captures (0.7.40), for example: |
163 <example> | 163 <example> |
164 location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ { | 164 location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ { |
165 alias /data/w3/images/$1; | 165 alias /data/w3/images/$1; |
166 } | 166 } |
186 | 186 |
187 </directive> | 187 </directive> |
188 | 188 |
189 | 189 |
190 <directive name="chunked_transfer_encoding"> | 190 <directive name="chunked_transfer_encoding"> |
191 <syntax><value>on</value> | <value>off</value></syntax> | 191 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
192 <default>on</default> | 192 <default>on</default> |
193 <context>http</context> | 193 <context>http</context> |
194 <context>server</context> | 194 <context>server</context> |
195 <context>location</context> | 195 <context>location</context> |
196 | 196 |
203 </directive> | 203 </directive> |
204 | 204 |
205 | 205 |
206 <directive name="client_body_buffer_size"> | 206 <directive name="client_body_buffer_size"> |
207 | 207 |
208 <syntax><argument>size</argument></syntax> | 208 <syntax><value>size</value></syntax> |
209 <default>8k|16k</default> | 209 <default>8k|16k</default> |
210 <context>http</context> | 210 <context>http</context> |
211 <context>server</context> | 211 <context>server</context> |
212 <context>location</context> | 212 <context>location</context> |
213 | 213 |
224 </directive> | 224 </directive> |
225 | 225 |
226 | 226 |
227 <directive name="client_body_in_file_only"> | 227 <directive name="client_body_in_file_only"> |
228 <syntax> | 228 <syntax> |
229 <value>on</value> | | 229 <literal>on</literal> | |
230 <value>clean</value> | | 230 <literal>clean</literal> | |
231 <value>off</value></syntax> | 231 <literal>off</literal></syntax> |
232 <default>off</default> | 232 <default>off</default> |
233 <context>http</context> | 233 <context>http</context> |
234 <context>server</context> | 234 <context>server</context> |
235 <context>location</context> | 235 <context>location</context> |
236 | 236 |
244 method of the module | 244 method of the module |
245 <link doc="ngx_http_perl_module.xml">ngx_http_perl_module</link>. | 245 <link doc="ngx_http_perl_module.xml">ngx_http_perl_module</link>. |
246 </para> | 246 </para> |
247 | 247 |
248 <para> | 248 <para> |
249 When set to the value <value>on</value>, temporary files are not | 249 When set to the value <literal>on</literal>, temporary files are not |
250 removed after request processing. | 250 removed after request processing. |
251 </para> | 251 </para> |
252 | 252 |
253 <para> | 253 <para> |
254 The value <value>clean</value> will cause the temporary files | 254 The value <literal>clean</literal> will cause the temporary files |
255 left after request processing to be removed. | 255 left after request processing to be removed. |
256 </para> | 256 </para> |
257 | 257 |
258 </directive> | 258 </directive> |
259 | 259 |
260 | 260 |
261 <directive name="client_body_in_single_buffer"> | 261 <directive name="client_body_in_single_buffer"> |
262 <syntax><value>on</value> | <value>off</value></syntax> | 262 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
263 <default>off</default> | 263 <default>off</default> |
264 <context>http</context> | 264 <context>http</context> |
265 <context>server</context> | 265 <context>server</context> |
266 <context>location</context> | 266 <context>location</context> |
267 | 267 |
276 </directive> | 276 </directive> |
277 | 277 |
278 | 278 |
279 <directive name="client_body_temp_path"> | 279 <directive name="client_body_temp_path"> |
280 <syntax> | 280 <syntax> |
281 <argument>path</argument> | 281 <value>path</value> |
282 [<argument>level1</argument> | 282 [<value>level1</value> |
283 [<argument>level2</argument> | 283 [<value>level2</value> |
284 [<argument>level3</argument>]]]</syntax> | 284 [<value>level3</value>]]]</syntax> |
285 <default>client_body_temp</default> | 285 <default>client_body_temp</default> |
286 <context>http</context> | 286 <context>http</context> |
287 <context>server</context> | 287 <context>server</context> |
288 <context>location</context> | 288 <context>location</context> |
289 | 289 |
303 | 303 |
304 </directive> | 304 </directive> |
305 | 305 |
306 | 306 |
307 <directive name="client_body_timeout"> | 307 <directive name="client_body_timeout"> |
308 <syntax><argument>time</argument></syntax> | 308 <syntax><value>time</value></syntax> |
309 <default>60s</default> | 309 <default>60s</default> |
310 <context>http</context> | 310 <context>http</context> |
311 <context>server</context> | 311 <context>server</context> |
312 <context>location</context> | 312 <context>location</context> |
313 | 313 |
323 | 323 |
324 </directive> | 324 </directive> |
325 | 325 |
326 | 326 |
327 <directive name="client_header_buffer_size"> | 327 <directive name="client_header_buffer_size"> |
328 <syntax><argument>size</argument></syntax> | 328 <syntax><value>size</value></syntax> |
329 <default>1k</default> | 329 <default>1k</default> |
330 <context>http</context> | 330 <context>http</context> |
331 <context>server</context> | 331 <context>server</context> |
332 | 332 |
333 <para> | 333 <para> |
343 | 343 |
344 </directive> | 344 </directive> |
345 | 345 |
346 | 346 |
347 <directive name="client_header_timeout"> | 347 <directive name="client_header_timeout"> |
348 <syntax><argument>time</argument></syntax> | 348 <syntax><value>time</value></syntax> |
349 <default>60s</default> | 349 <default>60s</default> |
350 <context>http</context> | 350 <context>http</context> |
351 <context>server</context> | 351 <context>server</context> |
352 | 352 |
353 <para> | 353 <para> |
360 | 360 |
361 </directive> | 361 </directive> |
362 | 362 |
363 | 363 |
364 <directive name="client_max_body_size"> | 364 <directive name="client_max_body_size"> |
365 <syntax><argument>size</argument></syntax> | 365 <syntax><value>size</value></syntax> |
366 <default>1m</default> | 366 <default>1m</default> |
367 <context>http</context> | 367 <context>http</context> |
368 <context>server</context> | 368 <context>server</context> |
369 <context>location</context> | 369 <context>location</context> |
370 | 370 |
377 <http-status code="413" text="Request Entity Too Large"/> | 377 <http-status code="413" text="Request Entity Too Large"/> |
378 is returned. | 378 is returned. |
379 Please be aware that | 379 Please be aware that |
380 <!--link doc="/web/upload.xml"-->browsers cannot correctly display | 380 <!--link doc="/web/upload.xml"-->browsers cannot correctly display |
381 this error<!--/link-->. | 381 this error<!--/link-->. |
382 Setting <argument>size</argument> to 0 disables client | 382 Setting <value>size</value> to 0 disables client |
383 request body size checking. | 383 request body size checking. |
384 </para> | 384 </para> |
385 | 385 |
386 </directive> | 386 </directive> |
387 | 387 |
388 | 388 |
389 <directive name="connection_pool_size"> | 389 <directive name="connection_pool_size"> |
390 <syntax><argument>size</argument></syntax> | 390 <syntax><value>size</value></syntax> |
391 <default>256</default> | 391 <default>256</default> |
392 <context>http</context> | 392 <context>http</context> |
393 <context>server</context> | 393 <context>server</context> |
394 | 394 |
395 <para> | 395 <para> |
400 | 400 |
401 </directive> | 401 </directive> |
402 | 402 |
403 | 403 |
404 <directive name="default_type"> | 404 <directive name="default_type"> |
405 <syntax><argument>mime-type</argument></syntax> | 405 <syntax><value>mime-type</value></syntax> |
406 <default>text/plain</default> | 406 <default>text/plain</default> |
407 <context>http</context> | 407 <context>http</context> |
408 <context>server</context> | 408 <context>server</context> |
409 <context>location</context> | 409 <context>location</context> |
410 | 410 |
415 | 415 |
416 </directive> | 416 </directive> |
417 | 417 |
418 | 418 |
419 <directive name="directio"> | 419 <directive name="directio"> |
420 <syntax><argument>size</argument> | <value>off</value></syntax> | 420 <syntax><value>size</value> | <literal>off</literal></syntax> |
421 <default>off</default> | 421 <default>off</default> |
422 <context>http</context> | 422 <context>http</context> |
423 <context>server</context> | 423 <context>server</context> |
424 <context>location</context> | 424 <context>location</context> |
425 <appeared-in>0.7.7</appeared-in> | 425 <appeared-in>0.7.7</appeared-in> |
428 Enables the use of | 428 Enables the use of |
429 the <c-def>O_DIRECT</c-def> flag (FreeBSD, Linux), | 429 the <c-def>O_DIRECT</c-def> flag (FreeBSD, Linux), |
430 the <c-def>F_NOCACHE</c-def> flag (Mac OS X), | 430 the <c-def>F_NOCACHE</c-def> flag (Mac OS X), |
431 or the <c-func>directio</c-func> function (Solaris), | 431 or the <c-func>directio</c-func> function (Solaris), |
432 when reading files that are larger than or equal to | 432 when reading files that are larger than or equal to |
433 the specified <argument>size</argument>. | 433 the specified <value>size</value>. |
434 It automatically disables (0.7.15) the use of | 434 It automatically disables (0.7.15) the use of |
435 <link id="sendfile"/> | 435 <link id="sendfile"/> |
436 for a given request. | 436 for a given request. |
437 It could be useful for serving large files: | 437 It could be useful for serving large files: |
438 <example> | 438 <example> |
443 | 443 |
444 </directive> | 444 </directive> |
445 | 445 |
446 | 446 |
447 <directive name="directio_alignment"> | 447 <directive name="directio_alignment"> |
448 <syntax><argument>size</argument></syntax> | 448 <syntax><value>size</value></syntax> |
449 <default>512</default> | 449 <default>512</default> |
450 <context>http</context> | 450 <context>http</context> |
451 <context>server</context> | 451 <context>server</context> |
452 <context>location</context> | 452 <context>location</context> |
453 <appeared-in>0.8.11</appeared-in> | 453 <appeared-in>0.8.11</appeared-in> |
462 </directive> | 462 </directive> |
463 | 463 |
464 | 464 |
465 <directive name="error_page"> | 465 <directive name="error_page"> |
466 <syntax> | 466 <syntax> |
467 <argument>code</argument> ... | 467 <value>code</value> ... |
468 [<value>=</value>[<argument>response</argument>]] | 468 [<literal>=</literal>[<value>response</value>]] |
469 <argument>uri</argument></syntax> | 469 <value>uri</value></syntax> |
470 <default/> | 470 <default/> |
471 <context>http</context> | 471 <context>http</context> |
472 <context>server</context> | 472 <context>server</context> |
473 <context>location</context> | 473 <context>location</context> |
474 <context>if in location</context> | 474 <context>if in location</context> |
475 | 475 |
476 <para> | 476 <para> |
477 Defines the URI that will be shown for the specified errors. | 477 Defines the URI that will be shown for the specified errors. |
478 These directives are inherited from the previous level if and | 478 These directives are inherited from the previous level if and |
479 only if there are no | 479 only if there are no |
480 <code>error_page</code> | 480 <literal>error_page</literal> |
481 directives on | 481 directives on |
482 the current level. | 482 the current level. |
483 A URI value can contain variables. | 483 A URI value can contain variables. |
484 </para> | 484 </para> |
485 | 485 |
525 </directive> | 525 </directive> |
526 | 526 |
527 | 527 |
528 <directive name="if_modified_since"> | 528 <directive name="if_modified_since"> |
529 <syntax> | 529 <syntax> |
530 <value>off</value> | | 530 <literal>off</literal> | |
531 <value>exact</value> | | 531 <literal>exact</literal> | |
532 <value>before</value></syntax> | 532 <literal>before</literal></syntax> |
533 <default>exact</default> | 533 <default>exact</default> |
534 <context>http</context> | 534 <context>http</context> |
535 <context>server</context> | 535 <context>server</context> |
536 <context>location</context> | 536 <context>location</context> |
537 <appeared-in>0.7.24</appeared-in> | 537 <appeared-in>0.7.24</appeared-in> |
542 <header>If-Modified-Since</header> | 542 <header>If-Modified-Since</header> |
543 request header field: | 543 request header field: |
544 | 544 |
545 <list type="tag"> | 545 <list type="tag"> |
546 | 546 |
547 <tag-name><value>off</value></tag-name> | 547 <tag-name><literal>off</literal></tag-name> |
548 <tag-desc> | 548 <tag-desc> |
549 the | 549 the |
550 <header>If-Modified-Since</header> request header field is ignored (0.7.34); | 550 <header>If-Modified-Since</header> request header field is ignored (0.7.34); |
551 </tag-desc> | 551 </tag-desc> |
552 | 552 |
553 <tag-name><value>exact</value></tag-name> | 553 <tag-name><literal>exact</literal></tag-name> |
554 <tag-desc> | 554 <tag-desc> |
555 exact match; | 555 exact match; |
556 </tag-desc> | 556 </tag-desc> |
557 | 557 |
558 <tag-name><value>before</value></tag-name> | 558 <tag-name><literal>before</literal></tag-name> |
559 <tag-desc> | 559 <tag-desc> |
560 modification time of a response is | 560 modification time of a response is |
561 less than or equal to the time in the <header>If-Modified-Since</header> | 561 less than or equal to the time in the <header>If-Modified-Since</header> |
562 request header field. | 562 request header field. |
563 </tag-desc> | 563 </tag-desc> |
567 | 567 |
568 </directive> | 568 </directive> |
569 | 569 |
570 | 570 |
571 <directive name="ignore_invalid_headers"> | 571 <directive name="ignore_invalid_headers"> |
572 <syntax><value>on</value> | <value>off</value></syntax> | 572 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
573 <default>on</default> | 573 <default>on</default> |
574 <context>http</context> | 574 <context>http</context> |
575 <context>server</context> | 575 <context>server</context> |
576 | 576 |
577 <para> | 577 <para> |
602 requests redirected by the <link id="error_page"/> directive; | 602 requests redirected by the <link id="error_page"/> directive; |
603 </listitem> | 603 </listitem> |
604 | 604 |
605 <listitem> | 605 <listitem> |
606 subrequests formed by the | 606 subrequests formed by the |
607 <command>include virtual</command> | 607 “<command>include virtual</command>” |
608 command of the module | 608 command of the module |
609 <link doc="ngx_http_ssi_module.xml">ngx_http_ssi_module</link>; | 609 <link doc="ngx_http_ssi_module.xml">ngx_http_ssi_module</link>; |
610 </listitem> | 610 </listitem> |
611 | 611 |
612 <listitem> | 612 <listitem> |
631 | 631 |
632 </directive> | 632 </directive> |
633 | 633 |
634 | 634 |
635 <directive name="keepalive_disable"> | 635 <directive name="keepalive_disable"> |
636 <syntax><value>none</value> | <argument>browser</argument> ...</syntax> | 636 <syntax><literal>none</literal> | <value>browser</value> ...</syntax> |
637 <default>msie6 safari</default> | 637 <default>msie6 safari</default> |
638 <context>http</context> | 638 <context>http</context> |
639 <context>server</context> | 639 <context>server</context> |
640 <context>location</context> | 640 <context>location</context> |
641 | 641 |
642 <para> | 642 <para> |
643 Disables keep-alive connections with misbehaving browsers. | 643 Disables keep-alive connections with misbehaving browsers. |
644 The <argument>browser</argument> arguments specify which | 644 The <value>browser</value> parameters specify which |
645 browsers will be affected. | 645 browsers will be affected. |
646 The value <value>msie6</value> disables keep-alive connections | 646 The value <literal>msie6</literal> disables keep-alive connections |
647 with old versions of MSIE, after seeing a POST request. | 647 with old versions of MSIE, after seeing a POST request. |
648 The value <value>safari</value> disables keep-alive connections | 648 The value <literal>safari</literal> disables keep-alive connections |
649 with Safari browsers. | 649 with Safari browsers. |
650 The value <value>none</value> enables keep-alive connections | 650 The value <literal>none</literal> enables keep-alive connections |
651 with all browsers. | 651 with all browsers. |
652 </para> | 652 </para> |
653 | 653 |
654 </directive> | 654 </directive> |
655 | 655 |
656 | 656 |
657 <directive name="keepalive_requests"> | 657 <directive name="keepalive_requests"> |
658 <syntax><argument>number</argument></syntax> | 658 <syntax><value>number</value></syntax> |
659 <default>100</default> | 659 <default>100</default> |
660 <context>http</context> | 660 <context>http</context> |
661 <context>server</context> | 661 <context>server</context> |
662 <context>location</context> | 662 <context>location</context> |
663 <appeared-in>0.8.0</appeared-in> | 663 <appeared-in>0.8.0</appeared-in> |
671 </directive> | 671 </directive> |
672 | 672 |
673 | 673 |
674 <directive name="keepalive_timeout"> | 674 <directive name="keepalive_timeout"> |
675 <syntax> | 675 <syntax> |
676 <argument>timeout</argument> | 676 <value>timeout</value> |
677 [<argument>header_timeout</argument>]</syntax> | 677 [<value>header_timeout</value>]</syntax> |
678 <default>75s</default> | 678 <default>75s</default> |
679 <context>http</context> | 679 <context>http</context> |
680 <context>server</context> | 680 <context>server</context> |
681 <context>location</context> | 681 <context>location</context> |
682 | 682 |
683 <para> | 683 <para> |
684 The first argument sets a timeout during which a keep-alive | 684 The first parameter sets a timeout during which a keep-alive |
685 client connection will stay open on the server side. | 685 client connection will stay open on the server side. |
686 The optional second argument sets a value in the | 686 The optional second parameter sets a value in the |
687 <header>Keep-Alive: timeout=<argument>time</argument></header> | 687 <header>Keep-Alive: timeout=<value>time</value></header> |
688 response header field. | 688 response header field. |
689 Two arguments may differ. | 689 Two parameters may differ. |
690 </para> | 690 </para> |
691 | 691 |
692 <para> | 692 <para> |
693 The | 693 The |
694 <header>Keep-Alive: timeout=<argument>time</argument></header> | 694 <header>Keep-Alive: timeout=<value>time</value></header> |
695 header field is understood by Mozilla and Konqueror. | 695 header field is understood by Mozilla and Konqueror. |
696 MSIE will close keep-alive connection in about 60 seconds. | 696 MSIE will close keep-alive connection in about 60 seconds. |
697 </para> | 697 </para> |
698 | 698 |
699 </directive> | 699 </directive> |
700 | 700 |
701 | 701 |
702 <directive name="large_client_header_buffers"> | 702 <directive name="large_client_header_buffers"> |
703 <syntax><argument>number</argument> <argument>size</argument></syntax> | 703 <syntax><value>number</value> <value>size</value></syntax> |
704 <default>4 8k</default> | 704 <default>4 8k</default> |
705 <context>http</context> | 705 <context>http</context> |
706 <context>server</context> | 706 <context>server</context> |
707 | 707 |
708 <para> | 708 <para> |
709 Sets the maximum <argument>number</argument> and <argument>size</argument> of | 709 Sets the maximum <value>number</value> and <value>size</value> of |
710 buffers used when reading large client request header. | 710 buffers used when reading large client request header. |
711 A request line cannot exceed the size of one buffer, or the client error | 711 A request line cannot exceed the size of one buffer, or the client error |
712 <http-status code="414" text="Request-URI Too Large"/> | 712 <http-status code="414" text="Request-URI Too Large"/> |
713 is returned. | 713 is returned. |
714 A request header field cannot exceed the size of one buffer as well, or the | 714 A request header field cannot exceed the size of one buffer as well, or the |
723 | 723 |
724 </directive> | 724 </directive> |
725 | 725 |
726 | 726 |
727 <directive name="limit_except"> | 727 <directive name="limit_except"> |
728 <syntax block="yes"><argument>method</argument> ...</syntax> | 728 <syntax block="yes"><value>method</value> ...</syntax> |
729 <default/> | 729 <default/> |
730 <context>location</context> | 730 <context>location</context> |
731 | 731 |
732 <para> | 732 <para> |
733 Limits allowed HTTP methods inside a location. | 733 Limits allowed HTTP methods inside a location. |
734 The <argument>method</argument> argument can be one of the following: | 734 The <value>method</value> parameter can be one of the following: |
735 <value>GET</value>, | 735 <literal>GET</literal>, |
736 <value>HEAD</value>, | 736 <literal>HEAD</literal>, |
737 <value>POST</value>, | 737 <literal>POST</literal>, |
738 <value>PUT</value>, | 738 <literal>PUT</literal>, |
739 <value>DELETE</value>, | 739 <literal>DELETE</literal>, |
740 <value>MKCOL</value>, | 740 <literal>MKCOL</literal>, |
741 <value>COPY</value>, | 741 <literal>COPY</literal>, |
742 <value>MOVE</value>, | 742 <literal>MOVE</literal>, |
743 <value>OPTIONS</value>, | 743 <literal>OPTIONS</literal>, |
744 <value>PROPFIND</value>, | 744 <literal>PROPFIND</literal>, |
745 <value>PROPPATCH</value>, | 745 <literal>PROPPATCH</literal>, |
746 <value>LOCK</value>, | 746 <literal>LOCK</literal>, |
747 <value>UNLOCK</value>, | 747 <literal>UNLOCK</literal>, |
748 or | 748 or |
749 <value>PATCH</value>. | 749 <literal>PATCH</literal>. |
750 Allowing the <value>GET</value> method also allows the | 750 Allowing the <literal>GET</literal> method also allows the |
751 <value>HEAD</value> method. | 751 <literal>HEAD</literal> method. |
752 Access to other methods can be limited using the | 752 Access to other methods can be limited using the |
753 <link doc="ngx_http_access_module.xml">ngx_http_access_module</link> | 753 <link doc="ngx_http_access_module.xml">ngx_http_access_module</link> |
754 and | 754 and |
755 <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link> | 755 <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link> |
756 modules directives: | 756 modules directives: |
766 | 766 |
767 </directive> | 767 </directive> |
768 | 768 |
769 | 769 |
770 <directive name="limit_rate"> | 770 <directive name="limit_rate"> |
771 <syntax><argument>rate</argument></syntax> | 771 <syntax><value>rate</value></syntax> |
772 <default>0</default> | 772 <default>0</default> |
773 <context>http</context> | 773 <context>http</context> |
774 <context>server</context> | 774 <context>server</context> |
775 <context>location</context> | 775 <context>location</context> |
776 <context>if in location</context> | 776 <context>if in location</context> |
777 | 777 |
778 <para> | 778 <para> |
779 Rate limits the transmission of a response to a client. | 779 Rate limits the transmission of a response to a client. |
780 The <argument>rate</argument> is specified in bytes per second. | 780 The <value>rate</value> is specified in bytes per second. |
781 Value 0 (the default) disables rate limiting. | 781 Value 0 (the default) disables rate limiting. |
782 <!-- | 782 <!-- |
783 The smaller the rate, the more accurate will be the limitation. | 783 The smaller the rate, the more accurate will be the limitation. |
784 --> | 784 --> |
785 The limit is per connection, so if a single client opens 2 connections, | 785 The limit is per connection, so if a single client opens 2 connections, |
808 | 808 |
809 </directive> | 809 </directive> |
810 | 810 |
811 | 811 |
812 <directive name="limit_rate_after"> | 812 <directive name="limit_rate_after"> |
813 <syntax><argument>size</argument></syntax> | 813 <syntax><value>size</value></syntax> |
814 <default>0</default> | 814 <default>0</default> |
815 <context>http</context> | 815 <context>http</context> |
816 <context>server</context> | 816 <context>server</context> |
817 <context>location</context> | 817 <context>location</context> |
818 <context>if in location</context> | 818 <context>if in location</context> |
836 | 836 |
837 </directive> | 837 </directive> |
838 | 838 |
839 | 839 |
840 <directive name="lingering_close"> | 840 <directive name="lingering_close"> |
841 <syntax><value>off</value> | <value>on</value> | <value>always</value></syntax> | 841 <syntax> |
842 <literal>off</literal> | | |
843 <literal>on</literal> | | |
844 <literal>always</literal></syntax> | |
842 <default>on</default> | 845 <default>on</default> |
843 <context>http</context> | 846 <context>http</context> |
844 <context>server</context> | 847 <context>server</context> |
845 <context>location</context> | 848 <context>location</context> |
846 <appeared-in>1.1.0</appeared-in> | 849 <appeared-in>1.1.0</appeared-in> |
849 <para> | 852 <para> |
850 Controls how nginx closes client connections. | 853 Controls how nginx closes client connections. |
851 </para> | 854 </para> |
852 | 855 |
853 <para> | 856 <para> |
854 The default value “<value>on</value>” instructs nginx to | 857 The default value “<literal>on</literal>” instructs nginx to |
855 <link id="lingering_timeout">wait for</link> and | 858 <link id="lingering_timeout">wait for</link> and |
856 <link id="lingering_time">process</link> additional data from a client | 859 <link id="lingering_time">process</link> additional data from a client |
857 before fully closing a connection, but only | 860 before fully closing a connection, but only |
858 if heuristics suggests that a client may be sending more data. | 861 if heuristics suggests that a client may be sending more data. |
859 </para> | 862 </para> |
860 | 863 |
861 <para> | 864 <para> |
862 The value “<value>always</value>” will cause nginx to unconditionally | 865 The value “<literal>always</literal>” will cause nginx to unconditionally |
863 wait for and process additional client data. | 866 wait for and process additional client data. |
864 </para> | 867 </para> |
865 | 868 |
866 <para> | 869 <para> |
867 The value “<value>off</value>” tells nginx to never wait for | 870 The value “<literal>off</literal>” tells nginx to never wait for |
868 more data and close the connection immediately. | 871 more data and close the connection immediately. |
869 This breaks the protocol and should not be used under normal circumstances. | 872 This breaks the protocol and should not be used under normal circumstances. |
870 </para> | 873 </para> |
871 | 874 |
872 </directive> | 875 </directive> |
873 | 876 |
874 | 877 |
875 <directive name="lingering_time"> | 878 <directive name="lingering_time"> |
876 <syntax><argument>time</argument></syntax> | 879 <syntax><value>time</value></syntax> |
877 <default>30s</default> | 880 <default>30s</default> |
878 <context>http</context> | 881 <context>http</context> |
879 <context>server</context> | 882 <context>server</context> |
880 <context>location</context> | 883 <context>location</context> |
881 | 884 |
888 | 891 |
889 </directive> | 892 </directive> |
890 | 893 |
891 | 894 |
892 <directive name="lingering_timeout"> | 895 <directive name="lingering_timeout"> |
893 <syntax><argument>time</argument></syntax> | 896 <syntax><value>time</value></syntax> |
894 <default>5s</default> | 897 <default>5s</default> |
895 <context>http</context> | 898 <context>http</context> |
896 <context>server</context> | 899 <context>server</context> |
897 <context>location</context> | 900 <context>location</context> |
898 | 901 |
908 </directive> | 911 </directive> |
909 | 912 |
910 | 913 |
911 <directive name="listen"> | 914 <directive name="listen"> |
912 <syntax> | 915 <syntax> |
913 <argument>address</argument>[:<argument>port</argument>] | 916 <value>address</value>[:<value>port</value>] |
914 [<parameter>default_server</parameter>] | 917 [<literal>default_server</literal>] |
915 [<parameter>setfib</parameter>=<argument>number</argument>] | 918 [<literal>setfib</literal>=<value>number</value>] |
916 [<parameter>backlog</parameter>=<argument>number</argument>] | 919 [<literal>backlog</literal>=<value>number</value>] |
917 [<parameter>rcvbuf</parameter>=<argument>size</argument>] | 920 [<literal>rcvbuf</literal>=<value>size</value>] |
918 [<parameter>sndbuf</parameter>=<argument>size</argument>] | 921 [<literal>sndbuf</literal>=<value>size</value>] |
919 [<parameter>accept_filter</parameter>=<argument>filter</argument>] | 922 [<literal>accept_filter</literal>=<value>filter</value>] |
920 [<parameter>deferred</parameter>] | 923 [<literal>deferred</literal>] |
921 [<parameter>bind</parameter>] | 924 [<literal>bind</literal>] |
922 [<parameter>ipv6only</parameter>=<value>on</value>|<value>off</value>] | 925 [<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>] |
923 [<parameter>ssl</parameter>] | 926 [<literal>ssl</literal>] |
924 [<parameter>so_keepalive</parameter>=<value>on</value>|<value>off</value>|[<argument>keepidle</argument>]:[<argument>keepintvl</argument>]:[<argument>keepcnt</argument>]]</syntax> | 927 [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax> |
925 <syntax> | 928 <syntax> |
926 <argument>port</argument> | 929 <value>port</value> |
927 [<parameter>default_server</parameter>] | 930 [<literal>default_server</literal>] |
928 [<parameter>setfib</parameter>=<argument>number</argument>] | 931 [<literal>setfib</literal>=<value>number</value>] |
929 [<parameter>backlog</parameter>=<argument>number</argument>] | 932 [<literal>backlog</literal>=<value>number</value>] |
930 [<parameter>rcvbuf</parameter>=<argument>size</argument>] | 933 [<literal>rcvbuf</literal>=<value>size</value>] |
931 [<parameter>sndbuf</parameter>=<argument>size</argument>] | 934 [<literal>sndbuf</literal>=<value>size</value>] |
932 [<parameter>accept_filter</parameter>=<argument>filter</argument>] | 935 [<literal>accept_filter</literal>=<value>filter</value>] |
933 [<parameter>deferred</parameter>] | 936 [<literal>deferred</literal>] |
934 [<parameter>bind</parameter>] | 937 [<literal>bind</literal>] |
935 [<parameter>ipv6only</parameter>=<value>on</value>|<value>off</value>] | 938 [<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>] |
936 [<parameter>ssl</parameter>] | 939 [<literal>ssl</literal>] |
937 [<parameter>so_keepalive</parameter>=<value>on</value>|<value>off</value>|[<argument>keepidle</argument>]:[<argument>keepintvl</argument>]:[<argument>keepcnt</argument>]]</syntax> | 940 [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax> |
938 <syntax> | 941 <syntax> |
939 <value>unix:</value><argument>path</argument> | 942 <literal>unix:</literal><value>path</value> |
940 [<parameter>default_server</parameter>] | 943 [<literal>default_server</literal>] |
941 [<parameter>backlog</parameter>=<argument>number</argument>] | 944 [<literal>backlog</literal>=<value>number</value>] |
942 [<parameter>rcvbuf</parameter>=<argument>size</argument>] | 945 [<literal>rcvbuf</literal>=<value>size</value>] |
943 [<parameter>sndbuf</parameter>=<argument>size</argument>] | 946 [<literal>sndbuf</literal>=<value>size</value>] |
944 [<parameter>accept_filter</parameter>=<argument>filter</argument>] | 947 [<literal>accept_filter</literal>=<value>filter</value>] |
945 [<parameter>deferred</parameter>] | 948 [<literal>deferred</literal>] |
946 [<parameter>bind</parameter>] | 949 [<literal>bind</literal>] |
947 [<parameter>ssl</parameter>] | 950 [<literal>ssl</literal>] |
948 [<parameter>so_keepalive</parameter>=<value>on</value>|<value>off</value>|[<argument>keepidle</argument>]:[<argument>keepintvl</argument>]:[<argument>keepcnt</argument>]]</syntax> | 951 [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax> |
949 <default>*:80 | *:8000</default> | 952 <default>*:80 | *:8000</default> |
950 <context>server</context> | 953 <context>server</context> |
951 | 954 |
952 <para> | 955 <para> |
953 Sets an <argument>address</argument> and a <argument>port</argument> for IP, | 956 Sets an <value>address</value> and a <value>port</value> for IP, |
954 or a <argument>path</argument> for a UNIX-domain socket, on which | 957 or a <value>path</value> for a UNIX-domain socket, on which |
955 the server will accept requests. | 958 the server will accept requests. |
956 Only one of <argument>address</argument> or <argument>port</argument> may be | 959 Only one of <value>address</value> or <value>port</value> may be |
957 specified. | 960 specified. |
958 An <argument>address</argument> may also be a hostname, for example: | 961 An <value>address</value> may also be a hostname, for example: |
959 <example> | 962 <example> |
960 listen 127.0.0.1:8000; | 963 listen 127.0.0.1:8000; |
961 listen 127.0.0.1; | 964 listen 127.0.0.1; |
962 listen 8000; | 965 listen 8000; |
963 listen *:8000; | 966 listen *:8000; |
966 IPv6 addresses (0.7.36) are specified in square brackets: | 969 IPv6 addresses (0.7.36) are specified in square brackets: |
967 <example> | 970 <example> |
968 listen [::]:8000; | 971 listen [::]:8000; |
969 listen [fe80::1]; | 972 listen [fe80::1]; |
970 </example> | 973 </example> |
971 UNIX-domain sockets (0.8.21) are specified with the “<code>unix:</code>” prefix: | 974 UNIX-domain sockets (0.8.21) are specified with the “<literal>unix:</literal>” prefix: |
972 <example> | 975 <example> |
973 listen unix:/var/run/nginx.sock; | 976 listen unix:/var/run/nginx.sock; |
974 </example> | 977 </example> |
975 </para> | 978 </para> |
976 | 979 |
977 <para> | 980 <para> |
978 If only <argument>address</argument> is given, the port 80 is used. | 981 If only <value>address</value> is given, the port 80 is used. |
979 </para> | 982 </para> |
980 | 983 |
981 <para> | 984 <para> |
982 If directive is not present then either the <code>*:80</code> is used | 985 If directive is not present then either the <literal>*:80</literal> is used |
983 if nginx runs with superuser privileges, or <code>*:8000</code> otherwise. | 986 if nginx runs with superuser privileges, or <literal>*:8000</literal> otherwise. |
984 </para> | 987 </para> |
985 | 988 |
986 <para> | 989 <para> |
987 The <parameter>default_server</parameter> parameter, if present, | 990 The <literal>default_server</literal> parameter, if present, |
988 will cause the server to become the default server for the specified | 991 will cause the server to become the default server for the specified |
989 <argument>address</argument>:<argument>port</argument> pair. | 992 <value>address</value>:<value>port</value> pair. |
990 If none of the directives have the <parameter>default_server</parameter> | 993 If none of the directives have the <literal>default_server</literal> |
991 parameter then the first server with the | 994 parameter then the first server with the |
992 <argument>address</argument>:<argument>port</argument> pair will be | 995 <value>address</value>:<value>port</value> pair will be |
993 the default server for this pair. | 996 the default server for this pair. |
994 <note> | 997 <note> |
995 In versions prior to 0.8.21 this parameter is named simply | 998 In versions prior to 0.8.21 this parameter is named simply |
996 <parameter>default</parameter>. | 999 <literal>default</literal>. |
997 </note> | 1000 </note> |
998 </para> | 1001 </para> |
999 | 1002 |
1000 <para> | 1003 <para> |
1001 A <code>listen</code> directive | 1004 A <literal>listen</literal> directive |
1002 can have several additional parameters specific to system calls | 1005 can have several additional parameters specific to system calls |
1003 <c-func>listen</c-func> and <c-func>bind</c-func>. | 1006 <c-func>listen</c-func> and <c-func>bind</c-func>. |
1004 They can be specified in any | 1007 They can be specified in any |
1005 <code>listen</code> directive, but only once for the given | 1008 <literal>listen</literal> directive, but only once for the given |
1006 <argument>address</argument>:<argument>port</argument> pair. | 1009 <value>address</value>:<value>port</value> pair. |
1007 <note> | 1010 <note> |
1008 In versions prior to 0.8.21, they could only be | 1011 In versions prior to 0.8.21, they could only be |
1009 specified in the <code>listen</code> directive with the | 1012 specified in the <literal>listen</literal> directive with the |
1010 <parameter>default</parameter> parameter. | 1013 <literal>default</literal> parameter. |
1011 </note> | 1014 </note> |
1012 <list type="tag"> | 1015 <list type="tag"> |
1013 | 1016 |
1014 <tag-name> | 1017 <tag-name> |
1015 <parameter>setfib</parameter>=<argument>number</argument> | 1018 <literal>setfib</literal>=<value>number</value> |
1016 </tag-name> | 1019 </tag-name> |
1017 <tag-desc> | 1020 <tag-desc> |
1018 this parameter (0.8.44) sets the associated FIB (routing table) | 1021 this parameter (0.8.44) sets the associated FIB (routing table) |
1019 for the listening socket. | 1022 for the listening socket. |
1020 This currently works only on FreeBSD. | 1023 This currently works only on FreeBSD. |
1021 </tag-desc> | 1024 </tag-desc> |
1022 | 1025 |
1023 <tag-name> | 1026 <tag-name> |
1024 <parameter>backlog</parameter>=<argument>number</argument> | 1027 <literal>backlog</literal>=<value>number</value> |
1025 </tag-name> | 1028 </tag-name> |
1026 <tag-desc> | 1029 <tag-desc> |
1027 sets the <parameter>backlog</parameter> parameter in the | 1030 sets the <literal>backlog</literal> parameter in the |
1028 <c-func>listen</c-func> call. | 1031 <c-func>listen</c-func> call. |
1029 By default, <parameter>backlog</parameter> equals -1 on FreeBSD | 1032 By default, <literal>backlog</literal> equals -1 on FreeBSD |
1030 and 511 on other platforms. | 1033 and 511 on other platforms. |
1031 </tag-desc> | 1034 </tag-desc> |
1032 | 1035 |
1033 <tag-name> | 1036 <tag-name> |
1034 <parameter>rcvbuf</parameter>=<argument>size</argument> | 1037 <literal>rcvbuf</literal>=<value>size</value> |
1035 </tag-name> | 1038 </tag-name> |
1036 <tag-desc> | 1039 <tag-desc> |
1037 sets the <c-def>SO_RCVBUF</c-def> parameter for the listening socket. | 1040 sets the <c-def>SO_RCVBUF</c-def> parameter for the listening socket. |
1038 </tag-desc> | 1041 </tag-desc> |
1039 | 1042 |
1040 <tag-name> | 1043 <tag-name> |
1041 <parameter>sndbuf</parameter>=<argument>size</argument> | 1044 <literal>sndbuf</literal>=<value>size</value> |
1042 </tag-name> | 1045 </tag-name> |
1043 <tag-desc> | 1046 <tag-desc> |
1044 sets the <c-def>SO_SNDBUF</c-def> parameter for the listening socket. | 1047 sets the <c-def>SO_SNDBUF</c-def> parameter for the listening socket. |
1045 </tag-desc> | 1048 </tag-desc> |
1046 | 1049 |
1047 <tag-name> | 1050 <tag-name> |
1048 <parameter>accept_filter</parameter>=<argument>filter</argument> | 1051 <literal>accept_filter</literal>=<value>filter</value> |
1049 </tag-name> | 1052 </tag-name> |
1050 <tag-desc> | 1053 <tag-desc> |
1051 sets the name of the accept filter. | 1054 sets the name of the accept filter. |
1052 This works only on FreeBSD, acceptable values are <value>dataready</value> | 1055 This works only on FreeBSD, acceptable values are <literal>dataready</literal> |
1053 and <value>httpready</value>. | 1056 and <literal>httpready</literal>. |
1054 On receipt of the <c-def>SIGHUP</c-def> signal, an accept filter can only be | 1057 On receipt of the <c-def>SIGHUP</c-def> signal, an accept filter can only be |
1055 changed in recent versions of FreeBSD, starting from 6.0, 5.4-STABLE | 1058 changed in recent versions of FreeBSD, starting from 6.0, 5.4-STABLE |
1056 and 4.11-STABLE. | 1059 and 4.11-STABLE. |
1057 </tag-desc> | 1060 </tag-desc> |
1058 | 1061 |
1059 <tag-name> | 1062 <tag-name> |
1060 <parameter>deferred</parameter> | 1063 <literal>deferred</literal> |
1061 </tag-name> | 1064 </tag-name> |
1062 <tag-desc> | 1065 <tag-desc> |
1063 instructs to use a deferred <c-func>accept</c-func> on Linux | 1066 instructs to use a deferred <c-func>accept</c-func> on Linux |
1064 using the <c-def>TCP_DEFER_ACCEPT</c-def> option. | 1067 using the <c-def>TCP_DEFER_ACCEPT</c-def> option. |
1065 </tag-desc> | 1068 </tag-desc> |
1066 | 1069 |
1067 <tag-name> | 1070 <tag-name> |
1068 <parameter>bind</parameter> | 1071 <literal>bind</literal> |
1069 </tag-name> | 1072 </tag-name> |
1070 <tag-desc> | 1073 <tag-desc> |
1071 instructs to make a separate <c-func>bind</c-func> call for a given | 1074 instructs to make a separate <c-func>bind</c-func> call for a given |
1072 <argument>address</argument>:<argument>port</argument> pair. | 1075 <value>address</value>:<value>port</value> pair. |
1073 This is because nginx will <c-func>bind</c-func> only to | 1076 This is because nginx will <c-func>bind</c-func> only to |
1074 <code>*</code>:<argument>port</argument> | 1077 <literal>*:</literal><value>port</value> |
1075 if there are several <code>listen</code> directives with | 1078 if there are several <literal>listen</literal> directives with |
1076 the same port but different addresses, and one of the | 1079 the same port but different addresses, and one of the |
1077 <code>listen</code> directives listens on all addresses | 1080 <literal>listen</literal> directives listens on all addresses |
1078 for the given port (<code>*</code>:<argument>port</argument>). | 1081 for the given port (<literal>*:</literal><value>port</value>). |
1079 It should be noted that in this case a <c-func>getsockname</c-func> | 1082 It should be noted that in this case a <c-func>getsockname</c-func> |
1080 system call will be made to determine an address that accepted a | 1083 system call will be made to determine an address that accepted a |
1081 connection. | 1084 connection. |
1082 If parameters <parameter>backlog</parameter>, <parameter>rcvbuf</parameter>, | 1085 If parameters <literal>backlog</literal>, <literal>rcvbuf</literal>, |
1083 <parameter>sndbuf</parameter>, <parameter>accept_filter</parameter>, | 1086 <literal>sndbuf</literal>, <literal>accept_filter</literal>, |
1084 <parameter>deferred</parameter>, or <parameter>so_keepalive</parameter> | 1087 <literal>deferred</literal>, or <literal>so_keepalive</literal> |
1085 are used then for a given | 1088 are used then for a given |
1086 <argument>address</argument>:<argument>port</argument> pair | 1089 <value>address</value>:<value>port</value> pair |
1087 a separate <c-func>bind</c-func> call will always be made. | 1090 a separate <c-func>bind</c-func> call will always be made. |
1088 </tag-desc> | 1091 </tag-desc> |
1089 | 1092 |
1090 <tag-name> | 1093 <tag-name> |
1091 <parameter>ipv6only</parameter>=<value>on</value>|<value>off</value> | 1094 <literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal> |
1092 </tag-name> | 1095 </tag-name> |
1093 <tag-desc> | 1096 <tag-desc> |
1094 this parameter (0.7.42) sets the value of the <c-def>IPV6_V6ONLY</c-def> | 1097 this parameter (0.7.42) sets the value of the <c-def>IPV6_V6ONLY</c-def> |
1095 parameter for the listening socket. | 1098 parameter for the listening socket. |
1096 This parameter can only be set once on start. | 1099 This parameter can only be set once on start. |
1097 </tag-desc> | 1100 </tag-desc> |
1098 | 1101 |
1099 <tag-name> | 1102 <tag-name> |
1100 <parameter>ssl</parameter> | 1103 <literal>ssl</literal> |
1101 </tag-name> | 1104 </tag-name> |
1102 <tag-desc> | 1105 <tag-desc> |
1103 this parameter (0.7.14) does not relate to system calls | 1106 this parameter (0.7.14) does not relate to system calls |
1104 <c-func>listen</c-func> and <c-func>bind</c-func>, but allows to | 1107 <c-func>listen</c-func> and <c-func>bind</c-func>, but allows to |
1105 specify that all connections accepted on this port should work in | 1108 specify that all connections accepted on this port should work in |
1111 listen 443 default ssl; | 1114 listen 443 default ssl; |
1112 </example> | 1115 </example> |
1113 </tag-desc> | 1116 </tag-desc> |
1114 | 1117 |
1115 <tag-name> | 1118 <tag-name> |
1116 <parameter>so_keepalive</parameter>=<value>on</value>|<value>off</value>|[<argument>keepidle</argument>]:[<argument>keepintvl</argument>]:[<argument>keepcnt</argument>] | 1119 <literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>] |
1117 </tag-name> | 1120 </tag-name> |
1118 <tag-desc> | 1121 <tag-desc> |
1119 this parameter (1.1.11) configures the “TCP keepalive” behavior | 1122 this parameter (1.1.11) configures the “TCP keepalive” behavior |
1120 for the listening socket. | 1123 for the listening socket. |
1121 If this parameter is omitted then the system default setting will be | 1124 If this parameter is omitted then the system default setting will be |
1122 in effect for the socket. | 1125 in effect for the socket. |
1123 If set to the value “<value>on</value>”, the <c-def>SO_KEEPALIVE</c-def> | 1126 If set to the value “<literal>on</literal>”, the <c-def>SO_KEEPALIVE</c-def> |
1124 socket option is turned on for the socket. | 1127 socket option is turned on for the socket. |
1125 If set to the value “<value>off</value>”, the <c-def>SO_KEEPALIVE</c-def> | 1128 If set to the value “<literal>off</literal>”, the <c-def>SO_KEEPALIVE</c-def> |
1126 socket option is turned off for the socket. | 1129 socket option is turned off for the socket. |
1127 Some operating systems support tuning TCP keepalive parameters on a per-socket | 1130 Some operating systems support tuning TCP keepalive parameters on a per-socket |
1128 basis using the <c-def>TCP_KEEPIDLE</c-def>, <c-def>TCP_KEEPINTVL</c-def>, | 1131 basis using the <c-def>TCP_KEEPIDLE</c-def>, <c-def>TCP_KEEPINTVL</c-def>, |
1129 and <c-def>TCP_KEEPCNT</c-def> socket options. | 1132 and <c-def>TCP_KEEPCNT</c-def> socket options. |
1130 On such systems (currently, Linux 2.4+ and NetBSD 5+) they can be configured | 1133 On such systems (currently, Linux 2.4+ and NetBSD 5+) they can be configured |
1131 using the <argument>keepidle</argument>, <argument>keepintvl</argument>, and | 1134 using the <value>keepidle</value>, <value>keepintvl</value>, and |
1132 <argument>keepcnt</argument> arguments. | 1135 <value>keepcnt</value> parameters. |
1133 One or two arguments may be omitted, in which case the system default setting | 1136 One or two parameters may be omitted, in which case the system default setting |
1134 for the corresponding socket option will be in effect. | 1137 for the corresponding socket option will be in effect. |
1135 For example, | 1138 For example, |
1136 <example>so_keepalive=30m::10</example> | 1139 <example>so_keepalive=30m::10</example> |
1137 will set idle timeout (<c-def>TCP_KEEPIDLE</c-def>) to 30 minutes, | 1140 will set idle timeout (<c-def>TCP_KEEPIDLE</c-def>) to 30 minutes, |
1138 leave probe interval (<c-def>TCP_KEEPINTVL</c-def>) at its system default, | 1141 leave probe interval (<c-def>TCP_KEEPINTVL</c-def>) at its system default, |
1152 </directive> | 1155 </directive> |
1153 | 1156 |
1154 | 1157 |
1155 <directive name="location"> | 1158 <directive name="location"> |
1156 <syntax block="yes">[ | 1159 <syntax block="yes">[ |
1157 <value>=</value> | | 1160 <literal>=</literal> | |
1158 <value>~</value> | | 1161 <literal>~</literal> | |
1159 <value>~*</value> | | 1162 <literal>~*</literal> | |
1160 <value>^~</value> | 1163 <literal>^~</literal> |
1161 ] <argument>uri</argument></syntax> | 1164 ] <value>uri</value></syntax> |
1162 <syntax block="yes"><value>@</value><argument>name</argument></syntax> | 1165 <syntax block="yes"><literal>@</literal><value>name</value></syntax> |
1163 <default/> | 1166 <default/> |
1164 <context>server</context> | 1167 <context>server</context> |
1165 <context>location</context> | 1168 <context>location</context> |
1166 | 1169 |
1167 <para> | 1170 <para> |
1168 Sets a configuration based on a request URI. | 1171 Sets a configuration based on a request URI. |
1169 A location can either be defined by a prefix string, or by a regular expression. | 1172 A location can either be defined by a prefix string, or by a regular expression. |
1170 Regular expressions are specified by prepending them with the | 1173 Regular expressions are specified by prepending them with the |
1171 “<value>~*</value>” prefix (for case-insensitive matching), or with the | 1174 “<literal>~*</literal>” prefix (for case-insensitive matching), or with the |
1172 “<value>~</value>” prefix (for case-sensitive matching). | 1175 “<literal>~</literal>” prefix (for case-sensitive matching). |
1173 To find a location matching a given request, nginx first checks | 1176 To find a location matching a given request, nginx first checks |
1174 locations defined using the prefix strings (prefix locations). | 1177 locations defined using the prefix strings (prefix locations). |
1175 Among them, the most specific one is searched. | 1178 Among them, the most specific one is searched. |
1176 Then regular expressions are checked, in the order of their appearance | 1179 Then regular expressions are checked, in the order of their appearance |
1177 in a configuration file. | 1180 in a configuration file. |
1195 Regular expressions can contain captures (0.7.40) that can later | 1198 Regular expressions can contain captures (0.7.40) that can later |
1196 be used in other directives. | 1199 be used in other directives. |
1197 </para> | 1200 </para> |
1198 | 1201 |
1199 <para> | 1202 <para> |
1200 If the most specific prefix location has the “<value>^~</value>” prefix | 1203 If the most specific prefix location has the “<literal>^~</literal>” prefix |
1201 then regular expressions are not checked. | 1204 then regular expressions are not checked. |
1202 </para> | 1205 </para> |
1203 | 1206 |
1204 <para> | 1207 <para> |
1205 Also, using the “<value>=</value>” prefix it is possible to define | 1208 Also, using the “<literal>=</literal>” prefix it is possible to define |
1206 an exact match of URI and location. | 1209 an exact match of URI and location. |
1207 If an exact match is found, the search terminates. | 1210 If an exact match is found, the search terminates. |
1208 For example, if a “<code>/</code>” request happens frequently, | 1211 For example, if a “<literal>/</literal>” request happens frequently, |
1209 defining “<code>location = /</code>” will speed up the processing | 1212 defining “<literal>location = /</literal>” will speed up the processing |
1210 of these requests, as search terminates right after the first | 1213 of these requests, as search terminates right after the first |
1211 comparison. | 1214 comparison. |
1212 Such a location cannot obviously contain nested locations. | 1215 Such a location cannot obviously contain nested locations. |
1213 </para> | 1216 </para> |
1214 | 1217 |
1215 <para> | 1218 <para> |
1216 <note> | 1219 <note> |
1217 In versions from 0.7.1 to 0.8.41, if a request matched the prefix | 1220 In versions from 0.7.1 to 0.8.41, if a request matched the prefix |
1218 location without the “<value>=</value>” and “<value>^~</value>” | 1221 location without the “<literal>=</literal>” and “<literal>^~</literal>” |
1219 prefixes, the search also terminated and regular expressions were | 1222 prefixes, the search also terminated and regular expressions were |
1220 not checked. | 1223 not checked. |
1221 </note> | 1224 </note> |
1222 </para> | 1225 </para> |
1223 | 1226 |
1238 | 1241 |
1239 location ~* \.(gif|jpg|jpeg)$ { | 1242 location ~* \.(gif|jpg|jpeg)$ { |
1240 [ configuration D ] | 1243 [ configuration D ] |
1241 } | 1244 } |
1242 </example> | 1245 </example> |
1243 The “<code>/</code>” request will match configuration A, | 1246 The “<literal>/</literal>” request will match configuration A, |
1244 the “<code>/documents/document.html</code>” request will match | 1247 the “<literal>/documents/document.html</literal>” request will match |
1245 configuration B, | 1248 configuration B, |
1246 the “<code>/images/1.gif</code>” request will match configuration C, and | 1249 the “<literal>/images/1.gif</literal>” request will match configuration C, and |
1247 the “<code>/documents/1.jpg</code>” request will match configuration D. | 1250 the “<literal>/documents/1.jpg</literal>” request will match configuration D. |
1248 </para> | 1251 </para> |
1249 | 1252 |
1250 <para> | 1253 <para> |
1251 The “<value>@</value>” prefix defines a named location. | 1254 The “<literal>@</literal>” prefix defines a named location. |
1252 Such a location is not used for a regular request processing, but instead | 1255 Such a location is not used for a regular request processing, but instead |
1253 used for request redirection. | 1256 used for request redirection. |
1254 They cannot be nested, and cannot contain nested locations. | 1257 They cannot be nested, and cannot contain nested locations. |
1255 </para> | 1258 </para> |
1256 | 1259 |
1260 | 1263 |
1261 </directive> | 1264 </directive> |
1262 | 1265 |
1263 | 1266 |
1264 <directive name="log_not_found"> | 1267 <directive name="log_not_found"> |
1265 <syntax><value>on</value> | <value>off</value></syntax> | 1268 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
1266 <default>on</default> | 1269 <default>on</default> |
1267 <context>http</context> | 1270 <context>http</context> |
1268 <context>server</context> | 1271 <context>server</context> |
1269 <context>location</context> | 1272 <context>location</context> |
1270 | 1273 |
1275 | 1278 |
1276 </directive> | 1279 </directive> |
1277 | 1280 |
1278 | 1281 |
1279 <directive name="log_subrequest"> | 1282 <directive name="log_subrequest"> |
1280 <syntax><value>on</value> | <value>off</value></syntax> | 1283 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
1281 <default>off</default> | 1284 <default>off</default> |
1282 <context>http</context> | 1285 <context>http</context> |
1283 <context>server</context> | 1286 <context>server</context> |
1284 <context>location</context> | 1287 <context>location</context> |
1285 | 1288 |
1290 | 1293 |
1291 </directive> | 1294 </directive> |
1292 | 1295 |
1293 | 1296 |
1294 <directive name="max_ranges"> | 1297 <directive name="max_ranges"> |
1295 <syntax><argument>number</argument></syntax> | 1298 <syntax><value>number</value></syntax> |
1296 <default/> | 1299 <default/> |
1297 <context>http</context> | 1300 <context>http</context> |
1298 <context>server</context> | 1301 <context>server</context> |
1299 <context>location</context> | 1302 <context>location</context> |
1300 | 1303 |
1308 | 1311 |
1309 </directive> | 1312 </directive> |
1310 | 1313 |
1311 | 1314 |
1312 <directive name="merge_slashes"> | 1315 <directive name="merge_slashes"> |
1313 <syntax><value>on</value> | <value>off</value></syntax> | 1316 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
1314 <default>on</default> | 1317 <default>on</default> |
1315 <context>http</context> | 1318 <context>http</context> |
1316 <context>server</context> | 1319 <context>server</context> |
1317 | 1320 |
1318 <para> | 1321 <para> |
1321 </para> | 1324 </para> |
1322 | 1325 |
1323 <para> | 1326 <para> |
1324 Note that compression is essential for the correct prefix string | 1327 Note that compression is essential for the correct prefix string |
1325 and regular expressions location matching. | 1328 and regular expressions location matching. |
1326 Without it, the “<code>//scripts/one.php</code>” request would not match | 1329 Without it, the “<literal>//scripts/one.php</literal>” request would not match |
1327 <example> | 1330 <example> |
1328 location /scripts/ { | 1331 location /scripts/ { |
1329 ... | 1332 ... |
1330 } | 1333 } |
1331 </example> | 1334 </example> |
1332 and might be processed as a static file, | 1335 and might be processed as a static file, |
1333 so it gets converted to “<code>/scripts/one.php</code>”. | 1336 so it gets converted to “<literal>/scripts/one.php</literal>”. |
1334 </para> | 1337 </para> |
1335 | 1338 |
1336 <para> | 1339 <para> |
1337 Turning the compression <value>off</value> can become necessary if a URI | 1340 Turning the compression <literal>off</literal> can become necessary if a URI |
1338 contains base64-encoded names, since base64 uses the “<code>/</code>” | 1341 contains base64-encoded names, since base64 uses the “<literal>/</literal>” |
1339 character internally. | 1342 character internally. |
1340 However, for security considerations, it is better to avoid turning off | 1343 However, for security considerations, it is better to avoid turning off |
1341 the compression. | 1344 the compression. |
1342 </para> | 1345 </para> |
1343 | 1346 |
1350 | 1353 |
1351 </directive> | 1354 </directive> |
1352 | 1355 |
1353 | 1356 |
1354 <directive name="msie_padding"> | 1357 <directive name="msie_padding"> |
1355 <syntax><value>on</value> | <value>off</value></syntax> | 1358 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
1356 <default>on</default> | 1359 <default>on</default> |
1357 <context>http</context> | 1360 <context>http</context> |
1358 <context>server</context> | 1361 <context>server</context> |
1359 <context>location</context> | 1362 <context>location</context> |
1360 | 1363 |
1365 | 1368 |
1366 </directive> | 1369 </directive> |
1367 | 1370 |
1368 | 1371 |
1369 <directive name="msie_refresh"> | 1372 <directive name="msie_refresh"> |
1370 <syntax><value>on</value> | <value>off</value></syntax> | 1373 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
1371 <default>off</default> | 1374 <default>off</default> |
1372 <context>http</context> | 1375 <context>http</context> |
1373 <context>server</context> | 1376 <context>server</context> |
1374 <context>location</context> | 1377 <context>location</context> |
1375 | 1378 |
1379 | 1382 |
1380 </directive> | 1383 </directive> |
1381 | 1384 |
1382 | 1385 |
1383 <directive name="open_file_cache"> | 1386 <directive name="open_file_cache"> |
1384 <syntax><value>off</value></syntax> | 1387 <syntax><literal>off</literal></syntax> |
1385 <syntax> | 1388 <syntax> |
1386 <parameter>max</parameter>=<argument>N</argument> | 1389 <literal>max</literal>=<value>N</value> |
1387 [<parameter>inactive</parameter>=<argument>time</argument>]</syntax> | 1390 [<literal>inactive</literal>=<value>time</value>]</syntax> |
1388 <default>off</default> | 1391 <default>off</default> |
1389 <context>http</context> | 1392 <context>http</context> |
1390 <context>server</context> | 1393 <context>server</context> |
1391 <context>location</context> | 1394 <context>location</context> |
1392 | 1395 |
1418 <para> | 1421 <para> |
1419 The directive has the following parameters: | 1422 The directive has the following parameters: |
1420 <list type="tag"> | 1423 <list type="tag"> |
1421 | 1424 |
1422 <tag-name> | 1425 <tag-name> |
1423 <parameter>max</parameter> | 1426 <literal>max</literal> |
1424 </tag-name> | 1427 </tag-name> |
1425 <tag-desc> | 1428 <tag-desc> |
1426 sets the maximum number of elements in the cache; | 1429 sets the maximum number of elements in the cache; |
1427 on cache overflow the least recently used (LRU) elements get removed; | 1430 on cache overflow the least recently used (LRU) elements get removed; |
1428 </tag-desc> | 1431 </tag-desc> |
1429 | 1432 |
1430 <tag-name> | 1433 <tag-name> |
1431 <parameter>inactive</parameter> | 1434 <literal>inactive</literal> |
1432 </tag-name> | 1435 </tag-name> |
1433 <tag-desc> | 1436 <tag-desc> |
1434 defines a time, after which an element gets removed from the cache | 1437 defines a time, after which an element gets removed from the cache |
1435 if there were no accesses to it during this time; | 1438 if there were no accesses to it during this time; |
1436 by default, it is 60 seconds; | 1439 by default, it is 60 seconds; |
1437 </tag-desc> | 1440 </tag-desc> |
1438 | 1441 |
1439 <tag-name> | 1442 <tag-name> |
1440 <value>off</value> | 1443 <literal>off</literal> |
1441 </tag-name> | 1444 </tag-name> |
1442 <tag-desc> | 1445 <tag-desc> |
1443 disables the cache. | 1446 disables the cache. |
1444 </tag-desc> | 1447 </tag-desc> |
1445 | 1448 |
1460 | 1463 |
1461 </directive> | 1464 </directive> |
1462 | 1465 |
1463 | 1466 |
1464 <directive name="open_file_cache_errors"> | 1467 <directive name="open_file_cache_errors"> |
1465 <syntax><value>on</value> | <value>off</value></syntax> | 1468 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
1466 <default>off</default> | 1469 <default>off</default> |
1467 <context>http</context> | 1470 <context>http</context> |
1468 <context>server</context> | 1471 <context>server</context> |
1469 <context>location</context> | 1472 <context>location</context> |
1470 | 1473 |
1477 | 1480 |
1478 | 1481 |
1479 <!-- | 1482 <!-- |
1480 | 1483 |
1481 <directive name="open_file_cache_events"> | 1484 <directive name="open_file_cache_events"> |
1482 <syntax><value>on</value> | <value>off</value></syntax> | 1485 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
1483 <default>off</default> | 1486 <default>off</default> |
1484 <context>http</context> | 1487 <context>http</context> |
1485 <context>server</context> | 1488 <context>server</context> |
1486 <context>location</context> | 1489 <context>location</context> |
1487 | 1490 |
1502 | 1505 |
1503 --> | 1506 --> |
1504 | 1507 |
1505 | 1508 |
1506 <directive name="open_file_cache_min_uses"> | 1509 <directive name="open_file_cache_min_uses"> |
1507 <syntax><argument>number</argument></syntax> | 1510 <syntax><value>number</value></syntax> |
1508 <default>1</default> | 1511 <default>1</default> |
1509 <context>http</context> | 1512 <context>http</context> |
1510 <context>server</context> | 1513 <context>server</context> |
1511 <context>location</context> | 1514 <context>location</context> |
1512 | 1515 |
1513 <para> | 1516 <para> |
1514 Sets the minimum <argument>number</argument> of file accesses during | 1517 Sets the minimum <value>number</value> of file accesses during |
1515 the period configured by the <parameter>inactive</parameter> parameter | 1518 the period configured by the <literal>inactive</literal> parameter |
1516 of the <link id="open_file_cache"/> directive, | 1519 of the <link id="open_file_cache"/> directive, |
1517 after which a file descriptor will remain open in the cache. | 1520 after which a file descriptor will remain open in the cache. |
1518 </para> | 1521 </para> |
1519 | 1522 |
1520 </directive> | 1523 </directive> |
1521 | 1524 |
1522 | 1525 |
1523 <directive name="open_file_cache_valid"> | 1526 <directive name="open_file_cache_valid"> |
1524 <syntax><argument>time</argument></syntax> | 1527 <syntax><value>time</value></syntax> |
1525 <default>60s</default> | 1528 <default>60s</default> |
1526 <context>http</context> | 1529 <context>http</context> |
1527 <context>server</context> | 1530 <context>server</context> |
1528 <context>location</context> | 1531 <context>location</context> |
1529 | 1532 |
1541 | 1544 |
1542 </directive> | 1545 </directive> |
1543 | 1546 |
1544 | 1547 |
1545 <directive name="optimize_server_names"> | 1548 <directive name="optimize_server_names"> |
1546 <syntax><value>on</value> | <value>off</value></syntax> | 1549 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
1547 <default>off</default> | 1550 <default>off</default> |
1548 <context>http</context> | 1551 <context>http</context> |
1549 <context>server</context> | 1552 <context>server</context> |
1550 | 1553 |
1551 <para> | 1554 <para> |
1569 | 1572 |
1570 </directive> | 1573 </directive> |
1571 | 1574 |
1572 | 1575 |
1573 <directive name="port_in_redirect"> | 1576 <directive name="port_in_redirect"> |
1574 <syntax><value>on</value> | <value>off</value></syntax> | 1577 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
1575 <default>on</default> | 1578 <default>on</default> |
1576 <context>http</context> | 1579 <context>http</context> |
1577 <context>server</context> | 1580 <context>server</context> |
1578 <context>location</context> | 1581 <context>location</context> |
1579 | 1582 |
1587 | 1590 |
1588 </directive> | 1591 </directive> |
1589 | 1592 |
1590 | 1593 |
1591 <directive name="postpone_output"> | 1594 <directive name="postpone_output"> |
1592 <syntax><argument>size</argument></syntax> | 1595 <syntax><value>size</value></syntax> |
1593 <default>1460</default> | 1596 <default>1460</default> |
1594 <context>http</context> | 1597 <context>http</context> |
1595 <context>server</context> | 1598 <context>server</context> |
1596 <context>location</context> | 1599 <context>location</context> |
1597 | 1600 |
1598 <para> | 1601 <para> |
1599 If possible, the output of client data will be postponed until | 1602 If possible, the output of client data will be postponed until |
1600 nginx has at least <argument>size</argument> bytes of data to send. | 1603 nginx has at least <value>size</value> bytes of data to send. |
1601 Value of zero disables postponing. | 1604 Value of zero disables postponing. |
1602 </para> | 1605 </para> |
1603 | 1606 |
1604 </directive> | 1607 </directive> |
1605 | 1608 |
1606 | 1609 |
1607 <directive name="read_ahead"> | 1610 <directive name="read_ahead"> |
1608 <syntax><argument>size</argument></syntax> | 1611 <syntax><value>size</value></syntax> |
1609 <default>0</default> | 1612 <default>0</default> |
1610 <context>http</context> | 1613 <context>http</context> |
1611 <context>server</context> | 1614 <context>server</context> |
1612 <context>location</context> | 1615 <context>location</context> |
1613 | 1616 |
1615 Sets the amount of pre-reading when working with files, in the kernel. | 1618 Sets the amount of pre-reading when working with files, in the kernel. |
1616 </para> | 1619 </para> |
1617 | 1620 |
1618 <para> | 1621 <para> |
1619 On Linux, the | 1622 On Linux, the |
1620 <code>posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)</code> | 1623 <literal>posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)</literal> |
1621 system call is used, so the <argument>size</argument> argument is ignored. | 1624 system call is used, so the <value>size</value> parameter is ignored. |
1622 </para> | 1625 </para> |
1623 | 1626 |
1624 <para> | 1627 <para> |
1625 On FreeBSD, the | 1628 On FreeBSD, the |
1626 <code>fcntl(O_READAHEAD,</code><argument>size</argument><code>)</code> | 1629 <literal>fcntl(O_READAHEAD,</literal> |
1630 <value>size</value><literal>)</literal> | |
1627 system call is used, supported in FreeBSD 9.0-CURRENT. | 1631 system call is used, supported in FreeBSD 9.0-CURRENT. |
1628 FreeBSD 7 needs to be | 1632 FreeBSD 7 needs to be |
1629 <link url="http://sysoev.ru/freebsd/patch.readahead.txt">patched</link>. | 1633 <link url="http://sysoev.ru/freebsd/patch.readahead.txt">patched</link>. |
1630 </para> | 1634 </para> |
1631 | 1635 |
1632 </directive> | 1636 </directive> |
1633 | 1637 |
1634 | 1638 |
1635 <directive name="recursive_error_pages"> | 1639 <directive name="recursive_error_pages"> |
1636 <syntax><value>on</value> | <value>off</value></syntax> | 1640 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
1637 <default>off</default> | 1641 <default>off</default> |
1638 <context>http</context> | 1642 <context>http</context> |
1639 <context>server</context> | 1643 <context>server</context> |
1640 <context>location</context> | 1644 <context>location</context> |
1641 | 1645 |
1647 | 1651 |
1648 </directive> | 1652 </directive> |
1649 | 1653 |
1650 | 1654 |
1651 <directive name="request_pool_size"> | 1655 <directive name="request_pool_size"> |
1652 <syntax><argument>size</argument></syntax> | 1656 <syntax><value>size</value></syntax> |
1653 <default>4k</default> | 1657 <default>4k</default> |
1654 <context>http</context> | 1658 <context>http</context> |
1655 <context>server</context> | 1659 <context>server</context> |
1656 | 1660 |
1657 <para> | 1661 <para> |
1663 </directive> | 1667 </directive> |
1664 | 1668 |
1665 | 1669 |
1666 <directive name="reset_timedout_connection"> | 1670 <directive name="reset_timedout_connection"> |
1667 <syntax> | 1671 <syntax> |
1668 <value>on</value> | <value>off</value></syntax> | 1672 <literal>on</literal> | <literal>off</literal></syntax> |
1669 <default>off</default> | 1673 <default>off</default> |
1670 <context>http</context> | 1674 <context>http</context> |
1671 <context>server</context> | 1675 <context>server</context> |
1672 <context>location</context> | 1676 <context>location</context> |
1673 | 1677 |
1690 </directive> | 1694 </directive> |
1691 | 1695 |
1692 | 1696 |
1693 <directive name="resolver"> | 1697 <directive name="resolver"> |
1694 <syntax> | 1698 <syntax> |
1695 <argument>address</argument> ... | 1699 <value>address</value> ... |
1696 [<parameter>valid</parameter>=<argument>time</argument>]</syntax> | 1700 [<literal>valid</literal>=<value>time</value>]</syntax> |
1697 <default/> | 1701 <default/> |
1698 <context>http</context> | 1702 <context>http</context> |
1699 <context>server</context> | 1703 <context>server</context> |
1700 <context>location</context> | 1704 <context>location</context> |
1701 | 1705 |
1703 Configures name servers used to resolve upstream server names, | 1707 Configures name servers used to resolve upstream server names, |
1704 for example: | 1708 for example: |
1705 <example> | 1709 <example> |
1706 resolver 127.0.0.1 192.0.2.1; | 1710 resolver 127.0.0.1 192.0.2.1; |
1707 </example> | 1711 </example> |
1708 An <argument>address</argument> argument may be specified as | 1712 An <value>address</value> parameter may be specified as |
1709 either an IPv4 address or a hostname; | 1713 either an IPv4 address or a hostname; |
1710 in the latter case, the first resolved IPv4 address is used. | 1714 in the latter case, the first resolved IPv4 address is used. |
1711 Name servers are queried in a round-robin fashion. | 1715 Name servers are queried in a round-robin fashion. |
1712 <note> | 1716 <note> |
1713 Before version 1.1.7, only a single name server could be configured. | 1717 Before version 1.1.7, only a single name server could be configured. |
1714 </note> | 1718 </note> |
1715 By default, nginx caches answers using the TTL value of a response. | 1719 By default, nginx caches answers using the TTL value of a response. |
1716 An optional <parameter>valid</parameter> parameter allows to override it: | 1720 An optional <literal>valid</literal> parameter allows to override it: |
1717 <example> | 1721 <example> |
1718 resolver 127.0.0.1 192.0.2.1 valid=30s; | 1722 resolver 127.0.0.1 192.0.2.1 valid=30s; |
1719 </example> | 1723 </example> |
1720 <note> | 1724 <note> |
1721 Before version 1.1.9, tuning of caching time was not possible, | 1725 Before version 1.1.9, tuning of caching time was not possible, |
1725 | 1729 |
1726 </directive> | 1730 </directive> |
1727 | 1731 |
1728 | 1732 |
1729 <directive name="resolver_timeout"> | 1733 <directive name="resolver_timeout"> |
1730 <syntax><argument>time</argument></syntax> | 1734 <syntax><value>time</value></syntax> |
1731 <default>30s</default> | 1735 <default>30s</default> |
1732 <context>http</context> | 1736 <context>http</context> |
1733 <context>server</context> | 1737 <context>server</context> |
1734 <context>location</context> | 1738 <context>location</context> |
1735 | 1739 |
1742 | 1746 |
1743 </directive> | 1747 </directive> |
1744 | 1748 |
1745 | 1749 |
1746 <directive name="root"> | 1750 <directive name="root"> |
1747 <syntax><argument>path</argument></syntax> | 1751 <syntax><value>path</value></syntax> |
1748 <default>html</default> | 1752 <default>html</default> |
1749 <context>http</context> | 1753 <context>http</context> |
1750 <context>server</context> | 1754 <context>server</context> |
1751 <context>location</context> | 1755 <context>location</context> |
1752 <context>if in location</context> | 1756 <context>if in location</context> |
1757 <example> | 1761 <example> |
1758 location /i/ { | 1762 location /i/ { |
1759 root /data/w3; | 1763 root /data/w3; |
1760 } | 1764 } |
1761 </example> | 1765 </example> |
1762 “<code>/i/top.gif</code>” will be responded | 1766 “<literal>/i/top.gif</literal>” will be responded |
1763 with the file | 1767 with the file |
1764 <path>/data/w3/i/top.gif</path>. | 1768 <path>/data/w3/i/top.gif</path>. |
1765 </para> | 1769 </para> |
1766 | 1770 |
1767 <para> | 1771 <para> |
1768 The <argument>path</argument> value can contain variables | 1772 The <value>path</value> value can contain variables |
1769 except <var>$document_root</var> and <var>$realpath_root</var>. | 1773 except <var>$document_root</var> and <var>$realpath_root</var>. |
1770 </para> | 1774 </para> |
1771 | 1775 |
1772 <para> | 1776 <para> |
1773 A path to the file is constructed by merely adding a URI to the value | 1777 A path to the file is constructed by merely adding a URI to the value |
1774 of the <code>root</code> directive. | 1778 of the <literal>root</literal> directive. |
1775 If a URI need to be modified, the | 1779 If a URI need to be modified, the |
1776 <link id="alias"/> directive should be used. | 1780 <link id="alias"/> directive should be used. |
1777 </para> | 1781 </para> |
1778 | 1782 |
1779 </directive> | 1783 </directive> |
1780 | 1784 |
1781 | 1785 |
1782 <directive name="satisfy"> | 1786 <directive name="satisfy"> |
1783 <syntax><value>all</value> | <value>any</value></syntax> | 1787 <syntax><literal>all</literal> | <literal>any</literal></syntax> |
1784 <default>all</default> | 1788 <default>all</default> |
1785 <context>http</context> | 1789 <context>http</context> |
1786 <context>server</context> | 1790 <context>server</context> |
1787 <context>location</context> | 1791 <context>location</context> |
1788 | 1792 |
1789 <para> | 1793 <para> |
1790 Allows access if <value>all</value> or <value>any</value> of the | 1794 Allows access if <literal>all</literal> or <literal>any</literal> of the |
1791 <link doc="ngx_http_access_module.xml">ngx_http_access_module</link> | 1795 <link doc="ngx_http_access_module.xml">ngx_http_access_module</link> |
1792 or <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link> | 1796 or <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link> |
1793 modules grant access. | 1797 modules grant access. |
1794 </para> | 1798 </para> |
1795 | 1799 |
1810 | 1814 |
1811 </directive> | 1815 </directive> |
1812 | 1816 |
1813 | 1817 |
1814 <directive name="satisfy_any"> | 1818 <directive name="satisfy_any"> |
1815 <syntax><value>on</value> | <value>off</value></syntax> | 1819 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
1816 <default>off</default> | 1820 <default>off</default> |
1817 <context>http</context> | 1821 <context>http</context> |
1818 <context>server</context> | 1822 <context>server</context> |
1819 <context>location</context> | 1823 <context>location</context> |
1820 | 1824 |
1825 | 1829 |
1826 </directive> | 1830 </directive> |
1827 | 1831 |
1828 | 1832 |
1829 <directive name="send_lowat"> | 1833 <directive name="send_lowat"> |
1830 <syntax><argument>size</argument></syntax> | 1834 <syntax><value>size</value></syntax> |
1831 <default>0</default> | 1835 <default>0</default> |
1832 <context>http</context> | 1836 <context>http</context> |
1833 <context>server</context> | 1837 <context>server</context> |
1834 <context>location</context> | 1838 <context>location</context> |
1835 | 1839 |
1837 If set to a non-zero value, nginx will try to minimize the number | 1841 If set to a non-zero value, nginx will try to minimize the number |
1838 of send operations on client sockets by using either | 1842 of send operations on client sockets by using either |
1839 <c-def>NOTE_LOWAT</c-def> flag of | 1843 <c-def>NOTE_LOWAT</c-def> flag of |
1840 <link doc="../events.xml" id="kqueue"/>, | 1844 <link doc="../events.xml" id="kqueue"/>, |
1841 or the <c-def>SO_SNDLOWAT</c-def> socket option, | 1845 or the <c-def>SO_SNDLOWAT</c-def> socket option, |
1842 with the specified <argument>size</argument>. | 1846 with the specified <value>size</value>. |
1843 </para> | 1847 </para> |
1844 | 1848 |
1845 <para> | 1849 <para> |
1846 This directive is ignored on Linux, Solaris, and Windows. | 1850 This directive is ignored on Linux, Solaris, and Windows. |
1847 </para> | 1851 </para> |
1848 | 1852 |
1849 </directive> | 1853 </directive> |
1850 | 1854 |
1851 | 1855 |
1852 <directive name="send_timeout"> | 1856 <directive name="send_timeout"> |
1853 <syntax><argument>time</argument></syntax> | 1857 <syntax><value>time</value></syntax> |
1854 <default>60s</default> | 1858 <default>60s</default> |
1855 <context>http</context> | 1859 <context>http</context> |
1856 <context>server</context> | 1860 <context>server</context> |
1857 <context>location</context> | 1861 <context>location</context> |
1858 | 1862 |
1867 </directive> | 1871 </directive> |
1868 | 1872 |
1869 | 1873 |
1870 <directive name="sendfile"> | 1874 <directive name="sendfile"> |
1871 | 1875 |
1872 <syntax><value>on</value> | <value>off</value></syntax> | 1876 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
1873 <default>off</default> | 1877 <default>off</default> |
1874 <context>http</context> | 1878 <context>http</context> |
1875 <context>server</context> | 1879 <context>server</context> |
1876 <context>location</context> | 1880 <context>location</context> |
1877 <context>if in location</context> | 1881 <context>if in location</context> |
1884 </directive> | 1888 </directive> |
1885 | 1889 |
1886 | 1890 |
1887 <directive name="sendfile_max_chunk"> | 1891 <directive name="sendfile_max_chunk"> |
1888 | 1892 |
1889 <syntax><argument>size</argument></syntax> | 1893 <syntax><value>size</value></syntax> |
1890 <default>0</default> | 1894 <default>0</default> |
1891 <context>http</context> | 1895 <context>http</context> |
1892 <context>server</context> | 1896 <context>server</context> |
1893 <context>location</context> | 1897 <context>location</context> |
1894 | 1898 |
1921 | 1925 |
1922 </directive> | 1926 </directive> |
1923 | 1927 |
1924 | 1928 |
1925 <directive name="server_name"> | 1929 <directive name="server_name"> |
1926 <syntax><argument>name</argument> ...</syntax> | 1930 <syntax><value>name</value> ...</syntax> |
1927 <default>""</default> | 1931 <default>""</default> |
1928 <context>server</context> | 1932 <context>server</context> |
1929 | 1933 |
1930 <para> | 1934 <para> |
1931 Sets names of the virtual server, for example: | 1935 Sets names of the virtual server, for example: |
1936 </example> | 1940 </example> |
1937 </para> | 1941 </para> |
1938 | 1942 |
1939 <para> | 1943 <para> |
1940 The first name becomes the primary server name. | 1944 The first name becomes the primary server name. |
1941 Server names can include an asterisk (“<code>*</code>”) | 1945 Server names can include an asterisk (“<literal>*</literal>”) |
1942 to replace the first or last part of a name: | 1946 to replace the first or last part of a name: |
1943 <example> | 1947 <example> |
1944 server { | 1948 server { |
1945 server_name example.com *.example.com www.example.*; | 1949 server_name example.com *.example.com www.example.*; |
1946 } | 1950 } |
1955 } | 1959 } |
1956 </example> | 1960 </example> |
1957 </para> | 1961 </para> |
1958 | 1962 |
1959 <para> | 1963 <para> |
1960 If the argument equals “<var>$hostname</var>” (0.9.4), the | 1964 If the parameter equals “<var>$hostname</var>” (0.9.4), the |
1961 machine's hostname is substituted. | 1965 machine's hostname is substituted. |
1962 </para> | 1966 </para> |
1963 | 1967 |
1964 <para> | 1968 <para> |
1965 It is also possible to use regular expressions in server names, | 1969 It is also possible to use regular expressions in server names, |
1966 prepending the name with a tilde (“<code>~</code>”): | 1970 prepending the name with a tilde (“<literal>~</literal>”): |
1967 <example> | 1971 <example> |
1968 server { | 1972 server { |
1969 server_name www.example.com ~^www\d+\.example\.com$; | 1973 server_name www.example.com ~^www\d+\.example\.com$; |
1970 } | 1974 } |
1971 </example> | 1975 </example> |
2037 <listitem> | 2041 <listitem> |
2038 full names | 2042 full names |
2039 </listitem> | 2043 </listitem> |
2040 | 2044 |
2041 <listitem> | 2045 <listitem> |
2042 names with the prefix mask, e.g. “<code>*.example.com</code>” | 2046 names with the prefix mask, e.g. “<literal>*.example.com</literal>” |
2043 </listitem> | 2047 </listitem> |
2044 | 2048 |
2045 <listitem> | 2049 <listitem> |
2046 names with the suffix mask, e.g. “<code>mail.*</code>” | 2050 names with the suffix mask, e.g. “<literal>mail.*</literal>” |
2047 </listitem> | 2051 </listitem> |
2048 | 2052 |
2049 <listitem> | 2053 <listitem> |
2050 regular expressions | 2054 regular expressions |
2051 </listitem> | 2055 </listitem> |
2055 | 2059 |
2056 </directive> | 2060 </directive> |
2057 | 2061 |
2058 | 2062 |
2059 <directive name="server_name_in_redirect"> | 2063 <directive name="server_name_in_redirect"> |
2060 <syntax><value>on</value> | <value>off</value></syntax> | 2064 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
2061 <default>off</default> | 2065 <default>off</default> |
2062 <context>http</context> | 2066 <context>http</context> |
2063 <context>server</context> | 2067 <context>server</context> |
2064 <context>location</context> | 2068 <context>location</context> |
2065 | 2069 |
2078 | 2082 |
2079 </directive> | 2083 </directive> |
2080 | 2084 |
2081 | 2085 |
2082 <directive name="server_names_hash_bucket_size"> | 2086 <directive name="server_names_hash_bucket_size"> |
2083 <syntax><argument>size</argument></syntax> | 2087 <syntax><value>size</value></syntax> |
2084 <default>32|64|128</default> | 2088 <default>32|64|128</default> |
2085 <context>http</context> | 2089 <context>http</context> |
2086 | 2090 |
2087 <para> | 2091 <para> |
2088 Sets the bucket size for the server names hash tables. | 2092 Sets the bucket size for the server names hash tables. |
2093 | 2097 |
2094 </directive> | 2098 </directive> |
2095 | 2099 |
2096 | 2100 |
2097 <directive name="server_names_hash_max_size"> | 2101 <directive name="server_names_hash_max_size"> |
2098 <syntax><argument>size</argument></syntax> | 2102 <syntax><value>size</value></syntax> |
2099 <default>512</default> | 2103 <default>512</default> |
2100 <context>http</context> | 2104 <context>http</context> |
2101 | 2105 |
2102 <para> | 2106 <para> |
2103 Sets the maximum <argument>size</argument> of the server names hash tables. | 2107 Sets the maximum <value>size</value> of the server names hash tables. |
2104 For more information, please refer to | 2108 For more information, please refer to |
2105 <link doc="../hash.xml">Setting Up Hashes</link>. | 2109 <link doc="../hash.xml">Setting Up Hashes</link>. |
2106 </para> | 2110 </para> |
2107 | 2111 |
2108 </directive> | 2112 </directive> |
2109 | 2113 |
2110 | 2114 |
2111 <directive name="server_tokens"> | 2115 <directive name="server_tokens"> |
2112 <syntax><value>on</value> | <value>off</value></syntax> | 2116 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
2113 <default>on</default> | 2117 <default>on</default> |
2114 <context>http</context> | 2118 <context>http</context> |
2115 <context>server</context> | 2119 <context>server</context> |
2116 <context>location</context> | 2120 <context>location</context> |
2117 | 2121 |
2122 | 2126 |
2123 </directive> | 2127 </directive> |
2124 | 2128 |
2125 | 2129 |
2126 <directive name="tcp_nodelay"> | 2130 <directive name="tcp_nodelay"> |
2127 <syntax><value>on</value> | <value>off</value></syntax> | 2131 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
2128 <default>on</default> | 2132 <default>on</default> |
2129 <context>http</context> | 2133 <context>http</context> |
2130 <context>server</context> | 2134 <context>server</context> |
2131 <context>location</context> | 2135 <context>location</context> |
2132 | 2136 |
2138 | 2142 |
2139 </directive> | 2143 </directive> |
2140 | 2144 |
2141 | 2145 |
2142 <directive name="tcp_nopush"> | 2146 <directive name="tcp_nopush"> |
2143 <syntax><value>on</value> | <value>off</value></syntax> | 2147 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
2144 <default>off</default> | 2148 <default>off</default> |
2145 <context>http</context> | 2149 <context>http</context> |
2146 <context>server</context> | 2150 <context>server</context> |
2147 <context>location</context> | 2151 <context>location</context> |
2148 | 2152 |
2169 </directive> | 2173 </directive> |
2170 | 2174 |
2171 | 2175 |
2172 <directive name="try_files"> | 2176 <directive name="try_files"> |
2173 <syntax> | 2177 <syntax> |
2174 <argument>file</argument> ... | 2178 <value>file</value> ... |
2175 <argument>uri</argument></syntax> | 2179 <value>uri</value></syntax> |
2176 <syntax> | 2180 <syntax> |
2177 <argument>file</argument> ... | 2181 <value>file</value> ... |
2178 =<argument>code</argument></syntax> | 2182 =<value>code</value></syntax> |
2179 <default/> | 2183 <default/> |
2180 <context>server</context> | 2184 <context>server</context> |
2181 <context>location</context> | 2185 <context>location</context> |
2182 | 2186 |
2183 <para> | 2187 <para> |
2184 Checks the existence of files in the specified order, and uses | 2188 Checks the existence of files in the specified order, and uses |
2185 the first found file for request processing; the processing | 2189 the first found file for request processing; the processing |
2186 is performed in the current context. | 2190 is performed in the current context. |
2187 A path to the file is constructed from the | 2191 A path to the file is constructed from the |
2188 <argument>file</argument> argument | 2192 <value>file</value> parameter |
2189 according to the | 2193 according to the |
2190 <link id="root"/> and <link id="alias"/> directives. | 2194 <link id="root"/> and <link id="alias"/> directives. |
2191 It is possible to check the directory existence by specifying | 2195 It is possible to check the directory existence by specifying |
2192 a slash at the end of a name, e.g. “<code>$uri/</code>”. | 2196 a slash at the end of a name, e.g. “<literal>$uri/</literal>”. |
2193 If none of the files were found, an internal redirect to the | 2197 If none of the files were found, an internal redirect to the |
2194 <argument>uri</argument> specified by the last argument is made. | 2198 <value>uri</value> specified by the last parameter is made. |
2195 For example: | 2199 For example: |
2196 <example> | 2200 <example> |
2197 location /images/ { | 2201 location /images/ { |
2198 try_files $uri /images/default.gif; | 2202 try_files $uri /images/default.gif; |
2199 } | 2203 } |
2200 | 2204 |
2201 location = /images/default.gif { | 2205 location = /images/default.gif { |
2202 expires 30s; | 2206 expires 30s; |
2203 } | 2207 } |
2204 </example> | 2208 </example> |
2205 The last argument can also point to a named location, | 2209 The last parameter can also point to a named location, |
2206 see examples below. | 2210 see examples below. |
2207 As of version 0.7.51, the last argument can also be a | 2211 As of version 0.7.51, the last parameter can also be a |
2208 <argument>code</argument>: | 2212 <value>code</value>: |
2209 <example> | 2213 <example> |
2210 location / { | 2214 location / { |
2211 try_files $uri $uri/index.html $uri.html =404; | 2215 try_files $uri $uri/index.html $uri.html =404; |
2212 } | 2216 } |
2213 </example> | 2217 </example> |
2261 <example> | 2265 <example> |
2262 location / { | 2266 location / { |
2263 try_files $uri $uri/ @drupal; | 2267 try_files $uri $uri/ @drupal; |
2264 } | 2268 } |
2265 </example> | 2269 </example> |
2266 the <code>try_files</code> directive is equivalent to | 2270 the <literal>try_files</literal> directive is equivalent to |
2267 <example> | 2271 <example> |
2268 location / { | 2272 location / { |
2269 error_page 404 = @drupal; | 2273 error_page 404 = @drupal; |
2270 log_not_found off; | 2274 log_not_found off; |
2271 } | 2275 } |
2280 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; | 2284 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; |
2281 | 2285 |
2282 ... | 2286 ... |
2283 } | 2287 } |
2284 </example> | 2288 </example> |
2285 <code>try_files</code> checks the existence of the PHP file | 2289 <literal>try_files</literal> checks the existence of the PHP file |
2286 before passing the request to the FastCGI server. | 2290 before passing the request to the FastCGI server. |
2287 </para> | 2291 </para> |
2288 | 2292 |
2289 <para> | 2293 <para> |
2290 Example for Wordpress and Joomla: | 2294 Example for Wordpress and Joomla: |
2343 <path>conf/mime.types</path> file. | 2347 <path>conf/mime.types</path> file. |
2344 </para> | 2348 </para> |
2345 | 2349 |
2346 <para> | 2350 <para> |
2347 To make a particular location emit the | 2351 To make a particular location emit the |
2348 “<code>application/octet-stream</code>” | 2352 “<literal>application/octet-stream</literal>” |
2349 MIME type for all requests, try the following: | 2353 MIME type for all requests, try the following: |
2350 <example> | 2354 <example> |
2351 location /download/ { | 2355 location /download/ { |
2352 types { } | 2356 types { } |
2353 default_type application/octet-stream; | 2357 default_type application/octet-stream; |
2357 | 2361 |
2358 </directive> | 2362 </directive> |
2359 | 2363 |
2360 | 2364 |
2361 <directive name="types_hash_bucket_size"> | 2365 <directive name="types_hash_bucket_size"> |
2362 <syntax><argument>size</argument></syntax> | 2366 <syntax><value>size</value></syntax> |
2363 <default>32|64|128</default> | 2367 <default>32|64|128</default> |
2364 <context>http</context> | 2368 <context>http</context> |
2365 <context>server</context> | 2369 <context>server</context> |
2366 <context>location</context> | 2370 <context>location</context> |
2367 | 2371 |
2374 | 2378 |
2375 </directive> | 2379 </directive> |
2376 | 2380 |
2377 | 2381 |
2378 <directive name="types_hash_max_size"> | 2382 <directive name="types_hash_max_size"> |
2379 <syntax><argument>size</argument></syntax> | 2383 <syntax><value>size</value></syntax> |
2380 <default>1024</default> | 2384 <default>1024</default> |
2381 <context>http</context> | 2385 <context>http</context> |
2382 <context>server</context> | 2386 <context>server</context> |
2383 <context>location</context> | 2387 <context>location</context> |
2384 | 2388 |
2385 <para> | 2389 <para> |
2386 Sets the maximum <argument>size</argument> of the types hash tables. | 2390 Sets the maximum <value>size</value> of the types hash tables. |
2387 For more information, please refer to | 2391 For more information, please refer to |
2388 <link doc="../hash.xml">Setting Up Hashes</link>. | 2392 <link doc="../hash.xml">Setting Up Hashes</link>. |
2389 </para> | 2393 </para> |
2390 | 2394 |
2391 </directive> | 2395 </directive> |
2392 | 2396 |
2393 | 2397 |
2394 <directive name="underscores_in_headers"> | 2398 <directive name="underscores_in_headers"> |
2395 <syntax><value>on</value> | <value>off</value></syntax> | 2399 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
2396 <default>off</default> | 2400 <default>off</default> |
2397 <context>http</context> | 2401 <context>http</context> |
2398 <context>server</context> | 2402 <context>server</context> |
2399 | 2403 |
2400 <para> | 2404 <para> |
2406 | 2410 |
2407 </directive> | 2411 </directive> |
2408 | 2412 |
2409 | 2413 |
2410 <directive name="variables_hash_bucket_size"> | 2414 <directive name="variables_hash_bucket_size"> |
2411 <syntax><argument>size</argument></syntax> | 2415 <syntax><value>size</value></syntax> |
2412 <default>64</default> | 2416 <default>64</default> |
2413 <context>http</context> | 2417 <context>http</context> |
2414 | 2418 |
2415 <para> | 2419 <para> |
2416 Sets the bucket size for the variables hash table. | 2420 Sets the bucket size for the variables hash table. |
2420 | 2424 |
2421 </directive> | 2425 </directive> |
2422 | 2426 |
2423 | 2427 |
2424 <directive name="variables_hash_max_size"> | 2428 <directive name="variables_hash_max_size"> |
2425 <syntax><argument>size</argument></syntax> | 2429 <syntax><value>size</value></syntax> |
2426 <default>512</default> | 2430 <default>512</default> |
2427 <context>http</context> | 2431 <context>http</context> |
2428 | 2432 |
2429 <para> | 2433 <para> |
2430 Sets the maximum <argument>size</argument> of the variables hash table. | 2434 Sets the maximum <value>size</value> of the variables hash table. |
2431 For more information, please refer to | 2435 For more information, please refer to |
2432 <link doc="../hash.xml">Setting Up Hashes</link>. | 2436 <link doc="../hash.xml">Setting Up Hashes</link>. |
2433 </para> | 2437 </para> |
2434 | 2438 |
2435 </directive> | 2439 </directive> |
2437 </section> | 2441 </section> |
2438 | 2442 |
2439 <section id="variables" name="Embedded Variables"> | 2443 <section id="variables" name="Embedded Variables"> |
2440 | 2444 |
2441 <para> | 2445 <para> |
2442 The module <code>ngx_http_core_module</code> supports embedded variables with | 2446 The module <literal>ngx_http_core_module</literal> supports embedded variables |
2443 names matching those of the Apache Server. | 2447 with names matching those of the Apache Server. |
2444 First of all, these are variables representing client request header | 2448 First of all, these are variables representing client request header |
2445 fields, such as <var>$http_user_agent</var>, <var>$http_cookie</var>, | 2449 fields, such as <var>$http_user_agent</var>, <var>$http_cookie</var>, |
2446 and so on. | 2450 and so on. |
2447 It also supports other variables: | 2451 It also supports other variables: |
2448 <list type="tag"> | 2452 <list type="tag"> |
2449 | 2453 |
2450 <tag-name><var>$arg_</var><argument>name</argument></tag-name> | 2454 <tag-name><var>$arg_</var><value>name</value></tag-name> |
2451 <tag-desc> | 2455 <tag-desc> |
2452 argument <argument>name</argument> in the request line | 2456 argument <value>name</value> in the request line |
2453 </tag-desc> | 2457 </tag-desc> |
2454 | 2458 |
2455 <tag-name><var>$args</var></tag-name> | 2459 <tag-name><var>$args</var></tag-name> |
2456 <tag-desc> | 2460 <tag-desc> |
2457 arguments in the request line | 2461 arguments in the request line |
2475 <tag-name><var>$content_type</var></tag-name> | 2479 <tag-name><var>$content_type</var></tag-name> |
2476 <tag-desc> | 2480 <tag-desc> |
2477 <header>Content-Type</header> request header field | 2481 <header>Content-Type</header> request header field |
2478 </tag-desc> | 2482 </tag-desc> |
2479 | 2483 |
2480 <tag-name><var>$cookie_</var><argument>name</argument></tag-name> | 2484 <tag-name><var>$cookie_</var><value>name</value></tag-name> |
2481 <tag-desc> | 2485 <tag-desc> |
2482 the <argument>name</argument> cookie | 2486 the <value>name</value> cookie |
2483 </tag-desc> | 2487 </tag-desc> |
2484 | 2488 |
2485 <tag-name><var>$document_root</var></tag-name> | 2489 <tag-name><var>$document_root</var></tag-name> |
2486 <tag-desc> | 2490 <tag-desc> |
2487 <link id="root"/> directive's value for the current request | 2491 <link id="root"/> directive's value for the current request |
2501 <tag-name><var>$hostname</var></tag-name> | 2505 <tag-name><var>$hostname</var></tag-name> |
2502 <tag-desc> | 2506 <tag-desc> |
2503 host name | 2507 host name |
2504 </tag-desc> | 2508 </tag-desc> |
2505 | 2509 |
2506 <tag-name><var>$http_</var><argument>name</argument></tag-name> | 2510 <tag-name><var>$http_</var><value>name</value></tag-name> |
2507 <tag-desc> | 2511 <tag-desc> |
2508 the <argument>name</argument> request header field | 2512 the <value>name</value> request header field |
2509 </tag-desc> | 2513 </tag-desc> |
2510 | 2514 |
2511 <tag-name><var>$https</var></tag-name> | 2515 <tag-name><var>$https</var></tag-name> |
2512 <tag-desc> | 2516 <tag-desc> |
2513 “<code>on</code>” | 2517 “<literal>on</literal>” |
2514 if connection operates in SSL mode, | 2518 if connection operates in SSL mode, |
2515 or an empty string otherwise | 2519 or an empty string otherwise |
2516 </tag-desc> | 2520 </tag-desc> |
2517 | 2521 |
2518 <tag-name><var>$is_args</var></tag-name> | 2522 <tag-name><var>$is_args</var></tag-name> |
2519 <tag-desc> | 2523 <tag-desc> |
2520 “<code>?</code>” if a request line has arguments, | 2524 “<literal>?</literal>” if a request line has arguments, |
2521 or an empty string otherwise | 2525 or an empty string otherwise |
2522 </tag-desc> | 2526 </tag-desc> |
2523 | 2527 |
2524 <tag-name><var>$limit_rate</var></tag-name> | 2528 <tag-name><var>$limit_rate</var></tag-name> |
2525 <tag-desc> | 2529 <tag-desc> |
2600 </para> | 2604 </para> |
2601 </tag-desc> | 2605 </tag-desc> |
2602 | 2606 |
2603 <tag-name><var>$request_completion</var></tag-name> | 2607 <tag-name><var>$request_completion</var></tag-name> |
2604 <tag-desc> | 2608 <tag-desc> |
2605 “<code>OK</code>” if a request has completed, | 2609 “<literal>OK</literal>” if a request has completed, |
2606 or an empty string otherwise | 2610 or an empty string otherwise |
2607 </tag-desc> | 2611 </tag-desc> |
2608 | 2612 |
2609 <tag-name><var>$request_filename</var></tag-name> | 2613 <tag-name><var>$request_filename</var></tag-name> |
2610 <tag-desc> | 2614 <tag-desc> |
2614 </tag-desc> | 2618 </tag-desc> |
2615 | 2619 |
2616 <tag-name><var>$request_method</var></tag-name> | 2620 <tag-name><var>$request_method</var></tag-name> |
2617 <tag-desc> | 2621 <tag-desc> |
2618 request method, usually | 2622 request method, usually |
2619 “<code>GET</code>” or “<code>POST</code>” | 2623 “<literal>GET</literal>” or “<literal>POST</literal>” |
2620 </tag-desc> | 2624 </tag-desc> |
2621 | 2625 |
2622 <tag-name><var>$request_uri</var></tag-name> | 2626 <tag-name><var>$request_uri</var></tag-name> |
2623 <tag-desc> | 2627 <tag-desc> |
2624 full original request URI (with arguments) | 2628 full original request URI (with arguments) |
2625 </tag-desc> | 2629 </tag-desc> |
2626 | 2630 |
2627 <tag-name><var>$scheme</var></tag-name> | 2631 <tag-name><var>$scheme</var></tag-name> |
2628 <tag-desc> | 2632 <tag-desc> |
2629 request scheme, “<code>http</code>” or “<code>https</code>” | 2633 request scheme, “<literal>http</literal>” or “<literal>https</literal>” |
2630 </tag-desc> | 2634 </tag-desc> |
2631 | 2635 |
2632 <tag-name><var>$sent_http_</var><argument>name</argument></tag-name> | 2636 <tag-name><var>$sent_http_</var><value>name</value></tag-name> |
2633 <tag-desc> | 2637 <tag-desc> |
2634 the <argument>name</argument> response header field | 2638 the <value>name</value> response header field |
2635 </tag-desc> | 2639 </tag-desc> |
2636 | 2640 |
2637 <tag-name><var>$server_addr</var></tag-name> | 2641 <tag-name><var>$server_addr</var></tag-name> |
2638 <tag-desc> | 2642 <tag-desc> |
2639 an address of the server which accepted a request | 2643 an address of the server which accepted a request |
2640 <para> | 2644 <para> |
2641 Computing a value of this variable usually requires one system call. | 2645 Computing a value of this variable usually requires one system call. |
2642 To avoid a system call, the <link id="listen"/> directives | 2646 To avoid a system call, the <link id="listen"/> directives |
2643 must specify addresses and use the <parameter>bind</parameter> parameter. | 2647 must specify addresses and use the <literal>bind</literal> parameter. |
2644 </para> | 2648 </para> |
2645 </tag-desc> | 2649 </tag-desc> |
2646 | 2650 |
2647 <tag-name><var>$server_name</var></tag-name> | 2651 <tag-name><var>$server_name</var></tag-name> |
2648 <tag-desc> | 2652 <tag-desc> |
2655 </tag-desc> | 2659 </tag-desc> |
2656 | 2660 |
2657 <tag-name><var>$server_protocol</var></tag-name> | 2661 <tag-name><var>$server_protocol</var></tag-name> |
2658 <tag-desc> | 2662 <tag-desc> |
2659 request protocol, usually | 2663 request protocol, usually |
2660 “<code>HTTP/1.0</code>” | 2664 “<literal>HTTP/1.0</literal>” |
2661 or | 2665 or |
2662 “<code>HTTP/1.1</code>” | 2666 “<literal>HTTP/1.1</literal>” |
2663 </tag-desc> | 2667 </tag-desc> |
2664 | 2668 |
2665 <tag-name><var>$uri</var></tag-name> | 2669 <tag-name><var>$uri</var></tag-name> |
2666 <tag-desc> | 2670 <tag-desc> |
2667 current URI in request | 2671 current URI in request |