Mercurial > hg > nginx-site

comparison xml/en/docs/stream/ngx_stream_map_module.xml @ 1743:3d686cb47c2c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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
comparison
equal deleted inserted replaced
1742:c511b73da3a9 1743:3d686cb47c2c
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) Igor Sysoev
5 Copyright (C) Nginx, Inc.
6 -->
7
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
9
10 <module name="Module ngx_stream_map_module"
11 link="/en/docs/stream/ngx_stream_map_module.html"
12 lang="en"
13 rev="1">
14
15 <section id="summary">
16
17 <para>
18 The <literal>ngx_stream_map_module</literal> module (1.11.2) creates variables
19 whose values depend on values of other variables.
20 </para>
21
22 </section>
23
24
25 <section id="example" name="Example Configuration">
26
27 <para>
28 <example>
29 map $remote_addr $limit {
30 127.0.0.1 "";
31 default $binary_remote_addr;
32 }
33
34 limit_conn_zone $limit zone=addr:10m;
35 limit_conn addr 1;
36 </example>
37 </para>
38
39 </section>
40
41
42 <section id="directives" name="Directives">
43
44 <directive name="map">
45 <syntax block="yes">
46 <value>string</value>
47 <value>$variable</value></syntax>
48 <default/>
49 <context>stream</context>
50
51 <para>
52 Creates a new variable whose value
53 depends on values of one or more of the source variables
54 specified in the first parameter.
55 </para>
56
57 <para>
58 <note>
59 Since variables are evaluated only when they are used, the mere declaration
60 even of a large number of “<literal>map</literal>” variables
61 does not add any extra costs to connection processing.
62 </note>
63 </para>
64
65 <para>
66 Parameters inside the <literal>map</literal> block specify a mapping
67 between source and resulting values.
68 </para>
69
70 <para>
71 Source values are specified as strings or regular expressions.
72 </para>
73
74 <para>
75 Strings are matched ignoring the case.
76 </para>
77
78 <para>
79 A regular expression should either start from the “<literal>~</literal>”
80 symbol for a case-sensitive matching, or from the “<literal>~*</literal>”
81 symbols for case-insensitive matching.
82 A regular expression can contain named and positional captures
83 that can later be used in other directives along with the
84 resulting variable.
85 </para>
86
87 <para>
88 If a source value matches one of the names of special parameters
89 described below, it should be prefixed with the “<literal>\</literal>” symbol.
90 </para>
91
92 <para>
93 The resulting value can contain text,
94 variable, and their combination.
95 </para>
96
97 <para>
98 The directive also supports three special parameters:
99 <list type="tag">
100 <tag-name><literal>default</literal> <value>value</value></tag-name>
101 <tag-desc>
102 sets the resulting value if the source value matches none
103 of the specified variants.
104 When <literal>default</literal> is not specified, the default
105 resulting value will be an empty string.
106 </tag-desc>
107
108 <tag-name><literal>hostnames</literal></tag-name>
109 <tag-desc>
110 indicates that source values can be hostnames with a prefix or suffix mask:
111 <example>
112 *.example.com 1;
113 example.* 1;
114 </example>
115 The following two records
116 <example>
117 example.com 1;
118 *.example.com 1;
119 </example>
120 can be combined:
121 <example>
122 .example.com 1;
123 </example>
124 This parameter should be specified before the list of values.
125 </tag-desc>
126
127 <tag-name><literal>include</literal> <value>file</value></tag-name>
128 <tag-desc>
129 includes a file with values.
130 There can be several inclusions.
131 </tag-desc>
132
133 </list>
134 </para>
135
136 <para>
137 If the source value matches more than one of the specified variants,
138 e.g. both a mask and a regular expression match, the first matching
139 variant will be chosen, in the following order of priority:
140 <list type="enum">
141
142 <listitem>
143 string value without a mask
144 </listitem>
145
146 <listitem>
147 longest string value with a prefix mask,
148 e.g. “<literal>*.example.com</literal>”
149 </listitem>
150
151 <listitem>
152 longest string value with a suffix mask,
153 e.g. “<literal>mail.*</literal>”
154 </listitem>
155
156 <listitem>
157 first matching regular expression
158 (in order of appearance in a configuration file)
159 </listitem>
160
161 <listitem>
162 default value
163 </listitem>
164
165 </list>
166 </para>
167
168 </directive>
169
170
171 <directive name="map_hash_bucket_size">
172 <syntax><value>size</value></syntax>
173 <default>32|64|128</default>
174 <context>stream</context>
175
176 <para>
177 Sets the bucket size for the <link id="map"/> variables hash tables.
178 Default value depends on the processor’s cache line size.
179 The details of setting up hash tables are provided in a separate
180 <link doc="../hash.xml">document</link>.
181 </para>
182
183 </directive>
184
185
186 <directive name="map_hash_max_size">
187 <syntax><value>size</value></syntax>
188 <default>2048</default>
189 <context>stream</context>
190
191 <para>
192 Sets the maximum <value>size</value> of the <link id="map"/> variables
193 hash tables.
194 The details of setting up hash tables are provided in a separate
195 <link doc="../hash.xml">document</link>.
196 </para>
197
198 </directive>
199
200 </section>
201
202 </module>