<?xml version="1.0"?>

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

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

<module name="Модуль ngx_http_geo_module"
        link="/ru/docs/http/ngx_http_geo_module.html"
        lang="ru"
        rev="5">

<section id="summary">

<para>
Модуль <literal>ngx_http_geo_module</literal> создаёт переменные,
значения которых зависят от IP-адреса клиента.
</para>

</section>


<section id="example" name="Пример конфигурации">

<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="Директивы">

<directive name="geo">
<syntax block="yes">[<value>$адрес</value>] <value>$переменная</value></syntax>
<default/>
<context>http</context>

<para>
Описывает для указанной переменной зависимость значения от
IP-адреса клиента.
По умолчанию адрес берётся из переменной <var>$remote_addr</var>,
но его также можно получить из другой переменной (0.7.27), например:
<example>
geo $arg_remote_addr $geo {
    ...;
}
</example>
</para>

<para>
<note>
Поскольку переменные вычисляются только в момент использования,
само по себе наличие даже большого числа объявлений переменных
“<literal>geo</literal>” не влечёт за собой никаких дополнительных
расходов на обработку запросов.
</note>
</para>

<para>
Если значение переменной не представляет из себя правильный IP-адрес,
то используется адрес “<literal>255.255.255.255</literal>”.
</para>

<para>
Адреса задаются либо префиксами в формате CIDR
(включая одиночные адреса), либо в виде диапазонов (0.7.23).
<note>
IPv6-префиксы поддерживаются начиная с версий 1.3.10 и 1.2.7.
</note>
</para>

<para>
Также поддерживаются следующие специальные параметры:
<list type="tag">

<tag-name><literal>delete</literal></tag-name>
<tag-desc>
удаляет описанную сеть (0.7.23).
</tag-desc>

<tag-name><literal>default</literal></tag-name>
<tag-desc>
значение переменной, если адрес клиента не соответствует
ни одному из заданных адресов.
При задании адресов в формате CIDR
вместо <literal>default</literal> можно использовать
“<literal>0.0.0.0/0</literal>” и “<literal>::/0</literal>”.
Если параметр <literal>default</literal> не указан, значением
по умолчанию будет пустая строка.
</tag-desc>

<tag-name><literal>include</literal></tag-name>
<tag-desc>
включает файл с адресами и значениями.
Включений может быть несколько.
</tag-desc>

<tag-name><literal>proxy</literal></tag-name>
<tag-desc>
задаёт доверенные адреса (0.8.7, 0.7.63),
при запросе с которых будет использоваться адрес в переданном
поле заголовка запроса <header>X-Forwarded-For</header>.
В отличие от обычных адресов, доверенные адреса проверяются
последовательно.
<note>
Доверенные IPv6-адреса поддерживаются начиная с версий 1.3.0 и 1.2.1.
</note>
</tag-desc>

<tag-name><literal>proxy_recursive</literal></tag-name>
<tag-desc>
включает рекурсивный поиск адреса (1.3.0, 1.2.1).
При выключенном рекурсивном поиске вместо исходного адреса клиента,
совпадающего с одним из доверенных адресов, будет использоваться последний
адрес, переданный в <header>X-Forwarded-For</header>.
При включённом рекурсивном поиске вместо исходного адреса клиента,
совпадающего с одним из доверенных адресов, будет использоваться последний
не доверенный адрес, переданный в <header>X-Forwarded-For</header>.
</tag-desc>

<tag-name><literal>ranges</literal></tag-name>
<tag-desc>
указывает, что адреса задаются в виде диапазонов (0.7.23).
Этот параметр должен быть первым.
Для ускорения загрузки гео-базы нужно располагать адреса в порядке возрастания.
</tag-desc>

</list>
</para>

<para>
Пример:
<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>
В файле <path>conf/geo.conf</path> могут быть такие строки:
<example>
10.2.0.0/16    RU;
192.168.2.0/24 RU;
</example>
</para>

<para>
В качестве значения выбирается максимальное совпадение, например,
для адреса 127.0.0.1 будет выбрано значение “<literal>RU</literal>”,
а не “<literal>US</literal>”.
</para>

<para>
Пример описания диапазонов:
<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.2-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>