Mercurial > hg > nginx-site
comparison xml/en/docs/stream/ngx_stream_geo_module.xml @ 1751:3768eb3d9c6c
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> |