nginx

Module ngx_http_memcached_module


english
русский

简体中文
עברית
日本語
türkçe
italiano

news
about
download
security advisories
documentation
pgp keys
faq
links
books
support
donation

trac
wiki
twitter
nginx.com
blog
Example Configuration
Directives
     memcached_bind
     memcached_buffer_size
     memcached_connect_timeout
     memcached_gzip_flag
     memcached_next_upstream
     memcached_pass
     memcached_read_timeout
     memcached_send_timeout
Embedded Variables

The ngx_http_memcached_module module is used to obtain responses from a memcached server. The key is set in the $memcached_key variable. A response should be put in memcached in advance by means external to nginx.

Example Configuration

server {
    location / {
        set            $memcached_key "$uri?$args";
        memcached_pass host:11211;
        error_page     404 502 504 = @fallback;
    }

    location @fallback {
        proxy_pass     http://backend;
    }
}

Directives

Syntax: memcached_bind address | off;
Default:
Context: http, server, location

This directive appeared in version 0.8.22.

Makes outgoing connections to a memcached server originate from the specified local IP address. Parameter value can contain variables (1.3.12). The special value off (1.3.12) cancels the effect of the memcached_bind directive inherited from the previous configuration level, which allows the system to auto-assign the local IP address.

Syntax: memcached_buffer_size size;
Default:
memcached_buffer_size 4k|8k;
Context: http, server, location

Sets the size of the buffer used for reading the response received from the memcached server. The response is passed to the client synchronously, as soon as it is received.

Syntax: memcached_connect_timeout time;
Default:
memcached_connect_timeout 60s;
Context: http, server, location

Defines a timeout for establishing a connection with a memcached server. It should be noted that this timeout cannot usually exceed 75 seconds.

Syntax: memcached_gzip_flag flag;
Default:
Context: http, server, location

This directive appeared in version 1.3.6.

Enables the test for the flag presence in the memcached server response and sets the “Content-Encoding” response header field to “gzip” if the flag is set.

Syntax: memcached_next_upstream error | timeout | invalid_response | not_found | off ...;
Default:
memcached_next_upstream error timeout;
Context: http, server, location

Specifies in which cases a request should be passed to the next server:

error
an error occurred while establishing a connection with the server, passing a request to it, or reading the response header;
timeout
a timeout has occurred while establishing a connection with the server, passing a request to it, or reading the response header;
invalid_response
a server returned an empty or invalid response;
not_found
a response was not found on the server;
off
disables passing a request to the next server.

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.

The directive also defines what is considered an unsuccessful attempt of communication with a server. The cases of error, timeout and invalid_header are always considered unsuccessful attempts, even if they are not specified in the directive. The case of not_found is never considered an unsuccessful attempt.

Syntax: memcached_pass address;
Default:
Context: location, if in location

Sets the memcached server address. The address can be specified as a domain name or an address, and a port:

memcached_pass localhost:11211;

or as a UNIX-domain socket path:

memcached_pass unix:/tmp/memcached.socket;

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 server group.

Syntax: memcached_read_timeout time;
Default:
memcached_read_timeout 60s;
Context: http, server, location

Defines a timeout for reading a response from the memcached server. The timeout is set only between two successive read operations, not for the transmission of the whole response. If the memcached server does not transmit anything within this time, the connection is closed.

Syntax: memcached_send_timeout time;
Default:
memcached_send_timeout 60s;
Context: http, server, location

Sets a timeout for transmitting a request to the memcached server. The timeout is set only between two successive write operations, not for the transmission of the whole request. If the memcached server does not receive anything within this time, the connection is closed.

Embedded Variables

$memcached_key
Defines a key for obtaining response from a memcached server.