FAQ

Page Discussion History

HttpScgiModule

Contents

Synopsis

This module allows Nginx to interact with SCGI processes and control what parameters are passed to the process. This page was mostly copied from the FastCGI and proxy documentation, and may not be entirely accurate as a result.

This module first appeared in nginx-0.8.42

Example:

location / {
  include scgi_params;
  scgi_pass localhost:9000;
}

Caching example:

http {
  scgi_cache_path   /path/to/cache  levels=1:2
                       keys_zone=NAME:10m
                       inactive=5m;
 
  server {
    location / {
      scgi_pass    127.0.0.1:9000;
      scgi_cache   NAME;
      scgi_cache_valid   200 302  1h;
      scgi_cache_valid   301      1d;
      scgi_cache_valid   any      1m;
      scgi_cache_min_uses  1;
      scgi_cache_use_stale error  timeout invalid_header http_500;
    }
  }
}

The cache honors backend's Cache-Control, Expires, and etc. Vary handling is not implemented.

Directives

scgi_bind

syntax: scgi_bind address

default: none

context: http, server, location

example:

scgi_bind  192.168.1.1;

Binds each upstream connection to a local address before calling connect(). It may be useful if host has several interfaces/aliases and you want to pass outgoing connections from specific interface/address.

scgi_buffer_size

syntax: scgi_buffer_size the_size

default: scgi_buffer_size 4k/8k

context: http, server, location

This directive sets the buffersize, into which will be read the first part of the response, obtained from the scgi server.

In this part of response the small response-header is located, as a rule.

By default, the buffer size is equal to the size of one buffer in directive scgi_buffers, however it is possible to set it to less.

scgi_buffering

syntax: scgi_buffering on | off

default: scgi_buffering on

context: http, server, location

version: 1.1.5

variables: no

This directive controls response buffering of the response.

If buffering is activated, then nginx reads the response from the upstream server as fast as possible, saving it in the buffer as configured by directives scgi_buffer_size and scgi_buffers. If the response does not fit into memory, then parts of it will be written to disk.

If buffering is switched off, then the response is synchronously transferred to client immediately as it is received. nginx does not attempt to read the entire answer from the upstream server, the maximum size of data which nginx can accept from the server is set by directive scgi_buffer_size.

For Comet applications based on long-polling it is important to set scgi_buffering to off, otherwise the asynchronous response is buffered and the Comet does not work.

Buffering can be set on a per-request basis by setting the X-Accel-Buffering header in the response.

scgi_buffers

syntax: scgi_buffers the_number is_size

default: scgi_buffers 8 4k/8k

context: http, server, location

This directive sets the number and the size of buffers, into which will be read the answer, obtained from the scgi server. By default, the size of one buffer is equal to the size of page. Depending on platform this is either 4K, 8K or 16K.

scgi_busy_buffers_size

syntax: scgi_busy_buffers_size size

default: scgi_busy_buffers_size ["#scgi_buffer_size"] * 2

context: http, server, location, if

Undocumented

scgi_cache

syntax: scgi_cache zone|off

default: off

context: http, server, location

The directive specifies the area which actually is the share memory's name for caching. The same area can be used in several places.

scgi_cache_bypass

syntax: scgi_cache_bypass variable1 variable2...

default: none

context: http, server, location

version: >= 0.8.46

Specifies in what cases a request will bypass a cached response and pass the request to upstream.

scgi_cache_bypass $cookie_nocache  $arg_nocache$arg_comment;
scgi_cache_bypass $http_pragma     $http_authorization;

The expression is false if it is equal to the empty string or "0". For instance, in the above example, the request will always go through to the back-end if the cookie "nocache" is set in the request.

Note that the response from the back-end is still eligible for caching. Thus one way of refreshing an item in the cache is sending a request with a header you pick yourself, e.g. "My-Secret-Header: 1", then having a scgi_no_cache line like:

scgi_no_cache $http_my_secret_header;

scgi_cache_key

syntax: scgi_cache_key line

default: none

context: http, server, location

The directive sets the key for caching, for example:

scgi_cache_key localhost:9000$request_uri;

scgi_cache_methods

syntax: scgi_cache_methods [GET HEAD POST]

default: scgi_cache_methods GET HEAD

context: http, server, location

GET/HEAD is syntax sugar, i.e. you can not disable GET/HEAD even if you set just

scgi_cache_methods POST;

scgi_cache_min_uses

syntax: scgi_cache_min_uses the_number

default: scgi_cache_min_uses 1

context: http, server, location

Directive specifies after how many requests to the same URL in will be cached.

scgi_cache_path

syntax: scgi_cache_path path [levels=m:n] keys_zone=name:size [inactive=time] [max_size=size]

default: none

context: http

The clean_time parameter was removed in 0.7.45.

This directive specifies path to the cache storage and other cache parameters. All data is stored in the files. The cache key and the name of cache file are calculated as MD5 sum of the proxied URL.

