Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_geo_module.xml @ 369:68d9e5f2ea81

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
English translation of ngx_http_geo_module.
author Ruslan Ermilov <ru@nginx.com>
date Fri, 27 Jan 2012 22:29:01 +0000
parents
children 65750bdde8fb
comparison
equal deleted inserted replaced
368:ce12542164cf 369:68d9e5f2ea81
1 <?xml version="1.0"?>
2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4
5 <module name="Module ngx_http_geo_module"
6 link="/en/docs/http/ngx_http_geo_module.html"
7 lang="en">
8
9 <section id="summary">
10
11 <para>
12 The <literal>ngx_http_geo_module</literal> module creates variables
13 whose values depend on the client IP address.
14 </para>
15
16 </section>
17
18
19 <section id="example" name="Example Configuration">
20
21 <para>
22 <example>
23 geo $geo {
24 default 0;
25 127.0.0.1/32 2;
26 192.168.1.0/24 1;
27 10.1.0.0/16 1;
28 }
29 </example>
30 </para>
31
32 </section>
33
34
35 <section id="directives" name="Directives">
36
37 <directive name="geo">
38 <syntax block="yes">[<value>$address</value>] <value>$variable</value></syntax>
39 <default/>
40 <context>http</context>
41
42 <para>
43 Describes the dependency of values of the specified variable
44 on the client IP address.
45 By default an address is taken from the <var>$remote_addr</var> variable
46 but it can also be taken from another variable (0.7.27), for example:
47 <example>
48 geo $arg_remote_addr $geo {
49 ...;
50 }
51 </example>
52 If the value of a variable does not represent a valid IP address
53 then the “<literal>255.255.255.255</literal>” address is used.
54 </para>
55
56 <para>
57 Addresses are specified as CIDR or ranges (0.7.23).
58 There are also five special parameters:
59 <list type="tag">
60
61 <tag-name><literal>delete</literal></tag-name>
62 <tag-desc>
63 deletes the specified network (0.7.23).
64 </tag-desc>
65
66 <tag-name><literal>default</literal></tag-name>
67 <tag-desc>
68 a value of variable if the client address does not
69 match any of the specified addresses.
70 When CIDR is used, “<literal>0.0.0.0/0</literal>” can be written
71 instead of <literal>default</literal>.
72 </tag-desc>
73
74 <tag-name><literal>include</literal></tag-name>
75 <tag-desc>
76 includes a file with addresses and values.
77 There can be several inclusions.
78 </tag-desc>
79
80 <tag-name><literal>proxy</literal></tag-name>
81 <tag-desc>
82 sets the addresses of proxy servers (0.8.7, 0.7.63).
83 When a request comes from one of the proxy servers,
84 an address from the <header>X-Forwarded-For</header> request
85 header field will be used instead.
86 In contrast to the regular addresses, proxy server addresses are
87 checked sequentially.
88 </tag-desc>
89
90 <tag-name><literal>ranges</literal></tag-name>
91 <tag-desc>
92 indicates that addresses are specified as ranges (0.7.23).
93 This parameter should be the first.
94 To speed up loading of a geo base, addresses should be put in increasing order.
95 </tag-desc>
96
97 </list>
98 </para>
99
100 <para>
101 Example:
102 <example>
103 geo $country {
104 default ZZ;
105 include conf/geo.conf;
106 delete 127.0.0.0/16;
107 proxy 192.168.100.0/24;
108
109 127.0.0.0/24 US;
110 127.0.0.1/32 RU;
111 10.1.0.0/16 RU;
112 192.168.1.0/24 UK;
113 }
114 </example>
115 </para>
116
117 <para>
118 The <path>conf/geo.conf</path> file could contain the following lines:
119 <example>
120 10.2.0.0/16 RU;
121 192.168.2.0/24 RU;
122 </example>
123 </para>
124
125 <para>
126 A value of the most specific match is used.
127 For example, for the 127.0.0.1 address the value “<literal>RU</literal>”
128 will be chosen, not “<literal>US</literal>”.
129 </para>
130
131 <para>
132 Example with ranges:
133 <example>
134 geo $country {
135 ranges;
136 default ZZ;
137 127.0.0.0-127.0.0.0 US;
138 127.0.0.1-127.0.0.1 RU;
139 127.0.0.1-127.0.0.255 US;
140 10.1.0.0-10.1.255.255 RU;
141 192.168.1.0-192.168.1.255 UK;
142 }
143 </example>
144 </para>
145
146 </directive>
147
148 </section>
149
150 </module>