ngx_http_memcached_module.xml

<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_http_memcached_module"
        link="/en/docs/http/ngx_http_memcached_module.html"
        lang="en"
        rev="19">

<section id="summary">

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

</section>


<section id="example" name="Example Configuration">

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

    location @fallback {
        proxy_pass     http://backend;
    }
}
</example>
</para>

</section>


<section id="directives" name="Directives">

<directive name="memcached_allow_upstream">
<syntax><value>string</value> ...</syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.29.3</appeared-in>

<para>
Defines conditions under which access to a memcached server
is allowed or <link id="denied">denied</link>.
If all string parameters are not empty
and not equal to “0” then the access is allowed.
The conditions are evaluated each time
before a connection to a memcached server is established.
Parameter values can contain variables:
<example>
geo $upstream_last_addr $allow {
    volatile;
    10.10.0.0/24        1;
}

server {
    listen 127.0.0.1:8080;

    location / {
        memcached_pass           host:11211;
        memcached_allow_upstream $allow;
        ...
    }
}
</example>
</para>

<para>
<note>
This directive is available as part of our
<commercial_version>commercial subscription</commercial_version>.
</note>
</para>

</directive>


<directive name="memcached_bind">
<syntax>
    <value>address</value>
    [<literal>transparent </literal>] |
    <literal>off</literal></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>0.8.22</appeared-in>

<para>
Makes outgoing connections to a memcached server originate
from the specified local IP address with an optional port (1.11.2).
Parameter value can contain variables (1.3.12).
The special value <literal>off</literal> (1.3.12) cancels the effect
of the <literal>memcached_bind</literal> directive
inherited from the previous configuration level, which allows the
system to auto-assign the local IP address and port.
</para>

<para id="memcached_bind_transparent">
The <literal>transparent</literal> parameter (1.11.0) allows
outgoing connections to a memcached server originate
from a non-local IP address,
for example, from a real IP address of a client:
<example>
memcached_bind $remote_addr transparent;
</example>
In order for this parameter to work,
it is usually necessary to run nginx worker processes with the
<link doc="../ngx_core_module.xml" id="user">superuser</link> privileges.
On Linux it is not required (1.13.8) as if
the <literal>transparent</literal> parameter is specified, worker processes
inherit the <literal>CAP_NET_RAW</literal> capability from the master process.
It is also necessary to configure kernel routing table
to intercept network traffic from the memcached server.
</para>

</directive>


<directive name="memcached_bind_dynamic">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.29.3</appeared-in>

<para>
When enabled, makes the <link id="memcached_bind">bind</link> operation
at each connection attempt.
</para>

<para>
<note>
This directive is available as part of our
<commercial_version>commercial subscription</commercial_version>.
</note>
</para>

</directive>


<directive name="memcached_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 response
received from the memcached server.
The response is passed to the client synchronously, as soon as it is received.
</para>

</directive>


<directive name="memcached_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 memcached server.
It should be noted that this timeout cannot usually exceed 75 seconds.
</para>

</directive>


<directive name="memcached_gzip_flag">
<syntax><value>flag</value></syntax>
<default></default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.3.6</appeared-in>

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

</directive>


<directive name="memcached_next_upstream">
<syntax>
    <literal>error</literal> |
    <literal>timeout</literal> |
    <literal>denied</literal> |
    <literal>invalid_response</literal> |
    <literal>not_found</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 id="denied"><literal>denied</literal></tag-name>
<tag-desc>the server <link id="memcached_allow_upstream">denied</link>
the connection (1.29.3);
<para>
<note>
This parameter is available as part of our
<commercial_version>commercial subscription</commercial_version>.
</note>
</para>
</tag-desc>

<tag-name><literal>invalid_response</literal></tag-name>
<tag-desc>a server returned an empty or invalid response;</tag-desc>

<tag-name><literal>not_found</literal></tag-name>
<tag-desc>a response was not found on the server;</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
<link doc="ngx_http_upstream_module.xml" id="max_fails">unsuccessful
attempt</link> of communication with a server.
The cases of <literal>error</literal>, <literal>timeout</literal>,
<literal>denied</literal> and
<literal>invalid_response</literal> are always considered unsuccessful attempts,
even if they are not specified in the directive.
The case of <literal>not_found</literal>
is never considered an unsuccessful attempt.
</para>

<para>
Passing a request to the next server can be limited by
<link id="memcached_next_upstream_tries">the number of tries</link>
and by <link id="memcached_next_upstream_timeout">time</link>.
</para>

</directive>


<directive name="memcached_next_upstream_timeout">
<syntax><value>time</value></syntax>
<default>0</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.5</appeared-in>

<para>
Limits the time during which a request can be passed to the
<link id="memcached_next_upstream">next server</link>.
The <literal>0</literal> value turns off this limitation.
</para>

</directive>


<directive name="memcached_next_upstream_tries">
<syntax><value>number</value></syntax>
<default>0</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.5</appeared-in>

<para>
Limits the number of possible tries for passing a request to the
<link id="memcached_next_upstream">next server</link>.
The <literal>0</literal> value turns off this limitation.
</para>

</directive>


<directive name="memcached_pass">
<syntax><value>address</value></syntax>
<default/>
<context>location</context>
<context>if in location</context>

<para>
Sets the memcached server address.
The address can be specified as a domain name or IP address,
and a port:
<example>
memcached_pass localhost:11211;
</example>
or as a UNIX-domain socket path:
<example>
memcached_pass unix:/tmp/memcached.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="memcached_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 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.
</para>

</directive>


<directive name="memcached_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 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.
</para>

</directive>


<directive name="memcached_socket_keepalive">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.15.6</appeared-in>

<para>
Configures the “TCP keepalive” behavior
for outgoing connections to a memcached server.
By default, the operating system’s settings are in effect for the socket.
If the directive is set to the value “<literal>on</literal>”, the
<c-def>SO_KEEPALIVE</c-def> socket option is turned on for the socket.
</para>

</directive>

</section>


<section id="variables" name="Embedded Variables">

<para>
<list type="tag">

<tag-name id="var_memcached_key"><var>$memcached_key</var></tag-name>
<tag-desc>
Defines a key for obtaining response from a memcached server.
</tag-desc>

</list>
</para>

</section>

</module>