changeset 348:5a848934a12d

English translation of ngx_http_geoip_module, ngx_http_map_module, ngx_http_realip_module, ngx_http_secure_link_module, ngx_http_split_clients_module, and ngx_http_sub_module.
author Ruslan Ermilov <ru@nginx.com>
date Mon, 23 Jan 2012 16:50:35 +0000
parents daae2b619815
children 302222923e34
files xml/en/GNUmakefile xml/en/docs/http/ngx_http_geoip_module.xml xml/en/docs/http/ngx_http_map_module.xml xml/en/docs/http/ngx_http_realip_module.xml xml/en/docs/http/ngx_http_secure_link_module.xml xml/en/docs/http/ngx_http_split_clients_module.xml xml/en/docs/http/ngx_http_sub_module.xml xml/en/docs/index.xml
diffstat 8 files changed, 616 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/GNUmakefile
+++ b/xml/en/GNUmakefile
@@ -52,6 +52,7 @@ REFS =									\
 		http/ngx_http_empty_gif_module				\
 		http/ngx_http_fastcgi_module				\
 		http/ngx_http_flv_module				\
+		http/ngx_http_geoip_module				\
 		http/ngx_http_gzip_module				\
 		http/ngx_http_gzip_static_module			\
 		http/ngx_http_image_filter_module			\
@@ -59,9 +60,14 @@ REFS =									\
 		http/ngx_http_limit_conn_module				\
 		http/ngx_http_limit_req_module				\
 		http/ngx_http_log_module				\
+		http/ngx_http_map_module				\
 		http/ngx_http_mp4_module				\
 		http/ngx_http_proxy_module				\
 		http/ngx_http_random_index_module			\
+		http/ngx_http_realip_module				\
+		http/ngx_http_secure_link_module			\
+		http/ngx_http_split_clients_module			\
+		http/ngx_http_sub_module				\
 		http/ngx_http_upstream_module				\
 
 REFS_XML =	$(foreach name, $(REFS), xml/$(DOC_LANG)/docs/$(name).xml)
