Backing Up GUI Configuration: Difference between revisions

From VoIPmonitor.org
(Add warning about MySQL/MariaDB version differences during migration. Explain that direct mysqldump should not be used when database versions differ; instead use voipmonitor-migrate.conf via temporary database.)
(Add reference to Redundant_database page for full database dump/restore and online migration methods)
Line 478: Line 478:
* You require zero-downtime migration with parallel operation
* You require zero-downtime migration with parallel operation
* You need to migrate database files to a new storage system
* You need to migrate database files to a new storage system
Use the [[Redundant_database|database dump/restore or online migration]] method when:
* You need to migrate the FULL database including CDRs
* You want simple mysqldump restore (acceptable downtime) OR
* You need minimal/no downtime with online migration
The [[Redundant_database|Redundant Database]] guide covers:
;Method 1: Dump/Restore (With Downtime):
:# Stop the sniffer on the old server
:# Dump database: <code>mysqldump -u root -p voipmonitor > backup.sql</code>
:# Transfer and restore on new server: <code>mysql -u root -p voipmonitor < backup.sql</code>
;Method 2: Online Migration (Minimal/No Downtime):
:# Install new GUI with fresh database
:# Restore GUI configuration tables via backup/restore
:# Run migration instance to sync CDRs incrementally
:# See [[Redundant_database|Redundant Database]] for detailed configuration


