# &adminguide;

## Overview

This module is a lightweight wrapper for the MaxMind GeoIP API. It adds IP address-to-location lookup capability to &osips; scripts.

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 MaxMind website for more information on the location databases.

## Dependencies

### &osips; Modules

The following modules must be loaded before this module:

- No dependencies on other &osips; modules.

### External Libraries or Applications

The following libraries or applications must be installed before running &osips; with this module loaded:

- libGeoIP.

## Exported Parameters

### `mmgeoip_city_db_path` (string)

Path to either a GeoLite or GeoIP City database file.

Mandatory parameter.

#### Set mmgeoip_city_db_path parameter

    ...
    modparam("mmgeoip", "mmgeoip_city_db_path",
      "/usr/share/GeoIP/GeoLiteCity.dat")
    ...

### `cache_type` (string)

Databse memory caching options. The following options are available:

- STANDARD - Read database from file system; least memory used;

- MMAP_CACHE - Load database into mmap allocated memory;

  WARNING: this option will cause a segmentation fault if database file is changed at runtime!

- MEM_CACHE_CHECK - 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 MMAP_CACHE but it will allow reloads;

Default value for this parameter is MMAP_CACHE.

#### Set cache_type parameter

    ...
    modparam("mmgeoip", "cache_type","MEM_CACHE_CHECK")
    ...

## Exported Functions

### `mmg_lookup([fields,]src,dst)`

Looks up specified `field`s associated with IP address specified by the `src`. The resulting data are loaded in reverse order into the `dst` AVP.

`src` can be a pseudo-variable or AVP; and `dst` must be an AVP. `fields` defaults to "lon:lat," and is a colon-delimited list of these elements:

- `lat` Latitude

- `lon` Longitude

- `cont` Continent

- `cc` Country Code

- `reg` Region

- `city` City

- `pc` Postal Code

- `dma` DMA Code

- `ac` Area Code

- `TZ` Time Zone

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE,ERROR_ROUTE, and LOCAL_ROUTE.

#### `mmg_lookup` usage

    ...
    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");
    };
    ...

## Known Issues

It is not currently possible to load an updated location database without first stalling the server.