# &adminguide;

## 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.

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- none.

### External Libraries or Applications

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

- libmaxminddb - the GeoIP2 library.

## Parameters

### `path` (string)

Path to the GeoIP2 database file.

Default value is null.

#### Set `path` parameter

    ...
    modparam("geoip2", "path", "/usr/local/share/GeoIP/GeoLite2-City.mmdb")
    ...

## Functions

### `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).

#### `geoip2_match` usage

    ...
    if(geoip2_match("$si", "src"))
        xlog("SIP message from: $gip2(src=>cc)\n");
    ...

## 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

  - contc - continent code

Exported pseudo-variables are documented at &kamwikilink;.