kamailio · sokhapkin · Jan 27, 2015 · Feb 2, 2015 · Feb 2, 2015 · Feb 2, 2015
diff --git a/modules/geoip2/Makefile b/modules/geoip2/Makefile
@@ -0,0 +1,15 @@
+# $Id$
+#
+# WARNING: do not run this directly, it should be run by the master Makefile
+
+include ../../Makefile.defs
+auto_gen=
+NAME=geoip2.so
+LIBS= -lmaxminddb
+
+DEFS+=-DKAMAILIO_MOD_INTERFACE
+
+SERLIBPATH=../../lib
+SER_LIBS+=$(SERLIBPATH)/kmi/kmi
+
+include ../../Makefile.modules
diff --git a/modules/geoip2/README b/modules/geoip2/README
@@ -0,0 +1,146 @@
+geoip2 Module
+
+Sergey Okhapkin
+
+   callwithus.com
+
+Edited by
+
+Daniel-Constantin Mierla
+
+   <miconda@gmail.com>
+
+   Copyright © 2010 Daniel-Constantin Mierla (asipto.com)
+     __________________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1. Overview
+        2. Dependencies
+
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
+
+        3. Parameters
+
+              3.1. path (string)
+
+        4. Functions
+
+              4.1. geoip2_match(ipaddr, pvc)
+
+        5. Exported pseudo-variables
+
+   List of Examples
+
+   1.1. Set path parameter
+   1.2. geoip2_match usage
+
+Chapter 1. Admin Guide
+
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+
+        2.1. Kamailio Modules
+        2.2. External Libraries or Applications
+
+   3. Parameters
+
+        3.1. path (string)
+
+   4. Functions
+
+        4.1. geoip2_match(ipaddr, pvc)
+
+   5. Exported pseudo-variables
+
+1. Overview
+
+   This module allows real-time queries against the Max Mind GeoIP2
+   database to be performed from the config script.
+
+   The Max Mind GeoIP2 database is a map of IP network address assignments
+   to geographical locales that can be useful -- though approximate -- in
+   identifying the physical location with which an IP host address is
+   associated on a relatively granular level.
+
+   This database itself can be obtained on a free or commercial basis from
+   http://dev.maxmind.com/geoip/. The library libmaxminddb that interfaces
+   with the Max Mind API, as well as scripts to automate downloading of
+   the on-disk version are available at
+   http://dev.maxmind.com/geoip/geoip2/downloadable/.
+
+   This module exports a new class of pseudo-variables - $gip2(pvc=>key) -
+   to enable access to the results of a query to the database.
+
+   Many queries can be done and store results in different containers to
+   be able to use in parallel. Database is loaded at startup in cache.
+
+2. Dependencies
+
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
+
+2.1. Kamailio Modules
+
+   The following modules must be loaded before this module:
+     * none.
+
+2.2. External Libraries or Applications
+
+   The following libraries or applications must be installed before
+   running Kamailio with this module loaded:
+     * libmaxminddb - the GeoIP2 library.
+
+3. Parameters
+
+   3.1. path (string)
+
+3.1. path (string)
+
+   Path to the GeoIP2 database file.
+
+   Default value is “null”.
+
+   Example 1.1. Set path parameter
+...
+modparam("geoip2", "path", "/usr/local/share/GeoIP/GeoLite2-City.mmdb")
+...
+
+4. Functions
+
+   4.1. geoip2_match(ipaddr, pvc)
+
+4.1.  geoip2_match(ipaddr, pvc)
+
+   Match ipaddr against the GeoIP database and set the pvc container. The
+   function has to be called before accessing a key via: $gip2(pvc=>key).
+
+   Example 1.2. geoip2_match usage
+...
+if(geoip2_match("$si", "src"))
+    xlog("SIP message from: $gip2(src=>cc)\n");
+...
+
+5. Exported pseudo-variables
+
+     * $gip2(pvc=>key) - pvc is an identifier for this query result; it is
+       designated by the second parameter of geoip2_match(). The key can
+       be one of the following:
+          + cc - country code
+          + tz - time zone
+          + zip - postal code
+          + lat - latitude
+          + lon - longitude
+          + nmask - network mask (CIDR format)
+          + city - city
+          + regc - region
+          + regn - region name
+          + metro - metro code
+
+   Exported pseudo-variables are documented at
+   http://www.kamailio.org/wiki/.
diff --git a/modules/geoip2/doc/Makefile b/modules/geoip2/doc/Makefile
@@ -0,0 +1,4 @@
+docs = geoip2.xml
+
+docbook_dir = ../../../docbook
+include $(docbook_dir)/Makefile.module
diff --git a/modules/geoip2/doc/geoip2.xml b/modules/geoip2/doc/geoip2.xml
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding='ISO-8859-1'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+<!-- Include general documentation entities -->
+<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+%docentities;
+
+]>
+
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
+    <bookinfo>
+	<title>geoip2 Module</title>
+	<productname class="trade">&kamailioname;</productname>
+	<authorgroup>
+	    <author>
+		<firstname>Sergey</firstname>
+		<surname>Okhapkin</surname>
+		<affiliation><orgname>callwithus.com</orgname></affiliation>
+	    </author>
+	    <editor>
+		<firstname>Daniel-Constantin</firstname>
+		<surname>Mierla</surname>
+		    <email>miconda@gmail.com</email>
+	    </editor>
+	</authorgroup>
+	<copyright>
+	    <year>2010</year>
+	    <holder>Daniel-Constantin Mierla (asipto.com)</holder>
+	</copyright>
+    </bookinfo>
+    <toc></toc>
+
+	<xi:include href="geoip2_admin.xml"/>
+
+</book>
diff --git a/modules/geoip2/doc/geoip2_admin.xml b/modules/geoip2/doc/geoip2_admin.xml
@@ -0,0 +1,175 @@
+<?xml version="1.0" encoding='ISO-8859-1'?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+
+<!-- Include general documentation entities -->
+<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
+%docentities;
+
+]>
+
+<!-- Module User's Guide -->
+
+<chapter>
+
+    <title>&adminguide;</title>
+
+    <section>
+	<title>Overview</title>
+	<para>
+		This module allows real-time queries against the Max Mind GeoIP2 
+		database to be performed from the config script.  
+	</para>
+	<para>
+		The Max Mind GeoIP2 database is a map of IP network address assignments 
+		to geographical locales that can be useful -- though approximate --
+		in identifying the physical location with which an IP host address
+		is associated on a relatively granular level.
+	</para>
+	<para>
+		This database itself can be obtained on a free or commercial basis 
+		from <ulink url="http://dev.maxmind.com/geoip/">
+		http://dev.maxmind.com/geoip/</ulink>. The 
+		library libmaxminddb
+		that interfaces with the Max Mind API, as well as scripts to
+		automate downloading of the on-disk version are available at
+		<ulink url="http://dev.maxmind.com/geoip/geoip2/downloadable/">
+		http://dev.maxmind.com/geoip/geoip2/downloadable/</ulink>.
+	</para>
+	<para>
+		This module exports a new class of pseudo-variables -
+		$gip2(pvc=&gt;key) - to enable access to the results of a query to the
+		database.
+	</para>
+	<para>
+		Many queries can be done and store results in different containers to
+		be able to use in parallel. Database is loaded at startup in cache.
+	</para>
+    </section>
+    <section>
+	<title>Dependencies</title>
+	<section>
+	    <title>&kamailio; Modules</title>
+	    <para>
+		The following modules must be loaded before this module:
+	    	<itemizedlist>
+		    <listitem>
+			<para>
+			    <emphasis>none</emphasis>.
+			</para>
+		    </listitem>
+	    	</itemizedlist>
+	    </para>
+	</section>
+	<section>
+	    <title>External Libraries or Applications</title>
+	    <para>
+		The following libraries or applications must be installed before running
+		&kamailio; with this module loaded:
+	    	<itemizedlist>
+		    <listitem>
+			<para>
+			    <emphasis>libmaxminddb</emphasis> - the GeoIP2 library.
+			</para>
+		    </listitem>
+	    	</itemizedlist>
+	    </para>
+	</section>
+    </section>
+    <section>
+	<title>Parameters</title>
+	<section>
+	    <title><varname>path</varname> (string)</title>
+	    <para>
+		Path to the GeoIP2 database file.
+	    </para>
+	    <para>
+		<emphasis>
+		    Default value is <quote>null</quote>.
+		</emphasis>
+	    </para>
+	    <example>
+		<title>Set <varname>path</varname> parameter</title>
+		<programlisting format="linespecific">
+...
+modparam("geoip2", "path", "/usr/local/share/GeoIP/GeoLite2-City.mmdb")
+...
+</programlisting>
+	    </example>
+	</section>
+
+	</section>
+
+    <section>
+	<title>Functions</title>
+ 	<section>
+	    <title>
+		<function moreinfo="none">geoip2_match(ipaddr, pvc)</function>
+	    </title>
+	    <para>
+			Match ipaddr against the GeoIP database and set the pvc container. The
+			function has to be called before accessing a key via: $gip2(pvc=&gt;key).
+	    </para>
+		<example>
+		<title><function>geoip2_match</function> usage</title>
+		<programlisting format="linespecific">
+...
+if(geoip2_match("$si", "src"))
+    xlog("SIP message from: $gip2(src=&gt;cc)\n");
+...
+</programlisting>
+	    </example>
+	</section>
+
+    </section>
+
+	<section>
+		<title>Exported pseudo-variables</title>
+		<itemizedlist>
+			<listitem><para>
+				<emphasis>$gip2(pvc=&gt;key)</emphasis> - <emphasis>pvc</emphasis> is an 
+				identifier for this query result;  it is designated by the second 
+				parameter of geoip2_match(). The <emphasis>key</emphasis> can be one of
+				the following:
+				</para>
+			<itemizedlist>
+				<listitem><para>
+					<emphasis>cc</emphasis> - country code
+				</para></listitem>
+				<listitem><para>
+					<emphasis>tz</emphasis> - time zone
+				</para></listitem>
+				<listitem><para>
+					<emphasis>zip</emphasis> - postal code
+				</para></listitem>
+				<listitem><para>
+					<emphasis>lat</emphasis> - latitude
+				</para></listitem>
+				<listitem><para>
+					<emphasis>lon</emphasis> - longitude
+				</para></listitem>
+				<listitem><para>
+					<emphasis>nmask</emphasis> - network mask (CIDR format)
+				</para></listitem>
+				<listitem><para>
+					<emphasis>city</emphasis> - city
+				</para></listitem>
+				<listitem><para>
+					<emphasis>regc</emphasis> - region
+				</para></listitem>
+				<listitem><para>
+					<emphasis>regn</emphasis> - region name
+				</para></listitem>
+				<listitem><para>
+					<emphasis>metro</emphasis> - metro code
+				</para></listitem>
+			</itemizedlist>
+			</listitem>
+		</itemizedlist>
+		<para>
+		Exported pseudo-variables are documented at &kamwikilink;.
+		</para>
+	</section>
+
+</chapter>
+