Redundant database

This guide explains how to use a dedicated VoIPmonitor sensor instance to perform real-time replication of the CDR database to a secondary MySQL/MariaDB server. This provides a native, application-level method for creating backups or read-only replicas.

Overview & Use Case

VoIPmonitor offers multiple built-in mechanisms to replicate or synchronize Call Detail Records (CDRs) between instances. These methods enable datacenter failover, disaster recovery, hot-standby setups, and centralized reporting.

Available Synchronization Methods

There are three primary approaches for synchronizing CDRs between VoIPmonitor instances:

1. Database Backup Mode (Read-Only Replica): Use a dedicated sniffer instance to read from the primary database and write to a secondary database. This creates a one-way, read-only replica. This method is ideal for online GUI migration, hot-standby setups, or centralized reporting.

2. Master-Master Database Replication: Configure MySQL/MariaDB in a bidirectional replication topology. Both instances can write CDRs, and changes automatically propagate between them. This provides full high-availability with automatic failover and read load balancing. See Master-Master Replication for detailed setup.

3. Dual Write Method: Configure the active sniffer to write CDRs simultaneously to both a local and a remote database. This provides real-time synchronization without requiring MySQL replication setup. Note: This method only synchronizes CDRs; it does not synchronize GUI settings (users, sensors, capture rules, etc.).

This article primarily covers Method 1 (Database Backup Mode). Method 2 is covered in the Master-Master Replication guide. Method 3 is described below.

The database backup mode method is particularly useful for:

Online GUI Migration: Migrating the GUI database from an old server to a new server with minimal or no downtime. The sensor replicates CDR data incrementally while users continue using the old GUI. Once replication completes, you can switch users to the new GUI without service interruption.
Creating a read-only replica database for reporting or analysis without impacting the performance of the primary database.
Setting up a hot-standby database for disaster recovery.
Consolidating data from multiple, smaller VoIPmonitor databases into one central database.

The process incrementally syncs data starting from a specified date, ensuring that the destination database stays up-to-date in near real-time.

Architecture Overview

Online GUI Migration Workflow

When migrating the GUI to a new server, you have two primary methods:

Method 1: Dump/Restore (With Downtime)

If a service interruption is acceptable:

Stop the sniffer on the old server

Perform a database dump:

mysqldump -u root -p voipmonitor > backup.sql

Transfer and restore on new server:

mysql -u root -p voipmonitor < backup.sql

Repoint the GUI to the new database
Install and configure the new GUI instance

This method is simple but requires downtime and may take hours for terabyte-sized databases.

Method 2: Online Migration (Minimal/No Downtime)

Using the sensor's database backup mode:

Install VoIPmonitor GUI on the new server with a fresh empty database
On the old GUI: Go to Tools → Backup & Restore → Backup configuration TABLES and download the backup file
On the new GUI: Go to Tools → Backup & Restore → Restore configuration tables and upload the backup file
IMPORTANT: Complete this step BEFORE starting the migration instance
Create a voipmonitor-migrate.conf file by copying the old voipmonitor.conf and adding migration options (see Configuration section below)
Configure and run the migration instance in "database backup mode" on the new server
The sensor connects to the old database and replicates CDR data incrementally
Once replication catches up, switch users to the new GUI
Stop migration instance and decommission the old server

For assistance with this method, provide remote SSH access to both the old and new hosts to the support team.

Comparison: Dump/Restore vs Online Migration

Aspect	Dump/Restore	Online Migration
Downtime	Required (hours for large DBs)	Minimal/None
Complexity	Low - Manual SQL dump	Medium - Sensor configuration
Data Loss Risk	Moderate (if dump fails)	Low - Incremental sync
Best For	Small databases	Large databases, zero-downtime requirements

Configuration

To set up database replication, you will run a new, dedicated VoIPmonitor sensor instance on the server that hosts your secondary (destination) database. This instance requires its own voipmonitor.conf file.

Creating the Migration Configuration File

The migration configuration file should be named consistently to avoid confusion (e.g., voipmonitor-migrate.conf).

Important: Start with a copy of the existing configuration. The easiest way to create this configuration is to copy the existing voipmonitor.conf from the old server and add the migration-specific options. This ensures all existing settings are preserved.

# On the NEW server, copy the old config:
scp root@old-server:/etc/voipmonitor.conf /etc/voipmonitor-migrate.conf

Then edit /etc/voipmonitor-migrate.conf to modify the critical settings for migration mode.

Required Modifications

If you plan to run the migration instance while the original sniffer continues to capture traffic (zero-downtime migration), you MUST make the following changes to avoid conflicts:

# --- 1. CRITICAL: Change managerport to avoid conflicts ---
# The original sniffer typically uses managerport = 5029
managerport = 5030

