Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_uwsgi_module.xml @ 1191:ea85ba147fe9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Mechanically converted SCGI module docs to uwsgi.
author Ruslan Ermilov <ru@nginx.com>
date Sat, 17 May 2014 01:55:03 +0400
parents
children b5268820c3f3
comparison
equal deleted inserted replaced
1190:dd4cfc6ce770 1191:ea85ba147fe9
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) Igor Sysoev
5 Copyright (C) Nginx, Inc.
6 -->
7
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
9
10 <module name="Module ngx_http_uwsgi_module"
11 link="/en/docs/http/ngx_http_uwsgi_module.html"
12 lang="en"
13 rev="1">
14
15 <section id="summary">
16
17 <para>
18 The <literal>ngx_http_uwsgi_module</literal> module allows passing
19 requests to a uwsgi server.
20 </para>
21
22 </section>
23
24
25 <section id="example" name="Example Configuration">
26
27 <para>
28 <example>
29 location / {
30 include uwsgi_params;
31 uwsgi_pass localhost:9000;
32 }
33 </example>
34 </para>
35
36 </section>
37
38
39 <section id="directives" name="Directives">
40
41 <directive name="uwsgi_bind">
42 <syntax><value>address</value> | <literal>off</literal></syntax>
43 <default/>
44 <context>http</context>
45 <context>server</context>
46 <context>location</context>
47
48 <para>
49 Makes outgoing connections to a uwsgi server originate
50 from the specified local IP <value>address</value>.
51 Parameter value can contain variables (1.3.12).
52 The special value <literal>off</literal> (1.3.12) cancels the effect
53 of the <literal>uwsgi_bind</literal> directive
54 inherited from the previous configuration level, which allows the
55 system to auto-assign the local IP address.
56 </para>
57
58 </directive>
59
60
61 <directive name="uwsgi_buffer_size">
62 <syntax><value>size</value></syntax>
63 <default>4k|8k</default>
64 <context>http</context>
65 <context>server</context>
66 <context>location</context>
67
68 <para>
69 Sets the <value>size</value> of the buffer used for reading the first part
70 of the response received from the uwsgi server.
71 This part usually contains a small response header.
72 By default, the buffer size is equal to the size of one
73 buffer set by the <link id="uwsgi_buffers"/> directive.
74 It can be made smaller, however.
75 </para>
76
77 </directive>
78
79
80 <directive name="uwsgi_buffering">
81 <syntax><literal>on</literal> | <literal>off</literal></syntax>
82 <default>on</default>
83 <context>http</context>
84 <context>server</context>
85 <context>location</context>
86
87 <para>
88 Enables or disables buffering of responses from the uwsgi server.
89 </para>
90
91 <para>
92 When buffering is enabled, nginx receives a response from the uwsgi server
93 as soon as possible, saving it into the buffers set by the
94 <link id="uwsgi_buffer_size"/> and <link id="uwsgi_buffers"/> directives.
95 If the whole response does not fit into memory, a part of it can be saved
96 to a <link id="uwsgi_temp_path">temporary file</link> on the disk.
97 Writing to temporary files is controlled by the
98 <link id="uwsgi_max_temp_file_size"/> and
99 <link id="uwsgi_temp_file_write_size"/> directives.
100 </para>
101
102 <para>
103 When buffering is disabled, the response is passed to a client synchronously,
104 immediately as it is received.
105 nginx will not try to read the whole response from the uwsgi server.
106 The maximum size of the data that nginx can receive from the server
107 at a time is set by the <link id="uwsgi_buffer_size"/> directive.
108 </para>
109
110 <para>
111 Buffering can also be enabled or disabled by passing
112 “<literal>yes</literal>” or “<literal>no</literal>” in the
113 <header>X-Accel-Buffering</header> response header field.
114 This capability can be disabled using the
115 <link id="uwsgi_ignore_headers"/> directive.
116 </para>
117
118 </directive>
119
120
121 <directive name="uwsgi_buffers">
122 <syntax><value>number</value> <value>size</value></syntax>
123 <default>8 4k|8k</default>
124 <context>http</context>
125 <context>server</context>
126 <context>location</context>
127
128 <para>
129 Sets the <value>number</value> and <value>size</value> of the
130 buffers used for reading a response from the uwsgi server,
131 for a single connection.
132 By default, the buffer size is equal to one memory page.
133 This is either 4K or 8K, depending on a platform.
134 </para>
135
136 </directive>
137
138
139 <directive name="uwsgi_busy_buffers_size">
140 <syntax><value>size</value></syntax>
141 <default>8k|16k</default>
142 <context>http</context>
143 <context>server</context>
144 <context>location</context>
145
146 <para>
147 When <link id="uwsgi_buffering">buffering</link> of responses from the uwsgi
148 server is enabled, limits the total <value>size</value> of buffers that
149 can be busy sending a response to the client while the response is not
150 yet fully read.
151 In the meantime, the rest of the buffers can be used for reading the response
152 and, if needed, buffering part of the response to a temporary file.
153 By default, <value>size</value> is limited by the size of two buffers set by the
154 <link id="uwsgi_buffer_size"/> and <link id="uwsgi_buffers"/> directives.
155 </para>
156
157 </directive>
158
159
160 <directive name="uwsgi_cache">
161 <syntax><value>zone</value> | <literal>off</literal></syntax>
162 <default>off</default>
163 <context>http</context>
164 <context>server</context>
165 <context>location</context>
166
167 <para>
168 Defines a shared memory zone used for caching.
169 The same zone can be used in several places.
170 The <literal>off</literal> parameter disables caching inherited
171 from the previous configuration level.
172 </para>
173
174 </directive>
175
176
177 <directive name="uwsgi_cache_bypass">
178 <syntax><value>string</value> ...</syntax>
179 <default/>
180 <context>http</context>
181 <context>server</context>
182 <context>location</context>
183
184 <para>
185 Defines conditions under which the response will not be taken from a cache.
186 If at least one value of the string parameters is not empty and is not
187 equal to “0” then the response will not be taken from the cache:
188 <example>
189 uwsgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
190 uwsgi_cache_bypass $http_pragma $http_authorization;
191 </example>
192 Can be used along with the <link id="uwsgi_no_cache"/> directive.
193 </para>
194
195 </directive>
196
197
198 <directive name="uwsgi_cache_key">
199 <syntax><value>string</value></syntax>
200 <default/>
201 <context>http</context>
202 <context>server</context>
203 <context>location</context>
204
205 <para>
206 Defines a key for caching, for example
207 <example>
208 uwsgi_cache_key localhost:9000$request_uri;
209 </example>
210 </para>
211
212 </directive>
213
214
215 <directive name="uwsgi_cache_lock">
216 <syntax><literal>on</literal> | <literal>off</literal></syntax>
217 <default>off</default>
218 <context>http</context>
219 <context>server</context>
220 <context>location</context>
221 <appeared-in>1.1.12</appeared-in>
222
223 <para>
224 When enabled, only one request at a time will be allowed to populate
225 a new cache element identified according to the <link id="uwsgi_cache_key"/>
226 directive by passing a request to a uwsgi server.
227 Other requests of the same cache element will either wait
228 for a response to appear in the cache or the cache lock for
229 this element to be released, up to the time set by the
230 <link id="uwsgi_cache_lock_timeout"/> directive.
231 </para>
232
233 </directive>
234
235
236 <directive name="uwsgi_cache_lock_timeout">
237 <syntax><value>time</value></syntax>
238 <default>5s</default>
239 <context>http</context>
240 <context>server</context>
241 <context>location</context>
242 <appeared-in>1.1.12</appeared-in>
243
244 <para>
245 Sets a timeout for <link id="uwsgi_cache_lock"/>.
246 </para>
247
248 </directive>
249
250
251 <directive name="uwsgi_cache_methods">
252 <syntax>
253 <literal>GET</literal> |
254 <literal>HEAD</literal> |
255 <literal>POST</literal>
256 ...</syntax>
257 <default>GET HEAD</default>
258 <context>http</context>
259 <context>server</context>
260 <context>location</context>
261
262 <para>
263 If the client request method is listed in this directive then
264 the response will be cached.
265 “<literal>GET</literal>” and “<literal>HEAD</literal>” methods are always
266 added to the list, though it is recommended to specify them explicitly.
267 See also the <link id="uwsgi_no_cache"/> directive.
268 </para>
269
270 </directive>
271
272
273 <directive name="uwsgi_cache_min_uses">
274 <syntax><value>number</value></syntax>
275 <default>1</default>
276 <context>http</context>
277 <context>server</context>
278 <context>location</context>
279
280 <para>
281 Sets the <value>number</value> of requests after which the response
282 will be cached.
283 </para>
284
285 </directive>
286
287
288 <directive name="uwsgi_cache_path">
289 <syntax>
290 <value>path</value>
291 [<literal>levels</literal>=<value>levels</value>]
292 <literal>keys_zone</literal>=<value>name</value>:<value>size</value>
293 [<literal>inactive</literal>=<value>time</value>]
294 [<literal>max_size</literal>=<value>size</value>]
295 [<literal>loader_files</literal>=<value>number</value>]
296 [<literal>loader_sleep</literal>=<value>time</value>]
297 [<literal>loader_threshold</literal>=<value>time</value>]</syntax>
298 <default/>
299 <context>http</context>
300
301 <para>
302 Sets the path and other parameters of a cache.
303 Cache data are stored in files.
304 The file name in a cache is a result of
305 applying the MD5 function to the
306 <link id="uwsgi_cache_key">cache key</link>.
307 The <literal>levels</literal> parameter defines hierarchy levels of a cache.
308 For example, in the following configuration
309 <example>
310 uwsgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;
311 </example>
312 file names in a cache will look like this:
313 <example>
314 /data/nginx/cache/<emphasis>c</emphasis>/<emphasis>29</emphasis>/b7f54b2df7773722d382f4809d650<emphasis>29c</emphasis>
315 </example>
316 </para>
317
318 <para>
319 A cached response is first written to a temporary file,
320 and then the file is renamed.
321 Starting from version 0.8.9, temporary files and the cache can be put on
322 different file systems.
323 However, be aware that in this case a file is copied
324 across two file systems instead of the cheap renaming operation.
325 It is thus recommended that for any given location both cache and a directory
326 holding temporary files, set by the <link id="uwsgi_temp_path"/> directive,
327 are put on the same file system.
328 </para>
329
330 <para>
331 In addition, all active keys and information about data are stored
332 in a shared memory zone, whose <value>name</value> and <value>size</value>
333 are configured by the <literal>keys_zone</literal> parameter.
334 One megabyte zone can store about 8 thousand keys.
335 </para>
336
337 <para>
338 Cached data that are not accessed during the time specified by the
339 <literal>inactive</literal> parameter get removed from the cache
340 regardless of their freshness.
341 By default, <literal>inactive</literal> is set to 10 minutes.
342 </para>
343
344 <para>
345 The special “cache manager” process monitors the maximum cache size set
346 by the <literal>max_size</literal> parameter.
347 When this size is exceeded, it removes the least recently used data.
348 </para>
349
350 <para>
351 A minute after the start the special “cache loader” process is activated.
352 It loads information about previously cached data stored on file system
353 into a cache zone.
354 The loading is done in iterations.
355 During one iteration no more than <literal>loader_files</literal> items
356 are loaded (by default, 100).
357 Besides, the duration of one iteration is limited by the
358 <literal>loader_threshold</literal> parameter (by default, 200 milliseconds).
359 Between iterations, a pause configured by the <literal>loader_sleep</literal>
360 parameter (by default, 50 milliseconds) is made.
361 </para>
362
363 </directive>
364
365
366 <directive name="uwsgi_cache_purge">
367 <syntax>string ...</syntax>
368 <default/>
369 <context>http</context>
370 <context>server</context>
371 <context>location</context>
372 <appeared-in>1.5.7</appeared-in>
373
374 <para>
375 Defines conditions under which the request will be considered a cache
376 purge request.
377 If at least one value of the string parameters is not empty and is not equal
378 to “0” then the cache entry with a corresponding
379 <link id="uwsgi_cache_key">cache key</link> is removed.
380 The result of successful operation is indicated by returning
381 the <http-status code="204" text="No Content"/> response.
382 </para>
383
384 <para>
385 If the <link id="uwsgi_cache_key">cache key</link> of a purge request ends
386 with an asterisk (“<literal>*</literal>”), all cache entries matching the
387 wildcard key will be removed from the cache.
388 </para>
389
390 <para>
391 Example configuration:
392 <example>
393 uwsgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;
394
395 map $request_method $purge_method {
396 PURGE 1;
397 default 0;
398 }
399
400 server {
401 ...
402 location / {
403 uwsgi_pass backend;
404 uwsgi_cache cache_zone;
405 uwsgi_cache_key $uri;
406 uwsgi_cache_purge $purge_method;
407 }
408 }
409 </example>
410 <note>
411 This functionality is available as part of our
412 <commercial_version>commercial subscription</commercial_version>.
413 </note>
414 </para>
415
416 </directive>
417
418
419 <directive name="uwsgi_cache_revalidate">
420 <syntax><literal>on</literal> | <literal>off</literal></syntax>
421 <default>off</default>
422 <context>http</context>
423 <context>server</context>
424 <context>location</context>
425 <appeared-in>1.5.7</appeared-in>
426
427 <para>
428 Enables revalidation of expired cache items using conditional requests with
429 the <header>If-Modified-Since</header> header field.
430 </para>
431
432 </directive>
433
434
435 <directive name="uwsgi_cache_use_stale">
436 <syntax>
437 <literal>error</literal> |
438 <literal>timeout</literal> |
439 <literal>invalid_header</literal> |
440 <literal>updating</literal> |
441 <literal>http_500</literal> |
442 <literal>http_503</literal> |
443 <literal>http_403</literal> |
444 <literal>http_404</literal> |
445 <literal>off</literal>
446 ...</syntax>
447 <default>off</default>
448 <context>http</context>
449 <context>server</context>
450 <context>location</context>
451
452 <para>
453 Determines in which cases a stale cached response can be used
454 when an error occurs during communication with the uwsgi server.
455 The directive’s parameters match the parameters of the
456 <link id="uwsgi_next_upstream"/> directive.
457 </para>
458
459 <para>
460 Additionally, the <literal>updating</literal> parameter permits
461 using a stale cached response if it is currently being updated.
462 This allows minimizing the number of accesses to uwsgi servers
463 when updating cached data.
464 </para>
465
466 <para>
467 To minimize the number of accesses to uwsgi servers when
468 populating a new cache element, the <link id="uwsgi_cache_lock"/>
469 directive can be used.
470 </para>
471
472 </directive>
473
474
475 <directive name="uwsgi_cache_valid">
476 <syntax>[<value>code</value> ...] <value>time</value></syntax>
477 <default/>
478 <context>http</context>
479 <context>server</context>
480 <context>location</context>
481
482 <para>
483 Sets caching time for different response codes.
484 For example, the following directives
485 <example>
486 uwsgi_cache_valid 200 302 10m;
487 uwsgi_cache_valid 404 1m;
488 </example>
489 set 10 minutes of caching for responses with codes 200 and 302
490 and 1 minute for responses with code 404.
491 </para>
492
493 <para>
494 If only caching <value>time</value> is specified
495 <example>
496 uwsgi_cache_valid 5m;
497 </example>
498 then only 200, 301, and 302 responses are cached.
499 </para>
500
501 <para>
502 In addition, the <literal>any</literal> parameter can be specified
503 to cache any responses:
504 <example>
505 uwsgi_cache_valid 200 302 10m;
506 uwsgi_cache_valid 301 1h;
507 uwsgi_cache_valid any 1m;
508 </example>
509 </para>
510
511 <para>
512 Parameters of caching can also be set directly
513 in the response header.
514 This has higher priority than setting of caching time using the directive.
515 The <header>X-Accel-Expires</header> header field sets caching time of a
516 response in seconds.
517 The zero value disables caching for a response.
518 If the value starts with the <literal>@</literal> prefix, it sets an absolute
519 time in seconds since Epoch, up to which the response may be cached.
520 If the header does not include the <header>X-Accel-Expires</header> field,
521 parameters of caching may be set in the header fields
522 <header>Expires</header> or <header>Cache-Control</header>.
523 If the header includes the <header>Set-Cookie</header> field, such a
524 response will not be cached.
525 Processing of one or more of these response header fields can be disabled
526 using the <link id="uwsgi_ignore_headers"/> directive.
527 </para>
528
529 </directive>
530
531
532 <directive name="uwsgi_connect_timeout">
533 <syntax><value>time</value></syntax>
534 <default>60s</default>
535 <context>http</context>
536 <context>server</context>
537 <context>location</context>
538
539 <para>
540 Defines a timeout for establishing a connection with a uwsgi server.
541 It should be noted that this timeout cannot usually exceed 75 seconds.
542 </para>
543
544 </directive>
545
546
547 <directive name="uwsgi_hide_header">
548 <syntax><value>field</value></syntax>
549 <default/>
550 <context>http</context>
551 <context>server</context>
552 <context>location</context>
553
554 <para>
555 By default,
556 nginx does not pass the header fields <header>Status</header> and
557 <header>X-Accel-...</header> from the response of a uwsgi
558 server to a client.
559 The <literal>uwsgi_hide_header</literal> directive sets additional fields
560 that will not be passed.
561 If, on the contrary, the passing of fields needs to be permitted,
562 the <link id="uwsgi_pass_header"/> directive can be used.
563 </para>
564
565 </directive>
566
567
568 <directive name="uwsgi_ignore_client_abort">
569 <syntax><literal>on</literal> | <literal>off</literal></syntax>
570 <default>off</default>
571 <context>http</context>
572 <context>server</context>
573 <context>location</context>
574
575 <para>
576 Determines whether the connection with a uwsgi server should be
577 closed when a client closes the connection without waiting
578 for a response.
579 </para>
580
581 </directive>
582
583
584 <directive name="uwsgi_ignore_headers">
585 <syntax><value>field</value> ...</syntax>
586 <default/>
587 <context>http</context>
588 <context>server</context>
589 <context>location</context>
590
591 <para>
592 Disables processing of certain response header fields from the uwsgi server.
593 The following fields can be ignored: <header>X-Accel-Redirect</header>,
594 <header>X-Accel-Expires</header>, <header>X-Accel-Limit-Rate</header> (1.1.6),
595 <header>X-Accel-Buffering</header> (1.1.6),
596 <header>X-Accel-Charset</header> (1.1.6), <header>Expires</header>,
597 <header>Cache-Control</header>, and <header>Set-Cookie</header> (0.8.44).
598 </para>
599
600 <para>
601 If not disabled, processing of these header fields has the following
602 effect:
603 <list type="bullet" compact="no">
604
605 <listitem>
606 <header>X-Accel-Expires</header>, <header>Expires</header>,
607 <header>Cache-Control</header>, and <header>Set-Cookie</header>
608 set the parameters of response <link id="uwsgi_cache_valid">caching</link>;
609 </listitem>
610
611 <listitem>
612 <header>X-Accel-Redirect</header> performs an
613 <link doc="ngx_http_core_module.xml" id="internal">internal
614 redirect</link> to the specified URI;
615 </listitem>
616
617 <listitem>
618 <header>X-Accel-Limit-Rate</header> sets the
619 <link doc="ngx_http_core_module.xml" id="limit_rate">rate
620 limit</link> for transmission of a response to a client;
621 </listitem>
622
623 <listitem>
624 <header>X-Accel-Buffering</header> enables or disables
625 <link id="uwsgi_buffering">buffering</link> of a response;
626 </listitem>
627
628 <listitem>
629 <header>X-Accel-Charset</header> sets the desired
630 <link doc="ngx_http_charset_module.xml" id="charset"/>
631 of a response.
632 </listitem>
633
634 </list>
635 </para>
636
637 </directive>
638
639
640 <directive name="uwsgi_intercept_errors">
641 <syntax><literal>on</literal> | <literal>off</literal></syntax>
642 <default>off</default>
643 <context>http</context>
644 <context>server</context>
645 <context>location</context>
646
647 <para>
648 Determines whether a uwsgi server responses with codes greater than or equal
649 to 300 should be passed to a client or be redirected to nginx for processing
650 with the <link doc="ngx_http_core_module.xml" id="error_page"/> directive.
651 </para>
652
653 </directive>
654
655
656 <directive name="uwsgi_max_temp_file_size">
657 <syntax><value>size</value></syntax>
658 <default>1024m</default>
659 <context>http</context>
660 <context>server</context>
661 <context>location</context>
662
663 <para>
664 When <link id="uwsgi_buffering">buffering</link> of responses from the uwsgi
665 server is enabled, and the whole response does not fit into the buffers
666 set by the <link id="uwsgi_buffer_size"/> and <link id="uwsgi_buffers"/>
667 directives, a part of the response can be saved to a temporary file.
668 This directive sets the maximum <value>size</value> of the temporary file.
669 The size of data written to the temporary file at a time is set
670 by the <link id="uwsgi_temp_file_write_size"/> directive.
671 </para>
672
673 <para>
674 The zero value disables buffering of responses to temporary files.
675 </para>
676
677 </directive>
678
679
680 <directive name="uwsgi_next_upstream">
681 <syntax>
682 <literal>error</literal> |
683 <literal>timeout</literal> |
684 <literal>invalid_header</literal> |
685 <literal>http_500</literal> |
686 <literal>http_503</literal> |
687 <literal>http_403</literal> |
688 <literal>http_404</literal> |
689 <literal>off</literal>
690 ...</syntax>
691 <default>error timeout</default>
692 <context>http</context>
693 <context>server</context>
694 <context>location</context>
695
696 <para>
697 Specifies in which cases a request should be passed to the next server:
698 <list type="tag">
699
700 <tag-name><literal>error</literal></tag-name>
701 <tag-desc>an error occurred while establishing a connection with the
702 server, passing a request to it, or reading the response header;</tag-desc>
703
704 <tag-name><literal>timeout</literal></tag-name>
705 <tag-desc>a timeout has occurred while establishing a connection with the
706 server, passing a request to it, or reading the response header;</tag-desc>
707
708 <tag-name><literal>invalid_header</literal></tag-name>
709 <tag-desc>a server returned an empty or invalid response;</tag-desc>
710
711 <tag-name><literal>http_500</literal></tag-name>
712 <tag-desc>a server returned a response with the code 500;</tag-desc>
713
714 <tag-name><literal>http_503</literal></tag-name>
715 <tag-desc>a server returned a response with the code 503;</tag-desc>
716
717 <tag-name><literal>http_403</literal></tag-name>
718 <tag-desc>a server returned a response with the code 403;</tag-desc>
719
720 <tag-name><literal>http_404</literal></tag-name>
721 <tag-desc>a server returned a response with the code 404;</tag-desc>
722
723 <tag-name><literal>off</literal></tag-name>
724 <tag-desc>disables passing a request to the next server.</tag-desc>
725
726 </list>
727 </para>
728
729 <para>
730 One should bear in mind that passing a request to the next server is
731 only possible if nothing has been sent to a client yet.
732 That is, if an error or timeout occurs in the middle of the
733 transferring of a response, fixing this is impossible.
734 </para>
735
736 <para>
737 The directive also defines what is considered an unsuccessful attempt
738 of communication with a
739 <link doc="ngx_http_upstream_module.xml" id="server"/>.
740 The cases of <literal>error</literal>, <literal>timeout</literal> and
741 <literal>invalid_header</literal> are always considered unsuccessful attempts,
742 even if they are not specified in the directive.
743 The cases of <literal>http_500</literal> and <literal>http_503</literal> are
744 considered unsuccessful attempts only if they are specified in the directive.
745 The cases of <literal>http_403</literal> and <literal>http_404</literal>
746 are never considered unsuccessful attempts.
747 </para>
748
749 </directive>
750
751
752 <directive name="uwsgi_no_cache">
753 <syntax><value>string</value> ...</syntax>
754 <default/>
755 <context>http</context>
756 <context>server</context>
757 <context>location</context>
758
759 <para>
760 Defines conditions under which the response will not be saved to a cache.
761 If at least one value of the string parameters is not empty and is not
762 equal to “0” then the response will not be saved:
763 <example>
764 uwsgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
765 uwsgi_no_cache $http_pragma $http_authorization;
766 </example>
767 Can be used along with the <link id="uwsgi_cache_bypass"/> directive.
768 </para>
769
770 </directive>
771
772
773 <directive name="uwsgi_param">
774 <syntax>
775 <value>parameter</value> <value>value</value>
776 [<literal>if_not_empty</literal>]</syntax>
777 <default/>
778 <context>http</context>
779 <context>server</context>
780 <context>location</context>
781
782 <para>
783 Sets a <value>parameter</value> that should be passed to the uwsgi server.
784 The <value>value</value> can contain text, variables, and their combination.
785 These directives are inherited from the previous level if and
786 only if there are no
787 <literal>uwsgi_param</literal>
788 directives defined on the current level.
789 </para>
790
791 <para>
792 Standard
793 <link url="http://tools.ietf.org/html/rfc3875#section-4.1">CGI
794 environment variables</link>
795 should be provided as uwsgi headers, see the <path>uwsgi_params</path> file
796 provided in the distribution:
797 <example>
798 location / {
799 include uwsgi_params;
800 ...
801 }
802 </example>
803 </para>
804
805 <para>
806 If a directive is specified with <literal>if_not_empty</literal> (1.1.11) then
807 such a parameter will not be passed to the server until its value is not empty:
808 <example>
809 uwsgi_param HTTPS $https if_not_empty;
810 </example>
811 </para>
812
813 </directive>
814
815
816 <directive name="uwsgi_pass">
817 <syntax><value>address</value></syntax>
818 <default/>
819 <context>location</context>
820 <context>if in location</context>
821
822 <para>
823 Sets the address of a uwsgi server.
824 The address can be specified as a domain name or IP address,
825 and an optional port:
826 <example>
827 uwsgi_pass localhost:9000;
828 </example>
829 or as a UNIX-domain socket path:
830 <example>
831 uwsgi_pass unix:/tmp/uwsgi.socket;
832 </example>
833 </para>
834
835 <para>
836 If a domain name resolves to several addresses, all of them will be
837 used in a round-robin fashion.
838 In addition, an address can be specified as a
839 <link doc="ngx_http_upstream_module.xml">server group</link>.
840 </para>
841
842 </directive>
843
844
845 <directive name="uwsgi_pass_header">
846 <syntax><value>field</value></syntax>
847 <default/>
848 <context>http</context>
849 <context>server</context>
850 <context>location</context>
851
852 <para>
853 Permits passing <link id="uwsgi_hide_header">otherwise disabled</link> header
854 fields from a uwsgi server to a client.
855 </para>
856
857 </directive>
858
859
860 <directive name="uwsgi_pass_request_body">
861 <syntax><literal>on</literal> | <literal>off</literal></syntax>
862 <default>on</default>
863 <context>http</context>
864 <context>server</context>
865 <context>location</context>
866
867 <para>
868 Indicates whether the original request body is passed
869 to the uwsgi server.
870 See also the <link id="uwsgi_pass_request_headers"/> directive.
871 </para>
872
873 </directive>
874
875
876 <directive name="uwsgi_pass_request_headers">
877 <syntax><literal>on</literal> | <literal>off</literal></syntax>
878 <default>on</default>
879 <context>http</context>
880 <context>server</context>
881 <context>location</context>
882
883 <para>
884 Indicates whether the header fields of the original request are passed
885 to the uwsgi server.
886 See also the <link id="uwsgi_pass_request_body"/> directive.
887 </para>
888
889 </directive>
890
891
892 <directive name="uwsgi_read_timeout">
893 <syntax><value>time</value></syntax>
894 <default>60s</default>
895 <context>http</context>
896 <context>server</context>
897 <context>location</context>
898
899 <para>
900 Defines a timeout for reading a response from the uwsgi server.
901 The timeout is set only between two successive read operations,
902 not for the transmission of the whole response.
903 If the uwsgi server does not transmit anything within this time,
904 the connection is closed.
905 </para>
906
907 </directive>
908
909
910 <directive name="uwsgi_send_timeout">
911 <syntax><value>time</value></syntax>
912 <default>60s</default>
913 <context>http</context>
914 <context>server</context>
915 <context>location</context>
916
917 <para>
918 Sets a timeout for transmitting a request to the uwsgi server.
919 The timeout is set only between two successive write operations,
920 not for the transmission of the whole request.
921 If the uwsgi server does not receive anything within this time,
922 the connection is closed.
923 </para>
924
925 </directive>
926
927
928 <directive name="uwsgi_store">
929 <syntax>
930 <literal>on</literal> |
931 <literal>off</literal> |
932 <value>string</value></syntax>
933 <default>off</default>
934 <context>http</context>
935 <context>server</context>
936 <context>location</context>
937
938 <para>
939 Enables saving of files to a disk.
940 The <literal>on</literal> parameter saves files with paths
941 corresponding to the directives
942 <link doc="ngx_http_core_module.xml" id="alias"/> or
943 <link doc="ngx_http_core_module.xml" id="root"/>.
944 The <literal>off</literal> parameter disables saving of files.
945 In addition, the file name can be set explicitly using the
946 <value>string</value> with variables:
947 <example>
948 uwsgi_store /data/www$original_uri;
949 </example>
950 </para>
951
952 <para>
953 The modification time of files is set according to the received
954 <header>Last-Modified</header> response header field.
955 The response is first written to a temporary file,
956 and then the file is renamed.
957 Starting from version 0.8.9, temporary files and the persistent store
958 can be put on different file systems.
959 However, be aware that in this case a file is copied
960 across two file systems instead of the cheap renaming operation.
961 It is thus recommended that for any given location both saved files and a
962 directory holding temporary files, set by the <link id="uwsgi_temp_path"/>
963 directive, are put on the same file system.
964 </para>
965
966 <para>
967 This directive can be used to create local copies of static unchangeable
968 files, e.g.:
969 <example>
970 location /images/ {
971 root /data/www;
972 error_page 404 = /fetch$uri;
973 }
974
975 location /fetch/ {
976 internal;
977
978 uwsgi_pass backend:9000;
979 ...
980
981 uwsgi_store on;
982 uwsgi_store_access user:rw group:rw all:r;
983 uwsgi_temp_path /data/temp;
984
985 alias /data/www/;
986 }
987 </example>
988 </para>
989
990 </directive>
991
992
993 <directive name="uwsgi_store_access">
994 <syntax><value>users</value>:<value>permissions</value> ...</syntax>
995 <default>user:rw</default>
996 <context>http</context>
997 <context>server</context>
998 <context>location</context>
999
1000 <para>
1001 Sets access permissions for newly created files and directories, e.g.:
1002 <example>
1003 uwsgi_store_access user:rw group:rw all:r;
1004 </example>
1005 </para>
1006
1007 <para>
1008 If any <literal>group</literal> or <literal>all</literal> access permissions
1009 are specified then <literal>user</literal> permissions may be omitted:
1010 <example>
1011 uwsgi_store_access group:rw all:r;
1012 </example>
1013 </para>
1014
1015 </directive>
1016
1017
1018 <directive name="uwsgi_temp_file_write_size">
1019 <syntax><value>size</value></syntax>
1020 <default>8k|16k</default>
1021 <context>http</context>
1022 <context>server</context>
1023 <context>location</context>
1024
1025 <para>
1026 Limits the <value>size</value> of data written to a temporary file
1027 at a time, when buffering of responses from the uwsgi server
1028 to temporary files is enabled.
1029 By default, <value>size</value> is limited by two buffers set by the
1030 <link id="uwsgi_buffer_size"/> and <link id="uwsgi_buffers"/> directives.
1031 The maximum size of a temporary file is set by the
1032 <link id="uwsgi_max_temp_file_size"/> directive.
1033 </para>
1034
1035 </directive>
1036
1037
1038 <directive name="uwsgi_temp_path">
1039 <syntax>
1040 <value>path</value>
1041 [<value>level1</value>
1042 [<value>level2</value>
1043 [<value>level3</value>]]]</syntax>
1044 <default>uwsgi_temp</default>
1045 <context>http</context>
1046 <context>server</context>
1047 <context>location</context>
1048
1049 <para>
1050 Defines a directory for storing temporary files
1051 with data received from uwsgi servers.
1052 Up to three-level subdirectory hierarchy can be used underneath the specified
1053 directory.
1054 For example, in the following configuration
1055 <example>
1056 uwsgi_temp_path /spool/nginx/uwsgi_temp 1 2;
1057 </example>
1058 a temporary file might look like this:
1059 <example>
1060 /spool/nginx/uwsgi_temp/<emphasis>7</emphasis>/<emphasis>45</emphasis>/00000123<emphasis>457</emphasis>
1061 </example>
1062 </para>
1063
1064 </directive>
1065
1066 </section>
1067
1068 </module>