CountryGrouping: Difference between revisions

From VoIPmonitor.org
(Add documentation for country_code and country_code_prefix database tables)
(Add critical note about Country Prefix Rules tab being for exceptions only)
 
(4 intermediate revisions by the same user not shown)
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 features in VoIPmonitor: GeoIP for IP geolocation, phone number prefix detection, anti-fraud alerts, and geographic filtering.


== Understanding Performance Bottlenecks ==
== Country Detection Methods ==
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 two distinct methods for country detection:
@startuml
skinparam shadowing false
skinparam defaultFontName Arial
skinparam rectangle {
  BorderColor #4A90E2
  BackgroundColor #FFFFFF
}
 
title VoIPmonitor Performance Bottlenecks
 
rectangle "Network\nInterface" as NIC #E8F4FD
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"
T0 -right-> PROC
PROC -down-> DISK : "2. I/O\nBottleneck"
PROC -right-> DB : "3. Database\nBottleneck"
 
note bottom of T0
  Monitor: t0CPU in syslog
  Limit: Single CPU core
end note
 
note bottom of DISK
  Monitor: iostat, ioping
  Solution: SSD, TAR archives
end note
 
note bottom of DB
  Monitor: SQLq in syslog
  Solution: Partitioning, tuning
end note
@enduml
</kroki>
 
The three bottlenecks are:
# '''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.
# '''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.
 
== Optimizing Packet Capturing (CPU & Network) ==
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.
 
=== Use a Modern Linux Kernel & VoIPmonitor Build ===
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.
 
'''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.
 
=== Network Stack & Driver Tuning ===
For high-traffic environments (>500 Mbit/s), fine-tuning the network driver and kernel parameters is essential.
 
==== NIC Ring Buffer ====
The ring buffer is a queue between the network card driver and VoIPmonitor. A larger buffer prevents packet loss during short CPU usage spikes.
 
<syntaxhighlight lang="bash">
# Check maximum size
ethtool -g eth0
 
# Set to maximum (e.g., 16384)
ethtool -G eth0 rx 16384
</syntaxhighlight>
 
==== Interrupt Coalescing ====
This setting batches multiple hardware interrupts into one, reducing CPU overhead.
 
<syntaxhighlight lang="bash">
ethtool -C eth0 rx-usecs 1022
</syntaxhighlight>
 
==== Applying Settings Persistently ====
To make these settings permanent, add them to your network configuration. For Debian/Ubuntu using <code>/etc/network/interfaces</code>:
 
<syntaxhighlight lang="ini">
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.
 
==== Configuration-Level Optimizations ====
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 interface_ip_filter Instead of filter
: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">
# More efficient IP-based filtering
interface_ip_filter = 192.168.0.0/24
interface_ip_filter = 10.0.0.0/8
 
# Less efficient BPF filtering (avoid if possible)
# filter = udp and (host 192.168.0.0/24 or host 10.0.0.0/8)
</syntaxhighlight>
 
{{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"
{| class="wikitable"
! Method !! Based On !! Use Case !! Configuration
|-
|-
! Solution !! Type !! CPU Reduction !! Use Case
| '''GeoIP''' || IP address geolocation || Detect location of endpoints || Settings → System Configuration → GeoIP
|-
| '''[[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
| '''Country Prefixes''' || Phone number prefix (+1, +44, etc.) || Detect call destinations || Settings → Country Prefixes
|}
|}


;DPDK (Data Plane Development Kit)
{{Note|1=GeoIP tells you WHERE a device is located. Country Prefixes tell you WHERE a call is going to (destination number).}}
: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">
== GeoIP Configuration ==
# 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
GeoIP services are configured in '''Settings → System Configuration → GeoIP'''.
/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.}}
=== Service Priority ===


