Mercurial > hg > nginx-site
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—its | 1337 In such a case it is better to use the <var>$host</var> variable—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 |