Level parameter sets number and width of the names of subdirectories used to store caching files. For example, with the directive like:

scgi_cache_path  /data/nginx/cache  levels=1:2   keys_zone=one:10m;

the data will be stored in the following file:

/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c

Caching data is first written to the temporary file which is then moved to the final location in a cache directory. Starting from 0.8.9 it is possible to store temporary and cache files on different file systems, but it should be kept in mind that in such a case instead of cheap and atomic rename syscall a full file copy is performed. So it's better to use the same file system in both parameters of scgi_temp_path and scgi_cache_path directives.

In addition, all active keys and information about data are kept in the shared memory zone, which name and size are specified by the options of the key_zone parameter. In case this data haven't been accessed for the time, specified in the option of inactive parameter, it is wiped out from the memory. By default inactive period is set to 10 minutes.

To maintain the maximum size of the cache, which is set by max_size parameter, a special process cache manager periodically deletes old data from the cache.

scgi_cache_use_stale

syntax: scgi_cache_use_stale updating|error|timeout|invalid_header|http_500

default: scgi_cache_use_stale off

context: http, server, location

Determines whether or not Nginx will serve stale cached data in case of gateway event such as error, timeout etc.

scgi_cache_valid

syntax: scgi_cache_valid [http_return_code [...]] time

default: none

context: http, server, location

Directive sets caching period for the specified http return codes. For example:

scgi_cache_valid  200 302  10m;
scgi_cache_valid  404      1m;

sets caching period of 10 minutes for return codes 200 and 302 and 1 minute for the 404 code.

In case only caching period is specified:

scgi_cache_valid  5m;

the default behavior is to cache only replies with the codes 200, 301 and 302.

It's also possible to cache all the replies by specifying code "any":

 
scgi_cache_valid  200 302 10m;
scgi_cache_valid  301 1h;
scgi_cache_valid  any 1m;

scgi_connect_timeout

syntax: scgi_connect_timeout time

default: scgi_connect_timeout 60

context: http, server, location

Directive sets timeout period for connection with SCGI-server. It should be noted that this value can't exceed 75 seconds.

scgi_hide_header

syntax: scgi_hide_header name

context: http, server, location

By default, Nginx does not pass headers "Status" and "X-Accel-..." from the SCGI process back to the client. This directive can be used to hide other headers as well.

If the headers "Status" and "X-Accel-..." must be provided, then it is necessary to use directive scgi_pass_header to force them to be returned to the client.

scgi_ignore_client_abort

syntax: scgi_ignore_client_abort on|off

default: scgi_ignore_client_abort off

context: http, server, location

This directive determines if current request to the SCGI-server must be aborted in case the client aborts the request to the server.

scgi_ignore_headers

syntax: scgi_ignore_headers name [name...]

context: http, server, location

This directive forbids processing of the named headers from the SCGI-server reply. It is possible to specify headers like "X-Accel-Redirect", "X-Accel-Expires", "Expires" or "Cache-Control".

scgi_intercept_errors

syntax: scgi_intercept_errors on|off

default: scgi_intercept_errors off

context: http, server, location

This directive determines whether or not to transfer 4xx and 5xx errors back to the client or to allow Nginx to answer with directive error_page.

Note: You need to explicitly define the error_page handler for this for it to be useful. As Igor says, "nginx does not intercept an error if there is no custom handler for it it does not show its default pages. This allows to intercept some errors, while passing others as are."

scgi_max_temp_file_size

syntax: scgi_max_temp_file_size 0

default: ?

context: ?

This directive turns off scgi buffering according to the source code.

scgi_next_upstream

syntax: scgi_next_upstream error|timeout|invalid_header|http_500|http_503|http_404|off

default: scgi_next_upstream error timeout

context: http, server, location

This directive defines in which cases request will be passed to the next server:

  • error — an error occurred during connection to the server, passing request to it or reading server respond header;
  • timeout — a timeout occurred during connection to the server, passing request to it or reading server respond header;
  • invalid_header — server returned empty or invalid answer;
  • http_500 — server returned 500 respond;
  • http_503 — server returned 503 respond;
  • http_404 — server returned 404 respond;
  • off — explicitly forbids passing request to the next server;

It should be clear that passing request to the next server is possible only if no data have been yet returned to the client. So, if the error or timeout occurred during the data transmission to the client it's too late to fix it.

scgi_no_cache

syntax: scgi_no_cache variable [...]

default: none

context: http, server, location

Specifies in what cases the responses will not be stored, e.g.

scgi_no_cache $cookie_nocache  $arg_nocache$arg_comment;
scgi_no_cache $http_pragma     $http_authorization;

The expression is false if it is equal to the empty string or "0". For instance, in the above example, the response will not be stored if the cookie "nocache" is set in the request.

scgi_param

syntax: scgi_param parameter value

default: none

context: http, server, location

Directive assigns the parameter, which will be transferred to the SCGI-server.

