geoip: also include URL in docs
[sip-router] / modules / geoip / README
1 geoip Module
2
3 Daniel-Constantin Mierla
4
5    asipto.com
6
7 Edited by
8
9 Daniel-Constantin Mierla
10
11    <miconda@gmail.com>
12
13 Edited by
14
15 Alex Balashov
16
17    Evariste Systems LLC
18    <abalashov@evaristesys.com>
19
20    Copyright © 2010 Daniel-Constantin Mierla (asipto.com)
21      __________________________________________________________________
22
23    Table of Contents
24
25    1. Admin Guide
26
27         1. Overview
28         2. Dependencies
29
30               2.1. Kamailio Modules
31               2.2. External Libraries or Applications
32
33         3. Exported Parameters
34
35               3.1. path (string)
36
37         4. Exported Functions
38
39               4.1. geoip_match(ipaddr, pvc)
40
41         5. Exported pseudo-variables
42
43    List of Examples
44
45    1.1. Set path parameter
46    1.2. geoip_match usage
47
48 Chapter 1. Admin Guide
49
50    Table of Contents
51
52    1. Overview
53    2. Dependencies
54
55         2.1. Kamailio Modules
56         2.2. External Libraries or Applications
57
58    3. Exported Parameters
59
60         3.1. path (string)
61
62    4. Exported Functions
63
64         4.1. geoip_match(ipaddr, pvc)
65
66    5. Exported pseudo-variables
67
68 1. Overview
69
70    This module allows real-time queries against the Max Mind GeoIP
71    database to be performed from the config script.
72
73    The Max Mind GeoIP database is a map of IP network address assignments
74    to geographical locales that can be useful -- though approximate -- in
75    identifying the physical location with which an IP host address is
76    associated on a relatively granular level.
77
78    This database itself can be obtained on a free or commercial basis from
79    http://www.maxmind.com/app/ip-location. The library that interfaces
80    with the Max Mind API, as well as scripts to automate downloading of
81    the on-disk version of the open-source database is also packaged by the
82    Debian Linux distribution and its derivatives as libgeoip, and probably
83    by other distributions as well.
84
85    Debian Linux squeeze includes already a database as dependency, but as
86    this contain the wrong data, it will not work correctly with the
87    module. More acurate, the module expect the GeoIP City Edition, and
88    will not work with the GeoIP Country Edition. In newer Debian Linux
89    releases the package geoip-database-contrib should contain the
90    necessary database. You can download the Lite edition of the DB from
91    http://www.maxmind.com/app/geolitecity.
92
93    This module exports a new class of pseudo-variables - $gip(pvc=>key) -
94    to enable access to the results of a query to the database.
95
96    Many queries can be done and store results in different containers to
97    be able to use in parallel. Database is loaded at startup in cache.
98
99 2. Dependencies
100
101    2.1. Kamailio Modules
102    2.2. External Libraries or Applications
103
104 2.1. Kamailio Modules
105
106    The following modules must be loaded before this module:
107      * none.
108
109 2.2. External Libraries or Applications
110
111    The following libraries or applications must be installed before
112    running Kamailio with this module loaded:
113      * libgeoip - the GeoIP library.
114
115 3. Exported Parameters
116
117    3.1. path (string)
118
119 3.1. path (string)
120
121    Path to the GeoIP database file.
122
123    Default value is “null”.
124
125    Example 1.1. Set path parameter
126 ...
127 modparam("geoip", "path", "/usr/local/share/GeoLiteCity.dat")
128 ...
129
130 4. Exported Functions
131
132    4.1. geoip_match(ipaddr, pvc)
133
134 4.1.  geoip_match(ipaddr, pvc)
135
136    Match ipaddr against the GeoIP database and set the pvc container. The
137    function has to be called before accessing a key via: $gip(pvc=>key).
138
139    Example 1.2. geoip_match usage
140 ...
141 if(geoip_match("$si", "src"))
142     xlog("SIP message from: $gip(src=>cc)\n");
143 ...
144
145 5. Exported pseudo-variables
146
147      * $gip(pvc=>key) - pvc is an identifier for this query result; it is
148        designated by the second parameter of geoip_match(). The key can be
149        one of the following:
150           + cc - country code
151           + tz - time zone
152           + zip - postal code
153           + lat - latitude
154           + lon - longitude
155           + dma - dma code
156           + ips - ip start
157           + ipe - ip end
158           + city - city
159           + area - area code
160           + regc - region
161           + regn - region name
162           + metro - metro code
163
164    Exported pseudo-variables are documented at
165    http://www.kamailio.org/dokuwiki/.