Mercurial > hg > nginx-site
diff xml/en/docs/stream/ngx_stream_map_module.xml @ 1743:3d686cb47c2c
Documented the map module in stream.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 05 Jul 2016 17:58:34 +0300 |
parents | xml/en/docs/http/ngx_http_map_module.xml@5ee34b8faa79 |
children | c6b5826b64f7 |
line wrap: on
line diff
--- /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>