[sr-dev] git:master: Added some clarifications and additional information to the ' geoip' docs.

Module: sip-router Branch: master Commit: 8c5375ff34b111807873cf6007886219d99d34ce URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=8c5375f… Author: Alex Balashov &lt;abalashov(a)evaristesys.com&gt; Committer: Alex Balashov &lt;abalashov(a)evaristesys.com&gt; Date: Wed Oct 6 02:51:23 2010 -0400 Added some clarifications and additional information to the 'geoip' docs. --- modules/geoip/README | 37 ++++++++++++++++++++++++---------- modules/geoip/doc/geoip_admin.xml | 39 ++++++++++++++++++++++++++++-------- 2 files changed, 56 insertions(+), 20 deletions(-) diff --git a/modules/geoip/README b/modules/geoip/README index 01c3d9d..11c8c73 100644 --- a/modules/geoip/README +++ b/modules/geoip/README @@ -10,7 +10,7 @@ Daniel-Constantin Mierla &lt;miconda(a)gmail.com&gt; - Copyright � 2010 Daniel-Constantin Mierla (asipto.com) + Copyright © 2010 Daniel-Constantin Mierla (asipto.com) __________________________________________________________________ Table of Contents @@ -60,12 +60,26 @@ Chapter 1. Admin Guide 1. Overview - The module loads exports a new class of pseudo-variables - - $gip(pvc=>key) - to access results upon a query against Max Mind GeoIP - database. + This module allows real-time queries against the Max Mind GeoIP + database to be performed from the config script. + + The Max Mind GeoIP 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 + here. The library that interfaces with the Max Mind API, as well as + scripts to automate downloading of the on-disk version of the + open-source database is also packaged by the Debian Linux distribution + and its derivatives as libgeoip, and probably by other distributions as + well. + + This module exports a new class of pseudo-variables - $gip(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 chache. + be able to use in parallel. Database is loaded at startup in cache. 2. Dependencies @@ -89,9 +103,9 @@ Chapter 1. Admin Guide 3.1. path (string) - Path to GeoIP database file. + Path to the GeoIP database file. - Default value is "null". + Default value is “null”. Example 1.1. Set path parameter ... @@ -104,8 +118,8 @@ modparam("geoip", "path", "/usr/local/share/GeoLiteCity.dat") 4.1. geoip_match(ipaddr, pvc) - Match ipaddr against GeoIP database and set the pvc container. The - function has to be called before accessing any $gip(pvc=>key). + Match ipaddr against the GeoIP database and set the pvc container. The + function has to be called before accessing a key via: $gip(pvc=>key). Example 1.2. geoip_match usage ... @@ -115,8 +129,9 @@ if(geoip_match("$si", "src")) 5. Exported pseudo-variables - * $gip(pvc=>key) - pvc is second parameter of geoip_match() and key - can be: + * $gip(pvc=>key) - pvc is an identifier for this query result; it is + designated by the second parameter of geoip_match(). The key can be + one of the following: + cc - country code + tz - time zone + zip - postal code diff --git a/modules/geoip/doc/geoip_admin.xml b/modules/geoip/doc/geoip_admin.xml index 89d2ede..b8c9f17 100644 --- a/modules/geoip/doc/geoip_admin.xml +++ b/modules/geoip/doc/geoip_admin.xml @@ -17,13 +17,32 @@ <section> <title>Overview</title> <para> - The module loads exports a new class of pseudo-variables - - $gip(pvc=&gt;key) - to access results upon a query against Max Mind - GeoIP database. + This module allows real-time queries against the Max Mind GeoIP + database to be performed from the config script. + </para> + <para> + The Max Mind GeoIP 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. + </para> + <para> + This database itself can be obtained on a free or commercial basis + <ulink url="http://www.maxmind.com/app/ip-location">here</ulink>;here</ulink>. The + library that interfaces with the Max Mind API, as well as scripts to + automate downloading of the on-disk version of the open-source + database is also packaged by the Debian Linux distribution and + its derivatives as <emphasis>libgeoip</emphasis>, and probably by + other distributions as well. + </para> + <para> + This module exports a new class of pseudo-variables - + $gip(pvc=&gt;key) - to enable access to the results of a query to the + database. </para> <para> Many queries can be done and store results in different containers to - be able to use in parallel. Database is loaded at startup in chache. + be able to use in parallel. Database is loaded at startup in cache. </para> </section> <section> @@ -61,7 +80,7 @@ <section> <title><varname>path</varname> (string)</title> <para> - Path to GeoIP database file. + Path to the GeoIP database file. </para> <para> <emphasis> @@ -87,8 +106,8 @@ modparam("geoip", "path", "/usr/local/share/GeoLiteCity.dat") <function moreinfo="none">geoip_match(ipaddr, pvc)</function> </title> <para> - Match ipaddr against GeoIP database and set the pvc container. The - function has to be called before accessing any $gip(pvc=&gt;key). + Match ipaddr against the GeoIP database and set the pvc container. The + function has to be called before accessing a key via: $gip(pvc=&gt;key). </para> <example> <title><function>geoip_match</function> usage</title> @@ -107,8 +126,10 @@ if(geoip_match("$si", "src")) <title>Exported pseudo-variables</title> <itemizedlist> <listitem><para> - <emphasis>$gip(pvc=&gt;key)</emphasis> - pvc is second - parameter of geoip_match() and key can be: + <emphasis>$gip(pvc=&gt;key)</emphasis> - <emphasis>pvc</emphasis> is an + identifier for this query result; it is designated by the second + parameter of geoip_match(). The <emphasis>key</emphasis> can be one of + the following: </para> <itemizedlist> <listitem><para>