== Migrating VoIPmonitor to New Hardware (Data Migration Method) ==
== Migrating VoIPmonitor to New Hardware (Data Migration Method) ==
Line 558: Line 575:
== AI Summary for RAG ==
== AI Summary for RAG ==
'''Summary:''' This guide provides comprehensive guidance on backing up the VoIPmonitor GUI configuration using two methods: a quick web interface method for one-time backups before upgrades, and an automated CLI script method for scheduled daily backups. The web interface method accessed via '''GUI → Tools → Backup & restore''' allows users to select "configuration tables" (backing up all database settings made by GUI users including users, sensors, capture rules, alerts, dashboards, reports) and "configuration files" (backing up GUI configuration files like configuration.php). The CLI script method uses the `run.php` command-line tool to export configuration tables, data tables, and PHP configuration files, with automatic cleanup of old backups. The guide details creating the backup script, scheduling it with cron for Automated daily backups at 3:30 AM, and includes restoration methods using both the GUI web interface and CLI commands (`restoreGuiTables`, `mysql` import). Critical restoration information specifies what IS transferred (user accounts, permissions, sensor definitions, alert definitions, filters, dashboards) and what is NOT transferred (assignments of alerts to sensors, reports to sensors, sensor user access permissions, captured call data and PCAP files). The restore operation overwrites, not merges, existing data. The guide also covers a specialized procedure for importing only dashboards from one GUI instance to another by extracting and importing the `custom_config` table, noting that folder structures are not preserved and ownership may need adjustment. Troubleshooting guidance is included for scenarios where alerts disappear after upgrades (restore configuration tables via GUI). Additionally, the guide now includes a complete '''simple migration procedure''' for EOL systems: (1) backup GUI config using `php php/run.php backupGuiTables -t config -f backup.zip`, (2) backup `/etc/voipmonitor.conf` and `configuration.php`, (3) fresh install on new server with modern OS (Debian 12/Ubuntu 22.04), (4) restore all configurations on new system, (5) test with subset of traffic before full migration. This simple method is recommended for EOL OS when you do not need historical data migrated. A separate '''complex migration method with voipmonitor-migrate.conf''' is documented for scenarios requiring historical data transfer or zero-downtime migration, covering GUI backup/restore, creating `voipmonitor-migrate.conf`, and configuring parallel operation by changing `managerport` and disabling ALL `bind*` options. A new '''critical warning section on MySQL/MariaDB version differences''' explains that when migrating between servers with significantly different database versions, do not use mysqldump directly for the main CDR database. Instead, use a VoipMonitor migration instance with `voipmonitor-migrate.conf` to migrate via a temporary backup database on the new server (two-step process: old server to temporary DB, then temporary DB to final DB), which handles schema version differences automatically. GUI configuration tables typically have stable schemas and can be migrated directly without issues. As an alternative for smaller databases, mysqldump can be used with the `--compatible` option (e.g., `--compatible=mysql57` for MySQL 5.7 to 8.0 migration), though this may not work for all schema changes.
'''Summary:''' This guide provides comprehensive guidance on backing up the VoIPmonitor GUI configuration using two methods: a quick web interface method for one-time backups before upgrades, and an automated CLI script method for scheduled daily backups. The web interface method accessed via '''GUI → Tools → Backup & restore''' allows users to select "configuration tables" (backing up all database settings made by GUI users including users, sensors, capture rules, alerts, dashboards, reports) and "configuration files" (backing up GUI configuration files like configuration.php). The CLI script method uses the `run.php` command-line tool to export configuration tables, data tables, and PHP configuration files, with automatic cleanup of old backups. The guide details creating the backup script, scheduling it with cron for Automated daily backups at 3:30 AM, and includes restoration methods using both the GUI web interface and CLI commands (`restoreGuiTables`, `mysql` import). Critical restoration information specifies what IS transferred (user accounts, permissions, sensor definitions, alert definitions, filters, dashboards) and what is NOT transferred (assignments of alerts to sensors, reports to sensors, sensor user access permissions, captured call data and PCAP files). The restore operation overwrites, not merges, existing data. The guide also covers a specialized procedure for importing only dashboards from one GUI instance to another by extracting and importing the `custom_config` table, noting that folder structures are not preserved and ownership may need adjustment. Troubleshooting guidance is included for scenarios where alerts disappear after upgrades (restore configuration tables via GUI). Additionally, the guide now includes a complete '''simple migration procedure''' for EOL systems: (1) backup GUI config using `php php/run.php backupGuiTables -t config -f backup.zip`, (2) backup `/etc/voipmonitor.conf` and `configuration.php`, (3) fresh install on new server with modern OS (Debian 12/Ubuntu 22.04), (4) restore all configurations on new system, (5) test with subset of traffic before full migration. This simple method is recommended for EOL OS when you do not need historical data migrated. A separate '''complex migration method with voipmonitor-migrate.conf''' is documented for scenarios requiring historical data transfer or zero-downtime migration, covering GUI backup/restore, creating `voipmonitor-migrate.conf`, and configuring parallel operation by changing `managerport` and disabling ALL `bind*` options. A new '''critical warning section on MySQL/MariaDB version differences''' explains that when migrating between servers with significantly different database versions, do not use mysqldump directly for the main CDR database. Instead, use a VoipMonitor migration instance with `voipmonitor-migrate.conf` to migrate via a temporary backup database on the new server (two-step process: old server to temporary DB, then temporary DB to final DB), which handles schema version differences automatically. GUI configuration tables typically have stable schemas and can be migrated directly without issues. As an alternative for smaller databases, mysqldump can be used with the `--compatible` option (e.g., `--compatible=mysql57` for MySQL 5.7 to 8.0 migration), though this may not work for all schema changes.
'''Keywords:''' backup, restore, configuration, gui, settings, users, sensors, capture rules, cron, crontab, automation, disaster recovery, dashboard, migration, upgrade, `run.php`, `backupGuiTables`, `restoreGuiTables`, `backupGuiConfigurationFiles`, mysql, import, export, custom_config, overwrite, merge, assignment, not transferred, web interface, tools menu, quick backup, EOL, end-of-life, fresh installation, new server, `/etc/voipmonitor.conf`, `configuration.php`, Debian 12, Bookworm, Ubuntu 22.04, subset traffic, hardware migration, `voipmonitor-migrate.conf`, migration instance, parallel operation, `managerport`, `bind* options`, conflicts, mysql version, mariadb version, database version, version mismatch, `--compatible`, temporary database, schema differences, CDR migration
'''Keywords:''' backup, restore, configuration, gui, settings, users, sensors, capture rules, cron, crontab, automation, disaster recovery, dashboard, migration, upgrade, `run.php`, `backupGuiTables`, `restoreGuiTables`, `backupGuiConfigurationFiles`, mysql, import, export, custom_config, overwrite, merge, assignment, not transferred, web interface, tools menu, quick backup, EOL, end-of-life, fresh installation, new server, `/etc/voipmonitor.conf`, `configuration.php`, Debian 12, Bookworm, Ubuntu 22.04, subset traffic, hardware migration, `voipmonitor-migrate.conf`, migration instance, parallel operation, `managerport`, `bind* options`, conflicts, mysql version, mariadb version, database version, version mismatch, `--compatible`, temporary database, schema differences, CDR migration, mysqldump, database dump, database restore, full database migration, CDRs, online migration, downtime
'''Key Questions:'''
'''Key Questions:'''
* How do I back up my VoIPmonitor GUI before an upgrade?
* How do I back up my VoIPmonitor GUI before an upgrade?
Line 577: Line 594:
* When should I backup GUI configuration before migration?
* When should I backup GUI configuration before migration?
* Can I run original sniffer and migration instance simultaneously?
* Can I run original sniffer and migration instance simultaneously?
* How do I migrate the full database including CDRs using mysqldump?
* What is the dump/restore method for GUI database migration?
* How do I migrate GUI database with acceptable downtime?
* How do I perform online GUI migration with minimal downtime?
* Where is the backup and restore menu in the GUI?
* Where is the backup and restore menu in the GUI?
* What do "configuration tables" contain in the GUI backup?
* What do "configuration tables" contain in the GUI backup?

