Qqq1243: add uwsgi_cache_key on caching example

2013-04-03T14:02:14Z

add uwsgi_cache_key on caching example

WGH: [emerg] invalid value "no" in "uwsgi_buffering" directive, it must be "on" or "off"

2012-07-22T20:42:49Z

[emerg] invalid value "no" in "uwsgi_buffering" directive, it must be "on" or "off"

Andyvlx: /* Directives */

2012-06-15T14:03:03Z

‎Directives

Kolbyjack: Copy/paste error

2011-10-06T11:58:19Z

Copy/paste error

New page

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

''Do not confuse the uwsgi protocol with the uWSGI server (that speaks the uwsgi protocol)''

This module first appeared in nginx-0.8.40

Example:
<geshi lang="nginx">
location / {
include uwsgi_params;
uwsgi_pass unix:/var/run/example.com.sock;
}
</geshi>

Caching example:
<geshi lang="nginx">
http {
uwsgi_cache_path /path/to/cache levels=1:2
keys_zone=NAME:10m
inactive=5m;

server {
location / {
uwsgi_pass unix:/var/run/example.com.sock;
uwsgi_cache NAME;
uwsgi_cache_valid 200 302 1h;
uwsgi_cache_valid 301 1d;
uwsgi_cache_valid any 1m;
uwsgi_cache_min_uses 1;
uwsgi_cache_use_stale error timeout invalid_header http_500;
}
}
}
</geshi>

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

= Directives =
== uwsgi_bind ==
'''syntax:''' ''uwsgi_bind address''

'''default:''' ''none''

'''context:''' ''http, server, location''

'''example:'''
<geshi lang="nginx">
uwsgi_bind 192.168.1.1;
</geshi>

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

== uwsgi_buffer_size ==
'''syntax:''' ''uwsgi_buffer_size the_size''

'''default:''' ''uwsgi_buffer_size 4k/8k''

'''context:''' ''http, server, location''

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

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

