Mercurial > hg > nginx-site
changeset 298:0dcf07c393b6
English translation of the ngx_http_fastcgi_module module documentation.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Thu, 29 Dec 2011 07:56:40 +0000 |
parents | 94c8df379088 |
children | 2f318fe954ec |
files | xml/en/GNUmakefile xml/en/docs/http/ngx_http_fastcgi_module.xml xml/en/docs/index.xml xml/en/index.xml |
diffstat | 4 files changed, 817 insertions(+), 1 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/GNUmakefile Thu Dec 29 07:35:50 2011 +0000 +++ b/xml/en/GNUmakefile Thu Dec 29 07:56:40 2011 +0000 @@ -45,6 +45,7 @@ ngx_core_module \ http/ngx_http_core_module \ http/ngx_http_empty_gif_module \ + http/ngx_http_fastcgi_module \ http/ngx_http_flv_module \ http/ngx_http_image_filter_module \ http/ngx_http_index_module \
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/en/docs/http/ngx_http_fastcgi_module.xml Thu Dec 29 07:56:40 2011 +0000 @@ -0,0 +1,808 @@ +<?xml version="1.0"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_http_fastcgi_module" + link="/en/docs/http/ngx_http_fastcgi_module.html" + lang="en"> + +<section id="summary"> + +<para> +The <literal>ngx_http_fastcgi_module</literal> module allows to pass +requests to a FastCGI server. +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +location / { + fastcgi_pass localhost:9000; + fastcgi_index index.php; + + fastcgi_param SCRIPT_FILENAME /home/www/scripts/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; +} +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="fastcgi_buffer_size"> +<syntax><value>size</value></syntax> +<default>4k|8k</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Sets <value>size</value> of the buffer used for reading the first part +of a response received from the FastCGI 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 <link id="fastcgi_buffers"/> directive. +It can be made smaller however. +</para> + +</directive> + + +<directive name="fastcgi_buffers"> +<syntax><value>number</value> <value>size</value></syntax> +<default>8 4k|8k</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Sets the <value>number</value> and <value>size</value> of +buffers used for reading a response from the FastCGI 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. +</para> + +</directive> + + +<directive name="fastcgi_cache"> +<syntax><value>zone</value> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Defines a zone used for caching. +The same zone can be used in several places. +The <literal>off</literal> parameter disables caching inherited +from the previous configuration level. +</para> + +</directive> + + +<directive name="fastcgi_cache_bypass"> +<syntax><value>string</value> ...</syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +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: +<example> +fastcgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment; +fastcgi_cache_bypass $http_pragma $http_authorization; +</example> +Can be used along with the <link id="fastcgi_no_cache"/> directive. +</para> + +</directive> + + +<directive name="fastcgi_cache_key"> +<syntax><value>string</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Defines a key for caching, for example +<example> +fastcgi_cache_key localhost:9000$request_uri; +</example> +</para> + +</directive> + + +<directive name="fastcgi_cache_min_uses"> +<syntax><value>number</value></syntax> +<default>1</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Sets the <value>number</value> of requests after which the response +will be cached. +</para> + +</directive> + + +<directive name="fastcgi_cache_path"> +<syntax> + <value>path</value> + [<literal>levels</literal>=<value>levels</value>] + <literal>keys_zone</literal>=<value>name</value>:<value>size</value> + [<literal>inactive</literal>=<value>time</value>] + [<literal>max_size</literal>=<value>size</value>]</syntax> +<default/> +<context>http</context> + +<para> +Sets 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 <literal>levels</literal> parameter defines hierarchy levels of a cache. +For example, in the following configuration +<example> +fastcgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m; +</example> +file names in a cache will look like this: +<example> +/data/nginx/cache/<emphasis>c</emphasis>/<emphasis>29</emphasis>/b7f54b2df7773722d382f4809d650<emphasis>29c</emphasis> +</example> +</para> + +<para> +A cached response is first written to a temporary file, then a file is renamed. +Starting from version 0.8.9 temporary files and the cache can be put on +different file systems but be aware that in this case a file is copied +across two file systems instead of the cheap rename operation. +It is thus recommended that for any given location both cache and a directory +holding temporary files set by the <link id="fastcgi_temp_path"/> directive +are put on the same file system. +</para> + +<para> +In addition, all active keys and information about data are stored +in a shared memory zone, whose <value>name</value> and <value>size</value> +are configured by the <literal>keys_zone</literal> parameter. +Cached data that are not accessed during the time specified by the +<literal>inactive</literal> parameter get removed from the cache +regardless of their freshness. +By default, <literal>inactive</literal> is set to 10 minutes. +</para> + +<para> +The special process “cache manager” monitors the maximum cache size set +by the <literal>max_size</literal> parameter; +when this size is exceeded it removes the least recently used data. +</para> + +</directive> + + +<directive name="fastcgi_cache_use_stale"> +<syntax> + <literal>error</literal> | + <literal>timeout</literal> | + <literal>invalid_header</literal> | + <literal>updating</literal> | + <literal>http_500</literal> | + <literal>http_503</literal> | + <literal>http_404</literal> | + <literal>off</literal> + ...</syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +If an error occurs while working with the FastCGI server it is possible +to use a stale cached response. +This directives determines in which cases it is permitted. +The directive’s parameters match those of the +<link id="fastcgi_next_upstream"/> directive. +Additionally, the <literal>updating</literal> parameter permits +to use a stale cached response if it is currently being updated. +</para> + +</directive> + + +<directive name="fastcgi_cache_valid"> +<syntax>[<value>code</value> ...] <value>time</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Sets caching time for different response codes. +For example, the following directives +<example> +fastcgi_cache_valid 200 302 10m; +fastcgi_cache_valid 404 1m; +</example> +set 10 minutes of caching for responses with codes 200 and 302, +and 1 minute for responses with code 404. +</para> + +<para> +If only caching <value>time</value> is specified +<example> +fastcgi_cache_valid 5m; +</example> +then only 200, 301, and 302 responses are cached. +</para> + +<para> +In addition, it can be specified to cache any responses using the +<literal>any</literal> parameter: +<example> +fastcgi_cache_valid 200 302 10m; +fastcgi_cache_valid 301 1h; +fastcgi_cache_valid any 1m; +</example> +</para> + +</directive> + + +<directive name="fastcgi_connect_timeout"> +<syntax><value>time</value></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Defines a timeout for establishing a connection with the FastCGI server. +It should be noted that this timeout cannot usually exceed 75 seconds. +</para> + +</directive> + + +<directive name="fastcgi_hide_header"> +<syntax><value>field</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +By default, +nginx does not pass the header fields <header>Status</header> and +<header>X-Accel-...</header> from the response of the FastCGI +server to a client. +The <literal>fastcgi_hide_header</literal> directive sets additional fields +that will not be passed. +If, on the contrary, the passing of fields needs to be permitted, +the <link id="fastcgi_pass_header"/> directive can be used. +</para> + +</directive> + + +<directive name="fastcgi_ignore_client_abort"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Determines should the connection with the FastCGI server be +closed if a client closes a connection without waiting +for a response. +</para> + +</directive> + + +<directive name="fastcgi_ignore_headers"> +<syntax><value>field</value> ...</syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Disables processing of certain response header fields from the FastCGI server. +The following fields can be ignored: <header>X-Accel-Redirect</header>, +<header>X-Accel-Expires</header>, <header>X-Accel-Limit-Rate</header> (1.1.6), +<header>X-Accel-Buffering</header> (1.1.6), +<header>X-Accel-Charset</header> (1.1.6), <header>Expires</header>, +<header>Cache-Control</header>, and <header>Set-Cookie</header> (0.8.44). +</para> + +</directive> + + +<directive name="fastcgi_index"> +<syntax><value>name</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Sets a file name that will be appended after a URI that ends with +a slash, in the value of the <var>$fastcgi_script_name</var> variable. +For example, with these settings +<example> +fastcgi_index index.php; +fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name; +</example> +and the “<literal>/page.php</literal>” request, +the <literal>SCRIPT_FILENAME</literal> parameter will be equal to +“<literal>/home/www/scripts/php/page.php</literal>”, +and with the “<literal>/</literal>” request it will be equal to +“<literal>/home/www/scripts/php/index.php</literal>”. +</para> + +</directive> + + +<directive name="fastcgi_intercept_errors"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Determines whether FastCGI server responses with codes greater than or equal +to 400 should be passed to a client or be redirected to nginx for processing +using the <link doc="ngx_http_core_module.xml" id="error_page"/> directive. +</para> + +</directive> + + +<directive name="fastcgi_next_upstream"> +<syntax> + <literal>error</literal> | + <literal>timeout</literal> | + <literal>invalid_header</literal> | + <literal>http_500</literal> | + <literal>http_503</literal> | + <literal>http_404</literal> | + <literal>off</literal> + ...</syntax> +<default>error timeout</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Specifies in which cases a request should be passed to the next server: +<list type="tag"> + +<tag-name><literal>error</literal></tag-name> +<tag-desc>an error occurred while establishing a connection with the +server, passing it a request, or reading the response header;</tag-desc> + +<tag-name><literal>timeout</literal></tag-name> +<tag-desc>a timeout has occurred while establishing a connection with the +server, passing it a request, or reading the response header;</tag-desc> + +<tag-name><literal>invalid_header</literal></tag-name> +<tag-desc>a server returned empty or invalid response;</tag-desc> + +<tag-name><literal>http_500</literal></tag-name> +<tag-desc>a server returned a response with the code 500;</tag-desc> + +<tag-name><literal>http_503</literal></tag-name> +<tag-desc>a server returned a response with the code 503;</tag-desc> + +<tag-name><literal>http_404</literal></tag-name> +<tag-desc>a server returned a response with the code 404;</tag-desc> + +<tag-name><literal>off</literal></tag-name> +<tag-desc>disables passing a request to the next server.</tag-desc> + +</list> +</para> + +<para> +It should be understood that passing a request to the next server is +only possible if a client was not sent anything yet. +That is, if an error or a timeout occurs in the middle of +transferring a response, fixing this is impossible. +</para> + +</directive> + + +<directive name="fastcgi_no_cache"> +<syntax><value>string</value> ...</syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +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: +<example> +fastcgi_no_cache $cookie_nocache $arg_nocache$arg_comment; +fastcgi_no_cache $http_pragma $http_authorization; +</example> +Can be used along with the <link id="fastcgi_cache_bypass"/> directive. +</para> + +</directive> + + +<directive name="fastcgi_param"> +<syntax> + <value>parameter</value> <value>value</value> + [<literal>if_not_empty</literal>]</syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Sets a <value>parameter</value> that should be passed to the FastCGI server. +A <value>value</value> can contain text, variables, and their combination. +These directives are inherited from the previous level if and +only if there are no +<literal>fastcgi_param</literal> +directives defined on the current level. +</para> + +<para> +The following example shows the minimum required settings for PHP: +<example> +fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name; +fastcgi_param QUERY_STRING $query_string; +</example> +</para> + +<para> +The <literal>SCRIPT_FILENAME</literal> parameter is used in PHP for +determining the script name, and the <literal>QUERY_STRING</literal> +parameter is used to pass request parameters. +</para> + +<para> +For scripts that process <literal>POST</literal> requests, the +following three parameters are also required: +<example> +fastcgi_param REQUEST_METHOD $request_method; +fastcgi_param CONTENT_TYPE $content_type; +fastcgi_param CONTENT_LENGTH $content_length; +</example> +</para> + +<para> +If PHP was built with the <literal>--enable-force-cgi-redirect</literal> +configuration parameter, the <literal>REDIRECT_STATUS</literal> parameter +should also be passed with the value “200”: +<example> +fastcgi_param REDIRECT_STATUS 200; +</example> +</para> + +<para> +If a directive is specified with <literal>if_not_empty</literal> (1.1.11) then +such a parameter will not be passed to the server until its value is not empty: +<example> +fastcgi_param HTTPS $https if_not_empty; +</example> +</para> + +</directive> + + +<directive name="fastcgi_pass"> +<syntax><value>address</value></syntax> +<default/> +<context>location</context> +<context>if in location</context> + +<para> +Sets an address of the FastCGI server. +An address can be specified as a domain name or an address, and a port, +for example, +<example> + fastcgi_pass localhost:9000; +</example> +or as a UNIX-domain socket path: +<example> + fastcgi_pass unix:/tmp/fastcgi.socket; +</example> +</para> + +<para> +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 +<link doc="ngx_http_upstream_module.xml">server group</link>. +</para> + +</directive> + + +<directive name="fastcgi_pass_header"> +<syntax><value>field</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Permits to pass <link id="fastcgi_hide_header">otherwise disabled</link> header +fields from the FastCGI server to a client. +</para> + +</directive> + + +<directive name="fastcgi_read_timeout"> +<syntax><value>time</value></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Defines a timeout for reading a response from the FastCGI server. +A timeout is only set between two successive read operations, +not for the transmission of the whole response. +If a FastCGI server does not transmit anything within this time, +a connection is closed. +</para> + +</directive> + + +<directive name="fastcgi_send_timeout"> +<syntax><value>time</value></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Sets a timeout for transmitting a request to the FastCGI server. +A timeout is only set between two successive write operations, +not for the transmission of the whole request. +If a FastCGI server does not receive anything within this time, +a connection is closed. +</para> + +</directive> + + +<directive name="fastcgi_split_path_info"> +<syntax><value>regex</value></syntax> +<default/> +<context>location</context> + +<para> +Defines a regular expression that captures a value for the +<var>$fastcgi_path_info</var> variable. +A regular expression should have two captures, the first becomes +a value of the <var>$fastcgi_script_name</var> variable, the second +becomes a value of the <var>$fastcgi_path_info</var> variable. +For example, with these settings +<example> +location ~ ^(.+\.php)(.*)$ { + fastcgi_split_path_info ^(.+\.php)(.*)$; + fastcgi_param SCRIPT_FILENAME /path/to/php$fastcgi_script_name; + fastcgi_param PATH_INFO $fastcgi_path_info; +</example> +and the “<literal>/show.php/article/0001</literal>” request, +the <literal>SCRIPT_FILENAME</literal> parameter will be equal to +“<literal>/path/to/php/show.php</literal>”, and the +<literal>PATH_INFO</literal> parameter will be equal to +“<literal>/article/0001</literal>”. +</para> + +</directive> + + +<directive name="fastcgi_store"> +<syntax> + <literal>on</literal> | + <literal>off</literal> | + <value>string</value></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Enables saving of files to a disk. +The <literal>on</literal> parameter saves files with paths +corresponding to the directives +<link doc="ngx_http_core_module.xml" id="alias"/> or +<link doc="ngx_http_core_module.xml" id="root"/>. +The <literal>off</literal> parameter disables saving of files. +In addition, the file name can be set explicitly using the +<value>string</value> with variables: +<example> +fastcgi_store /data/www$original_uri; +</example> +</para> + +<para> +The modification time of files is set according to the received +<header>Last-Modified</header> response header field. +A response is first written to a temporary file, then a file is renamed. +Starting from version 0.8.9 temporary files and the persistent store +can be put on different file systems but be aware that in this case +a file is copied across two file systems instead of the cheap rename operation. +It is thus recommended that for any given location both saved files and a +directory holding temporary files set by the <link id="fastcgi_temp_path"/> +directive are put on the same file system. +</para> + +<para> +This directive can be used to create local copies of static unchangeable +files, e.g.: +<example> +location /images/ { + root /data/www; + open_file_cache_errors off; + error_page 404 = /fetch$uri; +} + +location /fetch/ { + internal; + + fastcgi_pass backend:9000; + ... + + fastcgi_store on; + fastcgi_store_access user:rw group:rw all:r; + fastcgi_temp_path /data/temp; + + alias /data/www/; +} +</example> +</para> + +</directive> + + +<directive name="fastcgi_store_access"> +<syntax><value>users</value>:<value>permissions</value> ...</syntax> +<default>user:rw</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Sets access permissions for newly created files and directories, e.g.: +<example> +fastcgi_store_access user:rw group:rw all:r; +</example> +</para> + +<para> +If any <literal>group</literal> or <literal>all</literal> access permissions +are specified then <literal>user</literal> permissions may be omitted: +<example> +fastcgi_store_access group:rw all:r; +</example> +</para> + +</directive> + + +<directive name="fastcgi_temp_path"> +<syntax> + <value>path</value> + [<value>level1</value> + [<value>level2</value> + [<value>level3</value>]]]</syntax> +<default>fastcgi_temp</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Defines a directory for storing temporary files +received from another server. +Up to three-level subdirectory hierarchy can be used underneath the specified +directory. +For example, in the following configuration +<example> +fastcgi_temp_path /spool/nginx/fastcgi_temp 1 2; +</example> +a temporary file might look like this: +<example> +/spool/nginx/fastcgi_temp/<emphasis>7</emphasis>/<emphasis>45</emphasis>/00000123<emphasis>457</emphasis> +</example> +</para> + +</directive> + +</section> + + +<section id="parameters" name="Parameters Passed to a FastCGI Server"> + +<para> +HTTP request header fields are passed to the FastCGI server as parameters. +In applications and scripts running as FastCGI servers, +these parameters are usually made available as environment variables. +For example, the <header>User-Agent</header> header field is passed as the +<literal>HTTP_USER_AGENT</literal> parameter. +In addition to HTTP request header fields it is possible to pass arbitrary +parameters using the <link id="fastcgi_param"/> directive. +</para> + +</section> + + +<section id="variables" name="Embedded Variables"> + +<para> +The <literal>ngx_http_fastcgi_module</literal> module supports embedded variables +that can be used to set parameters using the +<link id="fastcgi_param"/> directive: +<list type="tag"> + +<tag-name><var>$fastcgi_script_name</var></tag-name> +<tag-desc> +request URI or, if a URI ends with a slash, request URI with an index file +name configured by the <link id="fastcgi_index"/> directive appended to it. +This variable can be used to set the +<literal>SCRIPT_FILENAME</literal> and <literal>PATH_TRANSLATED</literal> +parameters that determine the script name in PHP. +For example, for the “<literal>/info/</literal>” request with the +following directives +<example> +fastcgi_index index.php; +fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name; +</example> +the <literal>SCRIPT_FILENAME</literal> parameter will be equal to +“<literal>/home/www/scripts/php/info/index.php</literal>”. + +<para> +When using the <link id="fastcgi_split_path_info"/> directive, +the <var>$fastcgi_script_name</var> variable equals to the value of +the first capture set by the directive. +</para> +</tag-desc> + +<tag-name><var>$fastcgi_path_info</var></tag-name> +<tag-desc>the value of the second capture set by the +<link id="fastcgi_split_path_info"/> directive. +This variable can be used to set the +<literal>PATH_INFO</literal> parameter. +</tag-desc> + +</list> +</para> + +</section> + +</module>
--- a/xml/en/docs/index.xml Thu Dec 29 07:35:50 2011 +0000 +++ b/xml/en/docs/index.xml Thu Dec 29 07:56:40 2011 +0000 @@ -71,6 +71,11 @@ </item> <item> +<a href="/en/docs/http/ngx_http_fastcgi_module.xml"> +ngx_http_fastcgi_module</a> +</item> + +<item> <a href="/en/docs/http/ngx_http_flv_module.xml"> ngx_http_flv_module</a> </item>
--- a/xml/en/index.xml Thu Dec 29 07:35:50 2011 +0000 +++ b/xml/en/index.xml Thu Dec 29 07:56:40 2011 +0000 @@ -53,7 +53,9 @@ </item> <item> -Accelerated support with caching of FastCGI, uwsgi, SCGI, and memcached servers; +Accelerated support with caching of +<link doc="docs/http/ngx_http_fastcgi_module.xml">FastCGI</link>, +uwsgi, SCGI, and memcached servers; <link doc="docs/http/ngx_http_upstream_module.xml">simple load balancing and fault tolerance</link>; </item>