Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_proxy_module.xml @ 281:7142ddd2764c
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—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> |