geoip: also include URL in docs
[sip-router] / modules / geoip / doc / geoip_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7 %docentities;
8
9 ]>
10
11 <!-- Module User's Guide -->
12
13 <chapter>
14     
15     <title>&adminguide;</title>
16     
17     <section>
18         <title>Overview</title>
19         <para>
20                 This module allows real-time queries against the Max Mind GeoIP 
21                 database to be performed from the config script.  
22         </para>
23         <para>
24                 The Max Mind GeoIP database is a map of IP network address assignments 
25                 to geographical locales that can be useful -- though approximate --
26                 in identifying the physical location with which an IP host address
27                 is associated on a relatively granular level.
28         </para>
29         <para>
30                 This database itself can be obtained on a free or commercial basis 
31                 from <ulink url="http://www.maxmind.com/app/ip-location">
32                 http://www.maxmind.com/app/ip-location</ulink>. The 
33                 library that interfaces with the Max Mind API, as well as scripts to
34                 automate downloading of the on-disk version of the open-source 
35                 database is also packaged by the Debian Linux distribution and 
36                 its derivatives as <emphasis>libgeoip</emphasis>, and probably by
37                 other distributions as well.
38         </para>
39         <para>
40                 Debian Linux squeeze includes already a database as dependency, but as
41                 this contain the wrong data, it will not work correctly with the module.
42                 More acurate, the module expect the <emphasis>GeoIP City Edition</emphasis>,
43                 and will not work with the <emphasis>GeoIP Country Edition</emphasis>. In
44                 newer Debian Linux releases the package <emphasis>geoip-database-contrib</emphasis>
45                 should contain the necessary database. You can download the Lite edition
46                 of the DB from <ulink url="http://www.maxmind.com/app/geolitecity">
47                 http://www.maxmind.com/app/geolitecity</ulink>.
48         </para>
49         <para>
50                 This module exports a new class of pseudo-variables -
51                 $gip(pvc=&gt;key) - to enable access to the results of a query to the
52                 database.
53         </para>
54         <para>
55                 Many queries can be done and store results in different containers to
56                 be able to use in parallel. Database is loaded at startup in cache.
57         </para>
58     </section>
59     <section>
60         <title>Dependencies</title>
61         <section>
62             <title>&kamailio; Modules</title>
63             <para>
64                 The following modules must be loaded before this module:
65                 <itemizedlist>
66                     <listitem>
67                         <para>
68                             <emphasis>none</emphasis>.
69                         </para>
70                     </listitem>
71                 </itemizedlist>
72             </para>
73         </section>
74         <section>
75             <title>External Libraries or Applications</title>
76             <para>
77                 The following libraries or applications must be installed before running
78                 &kamailio; with this module loaded:
79                 <itemizedlist>
80                     <listitem>
81                         <para>
82                             <emphasis>libgeoip</emphasis> - the GeoIP library.
83                         </para>
84                     </listitem>
85                 </itemizedlist>
86             </para>
87         </section>
88     </section>
89     <section>
90         <title>Exported Parameters</title>
91         <section>
92             <title><varname>path</varname> (string)</title>
93             <para>
94                 Path to the GeoIP database file.
95             </para>
96             <para>
97                 <emphasis>
98                     Default value is <quote>null</quote>.
99                 </emphasis>
100             </para>
101             <example>
102                 <title>Set <varname>path</varname> parameter</title>
103                 <programlisting format="linespecific">
104 ...
105 modparam("geoip", "path", "/usr/local/share/GeoLiteCity.dat")
106 ...
107 </programlisting>
108             </example>
109         </section>
110
111         </section>
112         
113     <section>
114         <title>Exported Functions</title>
115         <section>
116             <title>
117                 <function moreinfo="none">geoip_match(ipaddr, pvc)</function>
118             </title>
119             <para>
120                         Match ipaddr against the GeoIP database and set the pvc container. The
121                         function has to be called before accessing a key via: $gip(pvc=&gt;key).
122             </para>
123                 <example>
124                 <title><function>geoip_match</function> usage</title>
125                 <programlisting format="linespecific">
126 ...
127 if(geoip_match("$si", "src"))
128     xlog("SIP message from: $gip(src=&gt;cc)\n");
129 ...
130 </programlisting>
131             </example>
132         </section>
133         
134     </section>
135         
136         <section>
137                 <title>Exported pseudo-variables</title>
138                 <itemizedlist>
139                         <listitem><para>
140                                 <emphasis>$gip(pvc=&gt;key)</emphasis> - <emphasis>pvc</emphasis> is an 
141                                 identifier for this query result;  it is designated by the second 
142                                 parameter of geoip_match(). The <emphasis>key</emphasis> can be one of
143                                 the following:
144                                 </para>
145                         <itemizedlist>
146                                 <listitem><para>
147                                         <emphasis>cc</emphasis> - country code
148                                 </para></listitem>
149                                 <listitem><para>
150                                         <emphasis>tz</emphasis> - time zone
151                                 </para></listitem>
152                                 <listitem><para>
153                                         <emphasis>zip</emphasis> - postal code
154                                 </para></listitem>
155                                 <listitem><para>
156                                         <emphasis>lat</emphasis> - latitude
157                                 </para></listitem>
158                                 <listitem><para>
159                                         <emphasis>lon</emphasis> - longitude
160                                 </para></listitem>
161                                 <listitem><para>
162                                         <emphasis>dma</emphasis> - dma code
163                                 </para></listitem>
164                                 <listitem><para>
165                                         <emphasis>ips</emphasis> - ip start
166                                 </para></listitem>
167                                 <listitem><para>
168                                         <emphasis>ipe</emphasis> - ip end
169                                 </para></listitem>
170                                 <listitem><para>
171                                         <emphasis>city</emphasis> - city
172                                 </para></listitem>
173                                 <listitem><para>
174                                         <emphasis>area</emphasis> - area code
175                                 </para></listitem>
176                                 <listitem><para>
177                                         <emphasis>regc</emphasis> - region
178                                 </para></listitem>
179                                 <listitem><para>
180                                         <emphasis>regn</emphasis> - region name
181                                 </para></listitem>
182                                 <listitem><para>
183                                         <emphasis>metro</emphasis> - metro code
184                                 </para></listitem>
185                         </itemizedlist>
186                         </listitem>
187                 </itemizedlist>
188                 <para>
189                 Exported pseudo-variables are documented at &kamwikilink;.
190                 </para>
191         </section>
192
193 </chapter>
194