Mercurial > hg > nginx-site

changeset 1751:3768eb3d9c6c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented the geo module in stream.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 14 Jul 2016 20:33:05 +0300
parents 0e591e97737c
children b4de612feff8
files xml/en/GNUmakefile xml/en/docs/index.xml xml/en/docs/stream/ngx_stream_geo_module.xml xml/ru/GNUmakefile xml/ru/docs/index.xml xml/ru/docs/stream/ngx_stream_geo_module.xml
diffstat 6 files changed, 347 insertions(+), 2 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/GNUmakefile	Wed Jul 13 21:15:55 2016 +0300
+++ b/xml/en/GNUmakefile	Thu Jul 14 20:33:05 2016 +0300
@@ -96,6 +96,7 @@
 		mail/ngx_mail_ssl_module				\
 		stream/ngx_stream_access_module				\
 		stream/ngx_stream_core_module				\
+		stream/ngx_stream_geo_module				\
 		stream/ngx_stream_geoip_module				\
 		stream/ngx_stream_limit_conn_module			\
 		stream/ngx_stream_map_module				\
--- a/xml/en/docs/index.xml	Wed Jul 13 21:15:55 2016 +0300
+++ b/xml/en/docs/index.xml	Thu Jul 14 20:33:05 2016 +0300
@@ -8,7 +8,7 @@
 <article name="nginx documentation"
          link="/en/docs/"
          lang="en"
-         rev="27"
+         rev="28"
          toc="no">
 
 
@@ -492,6 +492,11 @@
 </listitem>
 
 <listitem>
+<link doc="stream/ngx_stream_geo_module.xml">
+ngx_stream_geo_module</link>
+</listitem>
+
+<listitem>
 <link doc="stream/ngx_stream_geoip_module.xml">
 ngx_stream_geoip_module</link>
 </listitem>
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/xml/en/docs/stream/ngx_stream_geo_module.xml	Thu Jul 14 20:33:05 2016 +0300
@@ -0,0 +1,166 @@
+<?xml version="1.0"?>
+
+<!--
+  Copyright (C) Nginx, Inc.
+  -->
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Module ngx_stream_geo_module"
+        link="/en/docs/stream/ngx_stream_geo_module.html"
+        lang="en"
+        rev="1">
+
+<section id="summary">
+
+<para>
+The <literal>ngx_stream_geo_module</literal> module (1.11.3) 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>stream</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, 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 connection 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.
+</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.
+</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>ranges</literal></tag-name>
+<tag-desc>
+indicates that addresses are specified as ranges.
+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;
+
+    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>
--- a/xml/ru/GNUmakefile	Wed Jul 13 21:15:55 2016 +0300
+++ b/xml/ru/GNUmakefile	Thu Jul 14 20:33:05 2016 +0300
@@ -85,6 +85,7 @@
 		mail/ngx_mail_ssl_module				\
 		stream/ngx_stream_access_module				\
 		stream/ngx_stream_core_module				\
+		stream/ngx_stream_geo_module				\
 		stream/ngx_stream_geoip_module				\
 		stream/ngx_stream_limit_conn_module			\
 		stream/ngx_stream_map_module				\
--- a/xml/ru/docs/index.xml	Wed Jul 13 21:15:55 2016 +0300
+++ b/xml/ru/docs/index.xml	Thu Jul 14 20:33:05 2016 +0300
@@ -8,7 +8,7 @@
 <article name="nginx: документация"
          link="/ru/docs/"
          lang="ru"
-         rev="27"
+         rev="28"
          toc="no">
 
 
@@ -496,6 +496,11 @@
 </listitem>
 
 <listitem>
+<link doc="stream/ngx_stream_geo_module.xml">
+ngx_stream_geo_module</link>
+</listitem>
+
+<listitem>
 <link doc="stream/ngx_stream_geoip_module.xml">
 ngx_stream_geoip_module</link>
 </listitem>
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/xml/ru/docs/stream/ngx_stream_geo_module.xml	Thu Jul 14 20:33:05 2016 +0300
@@ -0,0 +1,167 @@
+<?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_http_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>