=== RAID Controller Cache Policy ===
VoIPmonitor tries services in order until successful:
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:'''
# '''MaxMind API''' — Commercial, highest accuracy (requires API key)
* A healthy Battery Backup Unit (BBU) is required
# '''IPInfoDB API''' — Alternative service (requires API key)
* Specific commands vary by vendor (<code>megacli</code>, <code>ssacli</code>, <code>perccli</code>)
# '''Local database''' — Bundled with GUI, updated each release
* Refer to vendor documentation for LSI, HP, and Dell controllers
# '''Free portals''' — Fallback (ipinfodb, freegeoip, maxmind)


== Optimizing Database Performance (MySQL/MariaDB) ==
{{Tip|1=For the most accurate and up-to-date data, configure a MaxMind API key. API lookups use MaxMind's live database.}}
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.}}
For database update procedures, see [[Order_of_GeoIP_processing]].


=== Memory Configuration ===
== Country Prefix 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.}}
Country prefixes are used for '''destination country alerts''' based on called numbers (not IPs).


==== Buffer Pool Sizing ====
'''Configuration:''' Settings → Country Prefixes


{| class="wikitable"
{| class="wikitable"
! Setting !! Description
|-
|-
! Server Type !! Calculation !! Example (32GB RAM)
| Prefix list || Phone number prefixes per country (+1 for US, +44 for UK, etc.)
|-
|-
| '''Shared''' (VoIPmonitor + MySQL) || (Total RAM - VoIPmonitor - OS overhead) / 2 || 14GB
| NANPA support || North American Numbering Plan handling
|-
|-
| '''Dedicated''' MySQL server || 50-70% of total RAM || 20-22GB
| Strict for prefixes || Require exact prefix match
|}
|}


For shared servers, use this formula:
== Country-Based Anti-Fraud Alerts ==
<syntaxhighlight lang="text">
 
innodb_buffer_pool_size = (Total RAM - VoIPmonitor memory - OS overhead - safety margin) / 2
Configure in '''Alerts → Anti Fraud'''. For complete anti-fraud documentation, see [[Anti-fraud]].


Example for a 32GB server:
=== Alert Types ===
- 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"
{| class="wikitable"
! Alert !! Detection Method !! Trigger !! Use Case
|-
|-
! Deployment Size !! Minimum RAM !! Recommended RAM
| '''Country/Continent Destination''' || Phone prefix || Calls to specific countries/continents || Block high-fraud destinations
|-
| Small (<500 concurrent calls) || 8GB || 16GB
|-
|-
| Medium (500-2000 calls) || 16GB || 32GB
| '''Change CDR Country''' || GeoIP || Caller/callee IP country changes || Detect compromised accounts
|-
|-
| Large (>2000 calls) || 32GB || 64GB+
| '''Change REGISTER Country''' || GeoIP || Device registers from different country || Detect SIP credential theft
|}
|}


==== Disable Graphical Desktop ====
=== Country Destination Alert Configuration ===
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">
* '''Countries/Continents:''' Select targets (or "ALL")
# Disable display manager
* '''Exclude countries:''' Whitelist for legitimate destinations
systemctl stop gdm          # Ubuntu/Debian with GDM
* '''Strict for prefixes:''' Require exact prefix match
systemctl disable gdm
* '''Threshold:''' Number of calls or percentage to trigger


# Set default to multi-user (no GUI)
{{Warning|1=Country Destination Alert uses PHONE NUMBER PREFIXES, not GeoIP. To detect calls based on destination IP country, use CDR filters with GeoIP.}}
systemctl set-default multi-user.target


# Verify memory freed
=== Change Country Alerts Configuration ===
free -h
</syntaxhighlight>


=== Other Key Parameters ===
Both "Change CDR Country" and "Change REGISTER Country" alerts detect geographic anomalies:


<syntaxhighlight lang="ini">
* '''Exclude countries:''' Whitelist for expected travel (e.g., border regions)
# /etc/mysql/my.cnf or /etc/mysql/mariadb.conf.d/50-server.cnf
* '''Filter by number/IP:''' Apply only to specific users or ranges
* '''Time window:''' How far back to check for previous location


[mysqld]
== Country Filtering in CDR ==
# 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)
When GeoIP is enabled:
innodb_flush_log_at_trx_commit = 2


# Store each table in its own file (essential for partitioning)
# Go to '''CDR → Filter'''
innodb_file_per_table = 1
# Use country filter fields (Caller Country, Called Country)
# Select countries from dropdown or enter country codes


# LZ4 compression for modern MariaDB
Applications:
innodb_compression_algorithm = lz4
* Traffic analysis by geographic region
</syntaxhighlight>
* Compliance reporting
* International call pattern monitoring


{{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.}}
== Integration with IP Groups ==


=== Slow Query Log ===
Combine GeoIP features with [[Groups#IP_Groups|IP Groups]] for granular control:


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.
* Create IP Groups for known provider IPs per country
* Use Groups in alert filters for precise targeting
* Combine country alerts with IP-based filtering


{{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.}}
== Troubleshooting ==


<syntaxhighlight lang="ini">
=== GeoIP Data Not Showing ===
# /etc/mysql/my.cnf or /etc/my.cnf.d/mysql-server.cnf


[mysqld]
# Verify GeoIP configuration in System Configuration
# Disable slow query log (set to 1 to enable)
# Check network connectivity to voipmonitor.org
slow_query_log = 0
# Try manual database update (see [[Order_of_GeoIP_processing#Manual_Import|manual import]])


# Alternative: Increase threshold to only log extremely slow queries (e.g., 600 seconds = 10 minutes)
=== Incorrect Country Detection ===
long_query_time = 600
</syntaxhighlight>


After changing MySQL configuration, restart the database and dependent services:
{{Note|GeoIP accuracy depends on IP allocation databases which may be outdated for some ranges.}}


<syntaxhighlight lang="bash">
'''To correct GeoIP data:'''
# Restart MySQL/MariaDB
# Submit correction to [https://www.maxmind.com/en/geoip-correction MaxMind Correction Form]
systemctl restart mariadb  # or mysql
# Wait for MaxMind database update cycle
# Contact VoIPmonitor support to include updated data in next GUI release
# Upgrade GUI to receive corrected database


# Restart VoIPmonitor sniffer (depends on database)
'''Faster alternative:''' Configure MaxMind API key for real-time lookups.
systemctl restart voipmonitor
</syntaxhighlight>


=== Database Partitioning ===
== See Also ==
VoIPmonitor automatically splits large tables (like <code>cdr</code>) into daily partitions. This is enabled by default and '''highly recommended'''.


'''Benefits:'''
* [[Anti-fraud]] — Complete anti-fraud alert configuration
* Massively improves GUI query performance (only relevant partitions are scanned)
* [[Order_of_GeoIP_processing]] — GeoIP service priority and manual database updates
* Allows instant deletion of old data by dropping partitions (thousands of times faster than DELETE)
* [[Groups]] — IP Groups and Telephone Number Groups
* [[Alerts]] — General alert configuration


See [[Data_Cleaning#The_Modern_Method:_Partitioning_.28Recommended.29|Database Partitioning]] for configuration details.
=== Important: Country Prefix Rules Tab is for EXCEPTIONS Only ===


== Monitoring Live Performance ==
{{Warning|1=The '''Country Prefixes / Rules''' tab in the GUI is for '''exceptions only'''. Do NOT add standard country codes there.}}
VoIPmonitor logs detailed performance metrics every 10 seconds to syslog.


<syntaxhighlight lang="bash">
=== Common Mistake ===
# Debian/Ubuntu
tail -f /var/log/syslog | grep voipmonitor


# CentOS/RHEL
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:
tail -f /var/log/messages | grep voipmonitor
* Non-standard prefix exceptions
</syntaxhighlight>
* Special routing rules
* Override cases


=== Understanding the Log Output ===
=== Correct Configuration ===
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"
# Use the main '''Country Prefixes''' table for standard country codes (+1, +44, etc.)
|-
# Leave the '''Rules''' tab empty unless you have specific exceptions
! Metric !! Description !! Warning Threshold
# Standard codes should be added in the primary prefix list, not in the rules
|-
| <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 ===
=== Symptoms of Misconfiguration ===


The following diagrams illustrate the difference between standard kernel packet capture and optimized solutions:
* Country flags do not appear in CDR view
* Country filter in CDR view shows no results
* CDR Country column remains empty


[[File:kernelstandarddiagram.png|thumb|center|600px|Standard kernel packet capture path - packets traverse multiple kernel layers before reaching VoIPmonitor]]
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:ntop.png|thumb|center|600px|PF_RING/DPDK bypass mode - packets are delivered directly to VoIPmonitor, bypassing the kernel network stack]]


== See Also ==
* [[Sniffer_troubleshooting]] - Troubleshooting guide including OOM issues
* [[Data_Cleaning]] - Database and spool retention configuration
* [[Sniffer_configuration]] - Complete configuration reference
* [[DPDK]] - DPDK setup guide
* [[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:''' 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:'''
* How do I scale VoIPmonitor for thousands of concurrent calls?
* What is the difference between GeoIP and Country Prefixes in VoIPmonitor?
* What are the main performance bottlenecks in VoIPmonitor?
* How do I filter CDR by country?
* How do I fix high t0CPU usage?
* How do I set up country-based anti-fraud alerts?
* What is DPDK and when should I use it?
* What is the Change CDR Country alert?
* How do I calculate innodb_buffer_pool_size for a shared server?
* How do I detect when a device registers from a different country?
* What happens if innodb_buffer_pool_size is set too high?
* How do I whitelist countries in anti-fraud alerts?
* How do I interpret the performance metrics in syslog?
* What GeoIP services does VoIPmonitor use?
* Should I use a dedicated database server for VoIPmonitor?
* How do I configure country destination alerts?
* How much RAM does a VoIPmonitor server need?
* Does Country Destination Alert use GeoIP or phone prefixes?
* How can the slow query log affect memory utilization?
* How do I fix incorrect country detection?
* 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?

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"