<!-- Module User's Guide -->

<chapter>

  <title>&adminguide;</title>

  <section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
	  This module is a lightweight wrapper for the MaxMind GeoIP
	  API. It adds IP address-to-location lookup capability to
	  &osips; scripts.
	</para>
	<para>
	  Lookups are executed against the freely-available GeoLite City
	  database; and the non-free GeoIP City database is drop-in
	  compatible. All lookup fields provided by the API are accessible
	  by the script. Visit the
	  <ulink
	  url="https://dev.maxmind.com/geoip/"><citetitle>MaxMind
	  website</citetitle></ulink> for more information on the location
	  databases.
	</para>
	<para>
		The module is compatible with both legacy GeoIP and the
		newer GeoIP2 APIs and databases.
	</para>
  </section>
  <section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
	  <title>&osips; Modules</title>
	  <para>
		The following  modules must be loaded before this module:
		<itemizedlist>
		  <listitem>
			<para>
			  <emphasis>No dependencies on other &osips; modules</emphasis>.
			</para>
		  </listitem>
		</itemizedlist>
	  </para>
	</section>
	<section>
	  <title>External Libraries or Applications</title>
	  <para>
		The following libraries or applications must be installed before running
		&osips; with this module loaded:
		<itemizedlist>
		  <listitem>
			<para>
			  <emphasis>libGeoIP</emphasis> - for the legacy GeoIP API and database;
			</para>
		  </listitem>
		  <listitem>
			<para>
			  <emphasis>libmaxminddb</emphasis> - for the GeoIP2 API and database.
			</para>
		  </listitem>
		</itemizedlist>
	  </para>
	  <para>
	  	You can select which GeoIP library to use by setting the GEOIP environment variable,
	  	before compiling the module, to one of the following values:
	  	<itemizedlist>
	  		<listitem>
	  			<para><emphasis>GEOIPLEGACY  ***</emphasis> libGeoIP library shall be used</para>
	  		</listitem>

	  		<listitem>
	  			<para><emphasis>GEOIP2  ***</emphasis> libmaxminddb library shall be used;</para>
	  		</listitem>
	  	</itemizedlist>

	  	<para>IMPORTANT: If the selected library is not installed the module won't compile.</para>
	  	<para>NOTE: If GEOIP env is not set, the module will try to find which GeoIP library is installed,
	  		prioritizing libmaxminddb.</para>
	  </para>
	</section>
  </section>

  <section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>

	<section id="param_mmgeoip_city_db_path" xreflabel="mmgeoip_city_db_path">
	  <title><varname>mmgeoip_city_db_path</varname> (string)</title>
	  <para>
		Path to either a GeoLite or GeoIP City database file.
	  </para>
	  <para>
		<emphasis>
		  Mandatory parameter.
		</emphasis>
	  </para>
	  <example>
		<title>Set <quote>mmgeoip_city_db_path</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("mmgeoip", "mmgeoip_city_db_path",
  "/usr/share/GeoIP/GeoLiteCity.dat")
...
		</programlisting>
	  </example>
	</section>

	<section id="param_cache_type" xreflabel="cache_type">
	  <title><varname>cache_type</varname> (string)</title>
	  <para>
		Databse memory caching options. The following options are available:
		<itemizedlist>

			<listitem>
				<para>
					<emphasis>STANDARD</emphasis> - Read database from file system;
					least memory used;
				</para>
			</listitem>

			<listitem>
				<para>
					<emphasis>MMAP_CACHE</emphasis> - Load database into mmap allocated
					memory;
					<para><emphasis>WARNING: this option will cause a segmentation
							fault if database file is changed at runtime!</emphasis></para>
				</para>
			</listitem>

			<listitem>
				<para>
					<emphasis>MEM_CACHE_CHECK</emphasis> - Load database into memory;
					this mode checks for database updates; if database was modified,
					the file will be reloaded after 60 seconds; it will be slower than
					<emphasis>MMAP_CACHE</emphasis> but it will allow reloads;
				</para>
			</listitem>

		</itemizedlist>
	  </para>
	  <para>
		Default value for this parameter is <emphasis>MMAP_CACHE</emphasis>.
	  </para>
	  <para>
	  	NOTE: If libmaxminddb is used, this parameter will be ignored as the library only
	  	supports loading the database into mmap allocated memory.
	  </para>
	  <example>
		<title>Set <quote>cache_type</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("mmgeoip", "cache_type","MEM_CACHE_CHECK")
