Mercurial > hg > nginx-site
changeset 1743:3d686cb47c2c
Documented the map module in stream.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 05 Jul 2016 17:58:34 +0300 |
parents | c511b73da3a9 |
children | ab56dcd73af2 |
files | xml/en/GNUmakefile xml/en/docs/index.xml xml/en/docs/stream/ngx_stream_map_module.xml xml/ru/GNUmakefile xml/ru/docs/index.xml xml/ru/docs/stream/ngx_stream_map_module.xml |
diffstat | 6 files changed, 419 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/GNUmakefile Tue Jul 05 17:58:34 2016 +0300 +++ b/xml/en/GNUmakefile Tue Jul 05 17:58:34 2016 +0300 @@ -97,6 +97,7 @@ stream/ngx_stream_access_module \ stream/ngx_stream_core_module \ stream/ngx_stream_limit_conn_module \ + stream/ngx_stream_map_module \ stream/ngx_stream_proxy_module \ stream/ngx_stream_ssl_module \ stream/ngx_stream_upstream_module \
--- a/xml/en/docs/index.xml Tue Jul 05 17:58:34 2016 +0300 +++ b/xml/en/docs/index.xml Tue Jul 05 17:58:34 2016 +0300 @@ -8,7 +8,7 @@ <article name="nginx documentation" link="/en/docs/" lang="en" - rev="24" + rev="25" toc="no"> @@ -497,6 +497,11 @@ </listitem> <listitem> +<link doc="stream/ngx_stream_map_module.xml"> +ngx_stream_map_module</link> +</listitem> + +<listitem> <link doc="stream/ngx_stream_proxy_module.xml"> ngx_stream_proxy_module</link> </listitem>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/en/docs/stream/ngx_stream_map_module.xml Tue Jul 05 17:58:34 2016 +0300 @@ -0,0 +1,202 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_stream_map_module" + link="/en/docs/stream/ngx_stream_map_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_stream_map_module</literal> module (1.11.2) creates variables +whose values depend on values of other variables. +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +map $remote_addr $limit { + 127.0.0.1 ""; + default $binary_remote_addr; +} + +limit_conn_zone $limit zone=addr:10m; +limit_conn addr 1; +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="map"> +<syntax block="yes"> + <value>string</value> + <value>$variable</value></syntax> +<default/> +<context>stream</context> + +<para> +Creates a new variable whose value +depends on values of one or more of the source variables +specified in the first parameter. +</para> + +<para> +<note> +Since variables are evaluated only when they are used, the mere declaration +even of a large number of “<literal>map</literal>” variables +does not add any extra costs to connection processing. +</note> +</para> + +<para> +Parameters inside the <literal>map</literal> block specify a mapping +between source and resulting values. +</para> + +<para> +Source values are specified as strings or regular expressions. +</para> + +<para> +Strings are matched ignoring the case. +</para> + +<para> +A regular expression should either start from the “<literal>~</literal>” +symbol for a case-sensitive matching, or from the “<literal>~*</literal>” +symbols for case-insensitive matching. +A regular expression can contain named and positional captures +that can later be used in other directives along with the +resulting variable. +</para> + +<para> +If a source value matches one of the names of special parameters +described below, it should be prefixed with the “<literal>\</literal>” symbol. +</para> + +<para> +The resulting value can contain text, +variable, and their combination. +</para> + +<para> +The directive also supports three special parameters: +<list type="tag"> +<tag-name><literal>default</literal> <value>value</value></tag-name> +<tag-desc> +sets the resulting value if the source value matches none +of the specified variants. +When <literal>default</literal> is not specified, the default +resulting value will be an empty string. +</tag-desc> + +<tag-name><literal>hostnames</literal></tag-name> +<tag-desc> +indicates that source values can be hostnames with a prefix or suffix mask: +<example> +*.example.com 1; +example.* 1; +</example> +The following two records +<example> +example.com 1; +*.example.com 1; +</example> +can be combined: +<example> +.example.com 1; +</example> +This parameter should be specified before the list of values. +</tag-desc> + +<tag-name><literal>include</literal> <value>file</value></tag-name> +<tag-desc> +includes a file with values. +There can be several inclusions. +</tag-desc> + +</list> +</para> + +<para> +If the source value matches more than one of the specified variants, +e.g. both a mask and a regular expression match, the first matching +variant will be chosen, in the following order of priority: +<list type="enum"> + +<listitem> +string value without a mask +</listitem> + +<listitem> +longest string value with a prefix mask, +e.g. “<literal>*.example.com</literal>” +</listitem> + +<listitem> +longest string value with a suffix mask, +e.g. “<literal>mail.*</literal>” +</listitem> + +<listitem> +first matching regular expression +(in order of appearance in a configuration file) +</listitem> + +<listitem> +default value +</listitem> + +</list> +</para> + +</directive> + + +<directive name="map_hash_bucket_size"> +<syntax><value>size</value></syntax> +<default>32|64|128</default> +<context>stream</context> + +<para> +Sets the bucket size for the <link id="map"/> variables hash tables. +Default value depends on the processor’s cache line size. +The details of setting up hash tables are provided in a separate +<link doc="../hash.xml">document</link>. +</para> + +</directive> + + +<directive name="map_hash_max_size"> +<syntax><value>size</value></syntax> +<default>2048</default> +<context>stream</context> + +<para> +Sets the maximum <value>size</value> of the <link id="map"/> variables +hash tables. +The details of setting up hash tables are provided in a separate +<link doc="../hash.xml">document</link>. +</para> + +</directive> + +</section> + +</module>
--- a/xml/ru/GNUmakefile Tue Jul 05 17:58:34 2016 +0300 +++ b/xml/ru/GNUmakefile Tue Jul 05 17:58:34 2016 +0300 @@ -86,6 +86,7 @@ stream/ngx_stream_access_module \ stream/ngx_stream_core_module \ stream/ngx_stream_limit_conn_module \ + stream/ngx_stream_map_module \ stream/ngx_stream_proxy_module \ stream/ngx_stream_ssl_module \ stream/ngx_stream_upstream_module \
--- a/xml/ru/docs/index.xml Tue Jul 05 17:58:34 2016 +0300 +++ b/xml/ru/docs/index.xml Tue Jul 05 17:58:34 2016 +0300 @@ -8,7 +8,7 @@ <article name="nginx: документация" link="/ru/docs/" lang="ru" - rev="24" + rev="25" toc="no"> @@ -501,6 +501,11 @@ </listitem> <listitem> +<link doc="stream/ngx_stream_map_module.xml"> +ngx_stream_map_module</link> +</listitem> + +<listitem> <link doc="stream/ngx_stream_proxy_module.xml"> ngx_stream_proxy_module</link> </listitem>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/stream/ngx_stream_map_module.xml Tue Jul 05 17:58:34 2016 +0300 @@ -0,0 +1,203 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Модуль ngx_stream_map_module" + link="/ru/docs/stream/ngx_stream_map_module.html" + lang="ru" + rev="1"> + +<section id="summary"> + +<para> +Модуль <literal>ngx_stream_map_module</literal> (1.11.2) создаёт переменные, +значения которых зависят от значений других переменных. +</para> + +</section> + + +<section id="example" name="Пример конфигурации"> + +<para> +<example> +map $remote_addr $limit { + 127.0.0.1 ""; + default $binary_remote_addr; +} + +limit_conn_zone $limit zone=addr:10m; +limit_conn addr 1; +</example> +</para> + +</section> + + +<section id="directives" name="Директивы"> + +<directive name="map"> +<syntax block="yes"> + <value>строка</value> + <value>$переменная</value></syntax> +<default/> +<context>stream</context> + +<para> +Создаёт новую переменную, значение которой +зависит от значений одной или более исходных переменных, +указанных в первом параметре. +</para> + +<para> +<note> +Поскольку переменные вычисляются только в момент использования, +само по себе наличие даже большого числа объявлений переменных +“<literal>map</literal>” не влечёт за собой никаких дополнительных +расходов на обработку соединений. +</note> +</para> + +<para> +Параметры внутри блока <literal>map</literal> задают соответствие +между исходными и результирующими значениями. +</para> + +<para> +Исходные значения задаются строками или регулярными выражениями. +</para> + +<para> +Строки проверяются без учёта регистра. +</para> + +<para> +Перед регулярным выражением ставится символ “<literal>~</literal>”, +если при сравнении следует учитывать регистр символов, либо символы +“<literal>~*</literal>”, если регистр символов учитывать не нужно. +Регулярное выражение может содержать именованные и позиционные выделения, +которые могут затем использоваться в других директивах совместно с +результирующей переменной. +</para> + +<para> +Если исходное значение совпадает с именем одного из специальных параметров, +описанных ниже, перед ним следует поставить символ “<literal>\</literal>”. +</para> + +<para> +В качестве результирующего значения можно указать текст, +переменную и их комбинации. +</para> + +<para> +Директива также поддерживает три специальных параметра: +<list type="tag"> +<tag-name><literal>default</literal> <value>значение</value></tag-name> +<tag-desc> +задаёт результирующее значение, если исходное значение не +совпадает ни с одним из перечисленных. +Если параметр <literal>default</literal> не указан, результирующим значением +по умолчанию будет пустая строка. +</tag-desc> + +<tag-name><literal>hostnames</literal></tag-name> +<tag-desc> +указывает, что в качестве исходных значений можно +использовать маску для первой или последней части имени хоста, например, +<example> +*.example.com 1; +example.* 1; +</example> +Вместо двух записей +<example> +example.com 1; +*.example.com 1; +</example> +можно использовать одну: +<example> +.example.com 1; +</example> +Этот параметр следует указывать перед списком значений. +</tag-desc> + +<tag-name><literal>include</literal> <value>файл</value></tag-name> +<tag-desc> +включает файл со значениями. +Включений может быть несколько. +</tag-desc> + +</list> +</para> + +<para> +Если исходному значению соответствует несколько из указанных вариантов, +например, одновременно подходят и маска, и регулярное выражение, +будет выбран первый подходящий вариант в следующем порядке приоритета: +<list type="enum"> + +<listitem> +строковое значение без маски +</listitem> + +<listitem> +самое длинное строковое значение с маской в начале, +например “<literal>*.example.com</literal>” +</listitem> + +<listitem> +самое длинное строковое значение с маской в конце, +например “<literal>mail.*</literal>” +</listitem> + +<listitem> +первое подходящее регулярное выражение +(в порядке следования в конфигурационном файле) +</listitem> + +<listitem> +значение по умолчанию (<literal>default</literal>) +</listitem> + +</list> +</para> + +</directive> + + +<directive name="map_hash_bucket_size"> +<syntax><value>размер</value></syntax> +<default>32|64|128</default> +<context>stream</context> + +<para> +Задаёт размер корзины в хэш-таблицах для переменных <link id="map"/>. +Значение по умолчанию зависит от размера строки кэша процессора. +Подробнее настройка хэш-таблиц обсуждается в отдельном +<link doc="../hash.xml">документе</link>. +</para> + +</directive> + + +<directive name="map_hash_max_size"> +<syntax><value>размер</value></syntax> +<default>2048</default> +<context>stream</context> + +<para> +Задаёт максимальный размер хэш-таблиц для переменных <link id="map"/>. +Подробнее настройка хэш-таблиц обсуждается в отдельном +<link doc="../hash.xml">документе</link>. +</para> + +</directive> + +</section> + +</module>