How to enable ipv6 processing: Difference between revisions

Latest revision as of 18:00, 6 January 2026

This guide explains how to enable IPv6 support in VoIPmonitor, covering both new installations and existing IPv4-formatted databases.

Quick Start for New Installations

For a fresh VoIPmonitor installation, simply enable IPv6 before starting the service for the first time:

ipv6 = yes

Add this to your /etc/voipmonitor.conf file. The database will be created with IPv6 columns from the beginning.

Enabling IPv6 on Existing Installations

If you have an existing VoIPmonitor installation that was set up with only IPv4 addresses, enabling IPv6 requires a database schema migration. The correct order is critical: first prepare the database schema, then configure the sensors.

Step 1: Run Migration Script on Database/GUI Server

The migration script ipv6_alter.sql must be run only on the database/GUI server to add the necessary IPv6 columns to your database tables. This step prepares the database schema before sensors start writing IPv6 data.

⚠️ Warning: Backup your database before running any schema migration!

Location: Typically found in the scripts directory of your VoIPmonitor installation, such as /usr/share/voipmonitor/scripts/ or /var/www/html/scripts/.

# On the database/GUI server only:
mysql -u root -p voipmonitor < /path/to/scripts/ipv6_alter.sql

Step 2: Enable IPv6 in Configuration on Each Sensor

After the database schema is prepared, configure each sensor to write IPv6 data.

Edit /etc/voipmonitor.conf on each sensor:

ipv6 = yes

Step 3: Restart the Service on Each Sensor

systemctl restart voipmonitor

Verification

After the service restarts, VoIPmonitor will begin logging IPv6 addresses for calls involving IPv6 endpoints. You can verify this by checking the CDR view for calls with IPv6 addresses.

Troubleshooting: Hostname Lookup Issues After Migration

B-side IP Addresses Not Resolving to Hostnames

After running the IPv6 migration script, you may find that B-side (Destination/Called party) IP addresses fail to resolve to hostnames in the GUI, while A-side (Source/Caller) hostnames display correctly.

If you run the ipv6_alter.sql migration script before saving the hostname table with IPv6-compatible data, the hostname table may contain IP addresses stored in the old integer format. This causes lookups to fail for B-side addresses.

ℹ️ Note: Symptom: In the GUI CDR view, Called party IP addresses show only the IP address without hostname, while Caller party IP addresses display the hostname correctly.

To fix this issue, run the following SQL command on the VoIPMonitor database to correct the data format:

update hostname set ip=INET6_ATON(inet_ntoa(ip));

This command converts the IP addresses in the hostname table from integer format to binary format compatible with IPv6 column types.

After running the command, refresh the GUI CDR view to verify that B-side hostnames now resolve correctly.

Troubleshooting: IPv6 Traffic Not Being Captured

If you have enabled IPv6 and run the migration script, but VoIPmonitor is still not capturing IPv6 traffic, follow this troubleshooting checklist.

Verify Service Restart

Changes to /etc/voipmonitor.conf do not take effect until the service is restarted. Always restart after configuration changes:

systemctl restart voipmonitor

Check Traffic Reaches the Interface

Before assuming a VoIPmonitor configuration issue, verify that IPv6 packets are actually arriving at the network interface. Use tshark or tcpdump to inspect raw traffic:

# Replace eth0 with your actual interface name
tshark -i eth0 -Y "sip || rtp" -n

**If IPv6 packets appear here:** The issue is internal to VoIPmonitor (filters, configuration). Continue to the next steps.
**If NO IPv6 packets appear:** The issue is at the network/OS level:

   *   Switch mirroring (SPAN/RSPAN) may not include IPv6 traffic in the mirror session
   *   Tunnel endpoint may be misconfigured (for ERSPAN/GRE setups)
   *   Interface may not be in promiscuous mode: ip link set eth0 promisc on

Check BPF Filters

A common cause of missing IPv6 traffic is a restrictive filter directive in /etc/voipmonitor.conf that explicitly excludes IPv6.

**The Problem:** Standard BPF syntax often defaults to IPv4. For example, using filter = ip proto udp will explicitly drop IPv6 traffic (which uses the ip6 protocol indicator).
**The Fix:**

   *   Use protocol-agnostic syntax instead. Change ip proto udp to just udp or port 5060.
   *   Temporarily disable the filter to test: comment out the filter line in /etc/voipmonitor.conf.
   *   Restart the service and check if IPv6 calls appear.

For more details on filter syntax, see Capture Rules Documentation.

Verify Interface Configuration

Specific interfaces are preferred over interface = any for reliability in promiscuous mode:

interface = eth0

Ensure the interface is UP:

ip link show eth0

Check Database Schema Migration