new file mode 100644
--- /dev/null
+++ b/xml/en/docs/http/ngx_http_geoip_module.xml
@@ -0,0 +1,135 @@
+<?xml version="1.0"?>
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Module ngx_http_geoip_module"
+        link="/en/docs/http/ngx_http_geoip_module.html"
+        lang="en">
+
+<section id="summary">
+
+<para>
+The <literal>ngx_http_geoip_module</literal> module (0.8.6+) creates variables
+whose values depend on the client IP address, using the precompiled
+<link url="http://www.maxmind.com">MaxMind</link> databases.
+</para>
+
+<para>
+This module is not built by default, it should be enabled with the
+<literal>--with-http_geoip_module</literal>
+configuration parameter.
+<note>
+This module requires the
+<link url="http://www.maxmind.com/app/c">MaxMind GeoIP</link> library.
+</note>
+</para>
+
+</section>
+
+
+<section id="example" name="Example Configuration">
+
+<para>
+<example>
+http {
+    geoip_country GeoIP.dat;
+    geoip_city    GeoLiteCity.dat;
+    ...
+</example>
+</para>
+
+</section>
+
+
+<section id="directives" name="Directives">
+
+<directive name="geoip_country">
+<syntax><value>database</value></syntax>
+<default/>
+<context>http</context>
+
+<para>
+Specifies a database used to determine a country
+depending on the client IP address.
+The following variables are available when using this database:
+<list type="tag">
+
+<tag-name><var>$geoip_country_code</var></tag-name>
+<tag-desc>
+two-letter country code, for example,
+“<literal>RU</literal>”, “<literal>US</literal>”.
+</tag-desc>
+
+<tag-name><var>$geoip_country_code3</var></tag-name>
+<tag-desc>
+three-letter country code, for example,
+“<literal>RUS</literal>”, “<literal>USA</literal>”.
+</tag-desc>
+
+<tag-name><var>$geoip_country_name</var></tag-name>
+<tag-desc>
+country name, for example,
+“<literal>Russian Federation</literal>”, “<literal>United States</literal>”.
+</tag-desc>
+
+</list>
+</para>
+
+</directive>
+
+
+<directive name="geoip_city">
+<syntax><value>database</value></syntax>
+<default/>
+<context>http</context>
+
+<para>
+Specifies a database used to determine a country, region, and city
+depending on the client IP address.
+The following variables are available when using this database:
+<list type="tag">
+
+<tag-name><var>$geoip_city_country_code</var></tag-name>
+<tag-desc>
+two-letter country code, for example,
+“<literal>RU</literal>”, “<literal>US</literal>”.
+</tag-desc>
+
+<tag-name><var>$geoip_city_country_code3</var></tag-name>
+<tag-desc>
+three-letter country code, for example,
+“<literal>RUS</literal>”, “<literal>USA</literal>”.
+</tag-desc>
+
+<tag-name><var>$geoip_city_country_name</var></tag-name>
+<tag-desc>
+country name, for example,
+“<literal>Russian Federation</literal>”, “<literal>United States</literal>”.
+</tag-desc>
+
+<tag-name><var>$geoip_region</var></tag-name>
+<tag-desc>
+country region name (region, territory, state, province, federal land
+and the like), for example,
+“<literal>Moscow City</literal>”, “<literal>DC</literal>”.
+</tag-desc>
+
+<tag-name><var>$geoip_city</var></tag-name>
+<tag-desc>
+city name, for example,
+“<literal>Moscow</literal>”, “<literal>Washington</literal>”.
+</tag-desc>
+
+<tag-name><var>$geoip_postal_code</var></tag-name>
+<tag-desc>
+postal code.
+</tag-desc>
+
+</list>
+</para>
+
+</directive>
+
+</section>
+
+</module>
new file mode 100644
--- /dev/null
+++ b/xml/en/docs/http/ngx_http_map_module.xml
@@ -0,0 +1,123 @@
+<?xml version="1.0"?>
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Module ngx_http_map_module"
+        link="/en/docs/http/ngx_http_map_module.html"
+        lang="en">
+
+<section id="summary">
+
+<para>
+The <literal>ngx_http_map_module</literal> module creates variables
+whose values depend on values of other variables.
+</para>
+
+</section>
+
+
+<section id="example" name="Example Configuration">
+
+<para>
+<example>
+map $http_host $name  {
+    hostnames;
+
+    default       0;
+
+    example.com   1;
+    *.example.com 1;
+    test.com      2;
+    *.test.com    2;
+    .site.com     3;
+    wap.*         4;
+}
+</example>
+</para>
+
+</section>
+
+
+<section id="directives" name="Directives">
+
+<directive name="map">
+<syntax block="yes">
+    <value>$variable1</value>
+    <value>$variable2</value></syntax>
+<default/>
+<context>http</context>
+
+<para>
+Creates a variable whose value
+depends on the value of another variable.
+The directive supports three special parameters:
+<list type="tag">
+<tag-name><literal>default</literal> <value>value</value></tag-name>
+<tag-desc>
+sets a value for the second variable when the value
+of the first variable cannot be found.
+</tag-desc>
+
+<tag-name><literal>hostnames</literal></tag-name>
+<tag-desc>
+allows to specify hostnames with a prefix or suffix mask, as source
+values, for example,
+<example>
+*.example.com 1;
+example.*     1;
+</example>
+The following two records
+<example>
+example.com   1;
+*.example.com 1;
+</example>
+can be combined:
+<example>
+.example.com  1;
+</example>
+</tag-desc>
+
+<tag-name><literal>include</literal> <value>file</value></tag-name>
+<tag-desc>
+includes a file with values.
+There can be several inclusions.
+</tag-desc>
+
+</list>
+</para>
+
+</directive>
+
+
+<directive name="map_hash_bucket_size">
+<syntax><value>size</value></syntax>
+<default>32|64|128</default>
+<context>http</context>
+
+<para>
+Sets the bucket size for the <link id="map"/> variables hash tables.
+Default value depends on the size of the processor's cache line.
+For more information, please refer to
+<link doc="../hash.xml">Setting Up Hashes</link>.
+</para>
+
+</directive>
+
+
+<directive name="map_hash_max_size">
+<syntax><value>size</value></syntax>
+<default>2048</default>
+<context>http</context>
+
+<para>
+Sets the maximum <value>size</value> of the <link id="map"/> variables
+hash tables.
+For more information, please refer to
+<link doc="../hash.xml">Setting Up Hashes</link>.
+</para>
+
+</directive>
+
+</section>
+
+</module>
new file mode 100644
--- /dev/null
+++ b/xml/en/docs/http/ngx_http_realip_module.xml
@@ -0,0 +1,77 @@
+<?xml version="1.0"?>
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Module ngx_http_realip_module"
+        link="/en/docs/http/ngx_http_realip_module.html"
+        lang="en">
+
+<section id="summary">
+
+<para>
+The <literal>ngx_http_realip_module</literal> module allows
+to change the client address to the one sent in the specified header field.
+</para>
+
+<para>
+This module is not built by default, it should be enabled with the
+<literal>--with-http_realip_module</literal>
+configuration parameter.
+</para>
+
+</section>
+
+
+<section id="example" name="Example Configuration">
+
+<para>
+<example>
+    set_real_ip_from 192.168.1.0/24;
+    set_real_ip_from 192.168.2.1;
+    real_ip_header   X-Real-IP;
+</example>
+</para>
+
+</section>
+
+
+<section id="directives" name="Directives">
+
+<directive name="set_real_ip_from">
+<syntax><value>address</value> | <value>CIDR</value></syntax>
+<default/>
+<context>http</context>
+<context>server</context>
+<context>location</context>
+
+<para>
+Describes trusted addresses that are known to send correct
+replacement addresses.
+</para>
+
+</directive>
+
+
+<directive name="real_ip_header">
+<syntax>
+  <value>field</value> |
+  <literal>X-Real-IP</literal> |
+  <literal>X-Forwarded-For</literal></syntax>
+<default>X-Real-IP</default>
+<context>http</context>
+<context>server</context>
+<context>location</context>
+
+<para>
+Defines a request header field used to send
+the address for a replacement.
+In case of the <header>X-Forwarded-For</header> field,
+the last address in the field’s value is used.
+For other fields the whole value is used.
+</para>
+
+</directive>
+
+</section>
+
+</module>
new file mode 100644
--- /dev/null
+++ b/xml/en/docs/http/ngx_http_secure_link_module.xml
@@ -0,0 +1,86 @@
+<?xml version="1.0"?>
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Module ngx_http_secure_link_module"
+        link="/en/docs/http/ngx_http_secure_link_module.html"
+        lang="en">
+
+<section id="summary">
+
+<para>
+The <literal>ngx_http_secure_link_module</literal> module (0.7.18+) checks
+the validity of the requested link.
+</para>
+
+<para>
+This module is not built by default, it should be enabled with the
+<literal>--with-http_secure_link_module</literal>
+configuration parameter.
+</para>
+
+</section>
+
+
+<section id="example" name="Example Configuration">
+
+<para>
+<example>
+location /p/ {
+    secure_link_secret some_secret_word;
+
+    if ($secure_link = "") {
+        return 403;
+    }
+}
+</example>
+</para>
+
+</section>
+
+
+<section id="directives" name="Directives">
+
+<directive name="secure_link_secret">
+<syntax><value>word</value></syntax>
+<default/>
+<context>location</context>
+
+<para>
+Defines a secret <value>word</value> used to check the validity of the link.
+The full URL of the protected link looks as follows:
+<example>
+/prefix/<value>hash</value>/<value>link</value>
+</example>
+where <value>hash</value> is computed as
+<example>
+md5(link, secret_word);
+</example>
+</para>
+
+<para>
+A prefix is an arbitrary string not including a slash.
+</para>
+
+</directive>
+
+</section>
+
+
+<section id="variables" name="Embedded Variables">
+
+<para>
+<list type="tag">
+
+<tag-name><var>$secure_link</var></tag-name>
+<tag-desc>
+equals to the link extracted from the full URL.
+If hash is incorrect, this variable is set to an empty string.
+</tag-desc>
+
+</list>
+</para>
+
+</section>
+
+</module>
new file mode 100644
--- /dev/null
+++ b/xml/en/docs/http/ngx_http_split_clients_module.xml
@@ -0,0 +1,70 @@
+<?xml version="1.0"?>
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Module ngx_http_split_clients_module"
+        link="/en/docs/http/ngx_http_split_clients_module.html"
+        lang="en">
+
+<section id="summary">
+
+<para>
+The <literal>ngx_http_split_clients_module</literal> module creates
+variables suitable for A/B testing, also known as split testing.
+</para>
+
+</section>
+
+
+<section id="example" name="Example Configuration">
+
+<para>
+<example>
+http {
+    split_clients "${remote_addr}AAA" $variant {
+                   0.5%               .one;
+                   2.0%               .two;
+                   *                  "";
+    }
+
+    server {
+        location / {
+            index index${variant}.html;
+</example>
+</para>
+</section>
+
+
+<section id="directives" name="Directives">
+
+<directive name="split_clients">
+<syntax block="yes">
+    <value>string</value>
+    <value>$variable</value></syntax>
+<default/>
+<context>http</context>
+
+<para>
+Creates a variable for A/B testing, for example:
+<example>
+split_clients "${remote_addr}AAA" $variant {
+               0.5%               .one;
+               2.0%               .two;
+               *                  "";
+}
+</example>
+The value of the original string is hashed using MurmurHash2.
+In the example given, hash values from 0 to 21474836 (0.5%)
+correspond to the <var>$variant</var> variable taking the
+value <literal>".one"</literal>,
+hash values from 21474837 to 107374182 (2%) correspond to
+the value <literal>".two"</literal>,
+and hash values from 107374183 to 4294967297 correspond to
+the value <literal>""</literal>.
+</para>
+
+</directive>
+
+</section>
+
+</module>
new file mode 100644
--- /dev/null
+++ b/xml/en/docs/http/ngx_http_sub_module.xml
@@ -0,0 +1,89 @@
+<?xml version="1.0"?>
+
+<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
+
+<module name="Module ngx_http_sub_module"
+        link="/en/docs/http/ngx_http_sub_module.html"
+        lang="en">
+
+<section id="summary">
+
+<para>
+The <literal>ngx_http_sub_module</literal> module is a filter
+that modifies a response by replacing one specified string by another.
+</para>
+
+<para>
+This module is not built by default, it should be enabled with the
+<literal>--with-http_sub_module</literal>
+configuration parameter.
+</para>
+
+</section>
+
+
+<section id="example" name="Example Configuration">
+
+<para>
+<example>
+location / {
+    sub_filter      &lt;/head&gt;
+        '&lt;/head&gt;&lt;script language="javascript" src="$script"&gt;&lt;/script&gt;';
+    sub_filter_once on;
+}
+</example>
+</para>
+
+</section>
+
+
+<section id="directives" name="Directives">
+
+<directive name="sub_filter">
+<syntax><value>string</value> <value>replacement</value></syntax>
+<default/>
+<context>http</context>
+<context>server</context>
+<context>location</context>
+
+<para>
+Sets a string that needs to be changed, and a replacement string.
+The string to be replaced is matched ignoring the case.
+A replacement string can contain variables.
+</para>
+
+</directive>
+
+
+<directive name="sub_filter_once">
+<syntax><literal>on</literal> | <literal>off</literal></syntax>
+<default>on</default>
+<context>http</context>
+<context>server</context>
+<context>location</context>
+
+<para>
+Determines how many times to look for a string to be replaced,
+once or several times.
+</para>
+
+</directive>
+
+
+<directive name="sub_filter_types">
+<syntax><value>mime-type</value> ...</syntax>
+<default>text/html</default>
+<context>http</context>
+<context>server</context>
+<context>location</context>
+
+<para>
+Enables string replacement in responses with the specified MIME types
+in addition to “<literal>text/html</literal>”.
+</para>
+
+</directive>
+
+</section>
+
+</module>
--- a/xml/en/docs/index.xml
+++ b/xml/en/docs/index.xml
@@ -110,6 +110,11 @@ ngx_http_flv_module</a>
 </item>
 
 <item>
+<a href="/en/docs/http/ngx_http_geoip_module.xml">
+ngx_http_geoip_module</a>
+</item>
+
+<item>
 <a href="/en/docs/http/ngx_http_gzip_module.xml">
 ngx_http_gzip_module</a>
 </item>
@@ -145,6 +150,11 @@ ngx_http_log_module</a>
 </item>
 
 <item>
+<a href="/en/docs/http/ngx_http_map_module.xml">
+ngx_http_map_module</a>
+</item>
+
+<item>
 <a href="/en/docs/http/ngx_http_mp4_module.xml">
 ngx_http_mp4_module</a>
 </item>
@@ -160,6 +170,26 @@ ngx_http_random_index_module</a>
 </item>
 
 <item>
+<a href="/en/docs/http/ngx_http_realip_module.xml">
+ngx_http_realip_module</a>
+</item>
+
+<item>
+<a href="/en/docs/http/ngx_http_secure_link_module.xml">
+ngx_http_secure_link_module</a>
+</item>
+
+<item>
+<a href="/en/docs/http/ngx_http_split_clients_module.xml">
+ngx_http_split_clients_module</a>
+</item>
+
+<item>
+<a href="/en/docs/http/ngx_http_sub_module.xml">
+ngx_http_sub_module</a>
+</item>
+
+<item>
 <a href="/en/docs/http/ngx_http_upstream_module.xml">
 ngx_http_upstream_module</a>
 </item>