By default, the buffer size is equal to the size of one buffer in directive [[#uwsgi_buffers|uwsgi_buffers]], however it is possible to set it to less.

== uwsgi_buffering ==

'''syntax:''' uwsgi_buffering ''yes | no''

'''default:''' uwsgi_buffering ''yes''

'''context:''' ''http, server, location''

'''version:''' ''1.1.5''

'''variables:''' ''no''

This directive controls response buffering of the response.

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

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

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

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

== uwsgi_buffers ==
'''syntax:''' ''uwsgi_buffers the_number is_size''

'''default:''' ''uwsgi_buffers 8 4k/8k''

'''context:''' ''http, server, location''

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

== uwsgi_busy_buffers_size ==
'''syntax:''' ''uwsgi_busy_buffers_size size''

'''default:''' ''uwsgi_busy_buffers_size ["#uwsgi_buffer_size"] * 2''

'''context:''' ''http, server, location, if''

''Undocumented''

== uwsgi_cache ==
'''syntax:''' ''uwsgi_cache zone|off''

'''default:''' ''off''

'''context:''' ''http, server, location''

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

== uwsgi_cache_bypass ==
'''syntax:''' ''uwsgi_cache_bypass variable1 variable2...''

'''default:''' ''none''

'''context:''' ''http, server, location''

'''version:''' ''>= 0.8.46''

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

<geshi lang="nginx">
uwsgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
uwsgi_cache_bypass $http_pragma $http_authorization;
</geshi>

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

Note that the response from the back-end is still eligible for caching. Thus one way of refreshing an item in the cache is sending a request with a header you pick yourself, e.g. "My-Secret-Header: 1", then having a '''uwsgi_no_cache''' line like:
<geshi lang="nginx">
uwsgi_no_cache $http_my_secret_header;
</geshi>

== uwsgi_cache_key ==
'''syntax:''' ''uwsgi_cache_key line''

'''default:''' ''none''

'''context:''' ''http, server, location''

The directive sets the key for caching, for example:
<geshi lang="nginx">
uwsgi_cache_key localhost:9000$request_uri;
</geshi>

== uwsgi_cache_methods ==
'''syntax:''' ''uwsgi_cache_methods [GET HEAD POST]''

'''default:''' ''uwsgi_cache_methods GET HEAD''

'''context:''' ''http, server, location''

GET/HEAD is syntax sugar, i.e. you can not disable GET/HEAD even if you set just
<geshi lang="nginx">
uwsgi_cache_methods POST;
</geshi>

== uwsgi_cache_min_uses ==
'''syntax:''' ''uwsgi_cache_min_uses the_number''

'''default:''' ''uwsgi_cache_min_uses 1''

'''context:''' ''http, server, location''

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

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

'''default:''' ''none''

'''context:''' ''http''

The ''clean_time'' parameter was removed in 0.7.45.

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

Level parameter sets number and width of the names of subdirectories used to store caching files. For example, with the directive like:
<geshi lang="nginx">
uwsgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;
</geshi>
the data will be stored in the following file:
<geshi lang="nginx">
/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c
</geshi>

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 [[#uwsgi_temp_path|uwsgi_temp_path]] and <code>uwsgi_cache_path</code> 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 <code>key_zone</code> parameter. In case this data haven't been accessed for the time, specified in the option of <code>inactive</code> 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 <code>max_size</code> parameter, a special process '''cache manager''' periodically deletes old data from the cache.

== uwsgi_cache_use_stale ==
'''syntax:''' ''uwsgi_cache_use_stale updating|error|timeout|invalid_header|http_500''

'''default:''' ''uwsgi_cache_use_stale off''

'''context:''' ''http, server, location''

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

== uwsgi_cache_valid ==
'''syntax:''' ''uwsgi_cache_valid [http_return_code [...]] time''

'''default:''' ''none''

'''context:''' ''http, server, location''

Directive sets caching period for the specified http return codes. For example:
<geshi lang="nginx">
uwsgi_cache_valid 200 302 10m;
uwsgi_cache_valid 404 1m;
</geshi>
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:
<geshi lang="nginx">
uwsgi_cache_valid 5m;
</geshi>
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":
<geshi lang="nginx">
uwsgi_cache_valid 200 302 10m;
uwsgi_cache_valid 301 1h;
uwsgi_cache_valid any 1m;
</geshi>

== uwsgi_connect_timeout ==
'''syntax:''' ''uwsgi_connect_timeout time''

'''default:''' ''uwsgi_connect_timeout 60''

'''context:''' ''http, server, location''

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

== uwsgi_hide_header ==
'''syntax:''' ''uwsgi_hide_header name''

'''context:''' ''http, server, location''

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

If the "X-Accel-..." headers must be provided, then it is necessary to use directive [[#uwsgi_pass_header|uwsgi_pass_header]] to force them to be returned to the client.

== uwsgi_ignore_client_abort ==
'''syntax:''' ''uwsgi_ignore_client_abort on|off''

'''default:''' ''uwsgi_ignore_client_abort off''

'''context:''' ''http, server, location''

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

== uwsgi_ignore_headers ==
'''syntax:''' ''uwsgi_ignore_headers name [name...]''

'''context:''' ''http, server, location''

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

== uwsgi_intercept_errors ==
'''syntax:''' ''uwsgi_intercept_errors on|off''

'''default:''' ''uwsgi_intercept_errors off''

'''context:''' ''http, server, location''

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

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

== uwsgi_max_temp_file_size ==
'''syntax:''' ''uwsgi_max_temp_file_size 0''

'''default:''' ''?''

'''context:''' ''?''

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

== uwsgi_modifier1 ==
'''syntax:''' ''uwsgi_modifier1 value''

'''default:''' ''0''

'''context:''' ''server, location''

Set the first modifier for a uwsgi request (the default is a WSGI request)

== uwsgi_modifier2 ==
'''syntax:''' ''uwsgi_modifier2 value''

'''default:''' ''0''

'''context:''' ''server, location''

Set the second modifier for a uwsgi request

== uwsgi_next_upstream ==
'''syntax:''' ''uwsgi_next_upstream error|timeout|invalid_header|http_500|http_503|http_404|off''

'''default:''' ''uwsgi_next_upstream error timeout''

'''context:''' ''http, server, location''

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

* error — an error occurred during connection to the server, passing request to it or reading server respond header;
* timeout — a timeout occurred during connection to the server, passing request to it or reading server respond header;
* invalid_header — server returned empty or invalid answer;
* http_500 — server returned 500 respond;
* http_503 — server returned 503 respond;
* http_404 — server returned 404 respond;
* updating — ''?''
* 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.

== uwsgi_no_cache ==
'''syntax:''' ''uwsgi_no_cache variable [...]''

'''default:''' ''none''

'''context:''' ''http, server, location''

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

<geshi lang="nginx">
uwsgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
uwsgi_no_cache $http_pragma $http_authorization;
</geshi>

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

== uwsgi_param ==
'''syntax:''' ''uwsgi_param parameter value''

'''default:''' ''none''

'''context:''' ''http, server, location''

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

== uwsgi_pass ==
'''syntax:''' ''uwsgi_pass uwsgi-server''

'''default:''' ''none''

'''context:''' ''location, if in location''

Directive assigns the port or socket on which the uWSGI-server is listening. Port can be indicated by itself or as an address and port, for example:
<geshi lang="nginx">
uwsgi_pass localhost:9000;
</geshi>

using a Unix domain socket:
<geshi lang="nginx">
uwsgi_pass unix:/tmp/uwsgi.socket;
</geshi>

You may also use an upstream block.
<geshi lang="nginx">
upstream backend {
server 127.0.0.1:1234;
server unix:/var/run/example.com.sock;
}

uwsgi_pass backend;
</geshi>

== uwsgi_pass_header ==
'''syntax:''' ''uwsgi_pass_header name''

'''context:''' ''http, server, location''

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

== uwsgi_pass_request_body ==
'''syntax:''' ''uwsgi_pass_request_body on|off''

'''default:''' ''uwsgi_pass_request_body on''

'''context:''' ''http, server, location''

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

== uwsgi_pass_request_headers ==
'''syntax:''' ''uwsgi_pass_request_headers on|off''

'''default:''' ''uwsgi_pass_request_headers on''

'''context:''' ''http, server, location''

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

== uwsgi_read_timeout ==
'''syntax:''' ''uwsgi_read_timeout time''

'''default:''' ''uwsgi_read_timeout 60''

'''context:''' ''http, server, location''

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

== uwsgi_send_timeout ==
'''syntax:''' ''uwsgi_send_timeout time''

'''default:''' ''uwsgi_send_timeout 60''

'''context:''' ''http, server, location''

Directive specifies the timeout when sending the request to uwsgi. The timeout is calculated between two write operations, not for the whole request. If no data has been written during this period then nginx closes the connection.

== uwsgi_store ==
'''syntax:''' ''uwsgi_store on|off|path''

'''default:''' ''uwsgi_store off''

'''context:''' ''http, server, location''

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

<geshi lang="nginx">
uwsgi_store /data/www$original_uri;
</geshi>

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 [[#uwsgi_temp_path|uwsgi_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:

<geshi lang="nginx">
location /images/ {
root /data/www;
error_page 404 = /fetch$uri;
}

location /fetch {
internal;

uwsgi_pass backend;
uwsgi_store on;
uwsgi_store_access user:rw group:rw all:r;
uwsgi_temp_path /data/temp;

alias /data/www;
}
</geshi>

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

== uwsgi_store_access ==
'''syntax:''' ''uwsgi_store_access users:permissions [users:permission ...] ''

'''default:''' ''uwsgi_store_access user:rw''

'''context:''' ''http, server, location''

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

<geshi lang="nginx">
uwsgi_store_access user:rw group:rw all:r;
</geshi>

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

<geshi lang="nginx">
uwsgi_store_access group:rw all:r;
</geshi>

== uwsgi_string ==
'''syntax:''' ''uwsgi_string string''

'''default:''' ''none''

'''context:''' ''server, location''

append a string to a uwsgi request

Example (for a uwsgi compatible server that support the '''eval modifier''' as uWSGI)
<geshi lang="nginx">
location / {
uwsgi_pass unix:/var/run/example.com.sock;
uwsgi_pass_request_headers off;
uwsgi_pass_request_body off;
uwsgi_string "

import uwsgi

uwsgi.start_response('200 OK', [('Content-type','text/plain')])
total = 30+22
uwsgi.send("30 + 22 = %d" % total)

";

uwsgi_modifier1 22;
uwsgi_modifier2 0;

}
</geshi>

== uwsgi_temp_file_write_size ==
'''syntax:''' ''uwsgi_temp_file_write_size size''

'''default:''' ''uwsgi_temp_file_write_size ["#uwsgi_buffer_size"] * 2''

'''context:''' ''http, server, location, if''

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

== uwsgi_temp_path ==
'''syntax:''' ''uwsgi_temp_path path [level1 [level2 [level3]]]''

'''default:''' ''uwsgi_temp_path uwsgi_temp''

'''context:''' ''http, server, location''

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

<geshi lang="nginx">
uwsgi_temp_path /spool/nginx/uwsgi_temp 1 2;
</geshi>

Temporary file name may look like:

<geshi lang="nginx">
/spool/nginx/uwsgi_temp/7/45/00000123457
</geshi>

= Parameters transferred to uWSGI-server. =

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

= References =
* [http://projects.unbit.it/uwsgi/wiki uWSGI Project]
* [http://projects.unbit.it/uwsgi/wiki/RunOnNginx nginx page on uWSGI wiki]
* [http://www.westphahl.net/blog/2010/4/8/running-django-nginx-and-uwsgi/ Simon Westphahl's blog]
* [[NginxHttpFcgiModule|SCGI Module]]

= Links =
* [[HttpUwsgiModuleMultipleDynamicApplications|Multiple uWSGI apps from a single upstream]]

@@ Line 24: / Line 24: @@
    server {
      location / {
-       uwsgi_pass    unix:/var/run/example.com.sock;
+       uwsgi_pass          unix:/var/run/example.com.sock;
-       uwsgi_cache   NAME;
+       uwsgi_cache         NAME;
        uwsgi_cache_valid   200 302  1h;
        uwsgi_cache_valid   301      1d;

@@ Line 68: / Line 68: @@
 == uwsgi_buffering ==
-'''syntax:''' uwsgi_buffering ''yes | no''
+'''syntax:''' uwsgi_buffering ''on | off''
-'''default:''' uwsgi_buffering ''yes''
+'''default:''' uwsgi_buffering ''on''
 '''context:''' ''http, server, location''

@@ Line 150: / Line 150: @@
 uwsgi_cache_key localhost:9000$request_uri;
 </geshi>
 == uwsgi_cache_methods ==

HttpUwsgiModule - Revision history

Qqq1243: add uwsgi_cache_key on caching example

WGH: [emerg] invalid value "no" in "uwsgi_buffering" directive, it must be "on" or "off"

Andyvlx: /* Directives */

Kolbyjack: Copy/paste error