Revision as of 08:31, 6 January 2026


This guide provides a step-by-step method for creating regular, automated backups of your VoIPmonitor GUI's configuration. This includes users, sensors, capture rules, and all other settings configured through the web interface.

Overview

This backup procedure is designed to save only the GUI's configuration data, not the call data (CDRs) or captured PCAP files. It is an essential part of a disaster recovery plan, allowing you to quickly restore a known-good GUI configuration to a new or rebuilt server without backing up terabytes of call data.

The backup process works with three types of data:

  1. Configuration Tables: The core database tables that store settings, dashboards, and configurations (e.g., `users`, `sensors`, `custom_config`). These include all settings made by GUI users and administrators.
  2. Data Tables: Supporting data like saved reports.
  3. Configuration Files: The PHP configuration files from the GUI directory itself (e.g., `configuration.php`).

Quick Backup via GUI Web Interface

For a quick backup before an upgrade, you can use the built-in GUI backup feature directly from the web interface.

ℹ️ Note: This method is ideal for one-time backups before upgrades, reinstallation, or migrations. For automated daily backups, see the command-line script method below.

Steps:

1. Open the VoIPmonitor GUI web interface 2. Navigate to GUI → Tools → Backup & restore 3. Select :backup GUI: configuration tables to back up all database settings made by GUI users and administrators 4. Select :backup GUI: configuration files to back up GUI configuration files 5. Perform the backup 6. Download the generated backup file to a safe location

What Gets Backed Up:

  • Configuration Tables includes:
    • All user accounts and permissions
    • Sensor definitions and configurations
    • Capture rules and filters
    • Alert definitions and thresholds
    • Dashboard configurations
    • Reports and their definitions
  • Configuration Files includes:
    • `configuration.php` and other GUI-specific PHP configuration files

Restoring from GUI Backup:

If you need to restore after an upgrade (for example, if alerts disappear): 1. Navigate to GUI → Tools → Backup & restore 2. Select :restore GUI: configuration tables 3. Upload and select the backup file created earlier

⚠️ Warning: Restoring will overwrite existing GUI settings. Only perform this on a freshly installed GUI or be prepared to lose current configurations.

Automated Daily Backup Using CLI Script

This section describes how to set up automated daily backups using a command-line script. This method is ideal for production environments where you want regular, scheduled backups without manual intervention.

First, create a shell script that will run the export commands.

Create and edit the script file
nano /usr/local/sbin/backup_voipmonitor_gui.sh
Copy and paste the following content into the file
#!/bin/bash
#
# VoIPmonitor GUI Configuration Backup Script
#

# --- Configuration ---
# Set the base directory where backups will be stored
BACKUP_DIR="/var/backups/voipmonitor_gui"

# Set the retention period in days. Backups older than this will be deleted.
RETENTION_DAYS=30

# --- Script Logic ---

# Create the backup directory if it doesn't exist
mkdir -p "$BACKUP_DIR"

# Set the filename based on the current date
DAY=$(date "+%Y-%m-%d")
FILE_CFG_TABLES="$BACKUP_DIR/config_tables-${DAY}.sql"
FILE_DATA_TABLES="$BACKUP_DIR/data_tables-${DAY}.sql"
FILE_CFG_FILES="$BACKUP_DIR/config_files-${DAY}.tar.gz"

# Path to the GUI's run.php script
RUN_SCRIPT="/var/www/html/php/run.php"

echo "--- Starting VoIPmonitor GUI Backup for ${DAY} ---"

# Export the configuration and data tables as SQL dumps
php "$RUN_SCRIPT" backupGuiTables -t config -f "$FILE_CFG_TABLES"
php "$RUN_SCRIPT" backupGuiTables -t data -f "$FILE_DATA_TABLES"

# Backup the GUI's PHP configuration files into a compressed tarball
php "$RUN_SCRIPT" backupGuiConfigurationFiles -f "$FILE_CFG_FILES"

echo "Backup files created:"
ls -lh "$FILE_CFG_TABLES" "$FILE_DATA_TABLES" "$FILE_CFG_FILES"

# Clean up old backups
echo "--- Cleaning up backups older than ${RETENTION_DAYS} days ---"
find "$BACKUP_DIR" -type f -mtime +"$RETENTION_DAYS" -name '*-*-*-*.sql' -print -delete
find "$BACKUP_DIR" -type f -mtime +"$RETENTION_DAYS" -name '*-*-*-*.tar.gz' -print -delete

