Order of GeoIP processing: Difference between revisions

From VoIPmonitor.org
(Add MySQL GeoIP tables documentation with manual import procedure)
(Rewrite: add GeoIP use cases intro, consolidate manual import, improve tables)
 
(One intermediate revision by the same user not shown)
Line 2: Line 2:
[[Category:Configuration]]
[[Category:Configuration]]


= Order of GeoIP Processing =
= GeoIP Processing =


This page documents the priority order in which VoIPmonitor processes GeoIP lookups to determine geographic location of IP addresses.
VoIPmonitor uses GeoIP services to determine geographic location of IP addresses for:
* '''Anti-fraud alerts''' - Detecting calls to/from unexpected countries (see [[Anti-fraud]])
* '''CDR enrichment''' - Adding country information to call records
* '''Reporting''' - Country-based statistics and filtering


== Processing Priority ==
== Processing Priority ==


VoIPmonitor uses a fallback mechanism for GeoIP lookups. The system attempts each method in order until a successful result is obtained:
The system uses a fallback mechanism, trying each method in order until successful:


<kroki lang="mermaid">
<kroki lang="mermaid">
Line 25: Line 28:


{| class="wikitable"
{| class="wikitable"
! Priority !! Method !! Description
! Priority !! Method !! Notes
|-
|-
| 1 || '''MaxMind API''' || Commercial GeoIP service with high accuracy
| 1 || '''MaxMind API''' || Commercial service, highest accuracy. Requires API key.
|-
|-
| 2 || '''IPInfoDB API''' || Alternative commercial GeoIP API
| 2 || '''IPInfoDB API''' || Alternative commercial API
|-
|-
| 3 || '''Local Database''' || Offline GeoIP database stored on the server (file-based ''or'' MySQL tables)
| 3 || '''Local Database''' || File-based (<code>GeoIPCity.dat</code>) OR MySQL tables
|-
|-
| 4 || '''Free Portals''' || Fallback to free online GeoIP services
| 4 || '''Free Portals''' || Online fallback services
|}
|}
{{Tip|For best accuracy, configure MaxMind API with a valid license key.}}


== Configuration ==
== Configuration ==


GeoIP services are configured in:
'''GUI Path:''' Settings → System Configuration → GeoIP
* '''GUI Path:''' Settings → System Configuration → GeoIP


=== MySQL GeoIP Tables ===
=== Local Database Options ===


In addition to file-based GeoIP databases (GeoIPCity.dat), VoIPmonitor can store GeoIP data in MySQL database tables:
{| class="wikitable"
! Type !! Location/Table !! Description
|-
| File-based || <code>GeoIPCity.dat</code> || Legacy MaxMind format
|-
| MySQL IPv4 || <code>geoip_country</code> || Database table for IPv4
|-
| MySQL IPv6 || <code>geoipv6_country</code> || Database table for IPv6
|}


