Mercurial > hg > nginx-site
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 Mon Jan 23 16:46:36 2012 +0000 +++ b/xml/en/GNUmakefile Mon Jan 23 16:50:35 2012 +0000 @@ -52,6 +52,7 @@ 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 @@ 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)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/en/docs/http/ngx_http_geoip_module.xml Mon Jan 23 16:50:35 2012 +0000 @@ -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>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/en/docs/http/ngx_http_map_module.xml Mon Jan 23 16:50:35 2012 +0000 @@ -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>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/en/docs/http/ngx_http_realip_module.xml Mon Jan 23 16:50:35 2012 +0000 @@ -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>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/en/docs/http/ngx_http_secure_link_module.xml Mon Jan 23 16:50:35 2012 +0000 @@ -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>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/en/docs/http/ngx_http_split_clients_module.xml Mon Jan 23 16:50:35 2012 +0000 @@ -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>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/en/docs/http/ngx_http_sub_module.xml Mon Jan 23 16:50:35 2012 +0000 @@ -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 </head> + '</head><script language="javascript" src="$script"></script>'; + 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 Mon Jan 23 16:46:36 2012 +0000 +++ b/xml/en/docs/index.xml Mon Jan 23 16:50:35 2012 +0000 @@ -110,6 +110,11 @@ </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 @@ </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 @@ </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>