<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_http_geo_module"
        link="/en/docs/http/ngx_http_geo_module.html"
        lang="en"
        rev="5">

<section id="summary">

<para>
The <literal>ngx_http_geo_module</literal> module creates variables
with values depending on the client IP address.
</para>

</section>


<section id="example" name="Example Configuration">

<para>
<example>
geo $geo {
    default        0;

    127.0.0.1      2;
    192.168.1.0/24 1;
    10.1.0.0/16    1;

    ::1            2;
    2001:0db8::/32 1;
}
</example>
</para>

</section>


<section id="directives" name="Directives">

<directive name="geo">
<syntax block="yes">[<value>$address</value>] <value>$variable</value></syntax>
<default/>
<context>http</context>

<para>
Describes the dependency of values of the specified variable
on the client IP address.
By default, the address is taken from the <var>$remote_addr</var> variable,
but it can also be taken from another variable (0.7.27), for example:
<example>
geo $arg_remote_addr $geo {
    ...;
}
</example>
</para>

<para>
<note>
Since variables are evaluated only when used, the mere existence
of even a large number of declared “<literal>geo</literal>” variables
does not cause any extra costs for request processing.
</note>
</para>

<para>
If the value of a variable does not represent a valid IP address
then the “<literal>255.255.255.255</literal>” address is used.
</para>

<para>
Addresses are specified either as prefixes in CIDR notation
(including individual addresses) or as ranges (0.7.23).
<note>
IPv6 prefixes are supported starting from versions 1.3.10 and 1.2.7.
</note>
</para>

<para>
The following special parameters are also supported:
<list type="tag">

<tag-name><literal>delete</literal></tag-name>
<tag-desc>
deletes the specified network (0.7.23).
</tag-desc>

<tag-name><literal>default</literal></tag-name>
<tag-desc>
a value set to the variable if the client address does not
match any of the specified addresses.
When addresses are specified in CIDR notation,
“<literal>0.0.0.0/0</literal>” and “<literal>::/0</literal>”
can be used instead of <literal>default</literal>.
When <literal>default</literal> is not specified, the default
value will be an empty string.
</tag-desc>

<tag-name><literal>include</literal></tag-name>
<tag-desc>
includes a file with addresses and values.
There can be several inclusions.
</tag-desc>

<tag-name><literal>proxy</literal></tag-name>
<tag-desc>
defines trusted addresses (0.8.7, 0.7.63).
When a request comes from a trusted address,
an address from the <header>X-Forwarded-For</header> request
header field will be used instead.
In contrast to the regular addresses, trusted addresses are
checked sequentially.
<note>
Trusted IPv6 addresses are supported starting from versions 1.3.0 and 1.2.1.
</note>
</tag-desc>

<tag-name><literal>proxy_recursive</literal></tag-name>
<tag-desc>
enables recursive address search (1.3.0, 1.2.1).
If recursive search is disabled then instead of the original client
address that matches one of the trusted addresses, the last
address sent in <header>X-Forwarded-For</header> will be used.
If recursive search is enabled then instead of the original client
address that matches one of the trusted addresses, the last
non-trusted address sent in <header>X-Forwarded-For</header> will be used.
</tag-desc>

<tag-name><literal>ranges</literal></tag-name>
<tag-desc>
indicates that addresses are specified as ranges (0.7.23).
This parameter should be the first.
To speed up loading of a geo base, addresses should be put in ascending order.
</tag-desc>

</list>
</para>

<para>
Example:
<example>
geo $country {
    default        ZZ;
    include        conf/geo.conf;
    delete         127.0.0.0/16;
    proxy          192.168.100.0/24;
    proxy          2001:0db8::/32;

    127.0.0.0/24   US;
    127.0.0.1/32   RU;
    10.1.0.0/16    RU;
    192.168.1.0/24 UK;
}
</example>
</para>

<para>
The <path>conf/geo.conf</path> file could contain the following lines:
<example>
10.2.0.0/16    RU;
192.168.2.0/24 RU;
</example>
</para>

<para>
A value of the most specific match is used.
For example, for the 127.0.0.1 address the value “<literal>RU</literal>”
will be chosen, not “<literal>US</literal>”.
</para>

<para>
Example with ranges:
<example>
geo $country {
    ranges;
    default                   ZZ;
    127.0.0.0-127.0.0.0       US;
    127.0.0.1-127.0.0.1       RU;
    127.0.0.1-127.0.0.255     US;
    10.1.0.0-10.1.255.255     RU;
    192.168.1.0-192.168.1.255 UK;
}
</example>
</para>

</directive>

</section>

</module>