<?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="2">

<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 following special parameters are also supported:
<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>

<tag-name id="volatile"><literal>volatile</literal></tag-name>
<tag-desc>
indicates that the variable is not cacheable (1.11.7).
</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>