It is possible to use strings, variables and their combination as values. Directives not set are inherited from the outer level. Directives set in current level clear any previously defined directives for the current level.

scgi_param  SCGI             1;
scgi_param  REQUEST_URI      $request_uri;

Parameter REQUEST_URI is used to determine the name of script to execute, and QUERY_STRING contains the parameters of the request. scgi_param SCGI 1; is required to be in the list of parameters by the SCGI standard. scgi_param CONTENT_LENGTH $content_length; is automatically included as the first parameter.

If dealing with POST requests, two additional parameters are necessary.

  scgi_param  REQUEST_METHOD   $request_method;
  scgi_param  CONTENT_TYPE     $content_type;

scgi_pass

syntax: scgi_pass scgi-server

default: none

context: location, if in location

Directive assigns the port or socket on which the SCGI-server is listening. Port can be indicated by itself or as an address and port, for example:

  scgi_pass   localhost:9000;

using a Unix domain socket:

  scgi_pass   unix:/tmp/scgi.socket;

You may also use an upstream block.

upstream backend  {
  server   localhost:1234;
}
 
scgi_pass   backend;

scgi_pass_header

syntax: scgi_pass_header name

context: http, server, location

This directive explicitly allows to pass named headers to the client.

scgi_pass_request_body

syntax: scgi_pass_request_body on|off

default: scgi_pass_request_body on

context: http, server, location

Defines whether or not the request body should be passed to the scgi. Should usually be left on.

scgi_pass_request_headers

syntax: scgi_pass_request_headers on|off

default: scgi_pass_request_headers on

context: http, server, location

Defines whether or not the request headers should be passed to the scgi. Should usually be left on.

scgi_read_timeout

syntax: scgi_read_timeout time

default: scgi_read_timeout 60

context: http, server, location

Directive sets the amount of time for upstream to wait for a scgi process to send data. Change this directive if you have long running scgi processes that do not produce output until they have finished processing. If you are seeing an upstream timed out error in the error log, then increase this parameter to something more appropriate.

scgi_send_timeout

syntax: scgi_send_timeout time

default: scgi_send_timeout 60

context: http, server, location

Directive specifies request timeout to the server. The timeout is calculated between two write operations, not for the whole request. If no data have been written during this period then serve closes the connection.

scgi_store

syntax: scgi_store on|off|path

default: scgi_store off

context: http, server, location

This directive sets the path in which upstream files are stored. The parameter "on" preserves files in accordance with path specified in directives alias or root. The parameter "off" forbids storing. Furthermore, the name of the path can be clearly assigned with the aid of the line with the variables:

scgi_store   /data/www$original_uri;

The time of modification for the file will be set to the date of "Last-Modified" header in the response. To be able to safe files in this directory it is necessary that the path is under the directory with temporary files, given by directive scgi_temp_path for the data location.

This directive can be used for creating the local copies for dynamic output of the backend which is not very often changed, for example:

location /images/ {
  root                /data/www;
  error_page          404 = /fetch$uri;
}
 
location /fetch {
  internal;
 
  scgi_pass           scgi://backend;
  scgi_store          on;
  scgi_store_access   user:rw  group:rw  all:r;
  scgi_temp_path      /data/temp;
 
  alias               /data/www;
}

To be clear scgi_store is not a cache, it's rather mirror on demand.

scgi_store_access

syntax: scgi_store_access users:permissions [users:permission ...]

default: scgi_store_access user:rw

context: http, server, location

This directive assigns the permissions for the created files and directories, for example:

scgi_store_access  user:rw  group:rw  all:r;

If any rights for groups or all are assigned, then it is not necessary to assign rights for user:

scgi_store_access  group:rw  all:r;

scgi_temp_file_write_size

syntax: scgi_temp_file_write_size size

default: scgi_temp_file_write_size ["#scgi_buffer_size"] * 2

context: http, server, location, if

Sets the amount of data that will be flushed to the scgi_temp_path when writing. It may be used to prevent a worker process blocking for too long while spooling data.

scgi_temp_path

syntax: scgi_temp_path path [level1 [level2 [level3]]]

default: scgi_temp_path scgi_temp

context: http, server, location

This directive sets the path where to store temporary files received from another server. It is possible to use up to 3 levels of subdirectories to create hashed storage. Level value specifies how many symbols will be used for hashing. For example, in the following configuration:

scgi_temp_path  /spool/nginx/scgi_temp 1 2;

Temporary file name may look like:

/spool/nginx/scgi_temp/7/45/00000123457

Parameters transferred to SCGI-server.

The request headers are transferred to the SCGI-server in the form of parameters. In the applications and the scripts run from the SCGI-server, these parameters are usually accessible in the form of environment variables. For example, the header "User-agent" is transferred as parameter HTTP_USER_AGENT. Besides the headers of the HTTP request, it is possible to transfer arbitrary parameters with the aid of directive scgi_param.

References