echo "--- Backup complete ---"

Step 2: Make the Script Executable and Test It

Set the correct permissions so the script can be run.

chmod +x /usr/local/sbin/backup_voipmonitor_gui.sh

You can test the script by running it manually: `/usr/local/sbin/backup_voipmonitor_gui.sh`. It should create three new files in `/var/backups/voipmonitor_gui`.

Step 3: Schedule the Automated Backup with Cron

The final step is to create a cron job to run the script automatically every night.

Edit the system's crontab file
crontab -e
Add the following line to the end of the file

This example will run the backup script every day at 3:30 AM.

30 3 * * * /usr/local/sbin/backup_voipmonitor_gui.sh > /var/log/voipmonitor_backup.log 2>&1
  • The `> /var/log/voipmonitor_backup.log 2>&1` part redirects all output (both standard and error) to a log file, which is essential for troubleshooting the cron job if it fails.

Save and close the file. The cron daemon will automatically pick up the new schedule.

Importing Only Dashboards from Another GUI Instance

Use this procedure when you need to migrate dashboards from an old VoIPmonitor GUI instance to a new one.

Recommended Method: GUI Backup & Restore (Simple)

The easiest way to transfer dashboards is to use the built-in GUI backup and restore interface. This method is recommended because it correctly handles dashboard ownership tied to user and group IDs.

1. On the source server (Old GUI)

Navigate to GUI → Tools → Backup & restore

  • Select "backup GUI: configuration tables"
  • Perform the backup
  • Download the generated backup file
2. On the destination server (New GUI)

Navigate to GUI → Tools → Backup & restore

  • Select "restore"
  • Upload and select the backup file created from the source server

This will import the dashboards along with other GUI configuration. If you want to transfer ONLY dashboards (without other settings like sensors, capture rules, etc.), see the advanced method below.

---

Advanced Method: Manual SQL Extraction (Dashboards Only)

Use this advanced procedure when you need to migrate dashboards from an old VoIPmonitor GUI instance to a new one without importing other configurations like sensors or capture rules.

Dashboards are stored in the `custom_config` database table, which is part of the configuration backup.

Important Notes

  • This process imports dashboards, charts, and associated reports - it is not possible to isolate only the Dashboard layouts
  • Folder structures will NOT be preserved - you will need to manually recreate dashboard folders after import
  • Dashboard ownership may need to be adjusted (e.g., to make dashboards public or assign to the correct user)
  • Panel caching may need to be reconfigured for imported dashboards

Step 1: Create Backups on Both Instances

First, create backups on both the old and new GUI instances:

Old GUI Server:

cd /var/www/html
php php/run.php backupGuiTables -t config -f /tmp/old_gui_config.sql

New GUI Server:

cd /var/www/html
php php/run.php backupGuiTables -t config -f /tmp/new_gui_config.sql

The backup of the new instance is useful for rollback if the import causes issues.

Step 2: Extract the custom_config Table from Old Instance

The `custom_config` table contains dashboard definitions. Extract only this table from the old instance's backup file:

# Extract only the custom_config table INSERT statements
grep -A 100000 "Dumping data for table \`custom_config\`" /tmp/old_gui_config.sql | \
grep -B 100000 "Table structure for table" | \
grep "^INSERT INTO" > /tmp/custom_config_only.sql

Alternatively, you can manually extract the table by editing the SQL file and copying only the `INSERT INTO custom_config` statements.

Step 3: Modify Dashboard Ownership (If Needed)

The `custom_config` table may contain user-specific ownership information. If you need to adjust this, edit the `/tmp/custom_config_only.sql` file:

nano /tmp/custom_config_only.sql

Common modifications:

  • Change user ID values to match users on the new instance
  • Set ownership to make dashboards public (if your installation supports this)
  • Update any instance-specific paths or IDs

ℹ️ Note: The structure of the `custom_config` table includes fields that may reference user IDs and other instance-specific data. Review your SQL export carefully before importing to ensure data consistency.

Step 4: Import the custom_config Table to New Instance

Import the extracted `custom_config` table into the new GUI instance:

cd /var/www/html
mysql -u voipmonitor_user -p voipmonitor < /tmp/custom_config_only.sql

Or use the GUI web interface if it provides a table import function.

Step 5: Post-Import Tasks

After importing the dashboards, you will need to:

Recreate Dashboard Folder Structures

The import does not preserve folder hierarchies. Log in to the new GUI and manually create any dashboard folders, then move imported dashboards into the appropriate folders.

