CountryGrouping: Difference between revisions

From VoIPmonitor.org
(Add documentation for country_code and country_code_prefix database tables)
(Review: replaced duplicate Scaling content with relevant Country Grouping and GeoIP documentation)
Line 1: Line 1:
{{DISPLAYTITLE:Scaling and Performance Tuning}}
{{DISPLAYTITLE:Country Grouping and GeoIP-Based Features}}
Category:Administration
[[Category:Configuration]]


This guide provides a comprehensive overview of performance tuning and scaling for VoIPmonitor. It covers the three primary system bottlenecks and offers practical, expert-level advice for optimizing your deployment for high traffic loads.
This guide covers country-based grouping and GeoIP features in VoIPmonitor, including country filtering, anti-fraud alerts based on geographic location, and country-based CDR analysis.


== Understanding Performance Bottlenecks ==
== Overview ==
A VoIPmonitor deployment's maximum capacity is determined by three potential bottlenecks. Identifying and addressing the correct one is key to achieving high performance.


<kroki lang="plantuml">
VoIPmonitor uses GeoIP databases to determine the geographic location of IP addresses. This enables:
@startuml
* Country-based filtering in CDR views
skinparam shadowing false
* Anti-fraud alerts for destination countries/continents
skinparam defaultFontName Arial
* Detection of country changes for registered devices
skinparam rectangle {
* Geographic analysis and reporting
  BorderColor #4A90E2
  BackgroundColor #FFFFFF
}


title VoIPmonitor Performance Bottlenecks
== GeoIP Configuration ==


rectangle "Network\nInterface" as NIC #E8F4FD
GeoIP services are configured in '''GUI Settings → System Configuration → GeoIP'''.
rectangle "Packet Capture\n(t0 thread)" as T0 #FFE6E6
rectangle "RTP/SIP\nProcessing" as PROC #E6FFE6
rectangle "PCAP Files\nStorage" as DISK #FFF3E6
database "MySQL/MariaDB\nDatabase" as DB #E6E6FF


NIC -right-> T0 : "1. CPU\nBottleneck"
=== Service Priority ===
T0 -right-> PROC
VoIPmonitor uses GeoIP services in the following order:
PROC -down-> DISK : "2. I/O\nBottleneck"
# '''MaxMind API''' (if API key is configured)
PROC -right-> DB : "3. Database\nBottleneck"
# '''IPInfoDB API''' (if API key is configured and MaxMind not available)
# '''Local database''' (updated with each GUI release)
# '''Free demo portals''' (fallback: ipinfodb, freegeoip, maxmind)


note bottom of T0
For detailed GeoIP configuration, see [[Order_of_GeoIP_processing]].
  Monitor: t0CPU in syslog
  Limit: Single CPU core
end note


note bottom of DISK
== Country-Based Anti-Fraud Alerts ==
  Monitor: iostat, ioping
  Solution: SSD, TAR archives
end note


note bottom of DB
VoIPmonitor provides several anti-fraud alerts that use country detection. These are configured in '''GUI → Alerts → Anti Fraud'''.
  Monitor: SQLq in syslog
  Solution: Partitioning, tuning
end note
@enduml
</kroki>


The three bottlenecks are:
=== Country/Continent Destination Alert (Realtime) ===
# '''Packet Capturing (CPU & Network Stack):''' The ability of a single CPU core to read packets from the network interface. This is often the first limit encountered.
Triggers when calls are made to specific countries or continents.
# '''Disk I/O (Storage):''' The speed at which the sensor can write PCAP files to disk. Critical when call recording is enabled.
# '''Database Performance (MySQL/MariaDB):''' The rate at which the database can ingest CDRs and serve data to the GUI.


On a modern, well-tuned server (e.g., 24-core Xeon, 10Gbit NIC), a single VoIPmonitor instance can handle up to '''10,000 concurrent calls''' with full RTP analysis and recording, or over '''60,000 concurrent calls''' with SIP-only analysis.
'''Use cases:'''
* Block or alert on calls to high-fraud destinations
* Monitor international call patterns
* Enforce geographic calling restrictions