# --- 2. CRITICAL: Disable all packet capture bindings ---
# These prevent the migration instance from competing for network interfaces
# Comment out or delete ALL interface/bind options:
# interface = eth0       # DISABLE - do not capture packets
# interface = eth1       # DISABLE - do not capture packets
# interface = any        # DISABLE - do not capture packets

# --- 3. Destination Database (where to write data) ---
# Update to point to the NEW server's local database
mysqlhost                      = 127.0.0.1
mysqldb                        = voipmonitor
mysqlusername                  = root
mysqlpassword                  = new_db_password
cdr_partition                  = yes

# --- 4. Source Database (where to read data from) ---
# These parameters are ADDED to enable replication from the old database
database_backup_from_mysqlhost     = 192.168.0.1
database_backup_from_mysqldb       = voipmonitor
database_backup_from_mysqlusername = root
database_backup_from_mysqlpassword = old_db_password

# --- 5. Replication Control ---
# Choose the date from which replication should begin
database_backup_from_date          = 2024-01-01

# Performance tuning for replication speed
database_backup_insert_threads     = 3
database_backup_pause              = 3

# Performance Impact Explanation:
# - database_backup_pause: Higher values (e.g., 10-60 seconds) create MORE pause between batches,
#   resulting in LOWER load on the SOURCE database. Use high values if the source database
#   is also handling live traffic and cannot withstand additional replication load.
# - database_backup_insert_threads: Higher values use MORE threads for inserting data,
#   resulting in HIGHER load on both source and destination databases. Lower values (1-2)
#   are gentler on the system but replication is slower.

# --- 6. Optional: Migrate Static Data ---
# Set to 'yes' if migrating static data and you want to write NEW data to the new database.
# This is useful when you want the new server to continue accepting data after migration.
database_backup_desc_dir = yes

ℹ️ Note: database_backup_desc_dir = yes is an optional parameter that should be used when migrating static data (historical CDRs) and you plan to write new data to the destination database. This tells the migration instance to write both migrated data AND future new data to the destination database.

Configuration Parameters Reference

Parameter	Description
`managerport`	TCP port for the sensor's manager API. Must be different from the production sniffer (default: 5029).
`interface`	Network interface(s) to capture. Must be disabled/commented out for migration instance.
`mysqlhost`	IP/hostname of the destination database (new server).
`database_backup_from_mysqlhost`	IP/hostname of the source database (old server).
`database_backup_from_date`	Start date for incremental sync (format: YYYY-MM-DD).
`database_backup_insert_threads`	Number of parallel threads for inserting data (default: 1). Higher values = higher load on both source and destination databases. Lower values (1-2) = gentler on the system but slower replication.
`database_backup_pause`	Pause in seconds between sync batches (default: 0). Higher values = lower load on the SOURCE database. Use high values (10-60 seconds) if the source database handles live traffic.

Why These Changes Are Required

managerport: VoIPmonitor uses this port for internal communication and GUI connectivity. If both instances use the same port, they will conflict.

interface options

The migration instance should NOT capture packets - its only purpose is database replication. Disabling packet capture prevents:

CPU competition with the production sniffer
Duplicate packets being processed by both instances
Network interface conflicts

GUI Configuration Backup

Before starting the migration instance, you must migrate the GUI configuration tables (users, sensors, capture rules, alerts). This is done via the GUI's Tools → Backup & Restore feature.

IMPORTANT: Complete this step BEFORE starting the migration instance. See Backup and restore GUI tables for detailed instructions.

Running the Replication Instance

Once your configuration file is ready, you can start the sensor in this special mode.

Manual Test Run

It is highly recommended to first run the process manually to ensure all settings are correct and there are no connection errors.

voipmonitor --config-file /etc/voipmonitor-migrate.conf -k -v 1

Command-line options

-k: Prevents the process from forking into the background (keeps it in foreground).
-v 1: Sets verbosity to level 1, which will show status information.

Watch the output for any database connection errors or other warnings. A successful start will show messages indicating CDR data is being read from the source and written to the destination.

Running as a Service

To run the migration instance permanently as a background service, you will need to create a separate systemd or init.d service file for it. This process is covered in the Multiple Sniffer Instances guide. The key is to ensure the new service unit file uses the -c /etc/voipmonitor-migrate.conf argument to load your specific configuration.

Example systemd unit file (/etc/systemd/system/voipmonitor-migrate.service):

[Unit]
Description=VoIPmonitor Database Migration Instance
After=network.target mysql.service

[Service]
Type=simple
ExecStart=/usr/local/sbin/voipmonitor -c /etc/voipmonitor-migrate.conf
Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable and start:

systemctl daemon-reload
systemctl enable voipmonitor-migrate
systemctl start voipmonitor-migrate