Configure Panel Caching

If your dashboards use cached data for performance, you may need to reconfigure panel caching settings for the imported dashboards.

Verify Permissions

Check that users who should have access to the dashboards are appropriately configured in the new GUI instance.

Troubleshooting

If dashboards do not appear after import:

  • Verify the `custom_config` table was imported correctly by checking the database
  • Check for user ID mismatches between the old and new instances
  • Clear browser cache and refresh the GUI
  • Review any GUI error logs for related messages

How to Restore from a Backup

There are three methods to restore your GUI configuration: the recommended GUI method, the CLI method, or the manual method.

Warning: This process will overwrite your existing GUI settings. Perform these steps on a freshly installed GUI or be prepared to lose current configurations.

IMPORTANT: What IS and IS NOT Transferred

When restoring a GUI configuration backup to a new instance, the following applies:

What IS Transferred
  • User accounts (login credentials, user IDs)
  • Permissions and user group assignments
  • User settings and preferences
  • Sensor definitions (sensor names, IP addresses, capture rules)
  • Alert definitions and thresholds
  • Filter configurations
  • Dashboard configurations
What is NOT Transferred
  • Assignments of alerts to sensors - These must be reconfigured manually after restore
  • Assignments of reports to sensors - These must be reconfigured manually after restore
  • Sensor user assignments - Access permissions for sensors must be reassigned to users
  • Captured call data (CDRs) and PCAP files - These are not included in the backup
Behavior When Merging

If the new GUI instance already has existing data:

  • User accounts from the backup will overwrite existing users with the same username or ID
  • Sensor definitions will be replaced with the backed-up versions
  • Configuration settings will be overwritten
  • This is NOT a merge operation - it is a restore that replaces existing data

For these reasons, it is strongly recommended to perform the restore on a freshly installed GUI instance with no existing configuration.

Method 1: Using the GUI Web Interface (Recommended)

The simplest method is to use the built-in GUI backup and restore interface. This method correctly handles dashboard ownership tied to user and group IDs.

1. On the source server (Old GUI)

Navigate to GUI → Tools → Backup & restore

  • Select "backup GUI: configuration tables"
  • Perform the backup
  • Download the generated backup file
2. On the destination server (New GUI)

Navigate to GUI → Tools → Backup & restore

  • Select "restore"
  • Upload and select the backup file created from the source server

This is the recommended method for migrating dashboards because it automatically handles user ID mapping and ownership correctly.

Method 2: Using the restoreGuiTables CLI Command

The GUI provides a command-line tool to restore configuration tables directly without manually importing SQL files.

1. Navigate to your GUI directory
cd /var/www/html
2. Restore the configuration tables
php php/run.php restoreGuiTables -t config -f /var/backups/voipmonitor_gui/config_tables-YYYY-MM-DD.sql
php php/run.php restoreGuiTables -t data -f /var/backups/voipmonitor_gui/data_tables-YYYY-MM-DD.sql
3. Restore the Configuration Files

Extract the backed-up PHP configuration files into your GUI's web root.

# Extract the archive, overwriting existing files
tar xzf /var/backups/voipmonitor_gui/config_files-YYYY-MM-DD.tar.gz

Method 3: Manual MySQL Import

Alternatively, you can use the `mysql` command-line client to import the saved SQL dumps.

1. Restore the Database Tables
mysql -u your_user -p voipmonitor < /var/backups/voipmonitor_gui/config_tables-YYYY-MM-DD.sql
mysql -u your_user -p voipmonitor < /var/backups/voipmonitor_gui/data_tables-YYYY-MM-DD.sql
2. Restore the Configuration Files

Extract the backed-up PHP configuration files into your GUI's web root.

# Navigate to the GUI's root directory (path may vary)
cd /var/www/html/

# Extract the archive, overwriting existing files
tar xzf /var/backups/voipmonitor_gui/config_files-YYYY-MM-DD.tar.gz

After restoring both the database and files, your GUI's configuration should be fully recovered.

Important: MySQL/MariaDB Version Differences

⚠️ Warning: Database Version Mismatch: If you are migrating between servers with MySQL or MariaDB versions that differ significantly, do not use mysqldump directly to restore CDR data.

When the old and new servers have different database versions, a direct mysqldump restore may fail or cause compatibility issues. There are two solutions:

Solution 1
Use VoipMonitor Migration Instance (Recommended for CDR Migration)

Instead of using mysqldump directly for the main database: 1. Run a VoipMonitor migration instance using `voipmonitor-migrate.conf` 2. Configure the migration instance to read from the old database 3. Set the migration destination to a temporary backup database on the new server 4. After migration completes, run a second migration instance to move data from the temporary database to the final destination database 5. This approach handles schema version differences automatically