== Optimizing Packet Capturing (CPU & Network) ==
'''Configuration:'''
The most performance-critical task is the initial packet capture, handled by a single, highly optimized thread (t0). If this thread's CPU usage (<code>t0CPU</code> in logs) approaches 100%, you are hitting the capture limit.
* Select target countries or continents
* Set threshold (number of calls or percentage)
* Configure notification (email, script)


=== Use a Modern Linux Kernel & VoIPmonitor Build ===
=== Change CDR Country Alert (CDR-based) ===
Modern Linux kernels (3.2+) and VoIPmonitor builds include '''TPACKET_V3''' support, a high-speed packet capture mechanism. This is the single most important factor for high performance.
Detects when the IP address of a caller or callee changes to a different country between calls.


'''Recommendation:''' Always use a recent Linux distribution (AlmaLinux, Rocky Linux, or Debian) and the latest VoIPmonitor static binary. With this combination, a standard Intel 10Gbit NIC can often handle up to 2 Gbit/s of VoIP traffic without special drivers.
'''Use cases:'''
* Detect compromised accounts being used from different locations
* Identify VPN/proxy usage
* Monitor for credential theft


=== Network Stack & Driver Tuning ===
'''Configuration:'''
For high-traffic environments (>500 Mbit/s), fine-tuning the network driver and kernel parameters is essential.
* '''Exclude countries:''' Whitelist of allowed countries (e.g., if users legitimately travel between certain countries)
* Filter by specific numbers or IP ranges


==== NIC Ring Buffer ====
=== Change REGISTER Country Alert (CDR-based) ===
The ring buffer is a queue between the network card driver and VoIPmonitor. A larger buffer prevents packet loss during short CPU usage spikes.
Detects when a device's registration IP address changes to a different country.


<syntaxhighlight lang="bash">
'''Use cases:'''
# Check maximum size
* Detect SIP account takeover
ethtool -g eth0
* Monitor device mobility
* Identify suspicious registration patterns


# Set to maximum (e.g., 16384)
== Country Filtering in CDR ==
ethtool -G eth0 rx 16384
</syntaxhighlight>


==== Interrupt Coalescing ====
When GeoIP is enabled, you can filter CDR records by country in the GUI:
This setting batches multiple hardware interrupts into one, reducing CPU overhead.


<syntaxhighlight lang="bash">
# Go to '''CDR → Filter'''
ethtool -C eth0 rx-usecs 1022
# Use the country filter fields in the filter form
</syntaxhighlight>
# Select specific countries from the dropdown


==== Applying Settings Persistently ====
This allows you to:
To make these settings permanent, add them to your network configuration. For Debian/Ubuntu using <code>/etc/network/interfaces</code>:
* View all calls to/from a specific country
* Analyze traffic patterns by geographic region
* Generate country-specific reports


<syntaxhighlight lang="ini">
== Integration with IP Groups ==
auto eth0
iface eth0 inet manual
    up ip link set $IFACE up
    up ip link set $IFACE promisc on
    up ethtool -G $IFACE rx 16384
    up ethtool -C $IFACE rx-usecs 1022
</syntaxhighlight>


