# HG changeset patch # User Yaroslav Zhuravlev # Date 1398434414 -14400 # Node ID 9d3beb5890eb0cc568a1cf3ba128f080cd49d588 # Parent f2d939ac04498b9ad9879675bc5edd6b4cecbc21 Documented the scgi module. diff --git a/xml/en/GNUmakefile b/xml/en/GNUmakefile --- a/xml/en/GNUmakefile +++ b/xml/en/GNUmakefile @@ -68,6 +68,7 @@ REFS = \ http/ngx_http_realip_module \ http/ngx_http_referer_module \ http/ngx_http_rewrite_module \ + http/ngx_http_scgi_module \ http/ngx_http_secure_link_module \ http/ngx_http_spdy_module \ http/ngx_http_session_log_module \ diff --git a/xml/en/docs/http/ngx_http_scgi_module.xml b/xml/en/docs/http/ngx_http_scgi_module.xml new file mode 100644 --- /dev/null +++ b/xml/en/docs/http/ngx_http_scgi_module.xml @@ -0,0 +1,1055 @@ + + + + + + + + +
+ + +The ngx_http_scgi_module module allows passing +requests to an SCGI server. + + +
+ + +
+ + + +location / { + include scgi_params; + scgi_pass localhost:9000; +} + + + +
+ + +
+ + +address | off + +http +server +location + + +Makes outgoing connections to an SCGI server originate +from the specified local IP address. +Parameter value can contain variables (1.3.12). +The special value off (1.3.12) cancels the effect +of the scgi_bind directive +inherited from the previous configuration level, which allows the +system to auto-assign the local IP address. + + + + + + +size +4k|8k +http +server +location + + +Sets the size of the buffer used for reading the first part +of the response received from the SCGI server. +This part usually contains a small response header. +By default, the buffer size is equal to the size of one +buffer set by the directive. +It can be made smaller, however. + + + + + + +on | off +on +http +server +location + + +Enables or disables buffering of responses from the SCGI server. + + + +When buffering is enabled, nginx receives a response from the SCGI server +as soon as possible, saving it into the buffers set by the + and directives. +If the whole response does not fit into memory, a part of it can be saved +to a temporary file on the disk. +Writing to temporary files is controlled by the + and + directives. + + + +When buffering is disabled, the response is passed to a client synchronously, +immediately as it is received. +nginx will not try to read the whole response from the SCGI server. +The maximum size of the data that nginx can receive from the server +at a time is set by the directive. + + + +Buffering can also be enabled or disabled by passing +“yes” or “no” in the +
X-Accel-Buffering
response header field. +This capability can be disabled using the + directive. + + + + + + +number size +8 4k|8k +http +server +location + + +Sets the number and size of the +buffers used for reading a response from the SCGI server, +for a single connection. +By default, the buffer size is equal to one memory page. +This is either 4K or 8K, depending on a platform. + + + + + + +size +8k|16k +http +server +location + + +When buffering of responses from the SCGI +server is enabled, limits the total size of buffers that +can be busy sending a response to the client while the response is not +yet fully read. +In the meantime, the rest of the buffers can be used for reading the response +and, if needed, buffering part of the response to a temporary file. +By default, size is limited by the size of two buffers set by the + and directives. + + + + + + +zone | off +off +http +server +location + + +Defines a shared memory zone used for caching. +The same zone can be used in several places. +The off parameter disables caching inherited +from the previous configuration level. + + + + + + +string ... + +http +server +location + + +Defines conditions under which the response will not be taken from a cache. +If at least one value of the string parameters is not empty and is not +equal to “0” then the response will not be taken from the cache: + +scgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment; +scgi_cache_bypass $http_pragma $http_authorization; + +Can be used along with the directive. + + + + + + +string + +http +server +location + + +Defines a key for caching, for example + +scgi_cache_key localhost:9000$request_uri; + + + + + + + +on | off +off +http +server +location +1.1.12 + + +When enabled, only one request at a time will be allowed to populate +a new cache element identified according to the +directive by passing a request to an SCGI server. +Other requests of the same cache element will either wait +for a response to appear in the cache or the cache lock for +this element to be released, up to the time set by the + directive. + + + + + + +time +5s +http +server +location +1.1.12 + + +Sets a timeout for . + + + + + + + + GET | + HEAD | + POST + ... +GET HEAD +http +server +location + + +If the client request method is listed in this directive then +the response will be cached. +“GET” and “HEAD” methods are always +added to the list, though it is recommended to specify them explicitly. +See also the directive. + + + + + + +number +1 +http +server +location + + +Sets the number of requests after which the response +will be cached. + + + + + + + + path + [levels=levels] + keys_zone=name:size + [inactive=time] + [max_size=size] + [loader_files=number] + [loader_sleep=time] + [loader_threshold=time] + +http + + +Sets the path and other parameters of a cache. +Cache data are stored in files. +Both the key and file name in a cache are a result of +applying the MD5 function to the proxied URL. +The levels parameter defines hierarchy levels of a cache. +For example, in the following configuration + +scgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m; + +file names in a cache will look like this: + +/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c + + + + +A cached response is first written to a temporary file, +and then the file is renamed. +Starting from version 0.8.9, temporary files and the cache can be put on +different file systems. +However, be aware that in this case a file is copied +across two file systems instead of the cheap renaming operation. +It is thus recommended that for any given location both cache and a directory +holding temporary files, set by the directive, +are put on the same file system. + + + +In addition, all active keys and information about data are stored +in a shared memory zone, whose name and size +are configured by the keys_zone parameter. +Cached data that are not accessed during the time specified by the +inactive parameter get removed from the cache +regardless of their freshness. +By default, inactive is set to 10 minutes. + + + +The special “cache manager” process monitors the maximum cache size set +by the max_size parameter. +When this size is exceeded, it removes the least recently used data. + + + +A minute after the start the special “cache loader” process is activated. +It loads information about previously cached data stored on file system +into a cache zone. +The loading is done in iterations. +During one iteration no more than loader_files items +are loaded (by default, 100). +Besides, the duration of one iteration is limited by the +loader_threshold parameter (by default, 200 milliseconds). +Between iterations, a pause configured by the loader_sleep +parameter (by default, 50 milliseconds) is made. + + + + + + +string ... + +http +server +location +1.5.7 + + +Defines conditions under which the request will be considered a cache +purge request. +If at least one value of the string parameters is not empty and is not equal +to “0” then the cache entry with a corresponding +cache key is removed. +The result of successful operation is indicated by returning +the response. + + + +If the cache key of a purge request ends +with an asterisk (“*”), all cache entries matching the +wildcard key will be removed from the cache. + + + +Example configuration: + +scgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m; + +map $request_method $purge_method { + PURGE 1; + default 0; +} + +server { + ... + location / { + scgi_pass backend; + scgi_cache cache_zone; + scgi_cache_key $uri; + scgi_cache_purge $purge_method; + } +} + + +This functionality is available as part of our +commercial subscription. + + + + + + + +on | off +off +http +server +location +1.5.7 + + +Enables revalidation of expired cache items using conditional requests with +the
If-Modified-Since
header field. + + + + + + + + error | + timeout | + invalid_header | + updating | + http_500 | + http_503 | + http_403 | + http_404 | + off + ... +off +http +server +location + + +Determines in which cases a stale cached response can be used +when an error occurs during communication with the SCGI server. +The directive’s parameters match the parameters of the + directive. + + + +Additionally, the updating parameter permits +using a stale cached response if it is currently being updated. +This allows minimizing the number of accesses to SCGI servers +when updating cached data. + + + +To minimize the number of accesses to SCGI servers when +populating a new cache element, the +directive can be used. + + + + + + +[code ...] time + +http +server +location + + +Sets caching time for different response codes. +For example, the following directives + +scgi_cache_valid 200 302 10m; +scgi_cache_valid 404 1m; + +set 10 minutes of caching for responses with codes 200 and 302 +and 1 minute for responses with code 404. + + + +If only caching time is specified + +scgi_cache_valid 5m; + +then only 200, 301, and 302 responses are cached. + + + +In addition, the any parameter can be specified +to cache any responses: + +scgi_cache_valid 200 302 10m; +scgi_cache_valid 301 1h; +scgi_cache_valid any 1m; + + + + +Parameters of caching can also be set directly +in the response header. +This has higher priority than setting of caching time using the directive. +The
X-Accel-Expires
header field sets caching time of a +response in seconds. +The zero value disables caching for a response. +If the value starts with the @ prefix, it sets an absolute +time in seconds since Epoch, up to which the response may be cached. +If the header does not include the
X-Accel-Expires
field, +parameters of caching may be set in the header fields +
Expires
or
Cache-Control
. +If the header includes the
Set-Cookie
field, such a +response will not be cached. +Processing of one or more of these response header fields can be disabled +using the directive. + + + + + + +time +60s +http +server +location + + +Defines a timeout for establishing a connection with an SCGI server. +It should be noted that this timeout cannot usually exceed 75 seconds. + + + + + + +field + +http +server +location + + +By default, +nginx does not pass the header fields
Status
and +
X-Accel-...
from the response of an SCGI +server to a client. +The scgi_hide_header directive sets additional fields +that will not be passed. +If, on the contrary, the passing of fields needs to be permitted, +the directive can be used. + + + + + + +on | off +off +http +server +location + + +Determines whether the connection with an SCGI server should be +closed when a client closes the connection without waiting +for a response. + + + + + + +field ... + +http +server +location + + +Disables processing of certain response header fields from the SCGI server. +The following fields can be ignored:
X-Accel-Redirect
, +
X-Accel-Expires
,
X-Accel-Limit-Rate
(1.1.6), +
X-Accel-Buffering
(1.1.6), +
X-Accel-Charset
(1.1.6),
Expires
, +
Cache-Control
, and
Set-Cookie
(0.8.44). + + + +If not disabled, processing of these header fields has the following +effect: + + + +
X-Accel-Expires
,
Expires
, +
Cache-Control
, and
Set-Cookie
+set the parameters of response caching; + + + +
X-Accel-Redirect
performs an +internal +redirect to the specified URI; + + + +
X-Accel-Limit-Rate
sets the +rate +limit for transmission of a response to a client; + + + +
X-Accel-Buffering
enables or disables +buffering of a response; + + + +
X-Accel-Charset
sets the desired + +of a response. + + + + + + + + + +on | off +off +http +server +location + + +Determines whether an SCGI server responses with codes greater than or equal +to 300 should be passed to a client or be redirected to nginx for processing +with the directive. + + + + + + +size +1024m +http +server +location + + +When buffering of responses from the SCGI +server is enabled, and the whole response does not fit into the buffers +set by the and +directives, a part of the response can be saved to a temporary file. +This directive sets the maximum size of the temporary file. +The size of data written to the temporary file at a time is set +by the directive. + + + +The zero value disables buffering of responses to temporary files. + + + + + + + + error | + timeout | + invalid_header | + http_500 | + http_503 | + http_403 | + http_404 | + off + ... +error timeout +http +server +location + + +Specifies in which cases a request should be passed to the next server: + + +error +an error occurred while establishing a connection with the +server, passing a request to it, or reading the response header; + +timeout +a timeout has occurred while establishing a connection with the +server, passing a request to it, or reading the response header; + +invalid_header +a server returned an empty or invalid response; + +http_500 +a server returned a response with the code 500; + +http_503 +a server returned a response with the code 503; + +http_403 +a server returned a response with the code 403; + +http_404 +a server returned a response with the code 404; + +off +disables passing a request to the next server. + + + + + +One should bear in mind that passing a request to the next server is +only possible if nothing has been sent to a client yet. +That is, if an error or timeout occurs in the middle of the +transferring of a response, fixing this is impossible. + + + +The directive also defines what is considered an unsuccessful attempt +of communication with a +. +The cases of error, timeout and +invalid_header are always considered unsuccessful attempts, +even if they are not specified in the directive. +The cases of http_500 and http_503 are +considered unsuccessful attempts only if they are specified in the directive. +The cases of http_403 and http_404 +are never considered unsuccessful attempts. + + + + + + +string ... + +http +server +location + + +Defines conditions under which the response will not be saved to a cache. +If at least one value of the string parameters is not empty and is not +equal to “0” then the response will not be saved: + +scgi_no_cache $cookie_nocache $arg_nocache$arg_comment; +scgi_no_cache $http_pragma $http_authorization; + +Can be used along with the directive. + + + + + + + + parameter value + [if_not_empty] + +http +server +location + + +Sets a parameter that should be passed to the SCGI server. +The value can contain text, variables, and their combination. +These directives are inherited from the previous level if and +only if there are no +scgi_param +directives defined on the current level. + + + +Standard +CGI +environment variables +should be provided as SCGI headers, see the scgi_params file +provided in the distribution: + +location / { + include scgi_params; + ... +} + + + + + + + +address + +location +if in location + + +Sets the address of an SCGI server. +The address can be specified as a domain name or IP address, +and an optional port: + +scgi_pass localhost:9000; + +or as a UNIX-domain socket path: + +scgi_pass unix:/tmp/scgi.socket; + + + + +If a domain name resolves to several addresses, all of them will be +used in a round-robin fashion. +In addition, an address can be specified as a +server group. + + + + + + +field + +http +server +location + + +Permits passing otherwise disabled header +fields from an SCGI server to a client. + + + + + + +time +60s +http +server +location + + +Defines a timeout for reading a response from the SCGI server. +The timeout is set only between two successive read operations, +not for the transmission of the whole response. +If the SCGI server does not transmit anything within this time, +the connection is closed. + + + + + + +on | off +on +http +server +location + + +Indicates whether the original request body is passed +to the SCGI server. +See also the directive. + + + + + + +on | off +on +http +server +location + + +Indicates whether the header fields of the original request are passed +to the SCGI server. +See also the directive. + + + + + + +time +60s +http +server +location + + +Sets a timeout for transmitting a request to the SCGI server. +The timeout is set only between two successive write operations, +not for the transmission of the whole request. +If the SCGI server does not receive anything within this time, +the connection is closed. + + + + + + + + on | + off | + string +off +http +server +location + + +Enables saving of files to a disk. +The on parameter saves files with paths +corresponding to the directives + or +. +The off parameter disables saving of files. +In addition, the file name can be set explicitly using the +string with variables: + +scgi_store /data/www$original_uri; + + + + +The modification time of files is set according to the received +
Last-Modified
response header field. +The response is first written to a temporary file, +and then the file is renamed. +Starting from version 0.8.9, temporary files and the persistent store +can be put on different file systems. +However, be aware that in this case a file is copied +across two file systems instead of the cheap renaming operation. +It is thus recommended that for any given location both saved files and a +directory holding temporary files, set by the +directive, are put on the same file system. + + + +This directive can be used to create local copies of static unchangeable +files, e.g.: + +location /images/ { + root /data/www; + error_page 404 = /fetch$uri; +} + +location /fetch/ { + internal; + + scgi_pass backend:9000; + ... + + scgi_store on; + scgi_store_access user:rw group:rw all:r; + scgi_temp_path /data/temp; + + alias /data/www/; +} + + + + + + + +users:permissions ... +user:rw +http +server +location + + +Sets access permissions for newly created files and directories, e.g.: + +scgi_store_access user:rw group:rw all:r; + + + + +If any group or all access permissions +are specified then user permissions may be omitted: + +scgi_store_access group:rw all:r; + + + + + + + +size +8k|16k +http +server +location + + +Limits the size of data written to a temporary file +at a time, when buffering of responses from the SCGI server +to temporary files is enabled. +By default, size is limited by two buffers set by the + and directives. +The maximum size of a temporary file is set by the + directive. + + + + + + + + path + [level1 + [level2 + [level3]]] +scgi_temp +http +server +location + + +Defines a directory for storing temporary files +with data received from SCGI servers. +Up to three-level subdirectory hierarchy can be used underneath the specified +directory. +For example, in the following configuration + +scgi_temp_path /spool/nginx/scgi_temp 1 2; + +a temporary file might look like this: + +/spool/nginx/scgi_temp/7/45/00000123457 + + + + + +
+ + diff --git a/xml/en/docs/index.xml b/xml/en/docs/index.xml --- a/xml/en/docs/index.xml +++ b/xml/en/docs/index.xml @@ -8,7 +8,7 @@
@@ -333,6 +333,11 @@ ngx_http_rewrite_module + +ngx_http_scgi_module + + + ngx_http_secure_link_module