1180
|
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>
|