HttpFastcgiModule

WARNING: this article is obsoleted. Please refer to http://nginx.org/en/docs/ for the latest official documentation.

= Synopsis = This module allows Nginx to interact with FastCGI processes and control what parameters are passed to the process.

Example location / { fastcgi_pass  localhost:9000; fastcgi_index index.php;

fastcgi_param SCRIPT_FILENAME  $document_root/php/$fastcgi_script_name; fastcgi_param QUERY_STRING     $query_string; fastcgi_param REQUEST_METHOD   $request_method; fastcgi_param CONTENT_TYPE     $content_type; fastcgi_param CONTENT_LENGTH   $content_length; }

Caching example: http { fastcgi_cache_path  /path/to/cache  levels=1:2 keys_zone=NAME:10m inactive=5m; fastcgi_cache_key "$scheme$request_method$host$request_uri";

server { location / { fastcgi_pass   127.0.0.1:9000; fastcgi_cache  NAME; fastcgi_cache_valid  200 302  1h; fastcgi_cache_valid  301      1d; fastcgi_cache_valid  any      1m; fastcgi_cache_min_uses 1; fastcgi_cache_use_stale error timeout invalid_header http_500; } } }

The cache honors backend's Cache-Control, Expires, and etc. since version 0.7.48, Cache-Control: private and no-store only since 0.7.66, though. Vary handling is not implemented.

= Directives =

fastcgi_bind
syntax: fastcgi_bind address

default: none

context: http, server, location

version: &ge; 0.8.22

example: fastcgi_bind 192.168.1.1;

This directive binds each upstream socket 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.

fastcgi_buffer_size


This directive sets the buffer size for reading the header of the backend FastCGI process.

By default, the buffer size is equal to the size of one buffer in fastcgi_buffers. This directive allows you to set it to an arbitrary value.

fastcgi_buffers


This directive sets the number and the size of the buffers into which the reply from the FastCGI process in the backend is read.

fastcgi_buffers should be set to the typical fastcgi response size. You should handle most of responses in memory while the biggest responses are buffered to disk.

If you want to disable buffering to disk for all replies that are greater than the FastCGI buffers and transfer data synchronously to the client set fastcgi_max_temp_file_size to 0.

The fastcgi_buffer is equivalent to:

If a fastcgi response is 12k then  will allocated 3 buffers of 4k. This is why fastcgi_buffers has two parameters, while fastcgi_buffer_size (used for response header and first part) has just one paramter. After fastcgi_buffer_size has been emptied, it used together with fastcgi_buffers.

Example: fastcgi_buffers 256 4k; # Sets the buffer size to 4k + 256 * 4k = 1028k This means that any reply by the FastCGI process in the backend greater than 1M goes to disk. Only replies below 1M are handled directly in memory.

By default, the size of each buffer is equal to the OS page size. Depending on the platform and architecture this value is one of 4k, 8k or 16k.

On Linux you can get the page size issuing: getconf PAGESIZE it returns the page size in bytes.

fastcgi_busy_buffers_size


fastcgi_cache


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

fastcgi_cache_bypass


fastcgi_cache_key


The directive sets the key for caching, for example: fastcgi_cache_key "$scheme$request_method$host$request_uri";

Be advised that a  request can cause an empty response to be cached & later be distributed to   requests, avoid this by having $request_method in the cache key. Including the $scheme for the same reason may be beneficial to avoid serving up pages with insecure content to HTTPS visitors (or vice-versa).

fastcgi_cache_lock


fastcgi_cache_lock_timeout


fastcgi_cache_methods
syntax: fastcgi_cache_methods [GET HEAD POST];

default: fastcgi_cache_methods GET HEAD;

context: main, http, location

This directive specifies which HTTP methods are allowed to be used when caching FastCGI requests. Note that GET and HEAD are syntactic sugars, i.e., a mere convenience in terms of this directive configuration logic. They cannot be disabled even if you set: fastcgi_cache_methods POST; # note that GET and HEAD are still enabled

fastcgi_cache_min_uses


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

fastcgi_cache_path


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: fastcgi_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 fastcgi_temp_path and  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  parameter. In case this data haven't been accessed for the time, specified in the option of  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  parameter, a special process cache manager periodically deletes old data from the cache.

fastcgi_cache_use_stale


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

fastcgi_cache_valid


Directive sets caching period for the specified http return codes. For example: fastcgi_cache_valid 200 302  10m; fastcgi_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: fastcgi_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": fastcgi_cache_valid 200 302 10m; fastcgi_cache_valid 301 1h; fastcgi_cache_valid any 1m;

fastcgi_connect_timeout


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

fastcgi_hide_header


By default, Nginx does not pass headers "Status" and "X-Accel-..." from the FastCGI 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 fastcgi_pass_header to force them to be returned to the client.

fastcgi_ignore_client_abort


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

In 1.0.2 POST requests are not handled correctly when fastcgi_ignore_client_abort is set to on which can lead to workers processes segfaulting. Switching fastcgi_ignore_client_abort back to default (off) should resolve this issue.

fastcgi_ignore_headers


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

fastcgi_index
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_fastcgi_module/fastcgi_index.txt" />

The name of the file which will be appended to the URI and stored in the variable $fastcgi_script_name if URI concludes with a slash.

For example: fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME  $document_root$fastcgi_script_name; for the request "/page.php" parameter SCRIPT_FILENAME will be set to "/home/www/scripts/php/page.php", but for the "/" — "/home/www/scripts/php/index.php".

