comparison xml/en/docs/http/ngx_http_proxy_module.xml @ 959:fbb4cc6f8c3d

Text review of ngx_http_proxy_module.
author Egor Nikitin <yegor.nikitin@gmail.com>
date Wed, 07 Aug 2013 10:10:59 +0400
parents ba3d6ade3513
children 95c3c3bbf1ce
comparison
equal deleted inserted replaced
958:fd1f8e0a405e 959:fbb4cc6f8c3d
13 rev="12"> 13 rev="12">
14 14
15 <section id="summary"> 15 <section id="summary">
16 16
17 <para> 17 <para>
18 The <literal>ngx_http_proxy_module</literal> module allows to pass 18 The <literal>ngx_http_proxy_module</literal> module allows passing
19 requests to another server. 19 requests to another server.
20 </para> 20 </para>
21 21
22 </section> 22 </section>
23 23
46 <context>server</context> 46 <context>server</context>
47 <context>location</context> 47 <context>location</context>
48 <appeared-in>0.8.22</appeared-in> 48 <appeared-in>0.8.22</appeared-in>
49 49
50 <para> 50 <para>
51 Forces outgoing connections to a proxied server to originate 51 Makes outgoing connections to a proxied server to originate
52 from the specified local IP <value>address</value>. 52 from the specified local IP <value>address</value>.
53 Value of the parameter can contain variables (1.3.12). 53 Value of the parameter can contain variables (1.3.12).
54 The special value <literal>off</literal> (1.3.12) cancels the effect 54 The special value <literal>off</literal> (1.3.12) cancels the effect
55 of the <literal>proxy_bind</literal> directive 55 of the <literal>proxy_bind</literal> directive
56 inherited from the previous configuration level, allowing the 56 inherited from the previous configuration level, allowing the
57 system to auto-assign local address. 57 system to auto-assign the local IP address.
58 </para> 58 </para>
59 59
60 </directive> 60 </directive>
61 61
62 62
66 <context>http</context> 66 <context>http</context>
67 <context>server</context> 67 <context>server</context>
68 <context>location</context> 68 <context>location</context>
69 69
70 <para> 70 <para>
71 Sets <value>size</value> of the buffer used for reading the first part 71 Sets the <value>size</value> of the buffer used for reading the first part
72 of a response received from the proxied server. 72 of a response received from the proxied server.
73 This part usually contains a small response header. 73 This part usually contains a small response header.
74 By default, the buffer size is equal to the size of one 74 By default, the buffer size is equal to the size of one
75 buffer set by the <link id="proxy_buffers"/> directive. 75 buffer set by the <link id="proxy_buffers"/> directive.
76 It can be made smaller however. 76 It can be made smaller however.
90 Enables or disables buffering of responses from the proxied server. 90 Enables or disables buffering of responses from the proxied server.
91 </para> 91 </para>
92 92
93 <para> 93 <para>
94 When buffering is enabled, nginx receives a response from the proxied server 94 When buffering is enabled, nginx receives a response from the proxied server
95 as soon as possible, saving it into buffers set by the 95 as soon as possible, saving it into the buffers set by the
96 <link id="proxy_buffer_size"/> and <link id="proxy_buffers"/> directives. 96 <link id="proxy_buffer_size"/> and <link id="proxy_buffers"/> directives.
97 If the whole response does not fit into memory, part of it can be saved 97 If the whole response does not fit into memory, a part of it can be saved
98 to a <link id="proxy_temp_path">temporary file</link> on disk. 98 to a <link id="proxy_temp_path">temporary file</link> on the disk.
99 Writes to temporary files are controlled by the 99 Writing to temporary files is controlled by the
100 <link id="proxy_max_temp_file_size"/> and 100 <link id="proxy_max_temp_file_size"/> and
101 <link id="proxy_temp_file_write_size"/> directives. 101 <link id="proxy_temp_file_write_size"/> directives.
102 </para> 102 </para>
103 103
104 <para> 104 <para>
111 111
112 <para> 112 <para>
113 Buffering can also be enabled or disabled by passing 113 Buffering can also be enabled or disabled by passing
114 “<literal>yes</literal>” or “<literal>no</literal>” in the 114 “<literal>yes</literal>” or “<literal>no</literal>” in the
115 <header>X-Accel-Buffering</header> response header field. 115 <header>X-Accel-Buffering</header> response header field.
116 This ability can be disabled using the 116 This capability can be disabled using the
117 <link doc="ngx_http_proxy_module.xml" id="proxy_ignore_headers"/> directive. 117 <link doc="ngx_http_proxy_module.xml" id="proxy_ignore_headers"/> directive.
118 </para> 118 </para>
119 119
120 </directive> 120 </directive>
121 121
150 server is enabled, limits the total <value>size</value> of buffers that 150 server is enabled, limits the total <value>size</value> of buffers that
151 can be busy sending a response to the client while the response is not 151 can be busy sending a response to the client while the response is not
152 yet fully read. 152 yet fully read.
153 In the mean time, the rest of the buffers can be used for reading a response 153 In the mean time, the rest of the buffers can be used for reading a response
154 and, if needed, buffering part of a response to a temporary file. 154 and, if needed, buffering part of a response to a temporary file.
155 By default, <value>size</value> is limited by two buffers set by the 155 By default, <value>size</value> is limited by the size of two buffers set by the
156 <link id="proxy_buffer_size"/> and <link id="proxy_buffers"/> directives. 156 <link id="proxy_buffer_size"/> and <link id="proxy_buffers"/> directives.
157 </para> 157 </para>
158 158
159 </directive> 159 </directive>
160 160
229 <para> 229 <para>
230 When enabled, only one request at a time will be allowed to populate 230 When enabled, only one request at a time will be allowed to populate
231 a new cache element identified according to the <link id="proxy_cache_key"/> 231 a new cache element identified according to the <link id="proxy_cache_key"/>
232 directive by passing a request to a proxied server. 232 directive by passing a request to a proxied server.
233 Other requests of the same cache element will either wait 233 Other requests of the same cache element will either wait
234 for a response to appear in the cache, or the cache lock for 234 for a response to appear in the cache or the cache lock for
235 this element to be released, up to the time set by the 235 this element to be released, up to the time set by the
236 <link id="proxy_cache_lock_timeout"/> directive. 236 <link id="proxy_cache_lock_timeout"/> directive.
237 </para> 237 </para>
238 238
239 </directive> 239 </directive>
304 [<literal>loader_threshold</literal>=<value>time</value>]</syntax> 304 [<literal>loader_threshold</literal>=<value>time</value>]</syntax>
305 <default/> 305 <default/>
306 <context>http</context> 306 <context>http</context>
307 307
308 <para> 308 <para>
309 Sets path and other parameters of a cache. 309 Sets the path and other parameters of a cache.
310 Cache data are stored in files. 310 Cache data are stored in files.
311 Both the key and file name in a cache are a result of 311 Both the key and file name in a cache are a result of
312 applying the MD5 function to the proxied URL. 312 applying the MD5 function to the proxied URL.
313 313
314 The <literal>levels</literal> parameter defines hierarchy levels of a cache. 314 The <literal>levels</literal> parameter defines hierarchy levels of a cache.
321 /data/nginx/cache/<emphasis>c</emphasis>/<emphasis>29</emphasis>/b7f54b2df7773722d382f4809d650<emphasis>29c</emphasis> 321 /data/nginx/cache/<emphasis>c</emphasis>/<emphasis>29</emphasis>/b7f54b2df7773722d382f4809d650<emphasis>29c</emphasis>
322 </example> 322 </example>
323 </para> 323 </para>
324 324
325 <para> 325 <para>
326 A cached response is first written to a temporary file, then a file is renamed. 326 A cached response is first written to a temporary file,
327 Starting from version 0.8.9 temporary files and the cache can be put on 327 then the file is renamed.
328 different file systems but be aware that in this case a file is copied 328 Starting from version 0.8.9, temporary files and the cache can be put on
329 across two file systems instead of the cheap rename operation. 329 different file systems, but be aware that in this case a file is copied
330 across two file systems instead of the cheap renaming operation.
330 It is thus recommended that for any given location both cache and a directory 331 It is thus recommended that for any given location both cache and a directory
331 holding temporary files set by the <link id="proxy_temp_path"/> directive 332 holding temporary files, set by the <link id="proxy_temp_path"/> directive,
332 are put on the same file system. 333 are put on the same file system.
333 </para> 334 </para>
334 335
335 <para> 336 <para>
336 In addition, all active keys and information about data are stored 337 In addition, all active keys and information about data are stored
341 regardless of their freshness. 342 regardless of their freshness.
342 By default, <literal>inactive</literal> is set to 10 minutes. 343 By default, <literal>inactive</literal> is set to 10 minutes.
343 </para> 344 </para>
344 345
345 <para> 346 <para>
346 The special process “cache manager” monitors the maximum cache size set 347 The special “cache manager” process monitors the maximum cache size set
347 by the <literal>max_size</literal> parameter; 348 by the <literal>max_size</literal> parameter.
348 when this size is exceeded it removes the least recently used data. 349 When this size is exceeded, it removes the least recently used data.
349 </para> 350 </para>
350 351
351 <para> 352 <para>
352 A minute after the start the special process “cache loader” is activated 353 A minute after the start the special “cache loader” process is activated.
353 that loads information about previously cached data stored on file system 354 It loads information about previously cached data stored on file system
354 into a cache zone. 355 into a cache zone.
355 A load is done in iterations. 356 The loading is done in iterations.
356 During one iteration no more than <literal>loader_files</literal> items 357 During one iteration no more than <literal>loader_files</literal> items
357 are loaded (by default, 100). 358 are loaded (by default, 100).
358 Besides, the duration of one iteration is limited by the 359 Besides, the duration of one iteration is limited by the
359 <literal>loader_threshold</literal> parameter (by default, 200 milliseconds). 360 <literal>loader_threshold</literal> parameter (by default, 200 milliseconds).
360 A pause is made between iterations, configured by the 361 Between iterations, a pause configured by the <literal>loader_sleep</literal>
361 <literal>loader_sleep</literal> parameter (by default, 50 milliseconds). 362 parameter (by default, 50 milliseconds) is made.
362 </para> 363 </para>
363 364
364 </directive> 365 </directive>
365 366
366 367
382 <context>http</context> 383 <context>http</context>
383 <context>server</context> 384 <context>server</context>
384 <context>location</context> 385 <context>location</context>
385 386
386 <para> 387 <para>
387 If an error occurs while working with the proxied server it is possible 388 Determines in which cases a stale cached response can be used
388 to use a stale cached response. 389 when an error occurs in working with the proxied server.
389 This directives determines in which cases it is permitted. 390 The directive’s parameters match the parameters of the
390 The directive’s parameters match those of the
391 <link id="proxy_next_upstream"/> directive. 391 <link id="proxy_next_upstream"/> directive.
392 </para> 392 </para>
393 393
394 <para> 394 <para>
395 Additionally, the <literal>updating</literal> parameter permits 395 Additionally, the <literal>updating</literal> parameter permits
396 to use a stale cached response if it is currently being updated. 396 using a stale cached response if it is currently being updated.
397 This allows to minimize the number of accesses to proxied servers 397 This allows minimizing the number of accesses to proxied servers
398 when updating cached data. 398 when updating cached data.
399 </para> 399 </para>
400 400
401 <para> 401 <para>
402 To minimize the number of accesses to proxied servers when 402 To minimize the number of accesses to proxied servers when
432 </example> 432 </example>
433 then only 200, 301, and 302 responses are cached. 433 then only 200, 301, and 302 responses are cached.
434 </para> 434 </para>
435 435
436 <para> 436 <para>
437 In addition, it can be specified to cache any responses using the 437 In addition, the <literal>any</literal> parameter can be specified
438 <literal>any</literal> parameter: 438 to cache any responses:
439 <example> 439 <example>
440 proxy_cache_valid 200 302 10m; 440 proxy_cache_valid 200 302 10m;
441 proxy_cache_valid 301 1h; 441 proxy_cache_valid 301 1h;
442 proxy_cache_valid any 1m; 442 proxy_cache_valid any 1m;
443 </example> 443 </example>
444 </para> 444 </para>
445 445
446 <para> 446 <para>
447 Parameters of caching can also be set directly 447 Parameters of caching can also be set directly
448 in the response header. 448 in the response header.
449 This has a higher precedence than setting of caching time using the directive. 449 This has higher priority than setting of caching time using the directive.
450 The <header>X-Accel-Expires</header> header field sets caching time of a 450 The <header>X-Accel-Expires</header> header field sets caching time of a
451 response in seconds. 451 response in seconds.
452 The value 0 disables to cache a response. 452 The 0 value disables caching for a response.
453 If a value starts with the prefix <literal>@</literal>, it sets an absolute 453 If a value starts with the <literal>@</literal> prefix, it sets an absolute
454 time in seconds since Epoch, up to which the response may be cached. 454 time in seconds since Epoch, up to which the response may be cached.
455 If header does not include the <header>X-Accel-Expires</header> field, 455 If header does not include the <header>X-Accel-Expires</header> field,
456 parameters of caching may be set in the header fields 456 parameters of caching may be set in the header fields
457 <header>Expires</header> or <header>Cache-Control</header>. 457 <header>Expires</header> or <header>Cache-Control</header>.
458 If a header includes the <header>Set-Cookie</header> field, such a 458 If a header includes the <header>Set-Cookie</header> field, such a
470 <context>http</context> 470 <context>http</context>
471 <context>server</context> 471 <context>server</context>
472 <context>location</context> 472 <context>location</context>
473 473
474 <para> 474 <para>
475 Defines a timeout for establishing a connection with the proxied server. 475 Defines a timeout for establishing a connection with a proxied server.
476 It should be noted that this timeout cannot usually exceed 75 seconds. 476 It should be noted that this timeout cannot usually exceed 75 seconds.
477 </para> 477 </para>
478 478
479 </directive> 479 </directive>
480 480
490 490
491 <para> 491 <para>
492 Sets a text that should be changed in the <literal>domain</literal> 492 Sets a text that should be changed in the <literal>domain</literal>
493 attribute of the <header>Set-Cookie</header> header fields of a 493 attribute of the <header>Set-Cookie</header> header fields of a
494 proxied server response. 494 proxied server response.
495 Suppose a proxied server returned the header field 495 Suppose a proxied server returned the <header>Set-Cookie</header>
496 <header>Set-Cookie</header> with the attribute 496 header field with the attribute
497 “<literal>domain=localhost</literal>”. 497 “<literal>domain=localhost</literal>”.
498 The directive 498 The directive
499 <example> 499 <example>
500 proxy_cookie_domain localhost example.org; 500 proxy_cookie_domain localhost example.org;
501 </example> 501 </example>
503 “<literal>domain=example.org</literal>”. 503 “<literal>domain=example.org</literal>”.
504 </para> 504 </para>
505 505
506 <para> 506 <para>
507 A dot at the beginning of the <value>domain</value> and 507 A dot at the beginning of the <value>domain</value> and
508 <value>replacement</value> strings, and the <literal>domain</literal> 508 <value>replacement</value> strings and the <literal>domain</literal>
509 attribute is ignored. 509 attribute is ignored.
510 Matching is case-insensitive. 510 Matching is case-insensitive.
511 </para> 511 </para>
512 512
513 <para> 513 <para>
514 The strings <value>domain</value> and <value>replacement</value> 514 The <value>domain</value> and <value>replacement</value> strings
515 can contain variables: 515 can contain variables:
516 <example> 516 <example>
517 proxy_cookie_domain www.$host $host; 517 proxy_cookie_domain www.$host $host;
518 </example> 518 </example>
519 </para> 519 </para>
520 520
521 <para> 521 <para>
522 A directive can also be specified using regular expressions. 522 The directive can also be specified using regular expressions.
523 In this case, <value>domain</value> should start from 523 In this case, <value>domain</value> should start from
524 the “<literal>~</literal>” symbol. 524 the “<literal>~</literal>” symbol.
525 A regular expression can contain named and positional captures, 525 A regular expression can contain named and positional captures,
526 and <value>replacement</value> can reference them: 526 and <value>replacement</value> can reference them:
527 <example> 527 <example>
536 proxy_cookie_domain ~\.([a-z]+\.[a-z]+)$ $1; 536 proxy_cookie_domain ~\.([a-z]+\.[a-z]+)$ $1;
537 </example> 537 </example>
538 </para> 538 </para>
539 539
540 <para> 540 <para>
541 The <literal>off</literal> parameter cancels all 541 The <literal>off</literal> parameter cancels the effect of all
542 <literal>proxy_cookie_domain</literal> directives on the current level: 542 <literal>proxy_cookie_domain</literal> directives on the current level:
543 <example> 543 <example>
544 proxy_cookie_domain off; 544 proxy_cookie_domain off;
545 proxy_cookie_domain localhost example.org; 545 proxy_cookie_domain localhost example.org;
546 proxy_cookie_domain www.example.org example.org; 546 proxy_cookie_domain www.example.org example.org;
561 561
562 <para> 562 <para>
563 Sets a text that should be changed in the <literal>path</literal> 563 Sets a text that should be changed in the <literal>path</literal>
564 attribute of the <header>Set-Cookie</header> header fields of a 564 attribute of the <header>Set-Cookie</header> header fields of a
565 proxied server response. 565 proxied server response.
566 Suppose a proxied server returned the header field 566 Suppose a proxied server returned the <header>Set-Cookie</header>
567 <header>Set-Cookie</header> with the attribute 567 header field with the attribute
568 “<literal>path=/two/some/uri/</literal>”. 568 “<literal>path=/two/some/uri/</literal>”.
569 The directive 569 The directive
570 <example> 570 <example>
571 proxy_cookie_path /two/ /; 571 proxy_cookie_path /two/ /;
572 </example> 572 </example>
573 will rewrite this attribute to 573 will rewrite this attribute to
574 “<literal>path=/some/uri/</literal>”. 574 “<literal>path=/some/uri/</literal>”.
575 </para> 575 </para>
576 576
577 <para> 577 <para>
578 The strings <value>path</value> and <value>replacement</value> 578 The <value>path</value> and <value>replacement</value> strings
579 can contain variables: 579 can contain variables:
580 <example> 580 <example>
581 proxy_cookie_path $uri /some$uri; 581 proxy_cookie_path $uri /some$uri;
582 </example> 582 </example>
583 </para> 583 </para>
584 584
585 <para> 585 <para>
586 A directive can also be specified using regular expressions. 586 The directive can also be specified using regular expressions.
587 In this case, <value>path</value> should either start from 587 In this case, <value>path</value> should either start from
588 the “<literal>~</literal>” symbol for a case-sensitive matching, 588 the “<literal>~</literal>” symbol for a case-sensitive matching,
589 or from the “<literal>~*</literal>” symbols for case-insensitive 589 or from the “<literal>~*</literal>” symbols for case-insensitive
590 matching. 590 matching.
591 A regular expression can contain named and positional captures, 591 A regular expression can contain named and positional captures,
602 proxy_cookie_path / /two/; 602 proxy_cookie_path / /two/;
603 </example> 603 </example>
604 </para> 604 </para>
605 605
606 <para> 606 <para>
607 The <literal>off</literal> parameter cancels all 607 The <literal>off</literal> parameter cancels the effect of all
608 <literal>proxy_cookie_path</literal> directives on the current level: 608 <literal>proxy_cookie_path</literal> directives on the current level:
609 <example> 609 <example>
610 proxy_cookie_path off; 610 proxy_cookie_path off;
611 proxy_cookie_path /two/ /; 611 proxy_cookie_path /two/ /;
612 proxy_cookie_path ~*^/user/([^/]+) /u/$1; 612 proxy_cookie_path ~*^/user/([^/]+) /u/$1;
625 625
626 <para> 626 <para>
627 Sets the bucket <value>size</value> for hash tables 627 Sets the bucket <value>size</value> for hash tables
628 used by the <link id="proxy_hide_header"/> and <link id="proxy_set_header"/> 628 used by the <link id="proxy_hide_header"/> and <link id="proxy_set_header"/>
629 directives. 629 directives.
630 Details of setting up hash tables are provided in a separate 630 The details of setting up hash tables are provided in a separate
631 <link doc="../hash.xml">document</link>. 631 <link doc="../hash.xml">document</link>.
632 </para> 632 </para>
633 633
634 </directive> 634 </directive>
635 635
643 643
644 <para> 644 <para>
645 Sets the maximum <value>size</value> of hash tables 645 Sets the maximum <value>size</value> of hash tables
646 used by the <link id="proxy_hide_header"/> and <link id="proxy_set_header"/> 646 used by the <link id="proxy_hide_header"/> and <link id="proxy_set_header"/>
647 directives. 647 directives.
648 Details of setting up hash tables are provided in a separate 648 The details of setting up hash tables are provided in a separate
649 <link doc="../hash.xml">document</link>. 649 <link doc="../hash.xml">document</link>.
650 </para> 650 </para>
651 651
652 </directive> 652 </directive>
653 653
699 <context>http</context> 699 <context>http</context>
700 <context>server</context> 700 <context>server</context>
701 <context>location</context> 701 <context>location</context>
702 702
703 <para> 703 <para>
704 Determines should the connection with a proxied server be 704 Determines whether the connection with a proxied server should be
705 closed if a client closes a connection without waiting 705 closed when a client closes a connection without waiting
706 for a response. 706 for a response.
707 </para> 707 </para>
708 708
709 </directive> 709 </directive>
710 710
724 <header>X-Accel-Charset</header> (1.1.6), <header>Expires</header>, 724 <header>X-Accel-Charset</header> (1.1.6), <header>Expires</header>,
725 <header>Cache-Control</header>, and <header>Set-Cookie</header> (0.8.44). 725 <header>Cache-Control</header>, and <header>Set-Cookie</header> (0.8.44).
726 </para> 726 </para>
727 727
728 <para> 728 <para>
729 If not disabled, processing of these header fields has the following effect: 729 If not disabled, processing of these header fields has the following
730 effect:
730 <list type="bullet" compact="no"> 731 <list type="bullet" compact="no">
731 732
732 <listitem> 733 <listitem>
733 <header>X-Accel-Expires</header>, <header>Expires</header>, 734 <header>X-Accel-Expires</header>, <header>Expires</header>,
734 <header>Cache-Control</header>, and <header>Set-Cookie</header> 735 <header>Cache-Control</header>, and <header>Set-Cookie</header>
735 set parameters of response <link id="proxy_cache_valid">caching</link>; 736 set the parameters of response <link id="proxy_cache_valid">caching</link>;
736 </listitem> 737 </listitem>
737 738
738 <listitem> 739 <listitem>
739 <header>X-Accel-Redirect</header> performs an 740 <header>X-Accel-Redirect</header> performs an
740 <link doc="ngx_http_core_module.xml" id="internal">internal 741 <link doc="ngx_http_core_module.xml" id="internal">internal
741 redirect</link> to the specified URI; 742 redirect</link> to the specified URI;
742 </listitem> 743 </listitem>
743 744
744 <listitem> 745 <listitem>
745 <header>X-Accel-Limit-Rate</header> sets a 746 <header>X-Accel-Limit-Rate</header> sets the
746 <link doc="ngx_http_core_module.xml" id="limit_rate">rate 747 <link doc="ngx_http_core_module.xml" id="limit_rate">rate
747 limit</link> for transmission of a response to a client; 748 limit</link> for transmission of a response to a client;
748 </listitem> 749 </listitem>
749 750
750 <listitem> 751 <listitem>
772 <context>location</context> 773 <context>location</context>
773 774
774 <para> 775 <para>
775 Determines whether proxied responses with codes greater than or equal 776 Determines whether proxied responses with codes greater than or equal
776 to 300 should be passed to a client or be redirected to nginx for processing 777 to 300 should be passed to a client or be redirected to nginx for processing
777 using the <link doc="ngx_http_core_module.xml" id="error_page"/> directive. 778 by the <link doc="ngx_http_core_module.xml" id="error_page"/> directive.
778 </para> 779 </para>
779 780
780 </directive> 781 </directive>
781 782
782 783
787 <context>server</context> 788 <context>server</context>
788 <context>location</context> 789 <context>location</context>
789 790
790 <para> 791 <para>
791 When <link id="proxy_buffering">buffering</link> of responses from the proxied 792 When <link id="proxy_buffering">buffering</link> of responses from the proxied
792 server is enabled, and the whole response does not fit into memory buffers 793 server is enabled, and the whole response does not fit into the memory buffers
793 set by the <link id="proxy_buffer_size"/> and <link id="proxy_buffers"/> 794 set by the <link id="proxy_buffer_size"/> and <link id="proxy_buffers"/>
794 directives, part of a response can be saved to a temporary file. 795 directives, a part of a response can be saved to a temporary file.
795 This directive sets the maximum <value>size</value> of a temporary file. 796 This directive sets the maximum <value>size</value> of a temporary file.
796 The size of data written to a temporary file at a time is set 797 The size of data written to a temporary file at a time is set
797 by the <link id="proxy_temp_file_write_size"/> directive. 798 by the <link id="proxy_temp_file_write_size"/> directive.
798 </para> 799 </para>
799 800
800 <para> 801 <para>
801 Value of zero disables buffering of responses to temporary files. 802 The zero value disables buffering of responses to temporary files.
802 </para> 803 </para>
803 804
804 </directive> 805 </directive>
805 806
806 807
841 Specifies in which cases a request should be passed to the next server: 842 Specifies in which cases a request should be passed to the next server:
842 <list type="tag"> 843 <list type="tag">
843 844
844 <tag-name><literal>error</literal></tag-name> 845 <tag-name><literal>error</literal></tag-name>
845 <tag-desc>an error occurred while establishing a connection with the 846 <tag-desc>an error occurred while establishing a connection with the
846 server, passing it a request, or reading the response header;</tag-desc> 847 server, passing a request to it, or reading the response header;</tag-desc>
847 848
848 <tag-name><literal>timeout</literal></tag-name> 849 <tag-name><literal>timeout</literal></tag-name>
849 <tag-desc>a timeout has occurred while establishing a connection with the 850 <tag-desc>a timeout has occurred while establishing a connection with the
850 server, passing it a request, or reading the response header;</tag-desc> 851 server, passing a request to it, or reading the response header;</tag-desc>
851 852
852 <tag-name><literal>invalid_header</literal></tag-name> 853 <tag-name><literal>invalid_header</literal></tag-name>
853 <tag-desc>a server returned empty or invalid response;</tag-desc> 854 <tag-desc>a server returned an empty or invalid response;</tag-desc>
854 855
855 <tag-name><literal>http_500</literal></tag-name> 856 <tag-name><literal>http_500</literal></tag-name>
856 <tag-desc>a server returned a response with the code 500;</tag-desc> 857 <tag-desc>a server returned a response with the code 500;</tag-desc>
857 858
858 <tag-name><literal>http_502</literal></tag-name> 859 <tag-name><literal>http_502</literal></tag-name>
875 876
876 </list> 877 </list>
877 </para> 878 </para>
878 879
879 <para> 880 <para>
880 It should be understood that passing a request to the next server is 881 One should bear in mind that passing a request to the next server is
881 only possible if a client was not sent anything yet. 882 only possible if nothing has been sent to a client yet.
882 That is, if an error or a timeout occurs in the middle of 883 That is, if an error or timeout occurs in the middle of the
883 transferring a response, fixing this is impossible. 884 transferring of a response, fixing this is impossible.
884 </para> 885 </para>
885 886
886 <para> 887 <para>
887 The directive also defines what is considered an unsuccessful attempt 888 The directive also defines what is considered an unsuccessful attempt
888 of communication with a 889 of communication with a
927 <context>location</context> 928 <context>location</context>
928 <context>if in location</context> 929 <context>if in location</context>
929 <context>limit_except</context> 930 <context>limit_except</context>
930 931
931 <para> 932 <para>
932 Sets the protocol and address of a proxied server, and an optional URI 933 Sets the protocol and address of a proxied server and an optional URI
933 to which a location should be mapped. 934 to which a location should be mapped.
934 A protocol can be specified as 935 As a protocol, “<literal>http</literal>” or “<literal>https</literal>”
935 “<literal>http</literal>” or “<literal>https</literal>”. 936 can be specified.
936 An address can be specified as a domain name or IP address, 937 The address can be specified as a domain name or IP address,
937 and an optional port: 938 and an optional port:
938 <example> 939 <example>
939 proxy_pass http://localhost:8000/uri/; 940 proxy_pass http://localhost:8000/uri/;
940 </example> 941 </example>
941 or as a UNIX-domain socket path specified after the word 942 or as a UNIX-domain socket path specified after the word
955 <para> 956 <para>
956 A request URI is passed to the server as follows: 957 A request URI is passed to the server as follows:
957 <list type="bullet" compact="no"> 958 <list type="bullet" compact="no">
958 959
959 <listitem> 960 <listitem>
960 If <literal>proxy_pass</literal> is specified with URI, 961 If the <literal>proxy_pass</literal> directive is specified with a URI,
961 when passing a request to the server, part of a 962 then when a request is passed to the server, the part of a
962 <link doc="ngx_http_core_module.xml" id="location">normalized</link> 963 <link doc="ngx_http_core_module.xml" id="location">normalized</link>
963 request URI matching the location is replaced by a URI 964 request URI matching the location is replaced by a URI
964 specified in the directive: 965 specified in the directive:
965 <example> 966 <example>
966 location /name/ { 967 location /name/ {
968 } 969 }
969 </example> 970 </example>
970 </listitem> 971 </listitem>
971 972
972 <listitem> 973 <listitem>
973 If <literal>proxy_pass</literal> is specified without URI, 974 If <literal>proxy_pass</literal> is specified without a URI,
974 a request URI is passed to the server in the same form 975 the request URI is passed to the server in the same form
975 as sent by a client when processing an original request, 976 as sent by a client when the original request is processed,
976 or the full normalized request URI is passed 977 or the full normalized request URI is passed
977 when processing the changed URI: 978 when processing the changed URI:
978 <example> 979 <example>
979 location /some/path/ { 980 location /some/path/ {
980 proxy_pass http://127.0.0.1; 981 proxy_pass http://127.0.0.1;
981 } 982 }
982 </example> 983 </example>
983 <note> 984 <note>
984 Before version 1.1.12, 985 Before version 1.1.12,
985 if <literal>proxy_pass</literal> is specified without a URI, 986 if <literal>proxy_pass</literal> is specified without a URI,
986 an original request URI might be passed 987 the original request URI might be passed
987 instead of the changed URI in some cases. 988 instead of the changed URI in some cases.
988 </note> 989 </note>
989 </listitem> 990 </listitem>
990 </list> 991 </list>
991 </para> 992 </para>
992 993
993 <para> 994 <para>
994 In some cases, part of a request URI to be replaced cannot be determined: 995 In some cases, the part of a request URI to be replaced cannot be determined:
995 <list type="bullet" compact="no"> 996 <list type="bullet" compact="no">
996 997
997 <listitem> 998 <listitem>
998 When location is specified using a regular expression. 999 When location is specified using a regular expression.
999 <para> 1000 <para>
1000 In this case, the directive should be specified without URI. 1001 In this case, the directive should be specified without a URI.
1001 </para> 1002 </para>
1002 </listitem> 1003 </listitem>
1003 1004
1004 <listitem> 1005 <listitem>
1005 When URI is changed inside a proxied location using the 1006 When the URI is changed inside a proxied location using the
1006 <link doc="ngx_http_rewrite_module.xml" id="rewrite"/> directive, 1007 <link doc="ngx_http_rewrite_module.xml" id="rewrite"/> directive,
1007 and this same configuration will be used to process a request 1008 and this same configuration will be used to process a request
1008 (<literal>break</literal>): 1009 (<literal>break</literal>):
1009 <example> 1010 <example>
1010 location /name/ { 1011 location /name/ {
1011 rewrite /name/([^/]+) /users?name=$1 break; 1012 rewrite /name/([^/]+) /users?name=$1 break;
1012 proxy_pass http://127.0.0.1; 1013 proxy_pass http://127.0.0.1;
1013 } 1014 }
1014 </example> 1015 </example>
1015 <para> 1016 <para>
1016 In this case, a URI specified in the directive is ignored and 1017 In this case, the URI specified in the directive is ignored and
1017 the full changed request URI is passed to the server. 1018 the full changed request URI is passed to the server.
1018 </para> 1019 </para>
1019 </listitem> 1020 </listitem>
1020 </list> 1021 </list>
1021 </para> 1022 </para>
1022 1023
1023 <para> 1024 <para>
1024 A server name, its port and passed URI can also be specified using variables: 1025 A server name, its port and the passed URI can also be specified using
1026 variables:
1025 <example> 1027 <example>
1026 proxy_pass http://$host$uri; 1028 proxy_pass http://$host$uri;
1027 </example> 1029 </example>
1028 or even like this: 1030 or even like this:
1029 <example> 1031 <example>
1030 proxy_pass $request; 1032 proxy_pass $request;
1031 </example> 1033 </example>
1032 </para> 1034 </para>
1033 1035
1034 <para> 1036 <para>
1035 In this case the server name is searched among the described 1037 In this case, the server name is searched among the described
1036 <link doc="ngx_http_upstream_module.xml">server groups</link>, 1038 <link doc="ngx_http_upstream_module.xml">server groups</link>,
1037 and if not found is determined using a 1039 and, if not found, is determined using a
1038 <link doc="ngx_http_core_module.xml" id="resolver"/>. 1040 <link doc="ngx_http_core_module.xml" id="resolver"/>.
1039 </para> 1041 </para>
1040 1042
1041 <para> 1043 <para>
1042 <link doc="websocket.xml">WebSocket</link> proxying requires special 1044 <link doc="websocket.xml">WebSocket</link> proxying requires special
1052 <context>http</context> 1054 <context>http</context>
1053 <context>server</context> 1055 <context>server</context>
1054 <context>location</context> 1056 <context>location</context>
1055 1057
1056 <para> 1058 <para>
1057 Permits to pass <link id="proxy_hide_header">otherwise disabled</link> header 1059 Permits passing <link id="proxy_hide_header">otherwise disabled</link> header
1058 fields from a proxied server to a client. 1060 fields from a proxied server to a client.
1059 </para> 1061 </para>
1060 1062
1061 </directive> 1063 </directive>
1062 1064
1085 <context>http</context> 1087 <context>http</context>
1086 <context>server</context> 1088 <context>server</context>
1087 <context>location</context> 1089 <context>location</context>
1088 1090
1089 <para> 1091 <para>
1090 If disabled, the original request body will not be passed 1092 Allows disabling a passing of the original request body
1091 to the proxied server. 1093 to the proxied server.
1092 <example> 1094 <example>
1093 location /x-accel-redirect-here/ { 1095 location /x-accel-redirect-here/ {
1094 proxy_method GET; 1096 proxy_method GET;
1095 proxy_pass_request_body off; 1097 proxy_pass_request_body off;
1111 <context>http</context> 1113 <context>http</context>
1112 <context>server</context> 1114 <context>server</context>
1113 <context>location</context> 1115 <context>location</context>
1114 1116
1115 <para> 1117 <para>
1116 If disabled, header fields of the original request will not be passed to the 1118 Allows disabling a passing of the header fields of the original request
1117 proxied server. 1119 to the proxied server.
1118 <example> 1120 <example>
1119 location /x-accel-redirect-here/ { 1121 location /x-accel-redirect-here/ {
1120 proxy_method GET; 1122 proxy_method GET;
1121 proxy_pass_request_headers off; 1123 proxy_pass_request_headers off;
1122 proxy_pass_request_body off; 1124 proxy_pass_request_body off;
1139 <context>http</context> 1141 <context>http</context>
1140 <context>server</context> 1142 <context>server</context>
1141 <context>location</context> 1143 <context>location</context>
1142 1144
1143 <para> 1145 <para>
1144 Sets a text that should be changed in the header fields 1146 Sets the text that should be changed in the <header>Location</header>
1145 <header>Location</header> and <header>Refresh</header> of a response 1147 and <header>Refresh</header> header fields of a proxied server response.
1146 from the proxied server.
1147 Suppose a proxied server returned the header field 1148 Suppose a proxied server returned the header field
1148 “<literal>Location: http://localhost:8000/two/some/uri/</literal>”. 1149 “<literal>Location: http://localhost:8000/two/some/uri/</literal>”.
1149 The directive 1150 The directive
1150 <example> 1151 <example>
1151 proxy_redirect http://localhost:8000/two/ http://frontend/one/; 1152 proxy_redirect http://localhost:8000/two/ http://frontend/one/;
1153 will rewrite this string to 1154 will rewrite this string to
1154 “<literal>Location: http://frontend/one/some/uri/</literal>”. 1155 “<literal>Location: http://frontend/one/some/uri/</literal>”.
1155 </para> 1156 </para>
1156 1157
1157 <para> 1158 <para>
1158 A server name may be omitted from the <value>replacement</value> string: 1159 A server name may be omitted in the <value>replacement</value> string:
1159 <example> 1160 <example>
1160 proxy_redirect http://localhost:8000/two/ /; 1161 proxy_redirect http://localhost:8000/two/ /;
1161 </example> 1162 </example>
1162 then the primary server’s name and a port, if different from 80, 1163 then the primary server’s name and port, if different from 80,
1163 will be substituted. 1164 will be inserted.
1164 </para> 1165 </para>
1165 1166
1166 <para> 1167 <para>
1167 The default replacement specified by the <literal>default</literal> parameter 1168 The default replacement specified by the <literal>default</literal> parameter
1168 uses the parameters of the 1169 uses the parameters of the
1197 proxy_redirect http://$proxy_host:8000/ /; 1198 proxy_redirect http://$proxy_host:8000/ /;
1198 </example> 1199 </example>
1199 </para> 1200 </para>
1200 1201
1201 <para> 1202 <para>
1202 A directive can be specified (1.1.11) using regular expressions. 1203 The directive can be specified (1.1.11) using regular expressions.
1203 In this case, <value>redirect</value> should either start from 1204 In this case, <value>redirect</value> should either start with
1204 the “<literal>~</literal>” symbol for a case-sensitive matching, 1205 the “<literal>~</literal>” symbol for a case-sensitive matching,
1205 or from the “<literal>~*</literal>” symbols for case-insensitive 1206 or with the “<literal>~*</literal>” symbols for case-insensitive
1206 matching. 1207 matching.
1207 A regular expression can contain named and positional captures, 1208 A regular expression can contain named and positional captures,
1208 and <value>replacement</value> can reference them: 1209 and <value>replacement</value> can reference them:
1209 <example> 1210 <example>
1210 proxy_redirect ~^(http://[^:]+):\d+(/.+)$ $1$2; 1211 proxy_redirect ~^(http://[^:]+):\d+(/.+)$ $1$2;
1220 proxy_redirect http://www.example.com/ /; 1221 proxy_redirect http://www.example.com/ /;
1221 </example> 1222 </example>
1222 </para> 1223 </para>
1223 1224
1224 <para> 1225 <para>
1225 The <literal>off</literal> parameter cancels all 1226 The <literal>off</literal> parameter cancels the effect of all
1226 <literal>proxy_redirect</literal> directives on the current level: 1227 <literal>proxy_redirect</literal> directives on the current level:
1227 <example> 1228 <example>
1228 proxy_redirect off; 1229 proxy_redirect off;
1229 proxy_redirect default; 1230 proxy_redirect default;
1230 proxy_redirect http://localhost:8000/ /; 1231 proxy_redirect http://localhost:8000/ /;
1231 proxy_redirect http://www.example.com/ /; 1232 proxy_redirect http://www.example.com/ /;
1232 </example> 1233 </example>
1233 </para> 1234 </para>
1234 1235
1235 <para> 1236 <para>
1236 Using this directive it is also possible to add host names to relative 1237 Using this directive, it is also possible to add host names to relative
1237 redirects issued by a proxied server: 1238 redirects issued by a proxied server:
1238 <example> 1239 <example>
1239 proxy_redirect / /; 1240 proxy_redirect / /;
1240 </example> 1241 </example>
1241 </para> 1242 </para>
1249 <context>http</context> 1250 <context>http</context>
1250 <context>server</context> 1251 <context>server</context>
1251 <context>location</context> 1252 <context>location</context>
1252 1253
1253 <para> 1254 <para>
1254 If set to a non-zero value, nginx will try to minimize the number 1255 If the directive is set to a non-zero value, nginx will try to
1256 minimize the number
1255 of send operations on outgoing connections to a proxied server by using either 1257 of send operations on outgoing connections to a proxied server by using either
1256 <c-def>NOTE_LOWAT</c-def> flag of the 1258 <c-def>NOTE_LOWAT</c-def> flag of the
1257 <link doc="../events.xml" id="kqueue"/> method, 1259 <link doc="../events.xml" id="kqueue"/> method,
1258 or the <c-def>SO_SNDLOWAT</c-def> socket option, 1260 or the <c-def>SO_SNDLOWAT</c-def> socket option,
1259 with the specified <value>size</value>. 1261 with the specified <value>size</value>.
1290 <context>http</context> 1292 <context>http</context>
1291 <context>server</context> 1293 <context>server</context>
1292 <context>location</context> 1294 <context>location</context>
1293 1295
1294 <para> 1296 <para>
1295 Allows to redefine request body passed to the proxied server. 1297 Allows redefining the request body passed to the proxied server.
1296 A <value>value</value> can contain text, variables, and their combination. 1298 A <value>value</value> can contain text, variables, and their combination.
1297 </para> 1299 </para>
1298 1300
1299 </directive> 1301 </directive>
1300 1302
1306 <context>http</context> 1308 <context>http</context>
1307 <context>server</context> 1309 <context>server</context>
1308 <context>location</context> 1310 <context>location</context>
1309 1311
1310 <para> 1312 <para>
1311 Allows to redefine or append fields to the request header 1313 Allows redefining or appending fields to the request header
1312 <link id="proxy_pass_request_headers">passed</link> to the proxied server. 1314 <link id="proxy_pass_request_headers">passed</link> to the proxied server.
1313 A <value>value</value> can contain text, variables, and their combination. 1315 A <value>value</value> can contain text, variables, and their combinations.
1314 These directives are inherited from the previous level if and 1316 These directives are inherited from the previous level if and
1315 only if there are no 1317 only if there are no
1316 <literal>proxy_set_header</literal> 1318 <literal>proxy_set_header</literal>
1317 directives defined on the current level. 1319 directives defined on the current level.
1318 By default, only two fields are redefined: 1320 By default, only two fields are redefined:
1332 <para> 1334 <para>
1333 However, if this field is not present in a client request header then 1335 However, if this field is not present in a client request header then
1334 nothing will be passed. 1336 nothing will be passed.
1335 In such a case it is better to use the <var>$host</var> variable&mdash;its 1337 In such a case it is better to use the <var>$host</var> variable&mdash;its
1336 value equals the server name in the <header>Host</header> request header 1338 value equals the server name in the <header>Host</header> request header
1337 field, or the primary server name if this field is not present: 1339 field or the primary server name if this field is not present:
1338 <example> 1340 <example>
1339 proxy_set_header Host $host; 1341 proxy_set_header Host $host;
1340 </example> 1342 </example>
1341 </para> 1343 </para>
1342 1344
1343 <para> 1345 <para>
1344 In addition, a server name can be passed together with a port of the 1346 In addition, the server name can be passed together with the port of the
1345 proxied server: 1347 proxied server:
1346 <example> 1348 <example>
1347 proxy_set_header Host $host:$proxy_port; 1349 proxy_set_header Host $host:$proxy_port;
1348 </example> 1350 </example>
1349 </para> 1351 </para>
1369 <para> 1371 <para>
1370 Determines whether SSL sessions can be reused when working with 1372 Determines whether SSL sessions can be reused when working with
1371 the proxied server. 1373 the proxied server.
1372 If the errors 1374 If the errors
1373 “<literal>SSL3_GET_FINISHED:digest check failed</literal>” 1375 “<literal>SSL3_GET_FINISHED:digest check failed</literal>”
1374 appear in the logs, try to disable session reuse. 1376 appear in the logs, try disabling session reuse.
1375 </para> 1377 </para>
1376 1378
1377 </directive> 1379 </directive>
1378 1380
1379 1381
1403 1405
1404 <para> 1406 <para>
1405 The modification time of files is set according to the received 1407 The modification time of files is set according to the received
1406 <header>Last-Modified</header> response header field. 1408 <header>Last-Modified</header> response header field.
1407 A response is first written to a temporary file, then a file is renamed. 1409 A response is first written to a temporary file, then a file is renamed.
1408 Starting from version 0.8.9 temporary files and the persistent store 1410 Starting from version 0.8.9, temporary files and the persistent store
1409 can be put on different file systems but be aware that in this case 1411 can be put on different file systems, but be aware that in this case
1410 a file is copied across two file systems instead of the cheap rename operation. 1412 a file is copied across two file systems instead of the cheap renaming
1413 operation.
1411 It is thus recommended that for any given location both saved files and a 1414 It is thus recommended that for any given location both saved files and a
1412 directory holding temporary files set by the <link id="proxy_temp_path"/> 1415 directory holding temporary files set by the <link id="proxy_temp_path"/>
1413 directive are put on the same file system. 1416 directive are put on the same file system.
1414 </para> 1417 </para>
1415 1418