Dual Write Method (Real-Time Synchronization)

The dual write method is a simpler alternative to MySQL replication for synchronizing CDRs between two active VoIPmonitor instances. Instead of configuring database replication at the MySQL level, you configure the sniffer to write each CDR to both a local (primary) and a remote (secondary) database simultaneously.

Overview

In this setup, the sniffer writes each CDR record to two databases:

Primary Database (local): The main database for the instance
Secondary Database (remote): The secondary instance's database

This provides real-time synchronization without the complexity of MySQL replication configuration.

Use Cases

Active-Active Datacenter Deployment: Two separate datacenters both capturing traffic, with each sniffer writing to the other's database
Real-time Backup: Every CDR is immediately backed up to a remote database
Centralized Reporting: Multiple sniffers write to a central reporting database

Configuration

To enable dual write mode, add the secondary database connection parameters to your voipmonitor.conf:

# Primary Database Connection (Local)
mysqlhost      = 127.0.0.1
mysqldb        = voipmonitor
mysqlusername  = root
mysqlpassword  = primary_password

# Secondary Database Connection (Remote) - These parameters enable dual write
mysql2host      = 192.168.1.100
mysql2db        = voipmonitor
mysql2username  = root
mysql2password  = secondary_password

Important Notes

GUI Settings Not Synchronized: The dual write method only replicates CDR data. GUI configuration tables (users, sensors, capture rules, alerts) are NOT synchronized. You must manually configure these on each instance.

Write Performance Impact: Writing to two databases adds overhead. Ensure your network can handle the additional database traffic. Consider using a dedicated database server for the secondary if performance becomes an issue.

Connection Failure Handling: If the secondary database becomes unreachable, the sniffer will log connection errors but continue writing to the primary database. CDRs written during the outage will NOT be retroactively synced.

Suitable for Simple Scenarios: For complex high-availability requirements with bidirectional write support, consider Master-Master replication instead.

Comparison: Dual Write vs Master-Master Replication

Aspect	Dual Write Method	Master-Master Replication
Configuration Complexity	Low - Add mysql2* parameters	Medium - MySQL replication setup
Bidirectional Sync	No - A writes to B (one-way)	Yes - A and B sync with each other
GUI Settings Sync	No	Yes (via MySQL replication)
Automatic Failover	No	Yes (with load balancer)
Best For	Simple one-way backup	Full high-availability setup

Migrating PCAP (Packet Capture) Files

The database migration process described above migrates only the CDR (Call Detail Records). It does not migrate PCAP files. You must migrate PCAP files separately.

Using rsync to Copy PCAPs

Use rsync over SSH to copy the spooldir (default: /var/spool/voipmonitor) from the old server to the new server.

# Run on NEW SERVER pulling from OLD
rsync -avz root@old-server:/var/spool/voipmonitor/ /var/spool/voipmonitor/

-a: Archive mode (preserves permissions, times, symbolic links)
-v: Verbose output
-z: Compress during transfer (saves bandwidth)

Timezone Considerations (CRITICAL)

OS Timezone Must Match: If you are copying PCAP files from an old probe to a new probe that will continue capturing, ensure both systems have the same OS timezone configured.

PCAP file paths are based on directory structure: spooldir/YYYY-MM-DD/HH/MM/. The directory structure uses the system's local timezone. If the old probe was in timezone A and the new probe is in timezone B, the new probe will create PCAP files in different directory paths than the old files. This can cause the GUI to fail to find or link historical PCAPs.

The database stores relative paths, so as long as the directory structure is preserved and the timezone remains the same, the GUI will correctly reference the old PCAPs.

To check/set timezone:

# Check current timezone
timedatectl

# Set timezone (example for Europe/Prague)
timedatectl set-timezone Europe/Prague

Architecture-Specific Considerations

Client-Server Mode with Local Processing

In the new architecture where probes store their own PCAPs (packetbuffer_sender=no), you have these options:

Keep the PCAPs on the OLD probe hardware if it is becoming one of the new probes
Archive historical PCAPs to external storage
Copy to the new probe only if timezone matches

Centralized PCAP Storage: If you are centralizing PCAPs (packetbuffer_sender=yes), copy all old PCAPs to the Central Server's spool directory. Ensure the central server's OS timezone matches all probes' timezones.

Schema Changes and Database Compatibility

When migrating to a new server, especially when the MySQL/MariaDB versions or VoIPmonitor versions differ between the old and new systems, the database schema may require updates.

Automatic Schema Upgrade with Migration Instance

The migration instance using `voipmonitor-migrate.conf` automatically handles database schema upgrades during the CDR replication process. The latest sniffer binary includes the necessary schema updates, and running a migration instance ensures the destination database schema is brought up to date without manual intervention.

