CountryGrouping: Difference between revisions

From VoIPmonitor.org
(Add critical cdr_country_code parameter documentation and troubleshooting section)
(Add critical note about Country Prefix Rules tab being for exceptions only)
 
(6 intermediate revisions by the same user not shown)
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.
== Country Detection Methods ==


=== Required Sniffer Configuration ===
VoIPmonitor uses two distinct methods for country detection:


For country flags to appear in the CDR view, you must enable country code processing on each sniffer sensor. Edit the sniffer configuration file (typically <code>/etc/voipmonitor.conf</code>)
{| 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
|}


<pre>
{{Note|1=GeoIP tells you WHERE a device is located. Country Prefixes tell you WHERE a call is going to (destination number).}}
cdr_country_code = yes
</pre>


If this is set to <code>no</code> or commented out, country flags will not appear in the CDR view even if database number lookup is enabled and country prefixes are configured. After changing this setting, restart the sniffer service on the sensor for the changes to take effect.
== GeoIP Configuration ==


=== GUI Configuration ===
GeoIP services are configured in '''Settings → System Configuration → GeoIP'''.


For prefix matching, you need to set local country in Settings -> common settings:
=== Service Priority ===


*international prefixes - if calling to international destinations is prefixed with for example "00" put there 00
VoIPmonitor tries services in order until successful:
*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)


=== Troubleshooting ===
# '''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)


If country flags are not appearing in the CDR view:
{{Tip|1=For the most accurate and up-to-date data, configure a MaxMind API key. API lookups use MaxMind's live database.}}


# Verify <code>cdr_country_code = yes</code> is set in <code>/etc/voipmonitor.conf</code> on each sensor
For database update procedures, see [[Order_of_GeoIP_processing]].
# Restart the sniffer service after changing the configuration
# Check that "database number lookup" is enabled in Settings -> System Configuration
# Verify country prefixes are configured correctly in the GUI
# Make sure new calls are processed after the setting change (older CDRs will not show flags retroactively)


= CDR =
== Country Prefix Configuration ==


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


You can now filter by country IP addresses or caller/called country prefixes
'''Configuration:''' Settings → Country Prefixes


[[File:country_cdr_filter.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
|}


== CDR grid ==
== Country-Based Anti-Fraud Alerts ==


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.  
Configure in '''Alerts → Anti Fraud'''. For complete anti-fraud documentation, see [[Anti-fraud]].


[[File:country_cdr_brief.png]]
=== Alert Types ===


== CDR group panel ==
{| 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
|}


There are new grouping options - country by numbers or by ip address (src/dst)
=== Country Destination Alert Configuration ===


[[File:country_cdr_group.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


== CDR top calls ==
{{Warning|1=Country Destination Alert uses PHONE NUMBER PREFIXES, not GeoIP. To detect calls based on destination IP country, use CDR filters with GeoIP.}}


In CDR group panel tab -> top calls there are also grouping by country src/dst IP / numbers
=== Change Country Alerts Configuration ===


[[File:Country_cdr_group_topcalls.png]]
Both "Change CDR Country" and "Change REGISTER Country" alerts detect geographic anomalies:


= Dashboard =
* '''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


In dashboard you can create custom CDR grid grouped by country IP/number
== Country Filtering in CDR ==


[[File:country_dashboard_customgrid.png]]
When GeoIP is enabled:


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


You can create report which will show the same table as in dashboard
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.


[[File:country_report_form.png]]


[[File:country_report.png]]


== AI Summary for RAG ==
== AI Summary for RAG ==
'''Summary:''' Country grouping assigns country codes to SIP source/destination IP addresses and to called/caller numbers based on international prefixes. This feature requires both sniffer configuration and GUI setup. The most critical requirement is setting <code>cdr_country_code = yes</code> in /etc/voipmonitor.conf on each sensor - without this setting, country flags will NOT appear in the CDR view even if all other settings are configured. Additionally, enable "database number lookup" in the GUI, and configure the number classification rules: international prefixes (e.g., "00" or "+"), minimum international length (for numbers without prefixes), local country assignment for unmatched numbers, and trim prefixes to remove trunk codes (e.g., stripping leading "0"). The Troubleshooting checklist provides step-by-step guidance when flags do not appear in the CDR view.


'''Keywords:''' country grouping, country flags, CDR view, cdr_country_code, international prefixes, local country, trim prefixes, database number lookup, country filtering, number classification, voipmonitor.conf, sniffer configuration
'''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:'''
'''Key Questions:'''
* Why are country flags not appearing in the CDR view?
* What is the difference between GeoIP and Country Prefixes in VoIPmonitor?
* How do I enable country flags in VoIPmonitor?
* How do I filter CDR by country?
* What is the cdr_country_code setting?
* How do I set up country-based anti-fraud alerts?
* How do I configure international prefixes and local country?
* What is the Change CDR Country alert?
* What is the difference between international prefixes and local country?
* How do I detect when a device registers from a different country?
* How do I filter CDRs by country?
* How do I whitelist countries in anti-fraud alerts?
* How do I enable country grouping for SIP IP addresses?
* What GeoIP services does VoIPmonitor use?
* How do I configure country classification for phone numbers?
* How do I configure country destination alerts?
* Does Country Destination Alert use GeoIP or phone prefixes?
* How do I fix incorrect country detection?

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:

  1. MaxMind API — Commercial, highest accuracy (requires API key)
  2. IPInfoDB API — Alternative service (requires API key)
  3. Local database — Bundled with GUI, updated each release
  4. 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:

  1. Go to CDR → Filter
  2. Use country filter fields (Caller Country, Called Country)
  3. 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

  1. Verify GeoIP configuration in System Configuration
  2. Check network connectivity to voipmonitor.org
  3. 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:

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

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

See Also

Important: Country Prefix Rules Tab is for EXCEPTIONS Only

⚠️ Warning: 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., 32 for Belgium, 44 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

  1. Use the main Country Prefixes table for standard country codes (+1, +44, etc.)
  2. Leave the Rules tab empty unless you have specific exceptions
  3. 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 cdr_country_code = yes is set in voipmonitor.conf 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?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=CountryGrouping&oldid=10639"