<?xml version="1.0"?>

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

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

<module name="Модуль ngx_stream_geo_module"
        link="/ru/docs/stream/ngx_stream_geo_module.html"
        lang="ru"
        rev="1">

<section id="summary">

<para>
Модуль <literal>ngx_stream_geo_module</literal> (1.11.3) создаёт переменные,
значения которых зависят от 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>stream</context>

<para>
Описывает для указанной переменной зависимость значения от
IP-адреса клиента.
По умолчанию адрес берётся из переменной <var>$remote_addr</var>,
но его также можно получить из другой переменной, например:
<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
(включая одиночные адреса), либо в виде диапазонов.
</para>

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

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

</list>
</para>

<para>
Пример:
<example>
geo $country {
    default        ZZ;
    include        conf/geo.conf;
    delete         127.0.0.0/16;

    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>