Note: Modern systems using NetworkManager or systemd-networkd require different configuration methods.
For more granular control, combine GeoIP features with [[Groups#IP_Groups|IP Groups]]:


==== Configuration-Level Optimizations ====
* Create IP Groups for known provider IPs per country
Before investing in kernel-bypass solutions, ensure your <code>voipmonitor.conf</code> is optimized for performance. Several configuration parameters can significantly reduce CPU load and improve packet capture efficiency.
* Use Groups in alert filters for precise targeting
* Combine country-based alerts with IP-based filtering


;Use interface_ip_filter Instead of filter
== Troubleshooting ==
:If you need to filter by IP address or subnet, use <code>interface_ip_filter</code> instead of the general BPF <code>filter</code> option. The <code>interface_ip_filter</code> directive is more efficient and reduces CPU overhead compared to complex BPF filters.


<syntaxhighlight lang="ini">
=== GeoIP Data Not Showing ===
# More efficient IP-based filtering
* Check GeoIP configuration in System Configuration
interface_ip_filter = 192.168.0.0/24
* Verify GUI can reach voipmonitor.org for database updates
interface_ip_filter = 10.0.0.0/8
* See [[Order_of_GeoIP_processing#Manually_Updating_the_Local_GeoIP_Database|manual GeoIP database update]]


# Less efficient BPF filtering (avoid if possible)
=== Incorrect Country Detection ===
# filter = udp and (host 192.168.0.0/24 or host 10.0.0.0/8)
* GeoIP databases are not 100% accurate
</syntaxhighlight>
* Submit corrections to MaxMind: [https://www.maxmind.com/en/geoip-correction MaxMind Correction Form]
 
* After MaxMind updates, notify VoIPmonitor support for GUI release with updated data
{{Note|See [[Sniffer_configuration]] for the complete reference and description of <code>interface_ip_filter</code> (Interface Selection section).}}
 
;Optimize PCAP Compression Threads
:For systems with high call recording rates, PCAP compression can become CPU-intensive. VoIPmonitor can automatically scale compression threads.
 
<syntaxhighlight lang="ini">
# /etc/voipmonitor.conf
# Initial compression threads (auto-scales based on load)
pcap_dump_writethreads = 1
 
# Maximum compression threads (adjust based on CPU cores)
pcap_dump_writethreads_max = 32
 
# Asynchronous PCAP writing (enabled by default)
pcap_dump_asyncwrite = yes
</syntaxhighlight>
 
{{Tip|Set <code>pcap_dump_writethreads_max</code> to the number of CPU cores available for best performance on multi-core systems. Monitor <code>t0CPU</code> to ensure compression threads are not competing with the capture thread.}}
 
;Adjust Jitterbuffer Settings Based on Traffic Patterns
:Jitterbuffer simulation adds CPU overhead. For production environments with stable networks, consider adjusting jitterbuffer settings to balance accuracy with performance.
 
<syntaxhighlight lang="ini">
# /etc/voipmonitor.conf
# Fixed 50ms jitterbuffer (default: yes)
jitterbuffer_f1 = yes
 
# Fixed 200ms jitterbuffer (default: yes)
jitterbuffer_f2 = yes
 
# Adaptive jitterbuffer up to 500ms (default: yes)
jitterbuffer_adapt = yes
</syntaxhighlight>
 
{{Warning|Disabling jitterbuffer analysis reduces CPU load but removes MOS and jitter quality metrics from CDRs. Only disable if you do not require voice quality monitoring.}}
 
=== Advanced Kernel-Bypass Solutions ===
If kernel and driver tuning are insufficient, you can offload the capture process entirely by bypassing the kernel's network stack.
 
{| class="wikitable"
|-
! Solution !! Type !! CPU Reduction !! Use Case
|-
| '''[[DPDK]]''' || Open-source || ~70% || Multi-gigabit on commodity hardware
|-
| '''PF_RING ZC/DNA''' || Commercial || 90% → 20% || High-volume enterprise
|-
| '''Napatech SmartNICs''' || Hardware || <3% at 10 Gbit/s || Extreme performance requirements
|}
 
;DPDK (Data Plane Development Kit)
:A set of libraries and drivers for fast packet processing. VoIPmonitor can leverage DPDK to read packets directly from the network card, completely bypassing the kernel. See [[DPDK|DPDK guide]] for details.
 
;PF_RING ZC/DNA
:A commercial software driver from ntop.org that dramatically reduces CPU load by bypassing the kernel.
 
;Napatech SmartNICs
:Specialized hardware acceleration cards that deliver packets with near-zero CPU overhead.
 
== Optimizing Disk I/O ==
VoIPmonitor's modern storage engine is highly optimized to minimize random disk access, which is the primary cause of I/O bottlenecks.
 
=== VoIPmonitor Storage Strategy ===
Instead of writing a separate PCAP file for each call (which causes massive I/O load), VoIPmonitor groups all calls starting within the same minute into a single compressed <code>.tar</code> archive. This changes the I/O pattern from thousands of small, random writes to a few large, sequential writes, reducing IOPS by a factor of 10 or more.
 
'''Typical capacity:''' A standard 7200 RPM SATA drive can handle up to 2,000 concurrent calls with full recording.
 
=== Filesystem Tuning (ext4) ===
For the spool directory (<code>/var/spool/voipmonitor</code>), using an optimized ext4 filesystem can improve performance.
 
<syntaxhighlight lang="bash">
# Format partition without a journal (use with caution, requires battery-backed RAID controller)
mke2fs -t ext4 -O ^has_journal /dev/sda2
 
# Add to /etc/fstab for optimal performance
/dev/sda2  /var/spool/voipmonitor  ext4    errors=remount-ro,noatime,data=writeback,barrier=0 0 0
</syntaxhighlight>
 
{{Warning|Disabling the journal removes protection against filesystem corruption after crashes. Only use this with a battery-backed RAID controller.}}
 
=== RAID Controller Cache Policy ===
A misconfigured RAID controller is a common bottleneck. For database and spool workloads, the cache policy should be set to '''WriteBack''', not WriteThrough. This applies for RPM disks, not fast SSDs.
 
'''Requirements:'''
* A healthy Battery Backup Unit (BBU) is required
* Specific commands vary by vendor (<code>megacli</code>, <code>ssacli</code>, <code>perccli</code>)
* Refer to vendor documentation for LSI, HP, and Dell controllers
 
== Optimizing Database Performance (MySQL/MariaDB) ==
A well-tuned database is critical for both data ingestion from the sensor and GUI responsiveness.
 
{{Note|For extreme scenarios (4,000+ concurrent calls, UI lag, high SQL queue, or 1000+ CDRs/sec), see [[High-Performance_VoIPmonitor_and_MySQL_Setup_Manual]] for specialized configurations including innodb_flush_log_at_trx_commit=0, hourly partitioning, and centralized writer architecture.}}
 
=== Memory Configuration ===
The most critical database parameter is <code>innodb_buffer_pool_size</code>, which defines how much memory InnoDB uses to cache data and indexes.
 
{{Warning|On servers running both VoIPmonitor and MySQL, setting <code>innodb_buffer_pool_size</code> too high causes OOM (Out of Memory) killer events, resulting in CDR delays, crashes, and instability. See [[Sniffer_troubleshooting#Check_for_OOM_.28Out_of_Memory.29_Issues|OOM Troubleshooting]] for details.}}
 
==== Buffer Pool Sizing ====
 
{| class="wikitable"
|-
! Server Type !! Calculation !! Example (32GB RAM)
|-
| '''Shared''' (VoIPmonitor + MySQL) || (Total RAM - VoIPmonitor - OS overhead) / 2 || 14GB
|-
| '''Dedicated''' MySQL server || 50-70% of total RAM || 20-22GB
|}
 
For shared servers, use this formula:
<syntaxhighlight lang="text">
innodb_buffer_pool_size = (Total RAM - VoIPmonitor memory - OS overhead - safety margin) / 2
 
Example for a 32GB server:
- Total RAM: 32GB
- VoIPmonitor process memory: ~2GB (check with ps aux)
- OS + other services overhead: ~2GB
- Available for buffer pool: 28GB
- Recommended innodb_buffer_pool_size = 14G
</syntaxhighlight>
 
==== RAM Recommendations ====
{| class="wikitable"
|-
! Deployment Size !! Minimum RAM !! Recommended RAM
|-
| Small (<500 concurrent calls) || 8GB || 16GB
|-
| Medium (500-2000 calls) || 16GB || 32GB
|-
| Large (>2000 calls) || 32GB || 64GB+
|}
 
==== Disable Graphical Desktop ====
A graphical desktop environment consumes 1-2GB of RAM unnecessarily. VoIPmonitor is managed through a web interface and does not require a desktop.
 
<syntaxhighlight lang="bash">
# Disable display manager
systemctl stop gdm          # Ubuntu/Debian with GDM
systemctl disable gdm
 
# Set default to multi-user (no GUI)
systemctl set-default multi-user.target
 
# Verify memory freed
free -h
</syntaxhighlight>
 
=== Other Key Parameters ===
 
<syntaxhighlight lang="ini">
# /etc/mysql/my.cnf or /etc/mysql/mariadb.conf.d/50-server.cnf
 
[mysqld]
# Buffer pool size (calculate per above)
innodb_buffer_pool_size = 14G
 
# Flush logs to OS cache, write to disk once per second (faster, minimal data loss risk)
innodb_flush_log_at_trx_commit = 2
 
# Store each table in its own file (essential for partitioning)
innodb_file_per_table = 1
 
# LZ4 compression for modern MariaDB
innodb_compression_algorithm = lz4
</syntaxhighlight>
 
{{Warning|For deployments with 4,000+ concurrent calls experiencing UI unresponsiveness, database queue growth (SQLq), or extremely high CDR insertion rates (1000+ CDRs/sec), the intermediate settings above may not be sufficient. See [[High-Performance_VoIPmonitor_and_MySQL_Setup_Manual]] for extreme performance configurations optimized for 10,000+ concurrent calls, including innodb_flush_log_at_trx_commit=0, hourly partitioning, and centralized writer architecture.}}
 
=== Slow Query Log ===
 
The MySQL slow query log can consume significant memory and disk I/O on high-traffic systems. If you are experiencing high memory utilization alerts or performance issues with the database server, consider adjusting or disabling the slow query log.
 
{{Warning|Disabling the slow query log removes the ability to analyze slow queries for performance optimization. Only disable it temporarily or if you are certain you do not need it.}}
 
<syntaxhighlight lang="ini">
# /etc/mysql/my.cnf or /etc/my.cnf.d/mysql-server.cnf
 
[mysqld]
# Disable slow query log (set to 1 to enable)
slow_query_log = 0
 
# Alternative: Increase threshold to only log extremely slow queries (e.g., 600 seconds = 10 minutes)
long_query_time = 600
</syntaxhighlight>
 
After changing MySQL configuration, restart the database and dependent services:
 
<syntaxhighlight lang="bash">
# Restart MySQL/MariaDB
systemctl restart mariadb  # or mysql
 
# Restart VoIPmonitor sniffer (depends on database)
systemctl restart voipmonitor
</syntaxhighlight>
 
=== Database Partitioning ===
VoIPmonitor automatically splits large tables (like <code>cdr</code>) into daily partitions. This is enabled by default and '''highly recommended'''.
 
'''Benefits:'''
* Massively improves GUI query performance (only relevant partitions are scanned)
* Allows instant deletion of old data by dropping partitions (thousands of times faster than DELETE)
 
See [[Data_Cleaning#The_Modern_Method:_Partitioning_.28Recommended.29|Database Partitioning]] for configuration details.
 
== Monitoring Live Performance ==
VoIPmonitor logs detailed performance metrics every 10 seconds to syslog.
 
<syntaxhighlight lang="bash">
# Debian/Ubuntu
tail -f /var/log/syslog | grep voipmonitor
 
# CentOS/RHEL
tail -f /var/log/messages | grep voipmonitor
</syntaxhighlight>
 
=== Understanding the Log Output ===
Sample log line:
<syntaxhighlight lang="text">
voipmonitor[15567]: calls[315][355] PS[C:4 S:29/29 R:6354 A:6484] SQLq[0] heap[0|0|0] comp[54] [12.6Mb/s] t0CPU[5.2%] ... RSS/VSZ[323|752]MB
</syntaxhighlight>
 
{| class="wikitable"
|-
! Metric !! Description !! Warning Threshold
|-
| <code>calls[X][Y]</code> || X = active calls, Y = total calls in memory || -
|-
| <code>SQLq[C]</code> || SQL queries waiting to be sent to database || Growing consistently = DB bottleneck
|-
| <code>heap[A{{!}}B{{!}}C]</code> || Memory usage % for internal buffers || A = 100% → packet drops
|-
| <code>t0CPU[X%]</code> || '''Main packet capture thread CPU usage''' || >90-95% = capture limit reached
|-
| <code>RSS/VSZ[X{{!}}Y]MB</code> || Resident/Virtual memory usage || RSS growing = memory leak
|}
 
=== Performance Diagrams ===
 
The following diagrams illustrate the difference between standard kernel packet capture and optimized solutions:
 
[[File:kernelstandarddiagram.png|thumb|center|600px|Standard kernel packet capture path - packets traverse multiple kernel layers before reaching VoIPmonitor]]
 
[[File:ntop.png|thumb|center|600px|PF_RING/DPDK bypass mode - packets are delivered directly to VoIPmonitor, bypassing the kernel network stack]]


== See Also ==
== See Also ==
* [[Sniffer_troubleshooting]] - Troubleshooting guide including OOM issues
* [[Anti-fraud]] - Complete anti-fraud alert configuration
* [[Data_Cleaning]] - Database and spool retention configuration
* [[Order_of_GeoIP_processing]] - GeoIP service priority and manual updates
* [[Sniffer_configuration]] - Complete configuration reference
* [[Groups]] - IP Groups and Telephone Number Groups
* [[DPDK]] - DPDK setup guide
* [[Alerts]] - General alert configuration
* [[IO_Measurement]] - Disk I/O benchmarking tools


== AI Summary for RAG ==
== AI Summary for RAG ==
'''Summary:''' Expert guide to scaling VoIPmonitor for high-traffic environments. Covers three main bottlenecks: (1) Packet Capturing - optimized via TPACKET_V3, NIC tuning with ethtool (ring buffer, interrupt coalescing), configuration-level optimizations (interface_ip_filter more efficient than BPF filter, pcap_dump_writethreads for compression thread tuning, jitterbuffer settings for CPU/performance balance), and kernel-bypass solutions (DPDK, PF_RING, Napatech); (2) Disk I/O - VoIPmonitor uses TAR-based storage to reduce IOPS, with ext4 tuning and RAID WriteBack cache; (3) Database - critical innodb_buffer_pool_size tuning with formula for shared servers: (Total RAM - VoIPmonitor - OS overhead) / 2. For 32GB shared server, recommend 14GB buffer pool. Dedicated servers can use 50-70% of RAM. Covers slow query log as a memory/I/O consumer and disabling it for memory optimization. Covers partitioning benefits and syslog monitoring (t0CPU, SQLq, heap metrics). For extreme scenarios (4,000+ concurrent calls, UI lag, unresponsive GUI, high SQL queue), see High-Performance_VoIPmonitor_and_MySQL_Setup_Manual for specialized configurations including innodb_flush_log_at_trx_commit=0, hourly partitioning, centralized writer architecture, RTP thread tuning (rtpthreads, rtpthreads_start), and MySQL optimization settings (innodb_thread_concurrency, innodb_io_capacity, innodb_flush_method=O_DIRECT).


'''Keywords:''' scaling, performance tuning, bottleneck, t0CPU, TPACKET_V3, DPDK, PF_RING, ethtool, ring buffer, interface_ip_filter, BPF filter, pcap_dump_writethreads, jitterbuffer, jitterbuffer_f1, jitterbuffer_f2, jitterbuffer_adapt, compression threads, PCAP async write, innodb_buffer_pool_size, OOM killer, shared server memory, database partitioning, SQLq monitoring, slow query log, slow_query_log, long_query_time, UI lag, unresponsive GUI, high performance, 4000 concurrent calls, 5000 concurrent calls, innodb_flush_log_at_trx_commit=0, hourly partitioning, rtpthreads, rtpthreads_start, RTP threads, innodb_io_capacity, innodb_thread_concurrency, innodb_flush_method, extreme performance, High-Performance Manual
'''Summary:''' Guide to country grouping and GeoIP-based features in VoIPmonitor. Covers GeoIP service configuration (MaxMind, IPInfoDB, local database fallback), country-based anti-fraud alerts (Country/Continent Destination for real-time detection of calls to high-fraud destinations, Change CDR Country for detecting caller IP country changes between calls, Change REGISTER Country for detecting device registration from different countries), country filtering in CDR views, and integration with IP Groups. GeoIP enables geographic analysis, fraud detection, and compliance with calling restrictions.
 
'''Keywords:''' country grouping, GeoIP, MaxMind, IPInfoDB, 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


'''Key Questions:'''
'''Key Questions:'''
* How do I scale VoIPmonitor for thousands of concurrent calls?
* How do I filter CDR by country in VoIPmonitor?
* What are the main performance bottlenecks in VoIPmonitor?
* How do I set up country-based anti-fraud alerts?
* How do I fix high t0CPU usage?
* What is the Change CDR Country alert?
* What is DPDK and when should I use it?
* How do I detect when a device registers from a different country?
* How do I calculate innodb_buffer_pool_size for a shared server?
* How do I whitelist countries in anti-fraud alerts?
* What happens if innodb_buffer_pool_size is set too high?
* What GeoIP services does VoIPmonitor use?
* How do I interpret the performance metrics in syslog?
* How do I configure country destination alerts?
* Should I use a dedicated database server for VoIPmonitor?
* Can I combine country alerts with IP Groups?
* How much RAM does a VoIPmonitor server need?
* How do I troubleshoot incorrect country detection?
* How can the slow query log affect memory utilization?
* How do I disable or adjust the MySQL slow query log?
* Is interface_ip_filter more efficient than the filter option?
* How do I optimize PCAP compression threads for high traffic?
* Which jitterbuffer settings affect CPU load the most?
* What configuration options reduce CPU overhead?

Revision as of 11:24, 6 January 2026


This guide covers country-based grouping and GeoIP features in VoIPmonitor, including country filtering, anti-fraud alerts based on geographic location, and country-based CDR analysis.

Overview

VoIPmonitor uses GeoIP databases to determine the geographic location of IP addresses. This enables:

  • Country-based filtering in CDR views
  • Anti-fraud alerts for destination countries/continents
  • Detection of country changes for registered devices
  • Geographic analysis and reporting

GeoIP Configuration

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

Service Priority

VoIPmonitor uses GeoIP services in the following order:

  1. MaxMind API (if API key is configured)
  2. IPInfoDB API (if API key is configured and MaxMind not available)
  3. Local database (updated with each GUI release)
  4. Free demo portals (fallback: ipinfodb, freegeoip, maxmind)

For detailed GeoIP configuration, see Order_of_GeoIP_processing.

Country-Based Anti-Fraud Alerts

VoIPmonitor provides several anti-fraud alerts that use country detection. These are configured in GUI → Alerts → Anti Fraud.

Country/Continent Destination Alert (Realtime)

Triggers when calls are made to specific countries or continents.

Use cases:

  • Block or alert on calls to high-fraud destinations
  • Monitor international call patterns
  • Enforce geographic calling restrictions

Configuration:

  • Select target countries or continents
  • Set threshold (number of calls or percentage)
  • Configure notification (email, script)

Change CDR Country Alert (CDR-based)

Detects when the IP address of a caller or callee changes to a different country between calls.

Use cases:

  • Detect compromised accounts being used from different locations
  • Identify VPN/proxy usage
  • Monitor for credential theft

Configuration:

  • Exclude countries: Whitelist of allowed countries (e.g., if users legitimately travel between certain countries)
  • Filter by specific numbers or IP ranges

Change REGISTER Country Alert (CDR-based)

Detects when a device's registration IP address changes to a different country.

Use cases:

  • Detect SIP account takeover
  • Monitor device mobility
  • Identify suspicious registration patterns

Country Filtering in CDR

When GeoIP is enabled, you can filter CDR records by country in the GUI:

  1. Go to CDR → Filter
  2. Use the country filter fields in the filter form
  3. Select specific countries from the dropdown

This allows you to:

  • View all calls to/from a specific country
  • Analyze traffic patterns by geographic region
  • Generate country-specific reports

Integration with IP Groups

For more granular control, combine GeoIP features with IP Groups:

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

Troubleshooting

GeoIP Data Not Showing

  • Check GeoIP configuration in System Configuration
  • Verify GUI can reach voipmonitor.org for database updates
  • See manual GeoIP database update

Incorrect Country Detection

  • GeoIP databases are not 100% accurate
  • Submit corrections to MaxMind: MaxMind Correction Form
  • After MaxMind updates, notify VoIPmonitor support for GUI release with updated data

See Also

AI Summary for RAG

Summary: Guide to country grouping and GeoIP-based features in VoIPmonitor. Covers GeoIP service configuration (MaxMind, IPInfoDB, local database fallback), country-based anti-fraud alerts (Country/Continent Destination for real-time detection of calls to high-fraud destinations, Change CDR Country for detecting caller IP country changes between calls, Change REGISTER Country for detecting device registration from different countries), country filtering in CDR views, and integration with IP Groups. GeoIP enables geographic analysis, fraud detection, and compliance with calling restrictions.

Keywords: country grouping, GeoIP, MaxMind, IPInfoDB, 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

Key Questions:

  • How do I filter CDR by country in VoIPmonitor?
  • 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?
  • Can I combine country alerts with IP Groups?
  • How do I troubleshoot incorrect country detection?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=CountryGrouping&oldid=8758"