The ipv6_alter.sql script adds IPv6 columns to the database. If this migration is incomplete, IPv6 data cannot be stored.

Check the sensor logs during startup for database errors:

journalctl -u voipmonitor -n 50

As an alternative verification, use the GUI repair tool (accessible from the web interface):

Log in to the GUI
Add ?check_tables=1 to the URL (e.g., http://yourserver/?check_tables=1)
This triggers a schema check and adds any missing columns required for IPv6 support

Review Logs

If traffic is visible in tshark but not in VoIPmonitor, check for performance warnings in the logs:

journalctl -u voipmonitor -f

Look for warnings like:

t0CPU - sensor CPU usage is too high
dropping packets - packet loss due to overload

These indicate the sensor is overloaded, which typically affects random calls rather than a specific protocol like IPv6.

Common Root Causes

Symptom	Common Cause	Solution
No IPv6 traffic in VoIPmonitor or tshark	Network mirroring/switch config not including IPv6	Configure switch port mirroring to include IPv6 traffic
IPv6 traffic in tshark but not VoIPmonitor	BPF filter is IPv4-only	Remove or update `filter` directive to be protocol-agnostic
Database errors in logs	Incomplete schema migration	Re-run `ipv6_alter.sql` or use GUI `?check_tables=1`
Sporadic IPv6 captures	Sensor overloaded, dropping packets	Check `t0CPU` and `dropping packets` in logs; optimize sensor performance

Important Considerations for Existing Databases

Performance and Time

The migration process can be very time-consuming for large databases with millions of CDRs
The ipv6_alter.sql script adds columns to multiple tables, which requires copying existing data
During migration, the database may experience performance degradation

Impact on Historical Data

Converting existing IPv4 entries cannot retroactively convert them to IPv6 format
Historical statistics and reports may display inaccuracies after the migration, as pre-migration data will have NULL values in IPv6 columns
Some aggregations or filters may behave unexpectedly with the mixed IPv4/IPv6 data

Recommended Approach: Fresh Database

For most production environments, we recommend starting with a fresh database instead of migrating:

Export or back up any data you need to preserve (raw PCAPs, reports, etc.)
Use the GUI's Tools → Backup & Restore → Configuration TABLES feature to save your GUI settings, alerts, user permissions, and other configuration
Flush or drop the old VoIPmonitor database
Recreate it from scratch with ipv6 = yes enabled
Restore your GUI configuration tables from the backup

This approach avoids migration time, eliminates potential data inconsistencies, and ensures clean IPv6 operation going forward.

Preserving GUI Settings

When resetting the database, you can preserve your GUI configuration:

Access the VoIPmonitor GUI web interface
Navigate to Tools → Backup & Restore
Select Backup configuration TABLES
Save the backup file to a safe location
Create the new database with ipv6 = yes enabled
Use Restore configuration TABLES to reapply your settings

This restores:

User accounts and permissions
Alert rules and email notifications
Dashboard configurations
GUI settings and preferences
Custom capture rules

Note: This does not restore CDR data or PCAP files—those must be backed up separately if needed.

AI Summary for RAG

Summary: This guide covers enabling IPv6 support in VoIPmonitor. For new installations, set ipv6 = yes in voipmonitor.conf before first start. For existing systems with IPv4-only databases, the correct order is: (1) Run ipv6_alter.sql migration script on the database/GUI server only, (2) Enable ipv6 = yes on each sensor, (3) Restart the service. The migration is time-consuming for large databases and may cause historical statistics inaccuracies. The recommended approach for production environments is to flush the old database, start fresh with IPv6 enabled, and use "Tools → Backup & Restore → Configuration TABLES" to preserve GUI settings.

Keywords: ipv6, ipv6 enable, migration, database migration, ipv6_alter.sql, database server, gui server, sensor configuration, historical data, configuration backup, gui settings, troubleshooting, BPF filter, tshark, packet capture, hostname lookup, hostname table, INET6_ATON, INET_NTOA, B-side IP, destination IP

Key Questions:

How do I enable IPv6 on a new VoIPmonitor installation?
What is the correct order to run ipv6_alter.sql and configure ipv6 = yes?
Do I need to run ipv6_alter.sql on all sensors or just the database server?
How do I enable IPv6 on an existing IPv4-only VoIPmonitor installation?
What is the ipv6_alter.sql migration script?
Why might migration be problematic for existing databases?
Why is IPv6 traffic not being captured after enabling ipv6 = yes?
How to troubleshoot IPv6 packet capture issues?
How do BPF filters affect IPv6 traffic capture?
How to use tshark to verify IPv6 packets reach the interface?
B-side IP addresses not resolving to hostnames after IPv6 migration?
How to fix hostname table data format after ipv6_alter.sql migration?