...
		</programlisting>
	  </example>
	</section>

  </section>
  <section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_mmg_lookup" xreflabel="mmg_lookup()">
	  <title>
		<function moreinfo="none">mmg_lookup([fields,]src,dst)</function>
	  </title>
	  <para>
		Looks up information specified by <varname>field</varname> associated with
		the IP address <varname>src</varname>. The resulting data is loaded in
		<emphasis>reverse</emphasis> order into the <varname>dst</varname> AVP.
	  </para>
	  <para>Parameters:</para>
	  <itemizedlist>
	  	<listitem><para>
	  		<emphasis>fields</emphasis> (string, optional) - a list of elements delimited by
			one of these separators: ':', '|', ',', '/' or ' '(space). Accepts the following tokens:
	  		  <itemizedlist>
	  			<listitem> <para> <emphasis>lat</emphasis> - Latitude</para></listitem>
	  			<listitem> <para> <emphasis>lon</emphasis> - Longitude</para></listitem>
	  			<listitem> <para> <emphasis>cont</emphasis> - Continent</para></listitem>
	  			<listitem> <para> <emphasis>cc</emphasis> - Country Code</para></listitem>
	  			<listitem> <para> <emphasis>reg</emphasis> - Region</para></listitem>
	  			<listitem> <para> <emphasis>city</emphasis> - City</para></listitem>
	  			<listitem> <para> <emphasis>pc</emphasis> - Postal Code</para></listitem>
	  			<listitem> <para> <emphasis>dma</emphasis> - DMA Code</para></listitem>
	  			<listitem> <para> <emphasis>ac</emphasis> - Area Code, only available in the legacy GeoIP
	  			database</para></listitem>
	  			<listitem> <para> <emphasis>tz</emphasis> - Time Zone</para></listitem>
	  		  </itemizedlist>
	  	</para></listitem>
	  	<listitem><para>
	  		<emphasis>src</emphasis> (string) - IP address
	  	</para></listitem>
	  	<listitem><para>
	  		<emphasis>dst</emphasis> (var) - AVP to return the information associated with the IP in.
	  	</para></listitem>
	  </itemizedlist>
	  <para>
	  	When using the GeoIP2 library, each token from the list given in the <varname>fields</varname>
	  	parameter can be provided as a path to a specific key in the data structure associated with an
	  	IP. Thus, the token format is '<emphasis>key_name</emphasis>.<emphasis>key_name</emphasis>[<emphasis>.key_name</emphasis>]*'. If a key's value is an array, instead of a subkey name, an index should be
	  	provided in order to select the appropriate value.
	  </para>
	  <para>
	  	Example tokens: '<emphasis>country.names.en</emphasis>', '<emphasis>continent.names.en
	  	</emphasis>', '<emphasis>subdivisions.0.iso_code</emphasis>'. For more details about
	  	the available fields in the database and the key names that should be used to
	  	retrieve them, check the <ulink url="https://dev.maxmind.com/geoip/geoip2/"><citetitle>MaxMind
		GeoIP2 documentation</citetitle></ulink>.
	  </para>

	  <para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
		ONREPLY_ROUTE, BRANCH_ROUTE,ERROR_ROUTE, and LOCAL_ROUTE.
	  </para>

	  <example>
		<title><function moreinfo="none">mmg_lookup</function> usage</title>
		<programlisting format="linespecific">
...
if(mmg_lookup("lon:lat",$si,$avp(lat_lon))) {
  xlog("L_INFO","Source IP latitude:$(avp(lat_lon)[0])\n");
  xlog("L_INFO","Source IP longitude:$(avp(lat_lon)[1])\n");
};
...
# fields format only supported for GeoIP2
if(mmg_lookup("continent.names.en:country.iso_code,",$si,$avp(geodata))) {
  xlog("L_INFO","Source IP country code:$(avp(geodata)[0])\n");
  xlog("L_INFO","Source IP continent:$(avp(geodata)[1])\n");
};
...
		</programlisting>
	  </example>
	</section>
  </section>

  <section>
	<title>Known Issues</title>
	<para>
	  It is not currently possible to load an updated location
	  database without first stalling the server.
	</para>
  </section>

</chapter>

