Mercurial > hg > nginx-site

comparison xml/en/docs/stream/ngx_stream_geo_module.xml @ 1751:3768eb3d9c6c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented the geo module in stream.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 14 Jul 2016 20:33:05 +0300
parents xml/en/docs/http/ngx_http_geo_module.xml@95c3c3bbf1ce
children
comparison
equal deleted inserted replaced
1750:0e591e97737c 1751:3768eb3d9c6c
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) Nginx, Inc.
5 -->
6
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
8
9 <module name="Module ngx_stream_geo_module"
10 link="/en/docs/stream/ngx_stream_geo_module.html"
11 lang="en"
12 rev="1">
13
14 <section id="summary">
15
16 <para>
17 The <literal>ngx_stream_geo_module</literal> module (1.11.3) creates variables
18 with values depending on the client IP address.
19 </para>
20
21 </section>
22
23
24 <section id="example" name="Example Configuration">
25
26 <para>
27 <example>
28 geo $geo {
29 default 0;
30
31 127.0.0.1 2;
32 192.168.1.0/24 1;
33 10.1.0.0/16 1;
34
35 ::1 2;
36 2001:0db8::/32 1;
37 }
38 </example>
39 </para>
40
41 </section>
42
43
44 <section id="directives" name="Directives">
45
46 <directive name="geo">
47 <syntax block="yes">[<value>$address</value>] <value>$variable</value></syntax>
48 <default/>
49 <context>stream</context>
50
51 <para>
52 Describes the dependency of values of the specified variable
53 on the client IP address.
54 By default, the address is taken from the <var>$remote_addr</var> variable,
55 but it can also be taken from another variable, for example:
56 <example>
57 geo $arg_remote_addr $geo {
58 ...;
59 }
60 </example>
61 </para>
62
63 <para>
64 <note>
65 Since variables are evaluated only when used, the mere existence
66 of even a large number of declared “<literal>geo</literal>” variables
67 does not cause any extra costs for connection processing.
68 </note>
69 </para>
70
71 <para>
72 If the value of a variable does not represent a valid IP address
73 then the “<literal>255.255.255.255</literal>” address is used.
74 </para>
75
76 <para>
77 Addresses are specified either as prefixes in CIDR notation
78 (including individual addresses) or as ranges.
79 </para>
80
81 <para>
82 The following special parameters are also supported:
83 <list type="tag">
84
85 <tag-name><literal>delete</literal></tag-name>
86 <tag-desc>
87 deletes the specified network.
88 </tag-desc>
89
90 <tag-name><literal>default</literal></tag-name>
91 <tag-desc>
92 a value set to the variable if the client address does not
93 match any of the specified addresses.
94 When addresses are specified in CIDR notation,
95 “<literal>0.0.0.0/0</literal>” and “<literal>::/0</literal>”
96 can be used instead of <literal>default</literal>.
97 When <literal>default</literal> is not specified, the default
98 value will be an empty string.
99 </tag-desc>
100
101 <tag-name><literal>include</literal></tag-name>
102 <tag-desc>
103 includes a file with addresses and values.
104 There can be several inclusions.
105 </tag-desc>
106
107 <tag-name><literal>ranges</literal></tag-name>
108 <tag-desc>
109 indicates that addresses are specified as ranges.
110 This parameter should be the first.
111 To speed up loading of a geo base, addresses should be put in ascending order.
112 </tag-desc>
113
114 </list>
115 </para>
116
117 <para>
118 Example:
119 <example>
120 geo $country {
121 default ZZ;
122 include conf/geo.conf;
123 delete 127.0.0.0/16;
124
125 127.0.0.0/24 US;
126 127.0.0.1/32 RU;
127 10.1.0.0/16 RU;
128 192.168.1.0/24 UK;
129 }
130 </example>
131 </para>
132
133 <para>
134 The <path>conf/geo.conf</path> file could contain the following lines:
135 <example>
136 10.2.0.0/16 RU;
137 192.168.2.0/24 RU;
138 </example>
139 </para>
140
141 <para>
142 A value of the most specific match is used.
143 For example, for the 127.0.0.1 address the value “<literal>RU</literal>”
144 will be chosen, not “<literal>US</literal>”.
145 </para>
146
147 <para>
148 Example with ranges:
149 <example>
150 geo $country {
151 ranges;
152 default ZZ;
153 127.0.0.0-127.0.0.0 US;
154 127.0.0.1-127.0.0.1 RU;
155 127.0.0.1-127.0.0.255 US;
156 10.1.0.0-10.1.255.255 RU;
157 192.168.1.0-192.168.1.255 UK;
158 }
159 </example>
160 </para>
161
162 </directive>
163
164 </section>
165
166 </module>