Mercurial > hg > nginx-site
comparison 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 |
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> |