Solution 2
Use mysqldump --compatible Option

For smaller databases, you can use mysqldump with compatibility options:

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

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

These warnings apply primarily to the main CDR database. GUI configuration tables (users, sensors, dashboards) typically have stable schemas that can be migrated directly without issues.

Migrating to a New Server (Simple Fresh Installation Method)

This method describes the straightforward approach for migrating VoIPmonitor to a new server, which is especially useful when the old server is running an end-of-life (EOL) operating system that cannot be upgraded.

Overview

When dealing with legacy systems that have kernel compatibility issues or EOL operating systems, the simplest approach is to perform a fresh installation on new hardware and restore your configuration backups. This avoids complex migration procedures and potential compatibility problems.

This process involves: 1. Backing up GUI configuration tables 2. Backing up configuration files 3. Installing VoIPmonitor on the new server 4. Restoring configuration on the new system 5. Testing with a subset of traffic

Step 1: Backup Configuration on Old System

Before deactivating the old system, create backups of all essential configuration.

1. Backup GUI Configuration Tables

Run the backup command from your GUI installation directory:

cd /var/www/html
php php/run.php backupGuiTables -t config -f backup.zip

This command exports all GUI settings including:

  • User accounts and permissions
  • Sensor definitions
  • Capture rules
  • Dashboard configurations
  • Alert definitions
2. Backup Sniffer Configuration Files

Copy the main configuration file:

cp /etc/voipmonitor.conf /tmp/voipmonitor.conf.backup
3. Backup GUI Configuration File

configuration.php contains GUI-specific settings. Copy it from your GUI directory:

cp /var/www/html/voipmonitor/configuration.php /tmp/configuration.php.backup
# Note: Adjust the path if your GUI is installed in a different location

Transfer these backup files to the new server using SCP, FTP, or any other secure method.

Step 2: Perform Fresh Installation on New Server

On the new server, install VoIPmonitor following the standard installation procedures, using a current supported operating system such as Debian 12 (Bookworm) or Ubuntu 22.04.

Follow the Sniffer Installation Guide for the sensor component and the GUI Installation Guide for the web interface.

Step 3: Restore Configuration on New Server

After completing the fresh installation, restore your configuration files.

1. Restore the Sniffer Configuration
cp voipmonitor.conf.backup /etc/voipmonitor.conf
2. Restore the GUI Configuration File
cp configuration.php.backup /var/www/html/voipmonitor/configuration.php
3. Restore GUI Configuration Tables
cd /var/www/html
php php/run.php restoreGuiTables -t config -f backup.zip

Alternatively, you can use the web interface: 1. Navigate to GUI → Tools → Backup & restore 2. Select restore GUI: configuration tables 3. Upload the backup.zip file created in Step 1

Step 4: Start and Verify

Start the service and verify it is functioning correctly:

systemctl start voipmonitor
systemctl status voipmonitor

Monitor the logs to ensure the service starts without errors:

journalctl -u voipmonitor -f

Step 5: Test with Subset of Traffic

Before fully migrating or decommissioning the old system:

1. Configure network capture to monitor a subset of your traffic (using the capture rules or by mirroring only specific VLANs/ports) 2. Verify that calls are appearing in the GUI 3. Check for RTP capture issues that were present on the old system 4. Play back recorded calls to confirm audio quality

Once you are satisfied that the new system is functioning correctly: 1. Expand monitoring to full traffic if needed 2. Decommission the old VoIPmonitor installation (stop the service and disable it: systemctl stop voipmonitor && systemctl disable voipmonitor)

When to Use This Method vs voipmonitor-migrate.conf

Use this simple fresh installation method when:

  • The old server is EOL and cannot be upgraded
  • You do not need to migrate historical data (CDRs or PCAP files)
  • You want a clean start with zero compatibility issues
  • You have network access to the new server for SPAN/mirroring

Use the complex migration method with voipmonitor-migrate.conf when:

  • You need to transfer large amounts of historical call data
  • You require zero-downtime migration with parallel operation
  • You need to migrate database files to a new storage system

Use the database dump/restore or online migration method when:

  • You need to migrate the FULL database including CDRs
  • You want simple mysqldump restore (acceptable downtime) OR
  • You need minimal/no downtime with online migration

The Redundant Database guide covers:

Method 1
Dump/Restore (With Downtime):
  1. Stop the sniffer on the old server
  2. Dump database: mysqldump -u root -p voipmonitor > backup.sql
  3. Transfer and restore on new server: mysql -u root -p voipmonitor < backup.sql
