Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_proxy_module.xml @ 281:7142ddd2764c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Translated current version of ngx_http_proxy_module documentation into English.
author Ruslan Ermilov <ru@nginx.com>
date Tue, 27 Dec 2011 11:35:46 +0000
parents
children 9f5ee1c6fca5
comparison
equal deleted inserted replaced
280:cbb789d3ce5e 281:7142ddd2764c
1 <?xml version="1.0"?>
2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4
5 <module name="Module ngx_http_proxy_module"
6 link="/en/docs/http/ngx_http_proxy_module.html"
7 lang="en">
8
9 <section id="summary">
10
11 <para>
12 The <literal>ngx_http_proxy_module</literal> module allows to pass
13 requests to another server.
14 </para>
15
16 </section>
17
18
19 <section id="example" name="Example Configuration">
20
21 <para>
22 <example>
23 location / {
24 proxy_pass http://localhost:8000;
25 proxy_set_header Host $host;
26 proxy_set_header X-Real-IP $remote_addr;
27 }
28 </example>
29 </para>
30
31 </section>
32
33
34 <section id="directives" name="Directives">
35
36 <directive name="proxy_buffer_size">
37 <syntax><value>size</value></syntax>
38 <default>4k|8k</default>
39 <context>http</context>
40 <context>server</context>
41 <context>location</context>
42
43 <para>
44 Sets <value>size</value> of the buffer used for reading the first part
45 of a response received from the proxied server.
46 This part usually contains a small response header.
47 By default, the buffer size is equal to the size of one
48 buffer set by the <link id="proxy_buffers"/> directive.
49 It can be made smaller however.
50 </para>
51
52 </directive>
53
54
55 <directive name="proxy_buffering">
56 <syntax><literal>on</literal> | <literal>off</literal></syntax>
57 <default>on</default>
58 <context>http</context>
59 <context>server</context>
60 <context>location</context>
61
62 <para>
63 Enables or disables buffering a response from the proxied server.
64 </para>
65
66 <para>
67 When buffering is enabled, nginx receives a response from the proxied server
68 as soon as possible, saving it into buffers set by the
69 <link id="proxy_buffer_size"/> and <link id="proxy_buffers"/> directives.
70 If the whole response does not fit into memory, part of it is saved to a disk.
71 </para>
72
73 <para>
74 When buffering is disabled, a response is passed to a client synchronously,
75 immediately upon receipt.
76 nginx will not try to read the whole response from the proxied server.
77 The maximum size of the data that nginx can receive from the server
78 at a time is set by the <link id="proxy_buffer_size"/> directive.
79 </para>
80
81 </directive>
82
83
84 <directive name="proxy_buffers">
85 <syntax><value>number</value> <value>size</value></syntax>
86 <default>8 4k|8k</default>
87 <context>http</context>
88 <context>server</context>
89 <context>location</context>
90
91 <para>
92 Sets the <value>number</value> and <value>size</value> of
93 buffers used for reading a response from the proxied server,
94 for a single connection.
95 By default, the buffer size is equal to one memory page.
96 This is either 4K or 8K, depending on a platform.
97 </para>
98
99 </directive>
100
101
102 <directive name="proxy_cache">
103 <syntax><value>zone</value> | <literal>off</literal></syntax>
104 <default>off</default>
105 <context>http</context>
106 <context>server</context>
107 <context>location</context>
108
109 <para>
110 Defines a zone used for caching.
111 The same zone can be used in several places.
112 The <literal>off</literal> parameter disables caching inherited
113 from the previous configuration level.
114 </para>
115
116 </directive>
117
118
119 <directive name="proxy_cache_bypass">
120 <syntax><value>string</value> ...</syntax>
121 <default/>
122 <context>http</context>
123 <context>server</context>
124 <context>location</context>
125
126 <para>
127 Defines conditions under which the answer will not be taken from a cache.
128 If at least one value of the string parameters is not empty and is not
129 equal to “0” then the answer will not be taken from the cache:
130 <example>
131 proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
132 proxy_cache_bypass $http_pragma $http_authorization;
133 </example>
134 Can be used along with the <link id="proxy_no_cache"/> directive.
135 </para>
136
137 </directive>
138
139
140 <directive name="proxy_cache_key">
141 <syntax><value>string</value></syntax>
142 <default>$scheme$proxy_host$request_uri</default>
143 <context>http</context>
144 <context>server</context>
145 <context>location</context>
146
147 <para>
148 Defines a key for caching, for example
149 <example>
150 proxy_cache_key "$host$request_uri $cookie_user";
151 </example>
152 By default, the directive’s value is close to the string
153 <example>
154 proxy_cache_key $scheme$proxy_host$uri$is_args$args;
155 </example>
156 </para>
157
158 </directive>
159
160
161 <directive name="proxy_cache_min_uses">
162 <syntax><value>number</value></syntax>
163 <default>1</default>
164 <context>http</context>
165 <context>server</context>
166 <context>location</context>
167
168 <para>
169 Sets the <value>number</value> of requests after which the response
170 will be cached.
171 </para>
172
173 </directive>
174
175
176 <directive name="proxy_cache_path">
177 <syntax>
178 <value>path</value>
179 [<literal>levels</literal>=<value>levels</value>]
180 <literal>keys_zone</literal>=<value>name</value>:<value>size</value>
181 [<literal>inactive</literal>=<value>time</value>]
182 [<literal>max_size</literal>=<value>size</value>]</syntax>
183 <default/>
184 <context>http</context>
185
186 <para>
187 Sets path and other parameters of a cache.
188 Cache data are stored in files.
189 Both the key and file name in a cache are a result of
190 applying the MD5 function to the proxied URL.
191
192 The <literal>levels</literal> parameter defines hierarchy levels of a cache.
193 For example, in the following configuration
194 <example>
195 proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;
196 </example>
197 file names in a cache will look like this:
198 <example>
199 /data/nginx/cache/<emphasis>c</emphasis>/<emphasis>29</emphasis>/b7f54b2df7773722d382f4809d650<emphasis>29c</emphasis>
200 </example>
201 </para>
202
203 <para>
204 A cached response is first written to a temporary file, then a file is renamed.
205 Starting from version 0.8.9 temporary files and the cache can be put on
206 different file systems but be aware that in this case a file is copied
207 across two file systems instead of the cheap rename operation.
208 It is thus recommended that for any given location both cache and a directory
209 holding temporary files set by the <link id="proxy_temp_path"/> directive
210 are put on the same file system.
211 </para>
212
213 <para>
214 In addition, all active keys and information about data are stored
215 in a shared memory zone, whose <value>name</value> and <value>size</value>
216 are configured by the <literal>keys_zone</literal> parameter.
217 Cached data that are not accessed during the time specified by the
218 <literal>inactive</literal> parameter get removed from the cache
219 regardless of their freshness.
220 By default, <literal>inactive</literal> is set to 10 minutes.
221 </para>
222
223 <para>
224 The special process “cache manager” monitors the maximum cache size set
225 by the <literal>max_size</literal> parameter;
226 when this size is exceeded it removes the least recently used data.
227 </para>
228
229 </directive>
230
231
232 <directive name="proxy_cache_use_stale">
233 <syntax>
234 <literal>error</literal> |
235 <literal>timeout</literal> |
236 <literal>invalid_header</literal> |
237 <literal>updating</literal> |
238 <literal>http_500</literal> |
239 <literal>http_502</literal> |
240 <literal>http_503</literal> |
241 <literal>http_504</literal> |
242 <literal>http_404</literal> |
243 <literal>off</literal>
244 ...</syntax>
245 <default>off</default>
246 <context>http</context>
247 <context>server</context>
248 <context>location</context>
249
250 <para>
251 If an error occurs while working with the proxied server it is possible
252 to use a stale cached response.
253 This directives determines in which cases it is permitted.
254 The directive’s parameters match those of the
255 <link id="proxy_next_upstream"/> directive.
256 Additionally, the <literal>updating</literal> parameter permits
257 to use a stale cached response if it is currently being updated.
258 </para>
259
260 </directive>
261
262
263 <directive name="proxy_cache_valid">
264 <syntax>[<value>code</value> ...] <value>time</value></syntax>
265 <default/>
266 <context>http</context>
267 <context>server</context>
268 <context>location</context>
269
270 <para>
271 Sets caching time for different response codes.
272 For example, the following directives
273 <example>
274 proxy_cache_valid 200 302 10m;
275 proxy_cache_valid 404 1m;
276 </example>
277 set 10 minutes of caching for responses with codes 200 and 302,
278 and 1 minute for responses with code 404.
279 </para>
280
281 <para>
282 If only caching <value>time</value> is specified
283 <example>
284 proxy_cache_valid 5m;
285 </example>
286 then only 200, 301, and 302 responses are cached.
287 </para>
288
289 <para>
290 In addition, it can be specified to cache any answers using the
291 <literal>any</literal> parameter:
292 <example>
293 proxy_cache_valid 200 302 10m;
294 proxy_cache_valid 301 1h;
295 proxy_cache_valid any 1m;
296 </example>
297 </para>
298
299 </directive>
300
301
302 <directive name="proxy_connect_timeout">
303 <syntax><value>time</value></syntax>
304 <default>60s</default>
305 <context>http</context>
306 <context>server</context>
307 <context>location</context>
308
309 <para>
310 Defines a timeout for establishing a connection with the proxied server.
311 It should be noted that this timeout cannot usually exceed 75 seconds.
312 </para>
313
314 </directive>
315
316
317 <directive name="proxy_hide_header">
318 <syntax><value>field</value></syntax>
319 <default/>
320 <context>http</context>
321 <context>server</context>
322 <context>location</context>
323
324 <para>
325 By default,
326 nginx does not pass the header fields <header>Date</header>,
327 <header>Server</header>, <header>X-Pad</header>, and
328 <header>X-Accel-...</header> from the response of a proxied
329 server to a client.
330 The <literal>proxy_hide_header</literal> directive sets additional fields
331 that will not be passed.
332 If, on the contrary, the passing of fields needs to be enabled,
333 the <link id="proxy_pass_header"/> directive can be used.
334 </para>
335
336 </directive>
337
338
339 <directive name="proxy_ignore_client_abort">
340 <syntax><literal>on</literal> | <literal>off</literal></syntax>
341 <default>off</default>
342 <context>http</context>
343 <context>server</context>
344 <context>location</context>
345
346 <para>
347 Determines should the connection with a proxied server be
348 closed if a client closes a connection without waiting
349 for an answer.
350 </para>
351
352 </directive>
353
354
355 <directive name="proxy_ignore_headers">
356 <syntax><value>field</value> ...</syntax>
357 <default/>
358 <context>http</context>
359 <context>server</context>
360 <context>location</context>
361
362 <para>
363 Disables processing of some response header fields from the proxied server.
364 The following fields can be ignored: <header>X-Accel-Redirect</header>,
365 <header>X-Accel-Expires</header>, <header>X-Accel-Limit-Rate</header> (1.1.6),
366 <header>X-Accel-Buffering</header> (1.1.6),
367 <header>X-Accel-Charset</header> (1.1.6), <header>Expires</header>,
368 <header>Cache-Control</header>, and <header>Set-Cookie</header> (0.8.44).
369 </para>
370
371 </directive>
372
373
374 <directive name="proxy_intercept_errors">
375 <syntax><literal>on</literal> | <literal>off</literal></syntax>
376 <default>off</default>
377 <context>http</context>
378 <context>server</context>
379 <context>location</context>
380
381 <para>
382 Determines whether proxied responses with codes greater or equal to 400
383 should be passed to a client or be redirected to nginx for processing
384 using the <link doc="ngx_http_core_module.xml" id="error_page"/> directive.
385 </para>
386
387 </directive>
388
389
390 <directive name="proxy_next_upstream">
391 <syntax>
392 <literal>error</literal> |
393 <literal>timeout</literal> |
394 <literal>invalid_header</literal> |
395 <literal>http_500</literal> |
396 <literal>http_502</literal> |
397 <literal>http_503</literal> |
398 <literal>http_504</literal> |
399 <literal>http_404</literal> |
400 <literal>off</literal>
401 ...</syntax>
402 <default>error timeout</default>
403 <context>http</context>
404 <context>server</context>
405 <context>location</context>
406
407 <para>
408 Specifies in which cases a request should be passed to the next server:
409 <list type="tag">
410
411 <tag-name><literal>error</literal></tag-name>
412 <tag-desc>an error occurred while establishing a connection with the
413 server, passing it a request, or reading the response header;</tag-desc>
414
415 <tag-name><literal>timeout</literal></tag-name>
416 <tag-desc>a timeout has occurred while establishing a connection with the
417 server, passing it a request, or reading the response header;</tag-desc>
418
419 <tag-name><literal>invalid_header</literal></tag-name>
420 <tag-desc>a server returned empty or invalid response;</tag-desc>
421
422 <tag-name><literal>http_500</literal></tag-name>
423 <tag-desc>a server returned a response with the code 500;</tag-desc>
424
425 <tag-name><literal>http_502</literal></tag-name>
426 <tag-desc>a server returned a response with the code 502;</tag-desc>
427
428 <tag-name><literal>http_503</literal></tag-name>
429 <tag-desc>a server returned a response with the code 503;</tag-desc>
430
431 <tag-name><literal>http_504</literal></tag-name>
432 <tag-desc>a server returned a response with the code 504;</tag-desc>
433
434 <tag-name><literal>http_404</literal></tag-name>
435 <tag-desc>a server returned a response with the code 404;</tag-desc>
436
437 <tag-name><literal>off</literal></tag-name>
438 <tag-desc>disables passing a request to the next server.</tag-desc>
439
440 </list>
441 </para>
442
443 <para>
444 It should be understood that passing a request to the next server is
445 only possible if a client was not sent anything yet.
446 That is, if an error or a timeout occurs in the middle of
447 transferring a response, fixing this is impossible.
448 </para>
449
450 </directive>
451
452
453 <directive name="proxy_no_cache">
454 <syntax><value>string</value> ...</syntax>
455 <default/>
456 <context>http</context>
457 <context>server</context>
458 <context>location</context>
459
460 <para>
461 Defines conditions under which the answer will not be saved to a cache.
462 If at least one value of the string parameters is not empty and is not
463 equal to “0” then the answer will not be saved:
464 <example>
465 proxy_no_cache $cookie_nocache $arg_nocache$arg_comment;
466 proxy_no_cache $http_pragma $http_authorization;
467 </example>
468 Can be used along with the <link id="proxy_cache_bypass"/> directive.
469 </para>
470
471 </directive>
472
473
474 <directive name="proxy_pass">
475 <syntax><value>URL</value></syntax>
476 <default/>
477 <context>location</context>
478 <context>if in location</context>
479 <context>limit_except</context>
480
481 <para>
482 Sets an address of the proxied server and a URI that maps a location.
483 An address can be specified as a domain name or an address, and a port,
484 for example,
485 <example>
486 proxy_pass http://localhost:8000/uri/;
487 </example>
488 or as a UNIX-domain socket path:
489 <example>
490 proxy_pass http://unix:/tmp/backend.socket:/uri/;
491 </example>
492 here a path is specified after the word “<literal>unix</literal>”
493 and enclosed in two colons.
494 </para>
495
496 <para>
497 If a domain name maps to several addresses, all of them will be
498 used in a round-robin fashion.
499 In addition, an address can be specified as a
500 <link doc="ngx_http_upstream_module.xml">server group</link>.
501 </para>
502
503 <para>
504 When passing a request to the server, part of a URI matching the location
505 is replaced by a URI specified in the <literal>proxy_pass</literal> directive.
506 This rule has two exceptions where a replacement location cannot be
507 defined:
508 <list type="bullet">
509
510 <listitem>
511 when a location is specified using a regular expression;
512 </listitem>
513
514 <listitem>
515 if a URI is changed using the
516 <link doc="ngx_http_rewrite_module.xml" id="rewrite"/> directive
517 inside a proxied location, and this same configuration will be
518 used to process a request (<literal>break</literal>):
519 <example>
520 location /name/ {
521 rewrite /name/([^/]+) /users?name=$1 break;
522 proxy_pass http://127.0.0.1;
523 }
524 </example>
525 In these cases a URI is passed without mapping.
526 </listitem>
527
528 </list>
529 </para>
530
531 <para>
532 It can also be specified that a request URI should be passed unchanged,
533 in the same form it was sent by the client, not the processed form.
534 During a processing
535 <list type="bullet">
536
537 <listitem>
538 two or more adjacent slashes are replaced by one: “//” — “/”;
539 </listitem>
540
541 <listitem>
542 links to the current directory get removed: “/./” — “/”;
543 </listitem>
544
545 <listitem>
546 links to the parent directory get removed: “/dir/../” — “/”.
547 </listitem>
548
549 </list>
550 </para>
551
552 <para>
553 If a URI should be passed unchanged then the server URL should be specified
554 without a URI in the <literal>proxy_pass</literal> directive:
555 <example>
556 location /some/path/ {
557 proxy_pass http://127.0.0.1;
558 }
559 </example>
560 </para>
561
562 <para>
563 Server name, its port, and passed URI can be specified using variables:
564 <example>
565 proxy_pass http://$host$uri;
566 </example>
567 or like this:
568 <example>
569 proxy_pass $request;
570 </example>
571 </para>
572
573 <para>
574 In this case the server name is searched among the described
575 <link doc="ngx_http_upstream_module.xml">server groups</link>,
576 and if not found is determined using a
577 <link doc="ngx_http_core_module.xml" id="resolver"/>.
578 </para>
579
580 </directive>
581
582
583 <directive name="proxy_pass_header">
584 <syntax><value>field</value></syntax>
585 <default/>
586 <context>http</context>
587 <context>server</context>
588 <context>location</context>
589
590 <para>
591 Permits to pass <link id="proxy_hide_header">otherwise disabled</link> header
592 fields from a proxied server to a client.
593 </para>
594
595 </directive>
596
597
598 <directive name="proxy_read_timeout">
599 <syntax><value>time</value></syntax>
600 <default>60s</default>
601 <context>http</context>
602 <context>server</context>
603 <context>location</context>
604
605 <para>
606 Defines a timeout for reading a response from the proxied server.
607 A timeout is only set between two successive read operations,
608 not for the transmission of the whole response.
609 If a proxied server does not transmit anything within this time,
610 a connection is closed.
611 </para>
612
613 </directive>
614
615
616 <directive name="proxy_redirect">
617 <syntax><literal>default</literal></syntax>
618 <syntax><literal>off</literal></syntax>
619 <syntax><value>redirect</value> <value>replacement</value></syntax>
620 <default>default</default>
621 <context>http</context>
622 <context>server</context>
623 <context>location</context>
624
625 <para>
626 Sets a text that should be changed in the header fields
627 <header>Location</header> and <header>Refresh</header> of a response
628 from the proxied server.
629 Suppose a proxied server returned the header field
630 “<literal>Location: http://localhost:8000/two/some/uri/</literal>”.
631 The directive
632 <example>
633 proxy_redirect http://localhost:8000/two/ http://frontend/one/;
634 </example>
635 will rewrite this string to
636 “<literal>Location: http://frontend/one/some/uri/</literal>”.
637 </para>
638
639 <para>
640 A server name may be omitted from the <value>replacement</value> string:
641 <example>
642 proxy_redirect http://localhost:8000/two/ /;
643 </example>
644 then the primary server’s name and a port, if different from 80,
645 will be substituted.
646 </para>
647
648 <para>
649 The default replacement specified by the <literal>default</literal> parameter
650 uses the parameters of the
651 <link doc="ngx_http_core_module.xml" id="location"/> and
652 <link id="proxy_pass"/> directives.
653 Hence, the two configurations below are equivalent:
654 <example>
655 location /one/ {
656 proxy_pass http://upstream:port/two/;
657 proxy_redirect default;
658 </example>
659
660 <example>
661 location /one/ {
662 proxy_pass http://upstream:port/two/;
663 proxy_redirect http://upstream:port/two/ /one/;
664 </example>
665 The <literal>default</literal> parameter is not permitted if
666 <link id="proxy_pass"/> is specified using variables.
667 </para>
668
669 <para>
670 A <value>replacement</value> string can contain variables:
671 <example>
672 proxy_redirect http://localhost:8000/ http://$host:$server_port/;
673 </example>
674 </para>
675
676 <para>
677 A <value>redirect</value> can also contain (1.1.11) variables:
678 <example>
679 proxy_redirect http://$proxy_host:8000/ /;
680 </example>
681 </para>
682
683 <para>
684 A directive can be specified (1.1.11) using regular expressions.
685 In this case, <value>replacement</value> should either start from
686 the “<literal>~</literal>” symbol for a case-sensitive matching,
687 or from the “<literal>~*</literal>” symbols for case-insensitive
688 matching.
689 A regular expression can contain named and positional captures,
690 and <value>replacement</value> can reference them:
691 <example>
692 proxy_redirect ~^(http://[^:]+):\d+(/.+)$ $1$2;
693 proxy_redirect ~*/user/([^/]+)/(.+)$ http://$1.example.com/$2;
694 </example>
695 </para>
696
697 <para>
698 There could be several <literal>proxy_redirect</literal> directives:
699 <example>
700 proxy_redirect default;
701 proxy_redirect http://localhost:8000/ /;
702 proxy_redirect http://www.example.com/ /;
703 </example>
704 </para>
705
706 <para>
707 The <literal>off</literal> parameter cancels all
708 <literal>proxy_redirect</literal> directives on the current level:
709 <example>
710 proxy_redirect off;
711 proxy_redirect default;
712 proxy_redirect http://localhost:8000/ /;
713 proxy_redirect http://www.example.com/ /;
714 </example>
715 </para>
716
717 <para>
718 Using this directive it is also possible to add host names to relative
719 redirects issued by a proxied server:
720 <example>
721 proxy_redirect / /;
722 </example>
723 </para>
724
725 </directive>
726
727
728 <directive name="proxy_send_timeout">
729 <syntax><value>time</value></syntax>
730 <default>60s</default>
731 <context>http</context>
732 <context>server</context>
733 <context>location</context>
734
735 <para>
736 Sets a timeout for transmitting a request to the proxied server.
737 A timeout is only set between two successive write operations,
738 not for the transmission of the whole request.
739 If a proxied server does not receive anything within this time,
740 a connection is closed.
741 </para>
742
743 </directive>
744
745
746 <directive name="proxy_set_header">
747 <syntax><value>field</value> <value>value</value></syntax>
748 <default>Host $proxy_host</default>
749 <default>Connection close</default>
750 <context>http</context>
751 <context>server</context>
752 <context>location</context>
753
754 <para>
755 Allows to redefine or append fields to the request header
756 passed to the proxied server.
757 A <value>value</value> can contain text, variables, and their combination.
758 These directives are inherited from the previous level if and
759 only if there are no
760 <literal>proxy_set_header</literal>
761 directives defined on the current level.
762 By default, only two fields are redefined:
763 <example>
764 proxy_set_header Host $proxy_host;
765 proxy_set_header Connection close;
766 </example>
767 </para>
768
769 <para>
770 An unchanged <header>Host</header> request header field can be passed like this:
771 <example>
772 proxy_set_header Host $http_host;
773 </example>
774 </para>
775
776 <para>
777 However, if this field is not present in a client request header then
778 nothing will be passed.
779 In such a case it is better to use the <var>$host</var> variable&mdash;its
780 value equals the server name in the <header>Host</header> request header
781 field, or the primary server name if this field is not present:
782 <example>
783 proxy_set_header Host $host;
784 </example>
785 </para>
786
787 <para>
788 In addition, a server name can be passed together with a port of the
789 proxied server:
790 <example>
791 proxy_set_header Host $host:$proxy_port;
792 </example>
793 </para>
794
795 <para>
796 If the value of a header field is an empty string then this
797 field will not be passed to a proxied server:
798 <example>
799 proxy_set_header Accept-Encoding "";
800 </example>
801 </para>
802
803 </directive>
804
805
806 <directive name="proxy_ssl_session_reuse">
807 <syntax><literal>on</literal> | <literal>off</literal></syntax>
808 <default>on</default>
809 <context>http</context>
810 <context>server</context>
811 <context>location</context>
812
813 <para>
814 Determines whether SSL sessions can be reused when working with
815 the proxied server.
816 If the errors
817 “<literal>SSL3_GET_FINISHED:digest check failed</literal>”
818 appear in the logs, try to disable session reuse.
819 </para>
820
821 </directive>
822
823
824 <directive name="proxy_store">
825 <syntax>
826 <literal>on</literal> |
827 <literal>off</literal> |
828 <value>string</value></syntax>
829 <default>off</default>
830 <context>http</context>
831 <context>server</context>
832 <context>location</context>
833
834 <para>
835 Enables saving of files to a disk.
836 The <literal>on</literal> parameter saves files with paths
837 corresponding to the directives
838 <link doc="ngx_http_core_module.xml" id="alias"/> or
839 <link doc="ngx_http_core_module.xml" id="root"/>.
840 The <literal>off</literal> parameter disables saving of files.
841 In addition, the file name can be set explicitly using the
842 <value>string</value> with variables:
843 <example>
844 proxy_store /data/www$original_uri;
845 </example>
846 </para>
847
848 <para>
849 The modification time of files is set according to the received
850 <header>Last-Modified</header> response header field.
851 A response is first written to a temporary file, then a file is renamed.
852 Starting from version 0.8.9 temporary files and the persistent store
853 can be put on different file systems but be aware that in this case
854 a file is copied across two file systems instead of the cheap rename operation.
855 It is thus recommended that for any given location both saved files and a
856 directory holding temporary files set by the <link id="proxy_temp_path"/>
857 directive are put on the same file system.
858 </para>
859
860 <para>
861 This directive can be used to create local copies of static unchangeable
862 files, e.g.:
863 <example>
864 location /images/ {
865 root /data/www;
866 open_file_cache_errors off;
867 error_page 404 = /fetch$uri;
868 }
869
870 location /fetch/ {
871 internal;
872
873 proxy_pass http://backend/;
874 proxy_store on;
875 proxy_store_access user:rw group:rw all:r;
876 proxy_temp_path /data/temp;
877
878 alias /data/www/;
879 }
880 </example>
881 </para>
882
883 <para>
884 or like this:
885 <example>
886 location /images/ {
887 root /data/www;
888 error_page 404 = @fetch;
889 }
890
891 location @fetch {
892 internal;
893
894 proxy_pass http://backend;
895 proxy_store on;
896 proxy_store_access user:rw group:rw all:r;
897 proxy_temp_path /data/temp;
898
899 root /data/www;
900 }
901 </example>
902 </para>
903
904 </directive>
905
906
907 <directive name="proxy_store_access">
908 <syntax><value>users</value>:<value>permissions</value> ...</syntax>
909 <default>user:rw</default>
910 <context>http</context>
911 <context>server</context>
912 <context>location</context>
913
914 <para>
915 Sets access permissions for newly created files and directories, e.g.:
916 <example>
917 proxy_store_access user:rw group:rw all:r;
918 </example>
919 </para>
920
921 <para>
922 If any <literal>group</literal> or <literal>all</literal> access permissions
923 are specified then <literal>user</literal> permissions may be omitted:
924 <example>
925 proxy_store_access group:rw all:r;
926 </example>
927 </para>
928
929 </directive>
930
931
932 <directive name="proxy_temp_path">
933 <syntax>
934 <value>path</value>
935 [<value>level1</value>
936 [<value>level2</value>
937 [<value>level3</value>]]]</syntax>
938 <default>proxy_temp</default>
939 <context>http</context>
940 <context>server</context>
941 <context>location</context>
942
943 <para>
944 Defines a directory for storing temporary files
945 received from another server.
946 Up to three-level subdirectory hierarchy can be used underneath the specified
947 directory.
948 For example, in the following configuration
949 <example>
950 proxy_temp_path /spool/nginx/proxy_temp 1 2;
951 </example>
952 a temporary file might look like this:
953 <example>
954 /spool/nginx/proxy_temp/<emphasis>7</emphasis>/<emphasis>45</emphasis>/00000123<emphasis>457</emphasis>
955 </example>
956 </para>
957
958 </directive>
959
960 </section>
961
962
963 <section id="variables" name="Embedded Variables">
964
965 <para>
966 The <literal>ngx_http_proxy_module</literal> module supports embedded variables
967 that can be used to compose headers using the
968 <link id="proxy_set_header"/> directive:
969 <list type="tag">
970
971 <tag-name><var>$proxy_host</var></tag-name>
972 <tag-desc>name and port of a proxied server;</tag-desc>
973
974 <tag-name><var>$proxy_port</var></tag-name>
975 <tag-desc>port of a proxied server;</tag-desc>
976
977 <tag-name><var>$proxy_add_x_forwarded_for</var></tag-name>
978 <tag-desc>the <header>X-Forwarded-For</header> client request header field
979 with the <var>$remote_addr</var> variable appended to it, separated by a comma.
980 If the <header>X-Forwarded-For</header> field is not present in the client
981 request header, the <var>$proxy_add_x_forwarded_for</var> variable is equal
982 to the <var>$remote_addr</var> variable.</tag-desc>
983 </list>
984 </para>
985
986 </section>
987
988 </module>