src/modules/geoip/README
c13fefc2
 geoip Module
 
 Daniel-Constantin Mierla
 
    asipto.com
 
 Edited by
 
 Daniel-Constantin Mierla
 
    <miconda@gmail.com>
 
ad9e86d7
 Alex Balashov
 
    Evariste Systems LLC
    <abalashov@evaristesys.com>
 
8c5375ff
    Copyright © 2010 Daniel-Constantin Mierla (asipto.com)
c13fefc2
      __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
         1. Overview
         2. Dependencies
 
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
 
ba7961bb
         3. Parameters
c13fefc2
 
               3.1. path (string)
 
ba7961bb
         4. Functions
c13fefc2
 
               4.1. geoip_match(ipaddr, pvc)
 
         5. Exported pseudo-variables
 
    List of Examples
 
    1.1. Set path parameter
    1.2. geoip_match usage
 
 Chapter 1. Admin Guide
 
    Table of Contents
 
    1. Overview
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
ba7961bb
    3. Parameters
c13fefc2
 
         3.1. path (string)
 
ba7961bb
    4. Functions
c13fefc2
 
         4.1. geoip_match(ipaddr, pvc)
 
    5. Exported pseudo-variables
 
 1. Overview
 
8c5375ff
    This module allows real-time queries against the Max Mind GeoIP
7a1fb3ae
    database to be performed from the config script. It uses the old
    version of API, still very common on OS distributions. For using the
    new version of GeoIP API, see geoip2 module.
8c5375ff
 
    The Max Mind GeoIP 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.
 
4d777c51
    This database itself can be obtained on a free or commercial basis from
    http://www.maxmind.com/app/ip-location. The library that interfaces
    with the Max Mind API, as well as scripts to automate downloading of
    the on-disk version of the open-source database is also packaged by the
    Debian Linux distribution and its derivatives as libgeoip, and probably
    by other distributions as well.
8c5375ff
 
b280f89b
    Debian Linux squeeze includes already a database as dependency, but as
    this contain the wrong data, it will not work correctly with the
8868e624
    module. More accurate, the module expect the GeoIP City Edition, and
b280f89b
    will not work with the GeoIP Country Edition. In newer Debian Linux
    releases the package geoip-database-contrib should contain the
    necessary database. You can download the Lite edition of the DB from
4d777c51
    http://www.maxmind.com/app/geolitecity.
b280f89b
 
8c5375ff
    This module exports a new class of pseudo-variables - $gip(pvc=>key) -
    to enable access to the results of a query to the database.
c13fefc2
 
    Many queries can be done and store results in different containers to
8c5375ff
    be able to use in parallel. Database is loaded at startup in cache.
c13fefc2
 
 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:
      * libgeoip - the GeoIP library.
 
ba7961bb
 3. Parameters
c13fefc2
 
    3.1. path (string)
 
 3.1. path (string)
 
8c5375ff
    Path to the GeoIP database file.
c13fefc2
 
8c5375ff
    Default value is “null”.
c13fefc2
 
    Example 1.1. Set path parameter
 ...
 modparam("geoip", "path", "/usr/local/share/GeoLiteCity.dat")
 ...
 
ba7961bb
 4. Functions
c13fefc2
 
    4.1. geoip_match(ipaddr, pvc)
 
 4.1.  geoip_match(ipaddr, pvc)
 
8c5375ff
    Match ipaddr against the GeoIP database and set the pvc container. The
    function has to be called before accessing a key via: $gip(pvc=>key).
c13fefc2
 
    Example 1.2. geoip_match usage
 ...
 if(geoip_match("$si", "src"))
     xlog("SIP message from: $gip(src=>cc)\n");
 ...
 
 5. Exported pseudo-variables
 
8c5375ff
      * $gip(pvc=>key) - pvc is an identifier for this query result; it is
        designated by the second parameter of geoip_match(). The key can be
        one of the following:
c13fefc2
           + cc - country code
           + tz - time zone
           + zip - postal code
           + lat - latitude
           + lon - longitude
           + dma - dma code
           + ips - ip start
           + ipe - ip end
           + city - city
           + area - area code
           + regc - region
           + regn - region name
           + metro - metro code
7a1fb3ae
           + contc - continent code
c13fefc2
 
    Exported pseudo-variables are documented at
ff1bcdb4
    https://www.kamailio.org/wiki/.