fastcgi_intercept_errors
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_fastcgi_module/fastcgi_intercept_errors.txt" />

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."

fastcgi_keep_conn
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_fastcgi_module/fastcgi_keep_conn.txt" />

fastcgi_max_temp_file_size
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_fastcgi_module/fastcgi_max_temp_file_size.txt" />

To disable buffering to temporary files on disk for all replies that are greater than the fastcgi_buffers and transfer data synchronously to the client set fastcgi_max_temp_file_size to 0.

Otherwise if specified it must be equal or bigger than maximum of the value of fastcgi_buffer_size and one of the fastcgi_buffers.

fastcgi_next_upstream
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_fastcgi_module/fastcgi_next_upstream.txt" />

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.

fastcgi_no_cache
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_fastcgi_module/fastcgi_no_cache.txt" />

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

fastcgi_no_cache $cookie_nocache $arg_nocache$arg_comment; fastcgi_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 cache will be bypassed if the cookie "nocache" is set in the request.

fastcgi_param
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_fastcgi_module/fastcgi_param.txt" />

Directive assigns the parameter, which will be transferred to the FastCGI-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.

Below is an example of the minimally necessary parameters for PHP: fastcgi_param SCRIPT_FILENAME  /home/www/scripts/php$fastcgi_script_name; fastcgi_param QUERY_STRING     $query_string;

Parameter SCRIPT_FILENAME is used by PHP for determining the name of script to execute, and QUERY_STRING contains the parameters of the request.

If dealing with POST requests, then the three additional parameters are necessary. Below is an example of the minimally necessary parameters for PHP: fastcgi_param REQUEST_METHOD   $request_method; fastcgi_param CONTENT_TYPE     $content_type; fastcgi_param CONTENT_LENGTH   $content_length;

If PHP was compiled with --enable-force-cgi-redirect, then it is necessary to transfer parameter REDIRECT_STATUS with the value of "200": fastcgi_param REDIRECT_STATUS  200;

fastcgi_pass
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_fastcgi_module/fastcgi_pass.txt" />

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

using a Unix domain socket: fastcgi_pass  unix:/tmp/fastcgi.socket;

You may also use an upstream block. upstream backend { server  localhost:1234; }

fastcgi_pass  backend;

fastcgi_pass_header
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_fastcgi_module/fastcgi_pass_header.txt" />

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

fastcgi_pass_request_body
Determines whether the request body is passed to the backend. Should generally be left on.

fastcgi_pass_request_headers
Determines whether the request headers are passed to the backend as HTTP_* values. Should generally be left on.

fastcgi_read_timeout
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_fastcgi_module/fastcgi_read_timeout.txt" />

Directive sets the amount of time for upstream to wait for a fastcgi process to send data. Change this directive if you have long running fastcgi 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.

fastcgi_redirect_errors
Directive has been renamed to fastcgi_intercept_errors.

fastcgi_send_timeout
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_fastcgi_module/fastcgi_send_timeout.txt" />

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.

fastcgi_split_path_info
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_fastcgi_module/fastcgi_split_path_info.txt" />

This directive allows the setting of the SCRIPT_FILENAME (SCRIPT_NAME) and PATH_INFO variables of the CGI specification. The regex consists of two groups:


 * path to the script that will handle the request &mdash; corresponding to.
 * the value of the parameter to be given to the script &mdash; corresponding to the.

Here's an example. The script  receives as argument the string. The following configuration will handle path splitting properly: <geshi lang='nginx'> location ~ ^.+\.php { (...) fastcgi_split_path_info ^((?U).+\.php)(/?.+)$; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; fastcgi_param PATH_INFO $fastcgi_path_info; fastcgi_param PATH_TRANSLATED $document_root$fastcgi_path_info; (...) } Requesting  sets SCRIPT_FILENAME to   and  PATH_INFO to.

fastcgi_store
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_fastcgi_module/fastcgi_store.txt" />

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:

fastcgi_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 fastcgi_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;

fastcgi_pass          fastcgi://backend; fastcgi_store         on; fastcgi_store_access  user:rw  group:rw  all:r; fastcgi_temp_path     /data/temp;

alias                 /data/www; }

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

fastcgi_store_access
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_fastcgi_module/fastcgi_store_access.txt" />

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

fastcgi_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:

fastcgi_store_access group:rw  all:r;

fastcgi_temp_file_write_size
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_fastcgi_module/fastcgi_temp_file_write_size.txt" />

fastcgi_temp_path
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_fastcgi_module/fastcgi_temp_path.txt" />

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:

fastcgi_temp_path /spool/nginx/fastcgi_temp 1 2;

Temporary file name may look like:

/spool/nginx/fastcgi_temp/7/45/00000123457

= Parameters, transferred to FastCGI-server. =

The request headers are transferred to the FastCGI-server in the form of parameters. In the applications and the scripts run from the FastCGI-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 fastcgi_param.

= Variables =

$fastcgi_script_name
This variable is equal to the URI request or, if if the URI concludes with a forward slash, then the URI request plus the name of the index file given by fastcgi_index. It is possible to use this variable in place of both SCRIPT_FILENAME and PATH_TRANSLATED, utilized, in particular, for determining the name of the script in PHP.

For example, for the request "/info/": fastcgi_index index.php; fastcgi_param SCRIPT_FILENAME  /home/www/scripts/php$fastcgi_script_name;

SCRIPT_FILENAME would equal "/home/www/scripts/php/info/index.php".

= References = Original Documentation