* '''Table:''' <code>geoip_country</code> - IPv4 GeoIP data
Version tracking is stored in the <code>system</code> table:
* '''Table:''' '''geoipv6_country</code> - IPv6 GeoIP data
* <code>type='geoip_country_version'</code>
* '''Version tracking:''' The '''system''' table stores version numbers as:
* <code>type='geoipv6_country_version'</code>
  ** <code>type='geoip_country_version'</code>
  ** <code>type='geoipv6_country_version'</code>


The GUI's "Update GeoIP" function populates these tables from external sources. If the GUI update fails partially or incompletely, the version in the database may appear correct while actual data is missing.
== Manual GeoIP Import ==


==== Manual GeoIP Import ====
Use this when GUI "Update GeoIP" fails or completes partially (version shows correct but lookups fail).
 
If the GUI's "Update GeoIP" function fails or completes partially, you can manually populate the GeoIP tables by importing data from a working installation.
 
'''Step 1: Export GeoIP tables from a working installation'''
 
On a server with a fresh or correctly populated VoIPmonitor database:


'''Export from working server:'''
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
mysqldump -c voipmonitor geoip_country > gc.sql
mysqldump -c voipmonitor geoip_country > gc.sql
Line 66: Line 71:
</syntaxhighlight>
</syntaxhighlight>


The <code>-c</code> flag ensures complete INSERT statements are included.
'''Import to affected server:'''
 
'''Step 2: Import the data to the affected server'''
 
Transfer the <code>gc.sql</code> and <code>gc6.sql</code> files to the affected server via SCP, SFTP, or another secure method.
 
Import the data into your VoIPmonitor database:
 
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
mysql voipmonitor < gc.sql
mysql voipmonitor < gc.sql
Line 79: Line 77:
</syntaxhighlight>
</syntaxhighlight>


{{Warning|1=Ensure you are importing to the correct database name. Replace <code>voipmonitor</code> with your actual database name if different.}}
'''Update version tracking:'''
 
'''Step 3: Update version information in the system table'''
 
After importing, ensure the version tracking is updated to prevent GUI update prompts:
 
<syntaxhighlight lang="bash">
mysql voipmonitor
</syntaxhighlight>
 
<syntaxhighlight lang="sql">
<syntaxhighlight lang="sql">
-- Replace '12' with the actual version number
-- Replace '12' with actual version number from source
insert into voipmonitor.system set content='12\n',type='geoip_country_version';
INSERT INTO system SET content='12\n', type='geoip_country_version';
insert into voipmonitor.system set content='12\n',type='geoipv6_country_version';
INSERT INTO system SET content='12\n', type='geoipv6_country_version';
</syntaxhighlight>
</syntaxhighlight>


The version number should match the GeoIP database version you imported (e.g., version 12 corresponds to GeoIP database version 12).
{{Warning|1=Ensure database name matches your installation (default: <code>voipmonitor</code>).}}
 
==== Troubleshooting MySQL GeoIP Tables ====
 
'''Problem: GUI shows correct version but GeoIP lookups fail'''
 
Symptom: The <code>system</code> table shows the correct version, but GeoIP resolution does not work or returns incomplete results.
 
Cause: The GUI update may have completed the version tracking without fully populating the data tables.
 
Solution: Use the manual import procedure above to fully populate the <code>geoip_country</code> and <code>geoipv6_country</code> tables.
 
{{Tip|1=For best accuracy and reliability, configure the MaxMind API with a valid license key.}}


== Related Pages ==
== See Also ==


* [[CountryGrouping]] - Country-based filtering and anti-fraud alerts
* [[Anti-fraud]] - Country-based fraud detection using GeoIP
* [[Groups#IP_Groups|IP Groups]] - Creating IP address groups for filtering
* [[Groups#IP_Groups|IP Groups]] - Creating IP address groups for filtering


== AI Summary for RAG ==
== AI Summary for RAG ==


'''Summary:''' Documents the priority order for GeoIP processing in VoIPmonitor. The system uses a fallback mechanism: (1) MaxMind API (highest priority), (2) IPInfoDB API, (3) Local Database (file-based OR MySQL tables), (4) Free Portals (lowest priority). Each method is tried in sequence until a successful country lookup is achieved. Configuration is done via GUI Settings → System Configuration → GeoIP. MySQL tables: geoip_country (IPv4), geoipv6_country (IPv6) with version tracking in system table (type='geoip_country_version', type='geoipv6_country_version'). If GUI GeoIP update fails partially (version correct but data missing), manually import tables: mysqldump -c voipmonitor geoip_country > gc.sql from working installation, then mysql voipmonitor < gc.sql on affected server, update version in system table with insert into system set content='12\n',type='geoip_country_version'.
'''Summary:''' Documents GeoIP processing priority in VoIPmonitor. Uses fallback mechanism: (1) MaxMind API (commercial, highest accuracy), (2) IPInfoDB API, (3) Local Database (file-based GeoIPCity.dat OR MySQL tables geoip_country/geoipv6_country), (4) Free Portals. GeoIP is used for anti-fraud alerts, CDR country enrichment, and reporting. Configuration via GUI Settings → System Configuration → GeoIP. Version tracking in system table (geoip_country_version, geoipv6_country_version). Manual import procedure: mysqldump from working installation, import to affected server, update version in system table.


'''Keywords:''' GeoIP, MaxMind, IPInfoDB, country lookup, IP geolocation, processing order, priority, fallback, local database, MySQL tables, geoip_country, geoipv6_country, manual import, system table, geoip_country_version, geoipv6_country_version
'''Keywords:''' GeoIP, MaxMind, IPInfoDB, country lookup, IP geolocation, processing order, priority, fallback, local database, GeoIPCity.dat, MySQL tables, geoip_country, geoipv6_country, manual import, system table, geoip_country_version, anti-fraud, country detection


'''Key Questions:'''
'''Key Questions:'''
Line 124: Line 101:
* Which GeoIP service has highest priority?
* Which GeoIP service has highest priority?
* Where do I configure GeoIP services in VoIPmonitor?
* Where do I configure GeoIP services in VoIPmonitor?
* What happens if MaxMind API fails?
* How to manually import GeoIP data when GUI update fails?
* Does VoIPmonitor support local GeoIP database?
* What MySQL tables store GeoIP data?
* How to manually import GeoIP data from a working installation?
* What is GeoIP used for in VoIPmonitor?
* What are the MySQL tables for GeoIP data?
* GUI GeoIP update fails partially - how to fix?

Latest revision as of 16:47, 8 January 2026


GeoIP Processing

VoIPmonitor uses GeoIP services to determine geographic location of IP addresses for:

  • Anti-fraud alerts - Detecting calls to/from unexpected countries (see Anti-fraud)
  • CDR enrichment - Adding country information to call records
  • Reporting - Country-based statistics and filtering

Processing Priority

The system uses a fallback mechanism, trying each method in order until successful:

Priority Method Notes
1 MaxMind API Commercial service, highest accuracy. Requires API key.
2 IPInfoDB API Alternative commercial API
3 Local Database File-based (GeoIPCity.dat) OR MySQL tables
4 Free Portals Online fallback services

💡 Tip: For best accuracy, configure MaxMind API with a valid license key.

Configuration

GUI Path: Settings → System Configuration → GeoIP

Local Database Options

Type Location/Table Description
File-based GeoIPCity.dat Legacy MaxMind format
MySQL IPv4 geoip_country Database table for IPv4
MySQL IPv6 geoipv6_country Database table for IPv6

Version tracking is stored in the system table:

  • type='geoip_country_version'
  • type='geoipv6_country_version'

Manual GeoIP Import

Use this when GUI "Update GeoIP" fails or completes partially (version shows correct but lookups fail).

Export from working server: 

mysqldump -c voipmonitor geoip_country > gc.sql
mysqldump -c voipmonitor geoipv6_country > gc6.sql

Import to affected server: 

mysql voipmonitor < gc.sql
mysql voipmonitor < gc6.sql

Update version tracking: 

-- Replace '12' with actual version number from source
INSERT INTO system SET content='12\n', type='geoip_country_version';
INSERT INTO system SET content='12\n', type='geoipv6_country_version';

⚠️ Warning: Ensure database name matches your installation (default: voipmonitor).

See Also

  • Anti-fraud - Country-based fraud detection using GeoIP
  • IP Groups - Creating IP address groups for filtering

AI Summary for RAG

Summary: Documents GeoIP processing priority in VoIPmonitor. Uses fallback mechanism: (1) MaxMind API (commercial, highest accuracy), (2) IPInfoDB API, (3) Local Database (file-based GeoIPCity.dat OR MySQL tables geoip_country/geoipv6_country), (4) Free Portals. GeoIP is used for anti-fraud alerts, CDR country enrichment, and reporting. Configuration via GUI Settings → System Configuration → GeoIP. Version tracking in system table (geoip_country_version, geoipv6_country_version). Manual import procedure: mysqldump from working installation, import to affected server, update version in system table.

Keywords: GeoIP, MaxMind, IPInfoDB, country lookup, IP geolocation, processing order, priority, fallback, local database, GeoIPCity.dat, MySQL tables, geoip_country, geoipv6_country, manual import, system table, geoip_country_version, anti-fraud, country detection

Key Questions:

  • What is the order of GeoIP processing in VoIPmonitor?
  • Which GeoIP service has highest priority?
  • Where do I configure GeoIP services in VoIPmonitor?
  • How to manually import GeoIP data when GUI update fails?
  • What MySQL tables store GeoIP data?
  • What is GeoIP used for in VoIPmonitor?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Order_of_GeoIP_processing&oldid=10039"