Method 2
Online Migration (Minimal/No Downtime):
  1. Install new GUI with fresh database
  2. Restore GUI configuration tables via backup/restore
  3. Run migration instance to sync CDRs incrementally
  4. See Redundant Database for detailed configuration

Migrating VoIPmonitor to New Hardware (Data Migration Method)

This is an advanced method for migrating VoIPmonitor to a new hardware server while transferring existing call data. You use a dedicated migration instance to transfer configuration and data smoothly.

Overview

The migration process involves: 1. Backing up GUI configuration (must be done BEFORE starting migration) 2. Restoring GUI configuration on the new server 3. Running a migration instance using `voipmonitor-migrate.conf` 4. Optionally running the migration instance in parallel with the original sniffer

Step 1: Prepare for Migration

First, create a backup of all GUI configuration on the OLD server:

1. On the old GUI, navigate to GUI → Tools → Backup & restore 2. Select :backup GUI: configuration tables to back up all database settings (users, sensors, capture rules, dashboards, etc.) 3. Download the generated backup file

Step 2: Restore Configuration on New Hardware

On the NEW server:

1. Install VoIPmonitor Sniffer and GUI following the standard installation guide 2. Restore the GUI configuration backup:

  * Navigate to GUI → Tools → Backup & restore
  * Select :restore GUI: configuration tables
  * Upload and select the backup file created from the old server

Step 3: Create voipmonitor-migrate.conf

The migration configuration file is a copy of your original `voipmonitor.conf` with migration-specific options added.

Create the migration configuration file
cp /etc/voipmonitor.conf /etc/voipmonitor-migrate.conf

⚠️ Warning: You must complete the GUI backup and restore procedure BEFORE starting the migration instance. Do not skip steps 1-2.

Step 4: Configure Parallel Operation (Optional)

If you need to run the migration instance while the original sniffer is still active (for zero-downtime migration):

1. Edit `voipmonitor-migrate.conf` and modify these settings to avoid conflicts:

# Change the manager port to avoid conflicts with the original sniffer
# Default managerport is 6001, choose a different port (e.g., 6002)
managerport = 6002

# IMPORTANT: Comment out or disable ALL bind* options
# These bind to network interfaces and will cause conflicts if both instances are active
#bind = 0.0.0.0:5060
#bindbindip = 0.0.0.0
#bindbindport = 5061
#bindtlsbindport = 5062

2. Ensure other paths (spooldir, pcapdir, etc.) point to appropriate locations on the new hardware

Step 5: Run Migration Instance

Once configuration is restored and the migration config is prepared, start the migration instance:

# Start the migration instance
voipmonitor --voipmonitor-config /etc/voipmonitor-migrate.conf

# Or using systemd (if configured)
systemctl start voipmonitor- migrate.service

The migration instance will process and migrate data using the restored configuration while avoiding conflicts with any running original sniffer.

ℹ️ Note: After migration is complete, you can switch over to the new hardware by starting the standard voipmonitor service with the main `voipmonitor.conf` configuration file.

AI Summary for RAG

