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="Модуль ngx_http_memcached_module"
        link="/ru/docs/http/ngx_http_memcached_module.html"
        lang="ru"
        rev="19">

<section id="summary">

<para>
Модуль <literal>ngx_http_memcached_module</literal> позволяет получать
ответ из сервера memcached.
Ключ задаётся в переменной <var>$memcached_key</var>.
Ответ в memcached должен быть предварительно помещён внешним по отношению
к nginx’у способом.
</para>

</section>


<section id="example" name="Пример конфигурации">

<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="Директивы">

<directive name="memcached_allow_upstream">
<syntax><value>строка</value> ...</syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.29.3</appeared-in>

<para>
Задаёт условия, при которых доступ к серверу memcached
будет разрешён или <link id="denied">запрещён</link>.
Если все значения строковых параметров непустые
и не равны “0”, то доступ разрешён.
Условия проверяются каждый раз
перед установлением соединения с сервером memcached.
В значении параметров допустимо использование переменных:
<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>
Директива доступна как часть
<commercial_version>коммерческой подписки</commercial_version>.
</note>
</para>

</directive>


<directive name="memcached_bind">
<syntax>
    <value>адрес</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>
Задаёт локальный IP-адрес с необязательным портом (1.11.2),
который будет использоваться в исходящих соединениях с сервером memcached.
В значении параметра допустимо использование переменных (1.3.12).
Специальное значение <literal>off</literal> (1.3.12) отменяет действие
унаследованной с предыдущего уровня конфигурации
директивы <literal>memcached_bind</literal>, позволяя системе
самостоятельно выбирать локальный IP-адрес и порт.
</para>

<para id="memcached_bind_transparent">
Параметр <literal>transparent</literal> (1.11.0) позволяет
задать нелокальный IP-aдрес, который будет использоваться в
исходящих соединениях с сервером memcached,
например, реальный IP-адрес клиента:
<example>
memcached_bind $remote_addr transparent;
</example>
Для работы параметра
обычно требуется
запустить рабочие процессы nginx с привилегиями
<link doc="../ngx_core_module.xml" id="user">суперпользователя</link>.
В Linux этого не требуется (1.13.8), так как если
указан параметр <literal>transparent</literal>, то рабочие процессы
наследуют capability <literal>CAP_NET_RAW</literal> из главного процесса.
Также необходимо настроить таблицу маршрутизации ядра
для перехвата сетевого трафика с сервера memcached.
</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>
Если включено, операция <link id="memcached_bind">bind</link> осуществляется
при каждой попытке соединения.
</para>

<para>
<note>
Директива доступна как часть
<commercial_version>коммерческой подписки</commercial_version>.
</note>
</para>

</directive>


<directive name="memcached_buffer_size">
<syntax><value>размер</value></syntax>
<default>4k|8k</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт <value>размер</value> буфера, в который будет читаться ответ,
получаемый от сервера memcached.
Ответ синхронно передаётся клиенту сразу же по мере его поступления.
</para>

</directive>


<directive name="memcached_connect_timeout">
<syntax><value>время</value></syntax>
<default>60s</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт таймаут для установления соединения с сервером memcached.
Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.
</para>

</directive>


<directive name="memcached_gzip_flag">
<syntax><value>флаг</value></syntax>
<default></default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.3.6</appeared-in>

<para>
Включает проверку указанного <value>флага</value> в ответе
сервера memcached и установку поля “<literal>Content-Encoding</literal>”
заголовка ответа в “<literal>gzip</literal>”, если этот флаг установлен.
</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>
Определяет, в каких случаях запрос будет передан следующему серверу:
<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 id="denied"><literal>denied</literal></tag-name>
<tag-desc>сервер <link id="proxy_allow_upstream">отклонил</link>
соединение (1.29.3);
<para>
<note>
Параметр доступен как часть
<commercial_version>коммерческой подписки</commercial_version>.
</note>
</para>
</tag-desc>

<tag-name><literal>invalid_response</literal></tag-name>
<tag-desc>сервер вернул пустой или неверный ответ;</tag-desc>

<tag-name><literal>not_found</literal></tag-name>
<tag-desc>сервер не нашёл ответ;</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="max_fails">неудачной
попыткой</link> работы с сервером.
Случаи <literal>error</literal>, <literal>timeout</literal>,
<literal>denied</literal> и
<literal>invalid_response</literal>
всегда считаются неудачными попытками, даже если они не указаны в директиве.
Случай <literal>not_found</literal>
никогда не считается неудачной попыткой.
</para>

<para>
Передача запроса следующему серверу может быть ограничена по
<link id="memcached_next_upstream_tries">количеству попыток</link>
и по <link id="memcached_next_upstream_timeout">времени</link>.
</para>

</directive>


<directive name="memcached_next_upstream_timeout">
<syntax><value>время</value></syntax>
<default>0</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.5</appeared-in>

<para>
Ограничивает время, в течение которого возможна передача запроса
<link id="memcached_next_upstream">следующему серверу</link>.
Значение <literal>0</literal> отключает это ограничение.
</para>

</directive>


<directive name="memcached_next_upstream_tries">
<syntax><value>число</value></syntax>
<default>0</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.5</appeared-in>

<para>
Ограничивает число допустимых попыток для передачи запроса
<link id="memcached_next_upstream">следующему серверу</link>.
Значение <literal>0</literal> отключает это ограничение.
</para>

</directive>


<directive name="memcached_pass">
<syntax><value>адрес</value></syntax>
<default/>
<context>location</context>
<context>if в location</context>

<para>
Задаёт адрес сервера memcached.
Адрес может быть указан в виде доменного имени или IP-адреса,
и порта:
<example>
memcached_pass localhost:11211;
</example>
или в виде пути UNIX-сокета:
<example>
memcached_pass unix:/tmp/memcached.socket;
</example>
</para>

<para>
Если доменному имени соответствует несколько адресов, то все они будут
использоваться по очереди (round-robin).
И, кроме того, адрес может быть
<link doc="ngx_http_upstream_module.xml">группой серверов</link>.
</para>

</directive>


<directive name="memcached_read_timeout">
<syntax><value>время</value></syntax>
<default>60s</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт таймаут при чтении ответа сервера memcached.
Таймаут устанавливается не на всю передачу ответа,
а только между двумя операциями чтения.
Если по истечении этого времени сервер memcached ничего не передаст,
соединение закрывается.
</para>

</directive>


<directive name="memcached_send_timeout">
<syntax><value>время</value></syntax>
<default>60s</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт таймаут при передаче запроса серверу memcached.
Таймаут устанавливается не на всю передачу запроса,
а только между двумя операциями записи.
Если по истечении этого времени сервер memcached не примет новых данных,
соединение закрывается.
</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>
Конфигурирует поведение “TCP keepalive”
для исходящих соединений к серверу memcached.
По умолчанию для сокета действуют настройки операционной системы.
Если указано значение “<literal>on</literal>”, то
для сокета включается параметр <c-def>SO_KEEPALIVE</c-def>.
</para>

</directive>

</section>


<section id="variables" name="Встроенные переменные">

<para>
<list type="tag">

<tag-name id="var_memcached_key"><var>$memcached_key</var></tag-name>
<tag-desc>
Задаёт ключ для получения ответа из сервера memcached.
</tag-desc>

</list>
</para>

</section>

</module>