<?xml version="1.0"?>

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

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

<module name="Module ngx_stream_geoip_module"
        link="/en/docs/stream/ngx_stream_geoip_module.html"
        lang="en"
        rev="1">

<section id="summary">

<para>
The <literal>ngx_stream_geoip_module</literal> module (1.11.3) creates variables
with values depending on the client IP address, using the precompiled
<link url="http://www.maxmind.com">MaxMind</link> databases.
</para>

<para>
When using the databases with IPv6 support,
IPv4 addresses are looked up as IPv4-mapped IPv6 addresses.
</para>

<para>
This module is not built by default, it should be enabled with the
<literal>--with-stream_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>
stream {
    geoip_country         GeoIP.dat;
    geoip_city            GeoLiteCity.dat;

    map $geoip_city_continent_code $nearest_server {
        default        example.com;
        EU          eu.example.com;
        NA          na.example.com;
        AS          as.example.com;
    }
   ...
}
</example>
</para>

</section>


<section id="directives" name="Directives">

<directive name="geoip_country">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>

<para>
Specifies a database used to determine the country
depending on the client IP address.
The following variables are available when using this database:
<list type="tag">

<tag-name id="var_geoip_country_code"><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 id="var_geoip_country_code3"><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 id="var_geoip_country_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>file</value></syntax>
<default/>
<context>stream</context>

<para>
Specifies a database used to determine the country, region, and city
depending on the client IP address.
The following variables are available when using this database:
<list type="tag">

<tag-name id="var_geoip_area_code"><var>$geoip_area_code</var></tag-name>
<tag-desc>telephone area code (US only).
<note>
This variable may contain outdated information since
the corresponding database field is deprecated.
</note>
</tag-desc>

<tag-name id="var_geoip_city_continent_code">
<var>$geoip_city_continent_code</var></tag-name>
<tag-desc>two-letter continent code, for example,
“<literal>EU</literal>”, “<literal>NA</literal>”.
</tag-desc>

<tag-name id="var_geoip_city_country_code"><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 id="var_geoip_city_country_code3"><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 id="var_geoip_city_country_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 id="var_geoip_dma_code"><var>$geoip_dma_code</var></tag-name>
<tag-desc>
DMA region code in US (also known as “metro code”), according to the
<link url="https://developers.google.com/adwords/api/docs/appendix/cities-DMAregions">geotargeting</link>
in Google AdWords API.
</tag-desc>

<tag-name id="var_geoip_latitude"><var>$geoip_latitude</var></tag-name>
<tag-desc>latitude.</tag-desc>

<tag-name id="var_geoip_longitude"><var>$geoip_longitude</var></tag-name>
<tag-desc>longitude.</tag-desc>

<tag-name id="var_geoip_region"><var>$geoip_region</var></tag-name>
<tag-desc>
two-symbol country region code (region, territory, state, province, federal land
and the like), for example,
“<literal>48</literal>”, “<literal>DC</literal>”.
</tag-desc>

<tag-name id="var_geoip_region_name"><var>$geoip_region_name</var></tag-name>
<tag-desc>
country region name (region, territory, state, province, federal land
and the like), for example,
“<literal>Moscow City</literal>”, “<literal>District of Columbia</literal>”.
</tag-desc>

<tag-name id="var_geoip_city"><var>$geoip_city</var></tag-name>
<tag-desc>
city name, for example,
“<literal>Moscow</literal>”, “<literal>Washington</literal>”.
</tag-desc>

<tag-name id="var_geoip_postal_code"><var>$geoip_postal_code</var></tag-name>
<tag-desc>
postal code.
</tag-desc>

</list>
</para>

</directive>


<directive name="geoip_org">
<syntax><value>file</value></syntax>
<default/>
<context>stream</context>

<para>
Specifies a database used to determine the organization
depending on the client IP address.
The following variable is available when using this database:
<list type="tag">

<tag-name id="var_geoip_org"><var>$geoip_org</var></tag-name>
<tag-desc>
organization name, for example, “The University of Melbourne”.
</tag-desc>

</list>
</para>

</directive>

</section>

</module>