Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_scgi_module.xml @ 1180:9d3beb5890eb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented the scgi module.
author Yaroslav Zhuravlev <yar@nginx.com>
date Fri, 25 Apr 2014 18:00:14 +0400
parents
children ec1097156f81
comparison
equal deleted inserted replaced
1179:f2d939ac0449 1180:9d3beb5890eb
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_scgi_module"
11 link="/en/docs/http/ngx_http_scgi_module.html"
12 lang="en"
13 rev="1">
14
15 <section id="summary">
16
17 <para>
18 The <literal>ngx_http_scgi_module</literal> module allows passing
19 requests to an SCGI server.
20 </para>
21
22 </section>
23
24
25 <section id="example" name="Example Configuration">
26
27 <para>
28 <example>
29 location / {
30 include scgi_params;
31 scgi_pass localhost:9000;
32 }
33 </example>
34 </para>
35
36 </section>
37
38
39 <section id="directives" name="Directives">
40
41 <directive name="scgi_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 an SCGI 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>scgi_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="scgi_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 SCGI 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="scgi_buffers"/> directive.
74 It can be made smaller, however.
75 </para>
76
77 </directive>
78
79
80 <directive name="scgi_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 SCGI server.
89 </para>
90
91 <para>
92 When buffering is enabled, nginx receives a response from the SCGI server
93 as soon as possible, saving it into the buffers set by the
94 <link id="scgi_buffer_size"/> and <link id="scgi_buffers"/> directives.
95 If the whole response does not fit into memory, a part of it can be saved
96 to a <link id="scgi_temp_path">temporary file</link> on the disk.
97 Writing to temporary files is controlled by the
98 <link id="scgi_max_temp_file_size"/> and
99 <link id="scgi_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 SCGI 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="scgi_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="scgi_ignore_headers"/> directive.
116 </para>
117
118 </directive>
119
120
121 <directive name="scgi_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 SCGI 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="scgi_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="scgi_buffering">buffering</link> of responses from the SCGI
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="scgi_buffer_size"/> and <link id="scgi_buffers"/> directives.
155 </para>
156
157 </directive>
158
159
160 <directive name="scgi_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="scgi_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 scgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
190 scgi_cache_bypass $http_pragma $http_authorization;
191 </example>
192 Can be used along with the <link id="scgi_no_cache"/> directive.
193 </para>
194
195 </directive>
196
197
198 <directive name="scgi_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 scgi_cache_key localhost:9000$request_uri;
209 </example>
210 </para>
211
212 </directive>
213
214
215 <directive name="scgi_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="scgi_cache_key"/>
226 directive by passing a request to an SCGI 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="scgi_cache_lock_timeout"/> directive.
231 </para>
232
233 </directive>
234
235
236 <directive name="scgi_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="scgi_cache_lock"/>.
246 </para>
247
248 </directive>
249
250
251 <directive name="scgi_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="scgi_no_cache"/> directive.
268 </para>
269
270 </directive>
271
272
273 <directive name="scgi_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="scgi_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 Both the key and file name in a cache are a result of
305 applying the MD5 function to the proxied URL.
306 The <literal>levels</literal> parameter defines hierarchy levels of a cache.
307 For example, in the following configuration
308 <example>
309 scgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;
310 </example>
311 file names in a cache will look like this:
312 <example>
313 /data/nginx/cache/<emphasis>c</emphasis>/<emphasis>29</emphasis>/b7f54b2df7773722d382f4809d650<emphasis>29c</emphasis>
314 </example>
315 </para>
316
317 <para>
318 A cached response is first written to a temporary file,
319 and then the file is renamed.
320 Starting from version 0.8.9, temporary files and the cache can be put on
321 different file systems.
322 However, be aware that in this case a file is copied
323 across two file systems instead of the cheap renaming operation.
324 It is thus recommended that for any given location both cache and a directory
325 holding temporary files, set by the <link id="scgi_temp_path"/> directive,
326 are put on the same file system.
327 </para>
328
329 <para>
330 In addition, all active keys and information about data are stored
331 in a shared memory zone, whose <value>name</value> and <value>size</value>
332 are configured by the <literal>keys_zone</literal> parameter.
333 Cached data that are not accessed during the time specified by the
334 <literal>inactive</literal> parameter get removed from the cache
335 regardless of their freshness.
336 By default, <literal>inactive</literal> is set to 10 minutes.
337 </para>
338
339 <para>
340 The special “cache manager” process monitors the maximum cache size set
341 by the <literal>max_size</literal> parameter.
342 When this size is exceeded, it removes the least recently used data.
343 </para>
344
345 <para>
346 A minute after the start the special “cache loader” process is activated.
347 It loads information about previously cached data stored on file system
348 into a cache zone.
349 The loading is done in iterations.
350 During one iteration no more than <literal>loader_files</literal> items
351 are loaded (by default, 100).
352 Besides, the duration of one iteration is limited by the
353 <literal>loader_threshold</literal> parameter (by default, 200 milliseconds).
354 Between iterations, a pause configured by the <literal>loader_sleep</literal>
355 parameter (by default, 50 milliseconds) is made.
356 </para>
357
358 </directive>
359
360
361 <directive name="scgi_cache_purge">
362 <syntax>string ...</syntax>
363 <default/>
364 <context>http</context>
365 <context>server</context>
366 <context>location</context>
367 <appeared-in>1.5.7</appeared-in>
368
369 <para>
370 Defines conditions under which the request will be considered a cache
371 purge request.
372 If at least one value of the string parameters is not empty and is not equal
373 to “0” then the cache entry with a corresponding
374 <link id="scgi_cache_key">cache key</link> is removed.
375 The result of successful operation is indicated by returning
376 the <http-status code="204" text="No Content"/> response.
377 </para>
378
379 <para>
380 If the <link id="scgi_cache_key">cache key</link> of a purge request ends
381 with an asterisk (“<literal>*</literal>”), all cache entries matching the
382 wildcard key will be removed from the cache.
383 </para>
384
385 <para>
386 Example configuration:
387 <example>
388 scgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;
389
390 map $request_method $purge_method {
391 PURGE 1;
392 default 0;
393 }
394
395 server {
396 ...
397 location / {
398 scgi_pass backend;
399 scgi_cache cache_zone;
400 scgi_cache_key $uri;
401 scgi_cache_purge $purge_method;
402 }
403 }
404 </example>
405 <note>
406 This functionality is available as part of our
407 <commercial_version>commercial subscription</commercial_version>.
408 </note>
409 </para>
410
411 </directive>
412
413
414 <directive name="scgi_cache_revalidate">
415 <syntax><literal>on</literal> | <literal>off</literal></syntax>
416 <default>off</default>
417 <context>http</context>
418 <context>server</context>
419 <context>location</context>
420 <appeared-in>1.5.7</appeared-in>
421
422 <para>
423 Enables revalidation of expired cache items using conditional requests with
424 the <header>If-Modified-Since</header> header field.
425 </para>
426
427 </directive>
428
429
430 <directive name="scgi_cache_use_stale">
431 <syntax>
432 <literal>error</literal> |
433 <literal>timeout</literal> |
434 <literal>invalid_header</literal> |
435 <literal>updating</literal> |
436 <literal>http_500</literal> |
437 <literal>http_503</literal> |
438 <literal>http_403</literal> |
439 <literal>http_404</literal> |
440 <literal>off</literal>
441 ...</syntax>
442 <default>off</default>
443 <context>http</context>
444 <context>server</context>
445 <context>location</context>
446
447 <para>
448 Determines in which cases a stale cached response can be used
449 when an error occurs during communication with the SCGI server.
450 The directive’s parameters match the parameters of the
451 <link id="scgi_next_upstream"/> directive.
452 </para>
453
454 <para>
455 Additionally, the <literal>updating</literal> parameter permits
456 using a stale cached response if it is currently being updated.
457 This allows minimizing the number of accesses to SCGI servers
458 when updating cached data.
459 </para>
460
461 <para>
462 To minimize the number of accesses to SCGI servers when
463 populating a new cache element, the <link id="scgi_cache_lock"/>
464 directive can be used.
465 </para>
466
467 </directive>
468
469
470 <directive name="scgi_cache_valid">
471 <syntax>[<value>code</value> ...] <value>time</value></syntax>
472 <default/>
473 <context>http</context>
474 <context>server</context>
475 <context>location</context>
476
477 <para>
478 Sets caching time for different response codes.
479 For example, the following directives
480 <example>
481 scgi_cache_valid 200 302 10m;
482 scgi_cache_valid 404 1m;
483 </example>
484 set 10 minutes of caching for responses with codes 200 and 302
485 and 1 minute for responses with code 404.
486 </para>
487
488 <para>
489 If only caching <value>time</value> is specified
490 <example>
491 scgi_cache_valid 5m;
492 </example>
493 then only 200, 301, and 302 responses are cached.
494 </para>
495
496 <para>
497 In addition, the <literal>any</literal> parameter can be specified
498 to cache any responses:
499 <example>
500 scgi_cache_valid 200 302 10m;
501 scgi_cache_valid 301 1h;
502 scgi_cache_valid any 1m;
503 </example>
504 </para>
505
506 <para>
507 Parameters of caching can also be set directly
508 in the response header.
509 This has higher priority than setting of caching time using the directive.
510 The <header>X-Accel-Expires</header> header field sets caching time of a
511 response in seconds.
512 The zero value disables caching for a response.
513 If the value starts with the <literal>@</literal> prefix, it sets an absolute
514 time in seconds since Epoch, up to which the response may be cached.
515 If the header does not include the <header>X-Accel-Expires</header> field,
516 parameters of caching may be set in the header fields
517 <header>Expires</header> or <header>Cache-Control</header>.
518 If the header includes the <header>Set-Cookie</header> field, such a
519 response will not be cached.
520 Processing of one or more of these response header fields can be disabled
521 using the <link id="scgi_ignore_headers"/> directive.
522 </para>
523
524 </directive>
525
526
527 <directive name="scgi_connect_timeout">
528 <syntax><value>time</value></syntax>
529 <default>60s</default>
530 <context>http</context>
531 <context>server</context>
532 <context>location</context>
533
534 <para>
535 Defines a timeout for establishing a connection with an SCGI server.
536 It should be noted that this timeout cannot usually exceed 75 seconds.
537 </para>
538
539 </directive>
540
541
542 <directive name="scgi_hide_header">
543 <syntax><value>field</value></syntax>
544 <default/>
545 <context>http</context>
546 <context>server</context>
547 <context>location</context>
548
549 <para>
550 By default,
551 nginx does not pass the header fields <header>Status</header> and
552 <header>X-Accel-...</header> from the response of an SCGI
553 server to a client.
554 The <literal>scgi_hide_header</literal> directive sets additional fields
555 that will not be passed.
556 If, on the contrary, the passing of fields needs to be permitted,
557 the <link id="scgi_pass_header"/> directive can be used.
558 </para>
559
560 </directive>
561
562
563 <directive name="scgi_ignore_client_abort">
564 <syntax><literal>on</literal> | <literal>off</literal></syntax>
565 <default>off</default>
566 <context>http</context>
567 <context>server</context>
568 <context>location</context>
569
570 <para>
571 Determines whether the connection with an SCGI server should be
572 closed when a client closes the connection without waiting
573 for a response.
574 </para>
575
576 </directive>
577
578
579 <directive name="scgi_ignore_headers">
580 <syntax><value>field</value> ...</syntax>
581 <default/>
582 <context>http</context>
583 <context>server</context>
584 <context>location</context>
585
586 <para>
587 Disables processing of certain response header fields from the SCGI server.
588 The following fields can be ignored: <header>X-Accel-Redirect</header>,
589 <header>X-Accel-Expires</header>, <header>X-Accel-Limit-Rate</header> (1.1.6),
590 <header>X-Accel-Buffering</header> (1.1.6),
591 <header>X-Accel-Charset</header> (1.1.6), <header>Expires</header>,
592 <header>Cache-Control</header>, and <header>Set-Cookie</header> (0.8.44).
593 </para>
594
595 <para>
596 If not disabled, processing of these header fields has the following
597 effect:
598 <list type="bullet" compact="no">
599
600 <listitem>
601 <header>X-Accel-Expires</header>, <header>Expires</header>,
602 <header>Cache-Control</header>, and <header>Set-Cookie</header>
603 set the parameters of response <link id="scgi_cache_valid">caching</link>;
604 </listitem>
605
606 <listitem>
607 <header>X-Accel-Redirect</header> performs an
608 <link doc="ngx_http_core_module.xml" id="internal">internal
609 redirect</link> to the specified URI;
610 </listitem>
611
612 <listitem>
613 <header>X-Accel-Limit-Rate</header> sets the
614 <link doc="ngx_http_core_module.xml" id="limit_rate">rate
615 limit</link> for transmission of a response to a client;
616 </listitem>
617
618 <listitem>
619 <header>X-Accel-Buffering</header> enables or disables
620 <link id="scgi_buffering">buffering</link> of a response;
621 </listitem>
622
623 <listitem>
624 <header>X-Accel-Charset</header> sets the desired
625 <link doc="ngx_http_charset_module.xml" id="charset"/>
626 of a response.
627 </listitem>
628
629 </list>
630 </para>
631
632 </directive>
633
634
635 <directive name="scgi_intercept_errors">
636 <syntax><literal>on</literal> | <literal>off</literal></syntax>
637 <default>off</default>
638 <context>http</context>
639 <context>server</context>
640 <context>location</context>
641
642 <para>
643 Determines whether an SCGI server responses with codes greater than or equal
644 to 300 should be passed to a client or be redirected to nginx for processing
645 with the <link doc="ngx_http_core_module.xml" id="error_page"/> directive.
646 </para>
647
648 </directive>
649
650
651 <directive name="scgi_max_temp_file_size">
652 <syntax><value>size</value></syntax>
653 <default>1024m</default>
654 <context>http</context>
655 <context>server</context>
656 <context>location</context>
657
658 <para>
659 When <link id="scgi_buffering">buffering</link> of responses from the SCGI
660 server is enabled, and the whole response does not fit into the buffers
661 set by the <link id="scgi_buffer_size"/> and <link id="scgi_buffers"/>
662 directives, a part of the response can be saved to a temporary file.
663 This directive sets the maximum <value>size</value> of the temporary file.
664 The size of data written to the temporary file at a time is set
665 by the <link id="scgi_temp_file_write_size"/> directive.
666 </para>
667
668 <para>
669 The zero value disables buffering of responses to temporary files.
670 </para>
671
672 </directive>
673
674
675 <directive name="scgi_next_upstream">
676 <syntax>
677 <literal>error</literal> |
678 <literal>timeout</literal> |
679 <literal>invalid_header</literal> |
680 <literal>http_500</literal> |
681 <literal>http_503</literal> |
682 <literal>http_403</literal> |
683 <literal>http_404</literal> |
684 <literal>off</literal>
685 ...</syntax>
686 <default>error timeout</default>
687 <context>http</context>
688 <context>server</context>
689 <context>location</context>
690
691 <para>
692 Specifies in which cases a request should be passed to the next server:
693 <list type="tag">
694
695 <tag-name><literal>error</literal></tag-name>
696 <tag-desc>an error occurred while establishing a connection with the
697 server, passing a request to it, or reading the response header;</tag-desc>
698
699 <tag-name><literal>timeout</literal></tag-name>
700 <tag-desc>a timeout has occurred while establishing a connection with the
701 server, passing a request to it, or reading the response header;</tag-desc>
702
703 <tag-name><literal>invalid_header</literal></tag-name>
704 <tag-desc>a server returned an empty or invalid response;</tag-desc>
705
706 <tag-name><literal>http_500</literal></tag-name>
707 <tag-desc>a server returned a response with the code 500;</tag-desc>
708
709 <tag-name><literal>http_503</literal></tag-name>
710 <tag-desc>a server returned a response with the code 503;</tag-desc>
711
712 <tag-name><literal>http_403</literal></tag-name>
713 <tag-desc>a server returned a response with the code 403;</tag-desc>
714
715 <tag-name><literal>http_404</literal></tag-name>
716 <tag-desc>a server returned a response with the code 404;</tag-desc>
717
718 <tag-name><literal>off</literal></tag-name>
719 <tag-desc>disables passing a request to the next server.</tag-desc>
720
721 </list>
722 </para>
723
724 <para>
725 One should bear in mind that passing a request to the next server is
726 only possible if nothing has been sent to a client yet.
727 That is, if an error or timeout occurs in the middle of the
728 transferring of a response, fixing this is impossible.
729 </para>
730
731 <para>
732 The directive also defines what is considered an unsuccessful attempt
733 of communication with a
734 <link doc="ngx_http_upstream_module.xml" id="server"/>.
735 The cases of <literal>error</literal>, <literal>timeout</literal> and
736 <literal>invalid_header</literal> are always considered unsuccessful attempts,
737 even if they are not specified in the directive.
738 The cases of <literal>http_500</literal> and <literal>http_503</literal> are
739 considered unsuccessful attempts only if they are specified in the directive.
740 The cases of <literal>http_403</literal> and <literal>http_404</literal>
741 are never considered unsuccessful attempts.
742 </para>
743
744 </directive>
745
746
747 <directive name="scgi_no_cache">
748 <syntax><value>string</value> ...</syntax>
749 <default/>
750 <context>http</context>
751 <context>server</context>
752 <context>location</context>
753
754 <para>
755 Defines conditions under which the response will not be saved to a cache.
756 If at least one value of the string parameters is not empty and is not
757 equal to “0” then the response will not be saved:
758 <example>
759 scgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
760 scgi_no_cache $http_pragma $http_authorization;
761 </example>
762 Can be used along with the <link id="scgi_cache_bypass"/> directive.
763 </para>
764
765 </directive>
766
767
768 <directive name="scgi_param">
769 <syntax>
770 <value>parameter</value> <value>value</value>
771 [<literal>if_not_empty</literal>]</syntax>
772 <default/>
773 <context>http</context>
774 <context>server</context>
775 <context>location</context>
776
777 <para>
778 Sets a <value>parameter</value> that should be passed to the SCGI server.
779 The <value>value</value> can contain text, variables, and their combination.
780 These directives are inherited from the previous level if and
781 only if there are no
782 <literal>scgi_param</literal>
783 directives defined on the current level.
784 </para>
785
786 <para>
787 Standard
788 <link url="http://tools.ietf.org/html/rfc3875#section-4.1">CGI
789 environment variables</link>
790 should be provided as SCGI headers, see the <path>scgi_params</path> file
791 provided in the distribution:
792 <example>
793 location / {
794 include scgi_params;
795 ...
796 }
797 </example>
798 </para>
799
800 </directive>
801
802
803 <directive name="scgi_pass">
804 <syntax><value>address</value></syntax>
805 <default/>
806 <context>location</context>
807 <context>if in location</context>
808
809 <para>
810 Sets the address of an SCGI server.
811 The address can be specified as a domain name or IP address,
812 and an optional port:
813 <example>
814 scgi_pass localhost:9000;
815 </example>
816 or as a UNIX-domain socket path:
817 <example>
818 scgi_pass unix:/tmp/scgi.socket;
819 </example>
820 </para>
821
822 <para>
823 If a domain name resolves to several addresses, all of them will be
824 used in a round-robin fashion.
825 In addition, an address can be specified as a
826 <link doc="ngx_http_upstream_module.xml">server group</link>.
827 </para>
828
829 </directive>
830
831
832 <directive name="scgi_pass_header">
833 <syntax><value>field</value></syntax>
834 <default/>
835 <context>http</context>
836 <context>server</context>
837 <context>location</context>
838
839 <para>
840 Permits passing <link id="scgi_hide_header">otherwise disabled</link> header
841 fields from an SCGI server to a client.
842 </para>
843
844 </directive>
845
846
847 <directive name="scgi_read_timeout">
848 <syntax><value>time</value></syntax>
849 <default>60s</default>
850 <context>http</context>
851 <context>server</context>
852 <context>location</context>
853
854 <para>
855 Defines a timeout for reading a response from the SCGI server.
856 The timeout is set only between two successive read operations,
857 not for the transmission of the whole response.
858 If the SCGI server does not transmit anything within this time,
859 the connection is closed.
860 </para>
861
862 </directive>
863
864
865 <directive name="scgi_pass_request_body">
866 <syntax><literal>on</literal> | <literal>off</literal></syntax>
867 <default>on</default>
868 <context>http</context>
869 <context>server</context>
870 <context>location</context>
871
872 <para>
873 Indicates whether the original request body is passed
874 to the SCGI server.
875 See also the <link id="scgi_pass_request_headers"/> directive.
876 </para>
877
878 </directive>
879
880
881 <directive name="scgi_pass_request_headers">
882 <syntax><literal>on</literal> | <literal>off</literal></syntax>
883 <default>on</default>
884 <context>http</context>
885 <context>server</context>
886 <context>location</context>
887
888 <para>
889 Indicates whether the header fields of the original request are passed
890 to the SCGI server.
891 See also the <link id="scgi_pass_request_body"/> directive.
892 </para>
893
894 </directive>
895
896
897 <directive name="scgi_send_timeout">
898 <syntax><value>time</value></syntax>
899 <default>60s</default>
900 <context>http</context>
901 <context>server</context>
902 <context>location</context>
903
904 <para>
905 Sets a timeout for transmitting a request to the SCGI server.
906 The timeout is set only between two successive write operations,
907 not for the transmission of the whole request.
908 If the SCGI server does not receive anything within this time,
909 the connection is closed.
910 </para>
911
912 </directive>
913
914
915 <directive name="scgi_store">
916 <syntax>
917 <literal>on</literal> |
918 <literal>off</literal> |
919 <value>string</value></syntax>
920 <default>off</default>
921 <context>http</context>
922 <context>server</context>
923 <context>location</context>
924
925 <para>
926 Enables saving of files to a disk.
927 The <literal>on</literal> parameter saves files with paths
928 corresponding to the directives
929 <link doc="ngx_http_core_module.xml" id="alias"/> or
930 <link doc="ngx_http_core_module.xml" id="root"/>.
931 The <literal>off</literal> parameter disables saving of files.
932 In addition, the file name can be set explicitly using the
933 <value>string</value> with variables:
934 <example>
935 scgi_store /data/www$original_uri;
936 </example>
937 </para>
938
939 <para>
940 The modification time of files is set according to the received
941 <header>Last-Modified</header> response header field.
942 The response is first written to a temporary file,
943 and then the file is renamed.
944 Starting from version 0.8.9, temporary files and the persistent store
945 can be put on different file systems.
946 However, be aware that in this case a file is copied
947 across two file systems instead of the cheap renaming operation.
948 It is thus recommended that for any given location both saved files and a
949 directory holding temporary files, set by the <link id="scgi_temp_path"/>
950 directive, are put on the same file system.
951 </para>
952
953 <para>
954 This directive can be used to create local copies of static unchangeable
955 files, e.g.:
956 <example>
957 location /images/ {
958 root /data/www;
959 error_page 404 = /fetch$uri;
960 }
961
962 location /fetch/ {
963 internal;
964
965 scgi_pass backend:9000;
966 ...
967
968 scgi_store on;
969 scgi_store_access user:rw group:rw all:r;
970 scgi_temp_path /data/temp;
971
972 alias /data/www/;
973 }
974 </example>
975 </para>
976
977 </directive>
978
979
980 <directive name="scgi_store_access">
981 <syntax><value>users</value>:<value>permissions</value> ...</syntax>
982 <default>user:rw</default>
983 <context>http</context>
984 <context>server</context>
985 <context>location</context>
986
987 <para>
988 Sets access permissions for newly created files and directories, e.g.:
989 <example>
990 scgi_store_access user:rw group:rw all:r;
991 </example>
992 </para>
993
994 <para>
995 If any <literal>group</literal> or <literal>all</literal> access permissions
996 are specified then <literal>user</literal> permissions may be omitted:
997 <example>
998 scgi_store_access group:rw all:r;
999 </example>
1000 </para>
1001
1002 </directive>
1003
1004
1005 <directive name="scgi_temp_file_write_size">
1006 <syntax><value>size</value></syntax>
1007 <default>8k|16k</default>
1008 <context>http</context>
1009 <context>server</context>
1010 <context>location</context>
1011
1012 <para>
1013 Limits the <value>size</value> of data written to a temporary file
1014 at a time, when buffering of responses from the SCGI server
1015 to temporary files is enabled.
1016 By default, <value>size</value> is limited by two buffers set by the
1017 <link id="scgi_buffer_size"/> and <link id="scgi_buffers"/> directives.
1018 The maximum size of a temporary file is set by the
1019 <link id="scgi_max_temp_file_size"/> directive.
1020 </para>
1021
1022 </directive>
1023
1024
1025 <directive name="scgi_temp_path">
1026 <syntax>
1027 <value>path</value>
1028 [<value>level1</value>
1029 [<value>level2</value>
1030 [<value>level3</value>]]]</syntax>
1031 <default>scgi_temp</default>
1032 <context>http</context>
1033 <context>server</context>
1034 <context>location</context>
1035
1036 <para>
1037 Defines a directory for storing temporary files
1038 with data received from SCGI servers.
1039 Up to three-level subdirectory hierarchy can be used underneath the specified
1040 directory.
1041 For example, in the following configuration
1042 <example>
1043 scgi_temp_path /spool/nginx/scgi_temp 1 2;
1044 </example>
1045 a temporary file might look like this:
1046 <example>
1047 /spool/nginx/scgi_temp/<emphasis>7</emphasis>/<emphasis>45</emphasis>/00000123<emphasis>457</emphasis>
1048 </example>
1049 </para>
1050
1051 </directive>
1052
1053 </section>
1054
1055 </module>