Order of GeoIP processing: Difference between revisions

From VoIPmonitor.org
(Add documentation on manually updating GeoIP database by copying tables from another system)
(Rewrite: add GeoIP use cases intro, consolidate manual import, improve tables)
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
== This doc describes order of GeoIP location services used with voipmonitor GUI ==
{{DISPLAYTITLE:Order of GeoIP Processing}}
[[Category:Configuration]]


'''In the GUI settings''' -> system config -> '''GeoIP''' (You can define your keys for maxmind or ipinfodb.)
= GeoIP Processing =
* If you define keys for both providers the 'maxmind' have precedence.
* In case you don't define a key, the local db will be used instead (this local db is updated with each GUI release, its stored into local db.)
* In case you have no GeoIP data downloaded in local db (voipmonitor.org unacessible from GUI server), it will use following free(demo) portals in following order:
** ipinfodb
** freegeoip
** maxmind


== Manually Updating the Local GeoIP Database ==
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


If you cannot upgrade the GUI directly but need to update the local GeoIP database, you can manually copy the GeoIP tables from a system that has the latest data (e.g., a server with a recently upgraded GUI).
== Processing Priority ==


'''Procedure to copy GeoIP tables:'''
The system uses a fallback mechanism, trying each method in order until successful:


# On the source system (with the latest GUI version), backup the GeoIP tables:
<kroki lang="mermaid">
<pre>
%%{init: {'flowchart': {'nodeSpacing': 15, 'rankSpacing': 40}}}%%
mysqldump -u username -p voipmonitor geoip_country geoipv6_country > geoip_tables.sql
flowchart TB
</pre>
    A[IP Address] --> B{MaxMind API}
# Restore the backup on the target system:
    B -->|Success| Z[Return Country]
<pre>
    B -->|Fail| C{IPInfoDB API}
mysql -u username -p voipmonitor < geoip_tables.sql
    C -->|Success| Z
</pre>
    C -->|Fail| D{Local Database}
# Update the GeoIP version record in the `system` table to match the source version:
    D -->|Success| Z
<pre>
    D -->|Fail| E{Free Portals}
# First, check the current version on the source system
    E -->|Success| Z
mysql -u username -p -e "SELECT * FROM voipmonitor.system WHERE type = 'geoip_country_version';"
    E -->|Fail| F[Unknown]
</kroki>


# Then set the same version on the target system (example: version 14)
{| class="wikitable"
mysql -u username -p -e "INSERT INTO voipmonitor.system (type, content) VALUES ('geoip_country_version', '14') ON DUPLICATE KEY UPDATE content = '14';"
! Priority !! Method !! Notes
</pre>
|-
| 1 || '''MaxMind API''' || Commercial service, highest accuracy. Requires API key.
|-
| 2 || '''IPInfoDB API''' || Alternative commercial API
|-
| 3 || '''Local Database''' || File-based (<code>GeoIPCity.dat</code>) OR MySQL tables
|-
| 4 || '''Free Portals''' || Online fallback services
|}


After completing these steps, the GeoIP warning popup should no longer appear, as the local database will now be up-to-date.
{{Tip|For best accuracy, configure MaxMind API with a valid license key.}}


'''Note:''' This procedure is useful when:
== Configuration ==
* Direct GUI upgrade is not possible
* You have multiple systems and want to ensure consistent GeoIP data across them
* You need to quickly update GeoIP data without waiting for a new GUI release


== Correcting Incorrect GeoIP Data ==
'''GUI Path:''' Settings → System Configuration → GeoIP


The GeoIP location data is sourced from MaxMind. If you encounter incorrect IP location information, you can help improve the database accuracy by submitting a correction request to MaxMind directly.
=== Local Database Options ===


'''Procedure to submit a correction:'''
{| class="wikitable"
# Go to the MaxMind GeoIP Update Form: [https://www.maxmind.com/en/geoip-correction Submit a Correction Request]
! Type !! Location/Table !! Description
# Fill out the form with the IP address, country, and other location details that need to be corrected
|-
# Submit the correction request to MaxMind
| 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
|}


After MaxMind updates their database:
Version tracking is stored in the <code>system</code> table:
# Notify the VoIPmonitor support team about the correction you submitted
* <code>type='geoip_country_version'</code>
# The support team will release a new version of the GUI that includes the updated MaxMind database
* <code>type='geoipv6_country_version'</code>
# Upgrade to the latest GUI version to get the corrected GeoIP data


=== AI Summary for RAG ===
== Manual GeoIP Import ==
'''Summary:''' Describes the priority order for GeoIP services in VoIPmonitor (MaxMind API keys, local database, or free demo portals), how to manually update the local GeoIP database by copying tables between systems, and how to correct incorrect GeoIP data.


'''Keywords:''' GeoIP, MaxMind, IPInfoDB, geolocation, IP location, map, CDR, correction, update database, geoip_country, geoipv6_country, manual restore, copy tables
Use this when GUI "Update GeoIP" fails or completes partially (version shows correct but lookups fail).
 
'''Export from working server:'''
<syntaxhighlight lang="bash">
mysqldump -c voipmonitor geoip_country > gc.sql
mysqldump -c voipmonitor geoipv6_country > gc6.sql
</syntaxhighlight>
 
'''Import to affected server:'''
<syntaxhighlight lang="bash">
mysql voipmonitor < gc.sql
mysql voipmonitor < gc6.sql
</syntaxhighlight>
 
'''Update version tracking:'''
<syntaxhighlight lang="sql">
-- 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';
</syntaxhighlight>
 
{{Warning|1=Ensure database name matches your installation (default: <code>voipmonitor</code>).}}
 
== See Also ==
 
* [[Anti-fraud]] - Country-based fraud detection using GeoIP
* [[Groups#IP_Groups|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:'''
'''Key Questions:'''
* What is the order of GeoIP services used by VoIPmonitor?
* What is the order of GeoIP processing in VoIPmonitor?
* How do I manually update the local GeoIP database without upgrading the GUI?
* Which GeoIP service has highest priority?
* How do I copy GeoIP tables from one system to another?
* Where do I configure GeoIP services in VoIPmonitor?
* What is the geoip_country_version in the system table?
* How to manually import GeoIP data when GUI update fails?
* How do I correct incorrect GeoIP location data?
* What MySQL tables store GeoIP data?
* What is GeoIP used for in VoIPmonitor?

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"