"Fossies" - the Fresh Open Source Software Archive

Member "opensips-3.0.1/modules/mmgeoip/doc/mmgeoip_admin.xml" (29 May 2019, 8293 Bytes) of package /linux/misc/opensips-3.0.1.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) XML source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the last Fossies "Diffs" side-by-side code changes report for "mmgeoip_admin.xml": 2.4.5_vs_3.0.0.

    1 <!-- Module User's Guide -->
    2 
    3 <chapter>
    4 
    5   <title>&adminguide;</title>
    6 
    7   <section id="overview" xreflabel="Overview">
    8     <title>Overview</title>
    9     <para>
   10       This module is a lightweight wrapper for the MaxMind GeoIP
   11       API. It adds IP address-to-location lookup capability to
   12       &osips; scripts.
   13     </para>
   14     <para>
   15       Lookups are executed against the freely-available GeoLite City
   16       database; and the non-free GeoIP City database is drop-in
   17       compatible. All lookup fields provided by the API are accessible
   18       by the script. Visit the
   19       <ulink
   20       url="https://dev.maxmind.com/geoip/"><citetitle>MaxMind
   21       website</citetitle></ulink> for more information on the location
   22       databases.
   23     </para>
   24     <para>
   25         The module is compatible with both legacy GeoIP and the
   26         newer GeoIP2 APIs and databases.
   27     </para>
   28   </section>
   29   <section id="dependencies" xreflabel="Dependencies">
   30     <title>Dependencies</title>
   31     <section>
   32       <title>&osips; Modules</title>
   33       <para>
   34         The following  modules must be loaded before this module:
   35         <itemizedlist>
   36           <listitem>
   37             <para>
   38               <emphasis>No dependencies on other &osips; modules</emphasis>.
   39             </para>
   40           </listitem>
   41         </itemizedlist>
   42       </para>
   43     </section>
   44     <section>
   45       <title>External Libraries or Applications</title>
   46       <para>
   47         The following libraries or applications must be installed before running
   48         &osips; with this module loaded:
   49         <itemizedlist>
   50           <listitem>
   51             <para>
   52               <emphasis>libGeoIP</emphasis> - for the legacy GeoIP API and database;
   53             </para>
   54           </listitem>
   55           <listitem>
   56             <para>
   57               <emphasis>libmaxminddb</emphasis> - for the GeoIP2 API and database.
   58             </para>
   59           </listitem>
   60         </itemizedlist>
   61       </para>
   62       <para>
   63         You can select which GeoIP library to use by setting the GEOIP environment variable,
   64         before compiling the module, to one of the following values:
   65         <itemizedlist>
   66             <listitem>
   67                 <para><emphasis>GEOIPLEGACY  ***</emphasis> libGeoIP library shall be used</para>
   68             </listitem>
   69 
   70             <listitem>
   71                 <para><emphasis>GEOIP2  ***</emphasis> libmaxminddb library shall be used;</para>
   72             </listitem>
   73         </itemizedlist>
   74 
   75         <para>IMPORTANT: If the selected library is not installed the module won't compile.</para>
   76         <para>NOTE: If GEOIP env is not set, the module will try to find which GeoIP library is installed,
   77             prioritizing libmaxminddb.</para>
   78       </para>
   79     </section>
   80   </section>
   81 
   82   <section id="exported_parameters" xreflabel="Exported Parameters">
   83     <title>Exported Parameters</title>
   84 
   85     <section id="param_mmgeoip_city_db_path" xreflabel="mmgeoip_city_db_path">
   86       <title><varname>mmgeoip_city_db_path</varname> (string)</title>
   87       <para>
   88         Path to either a GeoLite or GeoIP City database file.
   89       </para>
   90       <para>
   91         <emphasis>
   92           Mandatory parameter.
   93         </emphasis>
   94       </para>
   95       <example>
   96         <title>Set <quote>mmgeoip_city_db_path</quote> parameter</title>
   97         <programlisting format="linespecific">
   98 ...
   99 modparam("mmgeoip", "mmgeoip_city_db_path",
  100   "/usr/share/GeoIP/GeoLiteCity.dat")
  101 ...
  102         </programlisting>
  103       </example>
  104     </section>
  105 
  106     <section id="param_cache_type" xreflabel="cache_type">
  107       <title><varname>cache_type</varname> (string)</title>
  108       <para>
  109         Databse memory caching options. The following options are available:
  110         <itemizedlist>
  111 
  112             <listitem>
  113                 <para>
  114                     <emphasis>STANDARD</emphasis> - Read database from file system;
  115                     least memory used;
  116                 </para>
  117             </listitem>
  118 
  119             <listitem>
  120                 <para>
  121                     <emphasis>MMAP_CACHE</emphasis> - Load database into mmap allocated
  122                     memory;
  123                     <para><emphasis>WARNING: this option will cause a segmentation
  124                             fault if database file is changed at runtime!</emphasis></para>
  125                 </para>
  126             </listitem>
  127 
  128             <listitem>
  129                 <para>
  130                     <emphasis>MEM_CACHE_CHECK</emphasis> - Load database into memory;
  131                     this mode checks for database updates; if database was modified,
  132                     the file will be reloaded after 60 seconds; it will be slower than
  133                     <emphasis>MMAP_CACHE</emphasis> but it will allow reloads;
  134                 </para>
  135             </listitem>
  136 
  137         </itemizedlist>
  138       </para>
  139       <para>
  140         Default value for this parameter is <emphasis>MMAP_CACHE</emphasis>.
  141       </para>
  142       <para>
  143         NOTE: If libmaxminddb is used, this parameter will be ignored as the library only
  144         supports loading the database into mmap allocated memory.
  145       </para>
  146       <example>
  147         <title>Set <quote>cache_type</quote> parameter</title>
  148         <programlisting format="linespecific">
  149 ...
  150 modparam("mmgeoip", "cache_type","MEM_CACHE_CHECK")
  151 ...
  152         </programlisting>
  153       </example>
  154     </section>
  155 
  156   </section>
  157   <section id="exported_functions" xreflabel="exported_functions">
  158     <title>Exported Functions</title>
  159     <section id="func_mmg_lookup" xreflabel="mmg_lookup()">
  160       <title>
  161         <function moreinfo="none">mmg_lookup([fields,]src,dst)</function>
  162       </title>
  163       <para>
  164         Looks up information specified by <varname>field</varname> associated with
  165         the IP address <varname>src</varname>. The resulting data is loaded in
  166         <emphasis>reverse</emphasis> order into the <varname>dst</varname> AVP.
  167       </para>
  168       <para>Parameters:</para>
  169       <itemizedlist>
  170         <listitem><para>
  171             <emphasis>fields</emphasis> (string, optional) - a list of elements delimited by
  172             one of these separators: ':', '|', ',', '/' or ' '(space). Accepts the following tokens:
  173               <itemizedlist>
  174                 <listitem> <para> <emphasis>lat</emphasis> - Latitude</para></listitem>
  175                 <listitem> <para> <emphasis>lon</emphasis> - Longitude</para></listitem>
  176                 <listitem> <para> <emphasis>cont</emphasis> - Continent</para></listitem>
  177                 <listitem> <para> <emphasis>cc</emphasis> - Country Code</para></listitem>
  178                 <listitem> <para> <emphasis>reg</emphasis> - Region</para></listitem>
  179                 <listitem> <para> <emphasis>city</emphasis> - City</para></listitem>
  180                 <listitem> <para> <emphasis>pc</emphasis> - Postal Code</para></listitem>
  181                 <listitem> <para> <emphasis>dma</emphasis> - DMA Code</para></listitem>
  182                 <listitem> <para> <emphasis>ac</emphasis> - Area Code, only available in the legacy GeoIP
  183                 database</para></listitem>
  184                 <listitem> <para> <emphasis>tz</emphasis> - Time Zone</para></listitem>
  185               </itemizedlist>
  186         </para></listitem>
  187         <listitem><para>
  188             <emphasis>src</emphasis> (string) - IP address
  189         </para></listitem>
  190         <listitem><para>
  191             <emphasis>dst</emphasis> (var) - AVP to return the information associated with the IP in.
  192         </para></listitem>
  193       </itemizedlist>
  194       <para>
  195         When using the GeoIP2 library, each token from the list given in the <varname>fields</varname>
  196         parameter can be provided as a path to a specific key in the data structure associated with an
  197         IP. Thus, the token format is '<emphasis>key_name</emphasis>.<emphasis>key_name</emphasis>[<emphasis>.key_name</emphasis>]*'. If a key's value is an array, instead of a subkey name, an index should be
  198         provided in order to select the appropriate value.
  199       </para>
  200       <para>
  201         Example tokens: '<emphasis>country.names.en</emphasis>', '<emphasis>continent.names.en
  202         </emphasis>', '<emphasis>subdivisions.0.iso_code</emphasis>'. For more details about
  203         the available fields in the database and the key names that should be used to
  204         retrieve them, check the <ulink url="https://dev.maxmind.com/geoip/geoip2/"><citetitle>MaxMind
  205         GeoIP2 documentation</citetitle></ulink>.
  206       </para>
  207 
  208       <para>
  209         This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
  210         ONREPLY_ROUTE, BRANCH_ROUTE,ERROR_ROUTE, and LOCAL_ROUTE.
  211       </para>
  212 
  213       <example>
  214         <title><function moreinfo="none">mmg_lookup</function> usage</title>
  215         <programlisting format="linespecific">
  216 ...
  217 if(mmg_lookup("lon:lat",$si,$avp(lat_lon))) {
  218   xlog("L_INFO","Source IP latitude:$(avp(lat_lon)[0])\n");
  219   xlog("L_INFO","Source IP longitude:$(avp(lat_lon)[1])\n");
  220 };
  221 ...
  222 # fields format only supported for GeoIP2
  223 if(mmg_lookup("continent.names.en:country.iso_code,",$si,$avp(geodata))) {
  224   xlog("L_INFO","Source IP country code:$(avp(geodata)[0])\n");
  225   xlog("L_INFO","Source IP continent:$(avp(geodata)[1])\n");
  226 };
  227 ...
  228         </programlisting>
  229       </example>
  230     </section>
  231   </section>
  232 
  233   <section>
  234     <title>Known Issues</title>
  235     <para>
  236       It is not currently possible to load an updated location
  237       database without first stalling the server.
  238     </para>
  239   </section>
  240 
  241 </chapter>
  242