CountryGrouping: Difference between revisions

Latest revision as of 01:40, 11 January 2026

This guide covers country-based features in VoIPmonitor: GeoIP for IP geolocation, phone number prefix detection, anti-fraud alerts, and geographic filtering.

Country Detection Methods

VoIPmonitor uses two distinct methods for country detection:

Method	Based On	Use Case	Configuration
GeoIP	IP address geolocation	Detect location of endpoints	Settings → System Configuration → GeoIP
Country Prefixes	Phone number prefix (+1, +44, etc.)	Detect call destinations	Settings → Country Prefixes

ℹ️ Note: GeoIP tells you WHERE a device is located. Country Prefixes tell you WHERE a call is going to (destination number).

GeoIP Configuration

GeoIP services are configured in Settings → System Configuration → GeoIP.

Service Priority

VoIPmonitor tries services in order until successful:

MaxMind API — Commercial, highest accuracy (requires API key)
IPInfoDB API — Alternative service (requires API key)
Local database — Bundled with GUI, updated each release
Free portals — Fallback (ipinfodb, freegeoip, maxmind)

💡 Tip: For the most accurate and up-to-date data, configure a MaxMind API key. API lookups use MaxMind's live database.

For database update procedures, see Order_of_GeoIP_processing.

Country Prefix Configuration

Country prefixes are used for destination country alerts based on called numbers (not IPs).

Configuration: Settings → Country Prefixes

Setting	Description
Prefix list	Phone number prefixes per country (+1 for US, +44 for UK, etc.)
NANPA support	North American Numbering Plan handling
Strict for prefixes	Require exact prefix match

Country-Based Anti-Fraud Alerts

Configure in Alerts → Anti Fraud. For complete anti-fraud documentation, see Anti-fraud.

Alert Types

Alert	Detection Method	Trigger	Use Case
Country/Continent Destination	Phone prefix	Calls to specific countries/continents	Block high-fraud destinations
Change CDR Country	GeoIP	Caller/callee IP country changes	Detect compromised accounts
Change REGISTER Country	GeoIP	Device registers from different country	Detect SIP credential theft

Country Destination Alert Configuration

Countries/Continents: Select targets (or "ALL")
Exclude countries: Whitelist for legitimate destinations
Strict for prefixes: Require exact prefix match
Threshold: Number of calls or percentage to trigger

⚠️ Warning: Country Destination Alert uses PHONE NUMBER PREFIXES, not GeoIP. To detect calls based on destination IP country, use CDR filters with GeoIP.

Change Country Alerts Configuration

Both "Change CDR Country" and "Change REGISTER Country" alerts detect geographic anomalies:

Exclude countries: Whitelist for expected travel (e.g., border regions)
Filter by number/IP: Apply only to specific users or ranges
Time window: How far back to check for previous location

Country Filtering in CDR

When GeoIP is enabled:

Go to CDR → Filter
Use country filter fields (Caller Country, Called Country)
Select countries from dropdown or enter country codes

Applications:

Traffic analysis by geographic region
Compliance reporting
International call pattern monitoring

Integration with IP Groups

Combine GeoIP features with IP Groups for granular control:

Create IP Groups for known provider IPs per country
Use Groups in alert filters for precise targeting
Combine country alerts with IP-based filtering

Troubleshooting

GeoIP Data Not Showing

Verify GeoIP configuration in System Configuration
Check network connectivity to voipmonitor.org
Try manual database update (see manual import)

Incorrect Country Detection

ℹ️ Note: GeoIP accuracy depends on IP allocation databases which may be outdated for some ranges.

To correct GeoIP data:

Submit correction to MaxMind Correction Form
Wait for MaxMind database update cycle
Contact VoIPmonitor support to include updated data in next GUI release
Upgrade GUI to receive corrected database

Faster alternative: Configure MaxMind API key for real-time lookups.

AI Summary for RAG

Summary: VoIPmonitor uses two country detection methods: GeoIP (IP address geolocation) for detecting WHERE devices are located, and Country Prefixes (phone number prefixes like +1, +44) for detecting WHERE calls are going. GeoIP services follow priority: MaxMind API → IPInfoDB API → local database → free portals. Anti-fraud alerts include Country/Continent Destination (prefix-based, real-time), Change CDR Country (GeoIP, detects caller IP country changes), and Change REGISTER Country (GeoIP, detects registration from different country). Country Destination Alert uses PHONE PREFIXES not GeoIP. CDR filtering supports country-based queries when GeoIP is enabled.

Keywords: country grouping, GeoIP, MaxMind, IPInfoDB, country prefixes, country filtering, anti-fraud, country destination alert, change CDR country, change REGISTER country, geographic location, IP geolocation, fraud detection, country whitelist, exclude countries, continent alert, phone prefix, NANPA, international prefix

Key Questions:

What is the difference between GeoIP and Country Prefixes in VoIPmonitor?
How do I filter CDR by country?
How do I set up country-based anti-fraud alerts?
What is the Change CDR Country alert?
How do I detect when a device registers from a different country?
How do I whitelist countries in anti-fraud alerts?
What GeoIP services does VoIPmonitor use?
How do I configure country destination alerts?
Does Country Destination Alert use GeoIP or phone prefixes?
How do I fix incorrect country detection?

@@ Line 1: / Line 1: @@
-= Country grouping =
+{{DISPLAYTITLE:Country Grouping and GeoIP-Based Features}}
+[[Category:Configuration]]
-== Settings ==
+This guide covers country-based features in VoIPmonitor: GeoIP for IP geolocation, phone number prefix detection, anti-fraud alerts, and geographic filtering.
-Country assign is implemented since sniffer 18.2 and GUI 16.11 and it assigns country to SIP source IP / destination IP and to called / caller number included in the first SIP INVITE. For prefix matching you need to set local country in Settings -> common settings:
+== Country Detection Methods ==
-*international prefixes - if calling to international destinations is prefixed with for example "00" put there 00
+VoIPmonitor uses two distinct methods for country detection:
-*min. international length - if you do not use prefix for calling to international destinations you might want to set here 10 which will treat every numbers longer than >= 10 as international number
-*local numbers are in - choose to which country belongs number which does not match international prefix or min. international length
-*trim prefixes - if you are using prefixes to call to special destinations or trunks (like 999 prefix) you should list it there (delimited with space)
-= CDR =
+{| class="wikitable"
+! Method !! Based On !! Use Case !! Configuration
+|-
+| '''GeoIP''' || IP address geolocation || Detect location of endpoints || Settings → System Configuration → GeoIP
+|-
+| '''Country Prefixes''' || Phone number prefix (+1, +44, etc.) || Detect call destinations || Settings → Country Prefixes
+|}
-== Filtering ==
+{{Note|1=GeoIP tells you WHERE a device is located. Country Prefixes tell you WHERE a call is going to (destination number).}}
-You can now filter by country IP addresses or caller/called country prefixes
+== GeoIP Configuration ==
-[[File:country_cdr_filter.png]]
+GeoIP services are configured in '''Settings → System Configuration → GeoIP'''.
-== CDR grid ==
+=== Service Priority ===
-In CDR section you should be able to see country flags in Caller and Called columns next to source and destination IP addresses and next to source / destination numbers.
+VoIPmonitor tries services in order until successful:
-[[File:country_cdr_brief.png]]
+# '''MaxMind API''' — Commercial, highest accuracy (requires API key)
+# '''IPInfoDB API''' — Alternative service (requires API key)
+# '''Local database''' — Bundled with GUI, updated each release
+# '''Free portals''' — Fallback (ipinfodb, freegeoip, maxmind)
-== CDR group panel ==
+{{Tip|1=For the most accurate and up-to-date data, configure a MaxMind API key. API lookups use MaxMind's live database.}}
-There are new grouping options - country by numbers or by ip address (src/dst)
+For database update procedures, see [[Order_of_GeoIP_processing]].
-[[File:country_cdr_group.png]]
+== Country Prefix Configuration ==
-== CDR top calls ==
+Country prefixes are used for '''destination country alerts''' based on called numbers (not IPs).
-In CDR group panel tab -> top calls there are also grouping by country src/dst IP / numbers
+'''Configuration:''' Settings → Country Prefixes
-[[File:Country_cdr_group_topcalls.png]]
+{| class="wikitable"
+! Setting !! Description
+|-
+| Prefix list || Phone number prefixes per country (+1 for US, +44 for UK, etc.)
+|-
+| NANPA support || North American Numbering Plan handling
+|-
+| Strict for prefixes || Require exact prefix match
+|}
-= Dashboard =
+== Country-Based Anti-Fraud Alerts ==
-In dashboard you can create custom CDR grid grouped by country IP/number
+Configure in '''Alerts → Anti Fraud'''. For complete anti-fraud documentation, see [[Anti-fraud]].
-[[File:country_dashboard_customgrid.png]]
+=== Alert Types ===
-= Report =
+{| class="wikitable"
+! Alert !! Detection Method !! Trigger !! Use Case
+|-
+| '''Country/Continent Destination''' || Phone prefix || Calls to specific countries/continents || Block high-fraud destinations
+|-
+| '''Change CDR Country''' || GeoIP || Caller/callee IP country changes || Detect compromised accounts
+|-
+| '''Change REGISTER Country''' || GeoIP || Device registers from different country || Detect SIP credential theft
+|}
-You can create report which will show the same table as in dashboard
+=== Country Destination Alert Configuration ===
-[[File:country_report_form.png]]
+* '''Countries/Continents:''' Select targets (or "ALL")
+* '''Exclude countries:''' Whitelist for legitimate destinations
+* '''Strict for prefixes:''' Require exact prefix match
+* '''Threshold:''' Number of calls or percentage to trigger
-[[File:country_report.png]]
+{{Warning|1=Country Destination Alert uses PHONE NUMBER PREFIXES, not GeoIP. To detect calls based on destination IP country, use CDR filters with GeoIP.}}
+=== Change Country Alerts Configuration ===
+Both "Change CDR Country" and "Change REGISTER Country" alerts detect geographic anomalies:
+* '''Exclude countries:''' Whitelist for expected travel (e.g., border regions)
+* '''Filter by number/IP:''' Apply only to specific users or ranges
+* '''Time window:''' How far back to check for previous location
+== Country Filtering in CDR ==
+When GeoIP is enabled:
+# Go to '''CDR → Filter'''
+# Use country filter fields (Caller Country, Called Country)
+# Select countries from dropdown or enter country codes
+Applications:
+* Traffic analysis by geographic region
+* Compliance reporting
+* International call pattern monitoring
+== Integration with IP Groups ==
+Combine GeoIP features with [[Groups#IP_Groups|IP Groups]] for granular control:
+* Create IP Groups for known provider IPs per country
+* Use Groups in alert filters for precise targeting
+* Combine country alerts with IP-based filtering
+== Troubleshooting ==
+=== GeoIP Data Not Showing ===
+# Verify GeoIP configuration in System Configuration
+# Check network connectivity to voipmonitor.org
+# Try manual database update (see [[Order_of_GeoIP_processing#Manual_Import|manual import]])
+=== Incorrect Country Detection ===
+{{Note|GeoIP accuracy depends on IP allocation databases which may be outdated for some ranges.}}
+'''To correct GeoIP data:'''
+# Submit correction to [https://www.maxmind.com/en/geoip-correction MaxMind Correction Form]
+# Wait for MaxMind database update cycle
+# Contact VoIPmonitor support to include updated data in next GUI release
+# Upgrade GUI to receive corrected database
+'''Faster alternative:''' Configure MaxMind API key for real-time lookups.
+== See Also ==
+* [[Anti-fraud]] — Complete anti-fraud alert configuration
+* [[Order_of_GeoIP_processing]] — GeoIP service priority and manual database updates
+* [[Groups]] — IP Groups and Telephone Number Groups
+* [[Alerts]] — General alert configuration
+=== Important: Country Prefix Rules Tab is for EXCEPTIONS Only ===
+{{Warning|1=The '''Country Prefixes / Rules''' tab in the GUI is for '''exceptions only'''. Do NOT add standard country codes there.}}
+=== Common Mistake ===
+If you add standard country codes (e.g., <code>32</code> for Belgium, <code>44</code> for UK) to the Rules tab, country detection will fail. The Rules tab is only for:
+* Non-standard prefix exceptions
+* Special routing rules
+* Override cases
+=== Correct Configuration ===
+# Use the main '''Country Prefixes''' table for standard country codes (+1, +44, etc.)
+# Leave the '''Rules''' tab empty unless you have specific exceptions
+# Standard codes should be added in the primary prefix list, not in the rules
+=== Symptoms of Misconfiguration ===
+* Country flags do not appear in CDR view
+* Country filter in CDR view shows no results
+* CDR Country column remains empty
+These symptoms occur even when <code>cdr_country_code = yes</code> is set in <code>voipmonitor.conf</code> and database number lookup is enabled.
+== AI Summary for RAG ==
+'''Summary:''' VoIPmonitor uses two country detection methods: GeoIP (IP address geolocation) for detecting WHERE devices are located, and Country Prefixes (phone number prefixes like +1, +44) for detecting WHERE calls are going. GeoIP services follow priority: MaxMind API → IPInfoDB API → local database → free portals. Anti-fraud alerts include Country/Continent Destination (prefix-based, real-time), Change CDR Country (GeoIP, detects caller IP country changes), and Change REGISTER Country (GeoIP, detects registration from different country). Country Destination Alert uses PHONE PREFIXES not GeoIP. CDR filtering supports country-based queries when GeoIP is enabled.
+'''Keywords:''' country grouping, GeoIP, MaxMind, IPInfoDB, country prefixes, country filtering, anti-fraud, country destination alert, change CDR country, change REGISTER country, geographic location, IP geolocation, fraud detection, country whitelist, exclude countries, continent alert, phone prefix, NANPA, international prefix
+'''Key Questions:'''
+* What is the difference between GeoIP and Country Prefixes in VoIPmonitor?
+* How do I filter CDR by country?
+* How do I set up country-based anti-fraud alerts?
+* What is the Change CDR Country alert?
+* How do I detect when a device registers from a different country?
+* How do I whitelist countries in anti-fraud alerts?
+* What GeoIP services does VoIPmonitor use?
+* How do I configure country destination alerts?
+* Does Country Destination Alert use GeoIP or phone prefixes?
+* How do I fix incorrect country detection?