Mercurial > hg > nginx-site
changeset 1191:ea85ba147fe9
Mechanically converted SCGI module docs to uwsgi.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Sat, 17 May 2014 01:55:03 +0400 |
parents | dd4cfc6ce770 |
children | b5268820c3f3 |
files | xml/en/GNUmakefile xml/en/docs/http/ngx_http_uwsgi_module.xml xml/ru/GNUmakefile xml/ru/docs/http/ngx_http_uwsgi_module.xml |
diffstat | 4 files changed, 2130 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/GNUmakefile +++ b/xml/en/GNUmakefile @@ -79,6 +79,7 @@ REFS = \ http/ngx_http_sub_module \ http/ngx_http_upstream_module \ http/ngx_http_userid_module \ + http/ngx_http_uwsgi_module \ http/ngx_http_xslt_module \ mail/ngx_mail_auth_http_module \ mail/ngx_mail_core_module \
new file mode 100644 --- /dev/null +++ b/xml/en/docs/http/ngx_http_uwsgi_module.xml @@ -0,0 +1,1068 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_http_uwsgi_module" + link="/en/docs/http/ngx_http_uwsgi_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_http_uwsgi_module</literal> module allows passing +requests to a uwsgi server. +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +location / { + include uwsgi_params; + uwsgi_pass localhost:9000; +} +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="uwsgi_bind"> +<syntax><value>address</value> | <literal>off</literal></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Makes outgoing connections to a uwsgi server originate +from the specified local IP <value>address</value>. +Parameter value can contain variables (1.3.12). +The special value <literal>off</literal> (1.3.12) cancels the effect +of the <literal>uwsgi_bind</literal> directive +inherited from the previous configuration level, which allows the +system to auto-assign the local IP address. +</para> + +</directive> + + +<directive name="uwsgi_buffer_size"> +<syntax><value>size</value></syntax> +<default>4k|8k</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Sets the <value>size</value> of the buffer used for reading the first part +of the response received from the uwsgi 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="uwsgi_buffers"/> directive. +It can be made smaller, however. +</para> + +</directive> + + +<directive name="uwsgi_buffering"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Enables or disables buffering of responses from the uwsgi server. +</para> + +<para> +When buffering is enabled, nginx receives a response from the uwsgi server +as soon as possible, saving it into the buffers set by the +<link id="uwsgi_buffer_size"/> and <link id="uwsgi_buffers"/> directives. +If the whole response does not fit into memory, a part of it can be saved +to a <link id="uwsgi_temp_path">temporary file</link> on the disk. +Writing to temporary files is controlled by the +<link id="uwsgi_max_temp_file_size"/> and +<link id="uwsgi_temp_file_write_size"/> directives. +</para> + +<para> +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 uwsgi server. +The maximum size of the data that nginx can receive from the server +at a time is set by the <link id="uwsgi_buffer_size"/> directive. +</para> + +<para> +Buffering can also be enabled or disabled by passing +“<literal>yes</literal>” or “<literal>no</literal>” in the +<header>X-Accel-Buffering</header> response header field. +This capability can be disabled using the +<link id="uwsgi_ignore_headers"/> directive. +</para> + +</directive> + + +<directive name="uwsgi_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 the +buffers used for reading a response from the uwsgi 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="uwsgi_busy_buffers_size"> +<syntax><value>size</value></syntax> +<default>8k|16k</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +When <link id="uwsgi_buffering">buffering</link> of responses from the uwsgi +server is enabled, limits the total <value>size</value> 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, <value>size</value> is limited by the size of two buffers set by the +<link id="uwsgi_buffer_size"/> and <link id="uwsgi_buffers"/> directives. +</para> + +</directive> + + +<directive name="uwsgi_cache"> +<syntax><value>zone</value> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Defines a shared memory 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="uwsgi_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> +uwsgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment; +uwsgi_cache_bypass $http_pragma $http_authorization; +</example> +Can be used along with the <link id="uwsgi_no_cache"/> directive. +</para> + +</directive> + + +<directive name="uwsgi_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> +uwsgi_cache_key localhost:9000$request_uri; +</example> +</para> + +</directive> + + +<directive name="uwsgi_cache_lock"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.1.12</appeared-in> + +<para> +When enabled, only one request at a time will be allowed to populate +a new cache element identified according to the <link id="uwsgi_cache_key"/> +directive by passing a request to a uwsgi 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 +<link id="uwsgi_cache_lock_timeout"/> directive. +</para> + +</directive> + + +<directive name="uwsgi_cache_lock_timeout"> +<syntax><value>time</value></syntax> +<default>5s</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.1.12</appeared-in> + +<para> +Sets a timeout for <link id="uwsgi_cache_lock"/>. +</para> + +</directive> + + +<directive name="uwsgi_cache_methods"> +<syntax> + <literal>GET</literal> | + <literal>HEAD</literal> | + <literal>POST</literal> + ...</syntax> +<default>GET HEAD</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +If the client request method is listed in this directive then +the response will be cached. +“<literal>GET</literal>” and “<literal>HEAD</literal>” methods are always +added to the list, though it is recommended to specify them explicitly. +See also the <link id="uwsgi_no_cache"/> directive. +</para> + +</directive> + + +<directive name="uwsgi_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="uwsgi_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>] + [<literal>loader_files</literal>=<value>number</value>] + [<literal>loader_sleep</literal>=<value>time</value>] + [<literal>loader_threshold</literal>=<value>time</value>]</syntax> +<default/> +<context>http</context> + +<para> +Sets the path and other parameters of a cache. +Cache data are stored in files. +The file name in a cache is a result of +applying the MD5 function to the +<link id="uwsgi_cache_key">cache key</link>. +The <literal>levels</literal> parameter defines hierarchy levels of a cache. +For example, in the following configuration +<example> +uwsgi_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, +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 <link id="uwsgi_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. +One megabyte zone can store about 8 thousand keys. +</para> + +<para> +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 “cache manager” process 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> + +<para> +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 <literal>loader_files</literal> items +are loaded (by default, 100). +Besides, the duration of one iteration is limited by the +<literal>loader_threshold</literal> parameter (by default, 200 milliseconds). +Between iterations, a pause configured by the <literal>loader_sleep</literal> +parameter (by default, 50 milliseconds) is made. +</para> + +</directive> + + +<directive name="uwsgi_cache_purge"> +<syntax>string ...</syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.5.7</appeared-in> + +<para> +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 +<link id="uwsgi_cache_key">cache key</link> is removed. +The result of successful operation is indicated by returning +the <http-status code="204" text="No Content"/> response. +</para> + +<para> +If the <link id="uwsgi_cache_key">cache key</link> of a purge request ends +with an asterisk (“<literal>*</literal>”), all cache entries matching the +wildcard key will be removed from the cache. +</para> + +<para> +Example configuration: +<example> +uwsgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m; + +map $request_method $purge_method { + PURGE 1; + default 0; +} + +server { + ... + location / { + uwsgi_pass backend; + uwsgi_cache cache_zone; + uwsgi_cache_key $uri; + uwsgi_cache_purge $purge_method; + } +} +</example> +<note> +This functionality is available as part of our +<commercial_version>commercial subscription</commercial_version>. +</note> +</para> + +</directive> + + +<directive name="uwsgi_cache_revalidate"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.5.7</appeared-in> + +<para> +Enables revalidation of expired cache items using conditional requests with +the <header>If-Modified-Since</header> header field. +</para> + +</directive> + + +<directive name="uwsgi_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_403</literal> | + <literal>http_404</literal> | + <literal>off</literal> + ...</syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Determines in which cases a stale cached response can be used +when an error occurs during communication with the uwsgi server. +The directive’s parameters match the parameters of the +<link id="uwsgi_next_upstream"/> directive. +</para> + +<para> +Additionally, the <literal>updating</literal> parameter permits +using a stale cached response if it is currently being updated. +This allows minimizing the number of accesses to uwsgi servers +when updating cached data. +</para> + +<para> +To minimize the number of accesses to uwsgi servers when +populating a new cache element, the <link id="uwsgi_cache_lock"/> +directive can be used. +</para> + +</directive> + + +<directive name="uwsgi_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> +uwsgi_cache_valid 200 302 10m; +uwsgi_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> +uwsgi_cache_valid 5m; +</example> +then only 200, 301, and 302 responses are cached. +</para> + +<para> +In addition, the <literal>any</literal> parameter can be specified +to cache any responses: +<example> +uwsgi_cache_valid 200 302 10m; +uwsgi_cache_valid 301 1h; +uwsgi_cache_valid any 1m; +</example> +</para> + +<para> +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 <header>X-Accel-Expires</header> header field sets caching time of a +response in seconds. +The zero value disables caching for a response. +If the value starts with the <literal>@</literal> 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 <header>X-Accel-Expires</header> field, +parameters of caching may be set in the header fields +<header>Expires</header> or <header>Cache-Control</header>. +If the header includes the <header>Set-Cookie</header> field, such a +response will not be cached. +Processing of one or more of these response header fields can be disabled +using the <link id="uwsgi_ignore_headers"/> directive. +</para> + +</directive> + + +<directive name="uwsgi_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 a uwsgi server. +It should be noted that this timeout cannot usually exceed 75 seconds. +</para> + +</directive> + + +<directive name="uwsgi_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 a uwsgi +server to a client. +The <literal>uwsgi_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="uwsgi_pass_header"/> directive can be used. +</para> + +</directive> + + +<directive name="uwsgi_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 whether the connection with a uwsgi server should be +closed when a client closes the connection without waiting +for a response. +</para> + +</directive> + + +<directive name="uwsgi_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 uwsgi 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> + +<para> +If not disabled, processing of these header fields has the following +effect: +<list type="bullet" compact="no"> + +<listitem> +<header>X-Accel-Expires</header>, <header>Expires</header>, +<header>Cache-Control</header>, and <header>Set-Cookie</header> +set the parameters of response <link id="uwsgi_cache_valid">caching</link>; +</listitem> + +<listitem> +<header>X-Accel-Redirect</header> performs an +<link doc="ngx_http_core_module.xml" id="internal">internal +redirect</link> to the specified URI; +</listitem> + +<listitem> +<header>X-Accel-Limit-Rate</header> sets the +<link doc="ngx_http_core_module.xml" id="limit_rate">rate +limit</link> for transmission of a response to a client; +</listitem> + +<listitem> +<header>X-Accel-Buffering</header> enables or disables +<link id="uwsgi_buffering">buffering</link> of a response; +</listitem> + +<listitem> +<header>X-Accel-Charset</header> sets the desired +<link doc="ngx_http_charset_module.xml" id="charset"/> +of a response. +</listitem> + +</list> +</para> + +</directive> + + +<directive name="uwsgi_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 a uwsgi 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 <link doc="ngx_http_core_module.xml" id="error_page"/> directive. +</para> + +</directive> + + +<directive name="uwsgi_max_temp_file_size"> +<syntax><value>size</value></syntax> +<default>1024m</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +When <link id="uwsgi_buffering">buffering</link> of responses from the uwsgi +server is enabled, and the whole response does not fit into the buffers +set by the <link id="uwsgi_buffer_size"/> and <link id="uwsgi_buffers"/> +directives, a part of the response can be saved to a temporary file. +This directive sets the maximum <value>size</value> of the temporary file. +The size of data written to the temporary file at a time is set +by the <link id="uwsgi_temp_file_write_size"/> directive. +</para> + +<para> +The zero value disables buffering of responses to temporary files. +</para> + +</directive> + + +<directive name="uwsgi_next_upstream"> +<syntax> + <literal>error</literal> | + <literal>timeout</literal> | + <literal>invalid_header</literal> | + <literal>http_500</literal> | + <literal>http_503</literal> | + <literal>http_403</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 a request to it, 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 a request to it, or reading the response header;</tag-desc> + +<tag-name><literal>invalid_header</literal></tag-name> +<tag-desc>a server returned an 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_403</literal></tag-name> +<tag-desc>a server returned a response with the code 403;</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> +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. +</para> + +<para> +The directive also defines what is considered an unsuccessful attempt +of communication with a +<link doc="ngx_http_upstream_module.xml" id="server"/>. +The cases of <literal>error</literal>, <literal>timeout</literal> and +<literal>invalid_header</literal> are always considered unsuccessful attempts, +even if they are not specified in the directive. +The cases of <literal>http_500</literal> and <literal>http_503</literal> are +considered unsuccessful attempts only if they are specified in the directive. +The cases of <literal>http_403</literal> and <literal>http_404</literal> +are never considered unsuccessful attempts. +</para> + +</directive> + + +<directive name="uwsgi_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> +uwsgi_no_cache $cookie_nocache $arg_nocache$arg_comment; +uwsgi_no_cache $http_pragma $http_authorization; +</example> +Can be used along with the <link id="uwsgi_cache_bypass"/> directive. +</para> + +</directive> + + +<directive name="uwsgi_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 uwsgi server. +The <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>uwsgi_param</literal> +directives defined on the current level. +</para> + +<para> +Standard +<link url="http://tools.ietf.org/html/rfc3875#section-4.1">CGI +environment variables</link> +should be provided as uwsgi headers, see the <path>uwsgi_params</path> file +provided in the distribution: +<example> +location / { + include uwsgi_params; + ... +} +</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> +uwsgi_param HTTPS $https if_not_empty; +</example> +</para> + +</directive> + + +<directive name="uwsgi_pass"> +<syntax><value>address</value></syntax> +<default/> +<context>location</context> +<context>if in location</context> + +<para> +Sets the address of a uwsgi server. +The address can be specified as a domain name or IP address, +and an optional port: +<example> +uwsgi_pass localhost:9000; +</example> +or as a UNIX-domain socket path: +<example> +uwsgi_pass unix:/tmp/uwsgi.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="uwsgi_pass_header"> +<syntax><value>field</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Permits passing <link id="uwsgi_hide_header">otherwise disabled</link> header +fields from a uwsgi server to a client. +</para> + +</directive> + + +<directive name="uwsgi_pass_request_body"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Indicates whether the original request body is passed +to the uwsgi server. +See also the <link id="uwsgi_pass_request_headers"/> directive. +</para> + +</directive> + + +<directive name="uwsgi_pass_request_headers"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Indicates whether the header fields of the original request are passed +to the uwsgi server. +See also the <link id="uwsgi_pass_request_body"/> directive. +</para> + +</directive> + + +<directive name="uwsgi_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 uwsgi server. +The timeout is set only between two successive read operations, +not for the transmission of the whole response. +If the uwsgi server does not transmit anything within this time, +the connection is closed. +</para> + +</directive> + + +<directive name="uwsgi_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 uwsgi server. +The timeout is set only between two successive write operations, +not for the transmission of the whole request. +If the uwsgi server does not receive anything within this time, +the connection is closed. +</para> + +</directive> + + +<directive name="uwsgi_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> +uwsgi_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. +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 <link id="uwsgi_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; + error_page 404 = /fetch$uri; +} + +location /fetch/ { + internal; + + uwsgi_pass backend:9000; + ... + + uwsgi_store on; + uwsgi_store_access user:rw group:rw all:r; + uwsgi_temp_path /data/temp; + + alias /data/www/; +} +</example> +</para> + +</directive> + + +<directive name="uwsgi_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> +uwsgi_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> +uwsgi_store_access group:rw all:r; +</example> +</para> + +</directive> + + +<directive name="uwsgi_temp_file_write_size"> +<syntax><value>size</value></syntax> +<default>8k|16k</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Limits the <value>size</value> of data written to a temporary file +at a time, when buffering of responses from the uwsgi server +to temporary files is enabled. +By default, <value>size</value> is limited by two buffers set by the +<link id="uwsgi_buffer_size"/> and <link id="uwsgi_buffers"/> directives. +The maximum size of a temporary file is set by the +<link id="uwsgi_max_temp_file_size"/> directive. +</para> + +</directive> + + +<directive name="uwsgi_temp_path"> +<syntax> + <value>path</value> + [<value>level1</value> + [<value>level2</value> + [<value>level3</value>]]]</syntax> +<default>uwsgi_temp</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Defines a directory for storing temporary files +with data received from uwsgi servers. +Up to three-level subdirectory hierarchy can be used underneath the specified +directory. +For example, in the following configuration +<example> +uwsgi_temp_path /spool/nginx/uwsgi_temp 1 2; +</example> +a temporary file might look like this: +<example> +/spool/nginx/uwsgi_temp/<emphasis>7</emphasis>/<emphasis>45</emphasis>/00000123<emphasis>457</emphasis> +</example> +</para> + +</directive> + +</section> + +</module>
--- a/xml/ru/GNUmakefile +++ b/xml/ru/GNUmakefile @@ -67,6 +67,7 @@ REFS = \ http/ngx_http_sub_module \ http/ngx_http_upstream_module \ http/ngx_http_userid_module \ + http/ngx_http_uwsgi_module \ http/ngx_http_xslt_module \ mail/ngx_mail_auth_http_module \ mail/ngx_mail_core_module \
new file mode 100644 --- /dev/null +++ b/xml/ru/docs/http/ngx_http_uwsgi_module.xml @@ -0,0 +1,1060 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Модуль ngx_http_uwsgi_module" + link="/ru/docs/http/ngx_http_uwsgi_module.html" + lang="ru" + rev="1"> + +<section id="summary"> + +<para> +Модуль <literal>ngx_http_uwsgi_module</literal> позволяет передавать +запросы uwsgi-серверу. +</para> + +</section> + + +<section id="example" name="Пример конфигурации"> + +<para> +<example> +location / { + include uwsgi_params; + uwsgi_pass localhost:9000; +} +</example> +</para> + +</section> + + +<section id="directives" name="Директивы"> + +<directive name="uwsgi_bind"> +<syntax><value>адрес</value> | <literal>off</literal></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Задаёт локальный IP-<value>адрес</value>, который будет использоваться в +исходящих соединениях с uwsgi-сервером. +В значении параметра допустимо использование переменных (1.3.12). +Специальное значение <literal>off</literal> (1.3.12) отменяет действие +унаследованной с предыдущего уровня конфигурации +директивы <literal>uwsgi_bind</literal>, позволяя системе +самостоятельно выбирать локальный IP-адрес. +</para> + +</directive> + + +<directive name="uwsgi_buffer_size"> +<syntax><value>размер</value></syntax> +<default>4k|8k</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Задаёт <value>размер</value> буфера, в который будет читаться +первая часть ответа, получаемого от uwsgi-сервера. +В этой части ответа находится, как правило, небольшой заголовок ответа. +По умолчанию размер буфера равен размеру одного буфера в директиве +<link id="uwsgi_buffers"/>, однако его можно сделать меньше. +</para> + +</directive> + + +<directive name="uwsgi_buffering"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Разрешает или запрещает использовать буферизацию ответов uwsgi-сервера. +</para> + +<para> +Если буферизация включена, то nginx принимает ответ uwsgi-сервера +как можно быстрее, сохраняя его в буферы, заданные директивами +<link id="uwsgi_buffer_size"/> и <link id="uwsgi_buffers"/>. +Если ответ не вмещается целиком в память, то его часть может быть записана +на диск во <link id="uwsgi_temp_path">временный файл</link>. +Запись во временные файлы контролируется директивами +<link id="uwsgi_max_temp_file_size"/> и +<link id="uwsgi_temp_file_write_size"/>. +</para> + +<para> +Если буферизация выключена, то ответ синхронно передаётся клиенту сразу же +по мере его поступления. +nginx не пытается считать весь ответ uwsgi-сервера. +Максимальный размер данных, который nginx может принять от сервера +за один раз, задаётся директивой <link id="uwsgi_buffer_size"/>. +</para> + +<para> +Буферизация может быть также включена или выключена путём передачи +значения “<literal>yes</literal>” или “<literal>no</literal>” в поле +<header>X-Accel-Buffering</header> заголовка ответа. +Эту возможность можно запретить с помощью директивы +<link id="uwsgi_ignore_headers"/>. +</para> + +</directive> + + +<directive name="uwsgi_buffers"> +<syntax><value>число</value> <value>размер</value></syntax> +<default>8 4k|8k</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Задаёт <value>число</value> и <value>размер</value> буферов +для одного соединения, +в которые будет читаться ответ, получаемый от uwsgi-сервера. +По умолчанию размер одного буфера равен размеру страницы. +В зависимости от платформы это или 4K, или 8K. +</para> + +</directive> + + +<directive name="uwsgi_busy_buffers_size"> +<syntax><value>размер</value></syntax> +<default>8k|16k</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +При включённой <link id="uwsgi_buffering">буферизации</link> ответов +uwsgi-сервера, ограничивает суммарный <value>размер</value> +буферов, которые могут быть заняты для отправки ответа клиенту, пока +ответ ещё не прочитан целиком. +Оставшиеся буферы тем временем могут использоваться для чтения ответа +и, при необходимости, буферизации части ответа во временный файл. +По умолчанию <value>размер</value> ограничен двумя буферами, заданными +директивами <link id="uwsgi_buffer_size"/> и <link id="uwsgi_buffers"/>. +</para> + +</directive> + + +<directive name="uwsgi_cache"> +<syntax><value>зона</value> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Задаёт зону разделяемой памяти, используемой для кэширования. +Одна и та же зона может использоваться в нескольких местах. +Параметр <literal>off</literal> запрещает кэширование, унаследованное +с предыдущего уровня конфигурации. +</para> + +</directive> + + +<directive name="uwsgi_cache_bypass"> +<syntax><value>строка</value> ...</syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Задаёт условия, при которых ответ не будет браться из кэша. +Если значение хотя бы одного из строковых параметров непустое и не равно “0”, +то ответ не берётся из кэша: +<example> +uwsgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment; +uwsgi_cache_bypass $http_pragma $http_authorization; +</example> +Можно использовать совместно с директивой <link id="uwsgi_no_cache"/>. +</para> + +</directive> + + +<directive name="uwsgi_cache_key"> +<syntax><value>строка</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Задаёт ключ для кэширования, например, +<example> +uwsgi_cache_key localhost:9000$request_uri; +</example> +</para> + +</directive> + + +<directive name="uwsgi_cache_lock"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.1.12</appeared-in> + +<para> +Если включено, одновременно только одному запросу будет позволено +заполнить новый элемент кэша, идентифицируемый согласно директиве +<link id="uwsgi_cache_key"/>, передав запрос на uwsgi-сервер. +Остальные запросы этого же элемента будут либо ожидать +появления ответа в кэше, либо освобождения блокировки +этого элемента, в течение времени, заданного директивой +<link id="uwsgi_cache_lock_timeout"/>. +</para> + +</directive> + + +<directive name="uwsgi_cache_lock_timeout"> +<syntax><value>время</value></syntax> +<default>5s</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.1.12</appeared-in> + +<para> +Задаёт таймаут для <link id="uwsgi_cache_lock"/>. +</para> + +</directive> + + +<directive name="uwsgi_cache_methods"> +<syntax> + <literal>GET</literal> | + <literal>HEAD</literal> | + <literal>POST</literal> + ...</syntax> +<default>GET HEAD</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Если метод запроса клиента указан в этой директиве, +то ответ будет закэширован. +Методы “<literal>GET</literal>” и “<literal>HEAD</literal>” всегда добавляются +в список, но тем не менее рекомендуется перечислять их явно. +См. также директиву <link id="uwsgi_no_cache"/>. +</para> + +</directive> + + +<directive name="uwsgi_cache_min_uses"> +<syntax><value>число</value></syntax> +<default>1</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Задаёт <value>число</value> запросов, после которого ответ будет закэширован. +</para> + +</directive> + + +<directive name="uwsgi_cache_path"> +<syntax> + <value>путь</value> + [<literal>levels</literal>=<value>уровни</value>] + <literal>keys_zone</literal>=<value>имя</value>:<value>размер</value> + [<literal>inactive</literal>=<value>время</value>] + [<literal>max_size</literal>=<value>размер</value>] + [<literal>loader_files</literal>=<value>число</value>] + [<literal>loader_sleep</literal>=<value>время</value>] + [<literal>loader_threshold</literal>=<value>время</value>]</syntax> +<default/> +<context>http</context> + +<para> +Задаёт путь и другие параметры кэша. +Данные кэша хранятся в файлах. +Именем файла в кэше является результат функции MD5 +от <link id="uwsgi_cache_key">ключа кэширования</link>. +Параметр <literal>levels</literal> задаёт уровни иерархии кэша, +например, при использовании +<example> +uwsgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m; +</example> +имена файлов в кэше будут такого вида: +<example> +/data/nginx/cache/<emphasis>c</emphasis>/<emphasis>29</emphasis>/b7f54b2df7773722d382f4809d650<emphasis>29c</emphasis> +</example> +</para> + +<para> +Кэшируемый ответ сначала записывается во временный файл, а потом этот файл +переименовывается. +Начиная с версии 0.8.9, временные файлы и кэш +могут располагаться на разных файловых системах. +Однако нужно учитывать, +что в этом случае вместо дешёвой операции переименовывания в пределах +одной файловой системы файл копируется с одной файловой системы на другую. +Поэтому лучше, если кэш будет находиться на той же файловой +системе, что и каталог с временными файлами, задаваемый директивой +<link id="uwsgi_temp_path"/> для данного location. +</para> + +<para> +Кроме того, все активные ключи и информация о данных хранятся в зоне +разделяемой памяти, <value>имя</value> и <value>размер</value> которой +задаются параметром <literal>keys_zone</literal>. +Зоны размером в 1 мегабайт достаточно для хранения около 8 тысяч ключей. +</para> + +<para> +Если к данным кэша не обращаются в течение времени, заданного параметром +<literal>inactive</literal>, то данные удаляются, независимо от их свежести. +По умолчанию <literal>inactive</literal> равен 10 минутам. +</para> + +<para> +Специальный процесс “cache manager” следит за максимальным размером кэша, +заданным параметром <literal>max_size</literal>, и при превышении +его размеров удаляет наименее востребованные данные. +</para> + +<para> +Через минуту после старта активируется специальный процесс “cache loader”, +который загружает в зону кэша информацию о ранее закэшированных данных, +хранящихся на файловой системе. +Загрузка происходит итерациями. +За одну итерацию загружается не более <literal>loader_files</literal> +элементов (по умолчанию 100). +Кроме того, время работы одной итерации ограничено параметром +<literal>loader_threshold</literal> (по умолчанию 200 миллисекунд). +Между итерациями делается пауза на время, заданное параметром +<literal>loader_sleep</literal> (по умолчанию 50 миллисекунд). +</para> + +</directive> + + +<directive name="uwsgi_cache_purge"> +<syntax>строка ...</syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.5.7</appeared-in> + +<para> +Задаёт условия, при которых запрос будет считаться запросом +на очистку кэша. +Если значение хотя бы одного из строковых параметров непустое и не равно “0”, +то запись в кэше с соответствующим +<link id="uwsgi_cache_key">ключом кэширования</link> удаляется. +В результате успешной операции возвращается ответ с кодом +<http-status code="204" text="No Content"/>. +</para> + +<para> +Если <link id="uwsgi_cache_key">ключ кэширования</link> +запроса на очистку заканчивается +звёздочкой (“<literal>*</literal>”), то все записи в кэше, соответствующие +этой маске, будут удалены из кэша. +</para> + +<para> +Пример конфигурации: +<example> +uwsgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m; + +map $request_method $purge_method { + PURGE 1; + default 0; +} + +server { + ... + location / { + uwsgi_pass http://backend; + uwsgi_cache cache_zone; + uwsgi_cache_key $uri; + uwsgi_cache_purge $purge_method; + } +} +</example> +<note> +Функциональность доступна как часть +<commercial_version>коммерческой подписки</commercial_version>. +</note> +</para> + +</directive> + + +<directive name="uwsgi_cache_revalidate"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.5.7</appeared-in> + +<para> +Разрешает ревалидацию просроченных элементов кэша при помощи +условных запросов с полем заголовка <header>If-Modified-Since</header>. +</para> + +</directive> + + +<directive name="uwsgi_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_403</literal> | + <literal>http_404</literal> | + <literal>off</literal> + ...</syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Определяет, в каких случаях можно использовать устаревший закэшированный ответ, +если при работе с uwsgi-сервером возникла ошибка. +Параметры директивы совпадают с параметрами +директивы <link id="uwsgi_next_upstream"/>. +</para> + +<para> +Кроме того, дополнительный параметр <literal>updating</literal> +разрешает использовать устаревший закэшированный ответ, +если на данный момент он уже обновляется. +Это позволяет минимизировать число обращений к uwsgi-серверам +при обновлении закэшированных данных. +</para> + +<para> +Чтобы минимизировать число обращений к uwsgi-серверам при +заполнении нового элемента кэша, можно воспользоваться директивой +<link id="uwsgi_cache_lock"/>. +</para> + +</directive> + + +<directive name="uwsgi_cache_valid"> +<syntax>[<value>код</value> ...] <value>время</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Задаёт время кэширования для разных кодов ответа. +Например, директивы +<example> +uwsgi_cache_valid 200 302 10m; +uwsgi_cache_valid 404 1m; +</example> +задают время кэширования 10 минут для ответов с кодами 200 и 302 +и 1 минуту для ответов с кодом 404. +</para> + +<para> +Если указано только <value>время</value> кэширования, +<example> +uwsgi_cache_valid 5m; +</example> +то кэшируются только ответы 200, 301 и 302. +</para> + +<para> +Кроме того, можно кэшировать любые ответы с помощью параметра +<literal>any</literal>: +<example> +uwsgi_cache_valid 200 302 10m; +uwsgi_cache_valid 301 1h; +uwsgi_cache_valid any 1m; +</example> +</para> + +<para> +Параметры кэширования могут также быть заданы непосредственно +в заголовке ответа. +Такой способ приоритетнее, чем задание времени кэширования с помощью директивы. +Поле заголовка <header>X-Accel-Expires</header> задаёт время кэширования +ответа в секундах. +Значение 0 запрещает кэшировать ответ. +Если значение начинается с префикса <literal>@</literal>, оно задаёт абсолютное +время в секундах с начала эпохи, до которого ответ может быть закэширован. +Если в заголовке нет поля <header>X-Accel-Expires</header>, +параметры кэширования определяются по полям заголовка +<header>Expires</header> или <header>Cache-Control</header>. +Ответ, в заголовке которого есть поле <header>Set-Cookie</header>, +не будет кэшироваться. +Обработка одного или более из этих полей заголовка может быть отключена +при помощи директивы <link id="uwsgi_ignore_headers"/>. +</para> + +</directive> + + +<directive name="uwsgi_connect_timeout"> +<syntax><value>время</value></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Задаёт таймаут для установления соединения с uwsgi-сервером. +Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд. +</para> + +</directive> + + +<directive name="uwsgi_hide_header"> +<syntax><value>поле</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +По умолчанию +nginx не передаёт клиенту поля заголовка <header>Status</header> и +<header>X-Accel-...</header> из ответа uwsgi-сервера. +Директива <literal>uwsgi_hide_header</literal> задаёт дополнительные поля, +которые не будут передаваться. +Если же передачу полей нужно разрешить, можно воспользоваться +директивой <link id="uwsgi_pass_header"/>. +</para> + +</directive> + + +<directive name="uwsgi_ignore_client_abort"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Определяет, закрывать ли соединение с uwsgi-сервером +в случае, если клиент закрыл соединение, не дождавшись ответа. +</para> + +</directive> + + +<directive name="uwsgi_ignore_headers"> +<syntax><value>поле</value> ...</syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Запрещает обработку некоторых полей заголовка из ответа uwsgi-сервера. +В директиве можно указать поля <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> и <header>Set-Cookie</header> (0.8.44). +</para> + +<para> +Если не запрещено, обработка этих полей заголовка заключается в следующем: +<list type="bullet" compact="no"> + +<listitem> +<header>X-Accel-Expires</header>, <header>Expires</header>, +<header>Cache-Control</header> и <header>Set-Cookie</header> +задают параметры <link id="uwsgi_cache_valid">кэширования</link> ответа; +</listitem> + +<listitem> +<header>X-Accel-Redirect</header> производит +<link doc="ngx_http_core_module.xml" id="internal">внутреннее +перенаправление</link> на указанный URI; +</listitem> + +<listitem> +<header>X-Accel-Limit-Rate</header> задаёт +<link doc="ngx_http_core_module.xml" id="limit_rate">ограничение +скорости</link> передачи ответа клиенту; +</listitem> + +<listitem> +<header>X-Accel-Buffering</header> включает или выключает +<link id="uwsgi_buffering">буферизацию</link> ответа; +</listitem> + +<listitem> +<header>X-Accel-Charset</header> задаёт желаемую +<link doc="ngx_http_charset_module.xml" id="charset">кодировку</link> +ответа. +</listitem> + +</list> +</para> + +</directive> + + +<directive name="uwsgi_intercept_errors"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Определяет, передавать ли клиенту ответы uwsgi-сервера с кодом +больше либо равным 300, или же перенаправлять их на обработку nginx’у с помощью +директивы <link doc="ngx_http_core_module.xml" id="error_page"/>. +</para> + +</directive> + + +<directive name="uwsgi_max_temp_file_size"> +<syntax><value>размер</value></syntax> +<default>1024m</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Если включена <link id="uwsgi_buffering">буферизация</link> ответов +uwsgi-сервера, и ответ не вмещается целиком в буферы, +заданные директивами <link id="uwsgi_buffer_size"/> и +<link id="uwsgi_buffers"/>, часть ответа может быть записана во временный файл. +Эта директива задаёт максимальный <value>размер</value> временного файла. +Размер данных, сбрасываемых во временный файл за один раз, задаётся +директивой <link id="uwsgi_temp_file_write_size"/>. +</para> + +<para> +Значение 0 отключает возможность буферизации ответов во временные файлы. +</para> + +</directive> + + +<directive name="uwsgi_next_upstream"> +<syntax> + <literal>error</literal> | + <literal>timeout</literal> | + <literal>invalid_header</literal> | + <literal>http_500</literal> | + <literal>http_503</literal> | + <literal>http_403</literal> | + <literal>http_404</literal> | + <literal>off</literal> + ...</syntax> +<default>error timeout</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Определяет, в каких случаях запрос будет передан следующему серверу: +<list type="tag"> + +<tag-name><literal>error</literal></tag-name> +<tag-desc>произошла ошибка соединения с сервером, передачи ему запроса или +чтения заголовка ответа сервера;</tag-desc> + +<tag-name><literal>timeout</literal></tag-name> +<tag-desc>произошёл таймаут во время соединения с сервером, +передачи ему запроса или чтения заголовка ответа сервера;</tag-desc> + +<tag-name><literal>invalid_header</literal></tag-name> +<tag-desc>сервер вернул пустой или неверный ответ;</tag-desc> + +<tag-name><literal>http_500</literal></tag-name> +<tag-desc>сервер вернул ответ с кодом 500;</tag-desc> + +<tag-name><literal>http_503</literal></tag-name> +<tag-desc>сервер вернул ответ с кодом 503;</tag-desc> + +<tag-name><literal>http_403</literal></tag-name> +<tag-desc>сервер вернул ответ с кодом 403;</tag-desc> + +<tag-name><literal>http_404</literal></tag-name> +<tag-desc>сервер вернул ответ с кодом 404;</tag-desc> + +<tag-name><literal>off</literal></tag-name> +<tag-desc>запрещает передачу запроса следующему серверу.</tag-desc> + +</list> +</para> + +<para> +Необходимо понимать, что передача запроса следующему серверу возможна +только при условии, что клиенту ещё ничего не передавалось. +То есть, если ошибка или таймаут возникли в середине передачи ответа, +то исправить это уже невозможно. +</para> + +<para> +Директива также определяет, что считается неудачной попыткой работы с +<link doc="ngx_http_upstream_module.xml" id="server">сервером</link>. +Случаи <literal>error</literal>, <literal>timeout</literal> и +<literal>invalid_header</literal> +всегда считаются неудачными попытками, даже если они не указаны в директиве. +Случаи <literal>http_500</literal> и <literal>http_503</literal> +считаются неудачными попытками, только если они указаны в директиве. +Случаи <literal>http_403</literal> и <literal>http_404</literal> +никогда не считаются неудачными попытками. +</para> + +</directive> + + +<directive name="uwsgi_no_cache"> +<syntax><value>строка</value> ...</syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Задаёт условия, при которых ответ не будет сохраняться в кэш. +Если значение хотя бы одного из строковых параметров непустое и не равно “0”, +то ответ не будет сохранён: +<example> +uwsgi_no_cache $cookie_nocache $arg_nocache$arg_comment; +uwsgi_no_cache $http_pragma $http_authorization; +</example> +Можно использовать совместно с директивой <link id="uwsgi_cache_bypass"/>. +</para> + +</directive> + + +<directive name="uwsgi_param"> +<syntax> + <value>параметр</value> <value>значение</value> + [<literal>if_not_empty</literal>]</syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Задаёт <value>параметр</value>, который будет передаваться uwsgi-серверу. +В качестве значения можно использовать текст, переменные и их комбинации. +Директивы наследуются с предыдущего уровня при условии, что на данном +уровне не описаны свои директивы <literal>uwsgi_param</literal>. +</para> + +<para> +Стандартные +<link url="http://tools.ietf.org/html/rfc3875#section-4.1">переменные +окружения CGI</link> +должны передаваться как заголовки uwsgi, см. файл <path>uwsgi_params</path> +из дистрибутива: +<example> +location / { + include uwsgi_params; + ... +} +</example> +</para> + +<para> +Если директива указана с <literal>if_not_empty</literal> (1.1.11), +то такой параметр с пустым значением передаваться на сервер не будет: +<example> +uwsgi_param HTTPS $https if_not_empty; +</example> +</para> + +</directive> + + +<directive name="uwsgi_pass"> +<syntax><value>адрес</value></syntax> +<default/> +<context>location</context> +<context>if в location</context> + +<para> +Задаёт адрес uwsgi-сервера. +Адрес может быть указан в виде доменного имени или адреса, и порта, например, +<example> +uwsgi_pass localhost:9000; +</example> +или в виде пути UNIX-сокета: +<example> +uwsgi_pass unix:/tmp/uwsgi.socket; +</example> +</para> + +<para> +Если доменному имени соответствует несколько адресов, то все они будут +использоваться по очереди (round-robin). +И, кроме того, адрес может быть +<link doc="ngx_http_upstream_module.xml">группой серверов</link>. +</para> + +</directive> + + +<directive name="uwsgi_pass_header"> +<syntax><value>поле</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Разрешает передавать от uwsgi-сервера клиенту +<link id="uwsgi_hide_header">запрещённые для передачи</link> поля заголовка. +</para> + +</directive> + + +<directive name="uwsgi_pass_request_body"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Позволяет запретить передачу исходного тела запроса +на uwsgi-сервер. +См. также директиву <link id="uwsgi_pass_request_headers"/>. +</para> + +</directive> + + +<directive name="uwsgi_pass_request_headers"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Позволяет запретить передачу полей заголовка исходного запроса на +uwsgi-сервер. +См. также директивы <link id="uwsgi_pass_request_body"/>. +</para> + +</directive> + + +<directive name="uwsgi_read_timeout"> +<syntax><value>время</value></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Задаёт таймаут при чтении ответа uwsgi-сервера. +Таймаут устанавливается не на всю передачу ответа, +а только между двумя операциями чтения. +Если по истечении этого времени uwsgi-сервер ничего не передаст, +соединение закрывается. +</para> + +</directive> + + +<directive name="uwsgi_send_timeout"> +<syntax><value>время</value></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Задаёт таймаут при передаче запроса uwsgi-серверу. +Таймаут устанавливается не на всю передачу запроса, +а только между двумя операциями записи. +Если по истечении этого времени uwsgi-сервер не примет новых данных, +соединение закрывается. +</para> + +</directive> + + +<directive name="uwsgi_store"> +<syntax> + <literal>on</literal> | + <literal>off</literal> | + <value>строка</value></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Разрешает сохранение на диск файлов. +Параметр <literal>on</literal> сохраняет файлы в соответствии с путями, +указанными в директивах +<link doc="ngx_http_core_module.xml" id="alias"/> или +<link doc="ngx_http_core_module.xml" id="root"/>. +Параметр <literal>off</literal> запрещает сохранение файлов. +Кроме того, имя файла можно задать явно с помощью строки с переменными: +<example> +uwsgi_store /data/www$original_uri; +</example> +</para> + +<para> +Время изменения файлов выставляется согласно полученному полю +<header>Last-Modified</header> в заголовке ответа. +Ответ сначала записывается во временный файл, а потом этот файл +переименовывается. +Начиная с версии 0.8.9, временный файл и постоянное место хранения ответа +могут располагаться на разных файловых системах. +Однако нужно учитывать, +что в этом случае вместо дешёвой операции переименовывания в пределах +одной файловой системы файл копируется с одной файловой системы на другую. +Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой +системе, что и каталог с временными файлами, задаваемый директивой +<link id="uwsgi_temp_path"/> для данного location. +</para> + +<para> +Директиву можно использовать для создания локальных копий статических +неизменяемых файлов, например, так: +<example> +location /images/ { + root /data/www; + error_page 404 = /fetch$uri; +} + +location /fetch/ { + internal; + + uwsgi_pass backend:9000; + ... + + uwsgi_store on; + uwsgi_store_access user:rw group:rw all:r; + uwsgi_temp_path /data/temp; + + alias /data/www/; +} +</example> +</para> + +</directive> + + +<directive name="uwsgi_store_access"> +<syntax><value>пользователи</value>:<value>права</value> ...</syntax> +<default>user:rw</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Задаёт права доступа для создаваемых файлов и каталогов, например, +<example> +uwsgi_store_access user:rw group:rw all:r; +</example> +</para> + +<para> +Если заданы какие-либо права для <literal>group</literal> или +<literal>all</literal>, то права для <literal>user</literal> +указывать необязательно: +<example> +uwsgi_store_access group:rw all:r; +</example> +</para> + +</directive> + + +<directive name="uwsgi_temp_file_write_size"> +<syntax><value>размер</value></syntax> +<default>8k|16k</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Ограничивает <value>размер</value> данных, сбрасываемых во временный файл +за один раз, при включённой буферизации ответов uwsgi-сервера +во временные файлы. +По умолчанию <value>размер</value> ограничен двумя буферами, заданными +директивами <link id="uwsgi_buffer_size"/> и <link id="uwsgi_buffers"/>. +Максимальный размер временного файла задаётся директивой +<link id="uwsgi_max_temp_file_size"/>. +</para> + +</directive> + + +<directive name="uwsgi_temp_path"> +<syntax> + <value>путь</value> + [<value>уровень1</value> + [<value>уровень2</value> + [<value>уровень3</value>]]]</syntax> +<default>uwsgi_temp</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Задаёт имя каталога для хранения временных файлов с данными, +полученными от uwsgi-серверов. +В каталоге может использоваться иерархия подкаталогов до трёх уровней. +Например, при такой конфигурации +<example> +uwsgi_temp_path /spool/nginx/uwsgi_temp 1 2; +</example> +временный файл будет следующего вида: +<example> +/spool/nginx/uwsgi_temp/<emphasis>7</emphasis>/<emphasis>45</emphasis>/00000123<emphasis>457</emphasis> +</example> +</para> + +</directive> + +</section> + +</module>