This approach is particularly useful when: - Migrating from a local MySQL database to a separate Percona/MySQL server - Upgrading VoIPmonitor versions during migration - Moving between database server versions

Identifying Schema Changes Manually

If you need to identify what schema changes are required on the old database (for verification or troubleshooting):

# 1. Restart the latest receiver sniffer to check logs for schema changes
systemctl restart voipmonitor

# 2. Monitor the log for SQL commands
tail -f /var/log/voipmonitor/voipmonitor.log | grep -E "CLI|ALTER|CREATE TABLE"

# These log entries show the SQL statements the sniffer needs to execute
# to bring the database schema up to date

The `CLI` and `ALTER` entries in the log indicate the specific schema modifications that the newer VoIPmonitor version requires.

Cross-OS and Database Version Migration

When migrating between servers with different MySQL/MariaDB versions or operating systems:

⚠️ Warning: If you are migrating between servers with MySQL or MariaDB versions that differ significantly, do not use mysqldump directly to restore CDR data. Use the migration instance method which handles schema version differences automatically.

For smaller databases where migration instance is not required, you can use mysqldump with compatibility options:

# Example for MySQL 5.7 to 8.0 migration (use with caution)
mysqldump -u root -p --compatible=mysql57 voipmonitor > backup.sql

However, this method may not work for all schema changes and the migration instance method is more reliable for handling complex schema migrations.

AI Summary for RAG

Summary: This article describes three methods for synchronizing VoIPmonitor databases between instances: (1) Database Backup Mode - using a dedicated sensor in "database backup mode" to perform application-level replication for read-only replicas (described in detail here), (2) Master-Master Database Replication - bidirectional MySQL/MariaDB replication for full high-availability (covered in Master-Master Replication), and (3) Dual Write Method - configuring the sniffer to write CDRs simultaneously to local and remote databases using mysql2* parameters. The article primarily covers Method 1 with configuration details for setting up destination (mysqlhost) and source (database_backup_from_mysqlhost) databases, including database_backup_from_date for sync control. To control database load during replication, use database_backup_pause (higher values = lower load on source database) and database_backup_insert_threads (higher values = higher load on both databases). PCAP files must be migrated separately using rsync, with critical attention to timezone matching between servers. SCHEMA CHANGES: When migrating to new servers or different MySQL/Percona versions, the migration instance using voipmonitor-migrate.conf automatically handles database schema upgrades. To identify required schema changes manually, restart the latest sniffer and check logs for "CLI" or "ALTER" SQL commands. For cross-version migration, do not use mysqldump directly - use the migration instance method which handles schema version differences automatically.

Keywords: database replication, backup, mysql backup, mariadb replication, replica, read-only, standby, disaster recovery, GUI migration, migrate database, online migration, zero downtime, database_backup_from_date, database_backup_from_mysqlhost, voipmonitor.conf, high availability, PCAP migration, spooldir, rsync, timezone, packetbuffer_sender, client-server mode, centralized storage, dual write, mysql2host, master-master replication, synchronize, datacenter, performance tuning, database_backup_pause, database_backup_insert_threads, performance impact, load control, schema, schema upgrade, database schema, CLI, ALTER, Percona, voipmonitor-migrate.conf, migration instance, new server, MySQL version, MariaDB version, cross-version migration, log analysis, sniffer restart, remote database, local MySQL to remote Percona

Key Questions:

How can I synchronize CDRs between two VoIPmonitor instances?
What methods are available for database replication in VoIPmonitor?
What is the difference between database backup mode, dual write, and master-master replication?
How can I migrate the GUI database with minimal downtime?
What is the difference between dump/restore and online migration?
How can I create a real-time backup of my VoIPmonitor database?
How do I configure dual write mode (mysql2*)?
What configuration is needed to mirror the VoIPmonitor database?
Can I use VoIPmonitor to create a read-only replica for reporting?
How does database_backup_from_date work?
How do I migrate PCAP files to a new server?
Why is timezone matching important when migrating PCAP files?
How can I use rsync to copy VoIPmonitor spooldir?
How can I control the database load during replication?
What is database_backup_pause and how does it affect performance?
What is database_backup_insert_threads and how does it affect performance?
How do I migrate VoIPmonitor from local MySQL to a separate Percona database?
How do I use a migration instance to transfer VoIPmonitor data?
What is voipmonitor-migrate.conf and how do I configure it?
Does the migration instance handle database schema upgrades automatically?
How do I identify required database schema changes when migrating?
How do I migrate VoIPmonitor to a new server including GUI, database, and sniffer?
Can I use mysqldump when migrating between different MySQL/MariaDB versions?
What log entries show the database schema changes needed by VoIPmonitor?