Summary: This guide provides comprehensive guidance on backing up the VoIPmonitor GUI configuration using two methods: a quick web interface method for one-time backups before upgrades, and an automated CLI script method for scheduled daily backups. The web interface method accessed via GUI → Tools → Backup & restore allows users to select "configuration tables" (backing up all database settings made by GUI users including users, sensors, capture rules, alerts, dashboards, reports) and "configuration files" (backing up GUI configuration files like configuration.php). The CLI script method uses the `run.php` command-line tool to export configuration tables, data tables, and PHP configuration files, with automatic cleanup of old backups. The guide details creating the backup script, scheduling it with cron for Automated daily backups at 3:30 AM, and includes restoration methods using both the GUI web interface and CLI commands (`restoreGuiTables`, `mysql` import). Critical restoration information specifies what IS transferred (user accounts, permissions, sensor definitions, alert definitions, filters, dashboards) and what is NOT transferred (assignments of alerts to sensors, reports to sensors, sensor user access permissions, captured call data and PCAP files). The restore operation overwrites, not merges, existing data. The guide also covers a specialized procedure for importing only dashboards from one GUI instance to another by extracting and importing the `custom_config` table, noting that folder structures are not preserved and ownership may need adjustment. Troubleshooting guidance is included for scenarios where alerts disappear after upgrades (restore configuration tables via GUI). Additionally, the guide now includes a complete simple migration procedure for EOL systems: (1) backup GUI config using `php php/run.php backupGuiTables -t config -f backup.zip`, (2) backup `/etc/voipmonitor.conf` and `configuration.php`, (3) fresh install on new server with modern OS (Debian 12/Ubuntu 22.04), (4) restore all configurations on new system, (5) test with subset of traffic before full migration. This simple method is recommended for EOL OS when you do not need historical data migrated. A separate complex migration method with voipmonitor-migrate.conf is documented for scenarios requiring historical data transfer or zero-downtime migration, covering GUI backup/restore, creating `voipmonitor-migrate.conf`, and configuring parallel operation by changing `managerport` and disabling ALL `bind*` options. A new critical warning section on MySQL/MariaDB version differences explains that when migrating between servers with significantly different database versions, do not use mysqldump directly for the main CDR database. Instead, use a VoipMonitor migration instance with `voipmonitor-migrate.conf` to migrate via a temporary backup database on the new server (two-step process: old server to temporary DB, then temporary DB to final DB), which handles schema version differences automatically. GUI configuration tables typically have stable schemas and can be migrated directly without issues. As an alternative for smaller databases, mysqldump can be used with the `--compatible` option (e.g., `--compatible=mysql57` for MySQL 5.7 to 8.0 migration), though this may not work for all schema changes. Keywords: backup, restore, configuration, gui, settings, users, sensors, capture rules, cron, crontab, automation, disaster recovery, dashboard, migration, upgrade, `run.php`, `backupGuiTables`, `restoreGuiTables`, `backupGuiConfigurationFiles`, mysql, import, export, custom_config, overwrite, merge, assignment, not transferred, web interface, tools menu, quick backup, EOL, end-of-life, fresh installation, new server, `/etc/voipmonitor.conf`, `configuration.php`, Debian 12, Bookworm, Ubuntu 22.04, subset traffic, hardware migration, `voipmonitor-migrate.conf`, migration instance, parallel operation, `managerport`, `bind* options`, conflicts, mysql version, mariadb version, database version, version mismatch, `--compatible`, temporary database, schema differences, CDR migration, mysqldump, database dump, database restore, full database migration, CDRs, online migration, downtime Key Questions:

  • How do I back up my VoIPmonitor GUI before an upgrade?
  • How do I back up GUI settings using the web interface?
  • How do I migrate VoIPmonitor to new hardware?
  • How do I migrate VoIPmonitor from an EOL operating system?
  • How do I perform a fresh installation migration to a new server?
  • What files do I need to backup when migrating VoIPmonitor?
  • How do I restore voipmonitor.conf and configuration.php on a new server?
  • How do I backup GUI configuration using backupGuiTables?
  • How do I test new VoIPmonitor installation with subset of traffic?
  • When should I use simple fresh installation migration vs voipmonitor-migrate.conf?
  • What is the voipmonitor-migrate.conf file?
  • How do I run VoIPmonitor migration in parallel with the original sniffer?
  • How do I configure voipmonitor-migrate.conf to avoid conflicts?
  • What managerport should I use for migration instance?
  • Do I need to change bind* options when running migration instance?
  • When should I backup GUI configuration before migration?
  • Can I run original sniffer and migration instance simultaneously?
  • How do I migrate the full database including CDRs using mysqldump?
  • What is the dump/restore method for GUI database migration?
  • How do I migrate GUI database with acceptable downtime?
  • How do I perform online GUI migration with minimal downtime?
  • Where is the backup and restore menu in the GUI?
  • What do "configuration tables" contain in the GUI backup?
  • What do "configuration files" contain in the GUI backup?
  • How can I save all my users, sensors, and settings?
  • Is there a script to automatically back up VoIPmonitor settings?
  • How do I schedule a daily backup using cron?
  • How do I restore my GUI configuration from a backup?
  • What does the `backupGuiTables` command do?
  • What does the `restoreGuiTables` command do?
  • Does this backup include my call recordings (CDRs/PCAPs)?
  • If alerts disappear after an upgrade, how do I restore them?
  • How do I import only dashboards from one GUI to another without importing sensors or filters?
  • Which table contains dashboard configurations in VoIPmonitor?
  • How do I extract only the custom_config table from a GUI backup?
  • Are sensor assignments preserved during restore?
  • Do I need to reconfigure alert to sensor assignments after migration?
  • Does the restore merge or overwrite existing data?
  • Can I transfer user accounts to a new VoIPmonitor instance?
  • How do I migrate VoIPmonitor when MySQL versions differ between servers?
  • What should I do if database versions are different during migration?
  • Can I use mysqldump when migrating between different MySQL versions?
  • How do I use voipmonitor-migrate.conf for database version migration?
  • What is the temporary database migration method?
  • Do I need to migrate GUI config differently when MySQL versions differ?
  • Can I use mysqldump --compatible for database migration?