Backing Up GUI Configuration: Difference between revisions

From VoIPmonitor.org
(Clarify distinction between -t config and -t data backup types (custom_config/dashboards are in -t config))
(Rewrite: consolidated structure, removed redundancy, added quick reference table)
 
Line 1: Line 1:
{{DISPLAYTITLE:Backing Up GUI Configuration}}
{{DISPLAYTITLE:Backing Up GUI Configuration}}


'''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.'''
This guide covers backing up and restoring VoIPmonitor GUI configuration data (users, sensors, alerts, dashboards). It does '''not''' cover CDR/PCAP data backup.


== Overview ==
== Quick Reference ==
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:
{| class="wikitable"
#'''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.
|-
#'''Data Tables:''' Supporting data like saved reports.
! Task !! Method !! Command/Path
#'''Configuration Files:''' The PHP configuration files from the GUI directory itself (e.g., `configuration.php`).
|-
| One-time backup || GUI || '''Tools → Backup & restore''' → select "configuration tables" + "configuration files"
|-
| Automated backup || CLI || <code>php run.php backupGuiTables -t config -f backup.sql</code>
|-
| Restore || GUI || '''Tools → Backup & restore''' → "restore"
|-
| Restore || CLI || <code>php run.php restoreGuiTables -t config -f backup.sql</code>
|}


== Quick Backup via GUI Web Interface ==
'''What Gets Backed Up:'''
* '''Configuration Tables:''' Users, sensors, capture rules, alerts, dashboards, reports
* '''Configuration Files:''' PHP config files (<code>configuration.php</code>)


For a quick backup before an upgrade, you can use the built-in GUI backup feature directly from the web interface.
{{Warning|1=Restoring '''overwrites''' existing settings. Perform on fresh GUI or accept data loss.}}


{{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.}}
== GUI Backup (Quick Method) ==


'''Steps:'''
Ideal for one-time backups before upgrades or migrations.


# Open the VoIPmonitor GUI web interface
# Navigate to '''GUI → Tools → Backup & restore'''
# Navigate to '''GUI → Tools → Backup & restore'''
# Select ''':backup GUI: configuration tables''' to back up all database settings made by GUI users and administrators
# Select "'''backup GUI: configuration tables'''"
# Select ''':backup GUI: configuration files''' to back up GUI configuration files
# Select "'''backup GUI: configuration files'''"
# Perform the backup
# Click backup and download the generated file
# Download the generated backup file to a safe location


'''What Gets Backed Up:'''
'''To Restore:'''
 
* '''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):
# Navigate to '''GUI → Tools → Backup & restore'''
# Navigate to '''GUI → Tools → Backup & restore'''
# Select ''':restore GUI: configuration tables'''
# Select "'''restore'''"
# Upload and select the backup file created earlier
# Upload the backup file


{{Warning|Restoring will overwrite existing GUI settings. Only perform this on a freshly installed GUI or be prepared to lose current configurations.}}
== Automated CLI Backup ==


== Automated Daily Backup Using CLI Script ==
For production environments requiring scheduled backups.


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.
=== Backup Script ===


First, create a shell script that will run the export commands.
Create <code>/usr/local/sbin/backup_voipmonitor_gui.sh</code>:


'''Create and edit the script file:'''
<syntaxhighlight lang="bash">
nano /usr/local/sbin/backup_voipmonitor_gui.sh
</syntaxhighlight>
'''Copy and paste the following content into the file:'''
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
#!/bin/bash
#!/bin/bash
#
# VoIPmonitor GUI Configuration Backup Script
# VoIPmonitor GUI Configuration Backup Script
#


# --- Configuration ---
# Set the base directory where backups will be stored
BACKUP_DIR="/var/backups/voipmonitor_gui"
BACKUP_DIR="/var/backups/voipmonitor_gui"
# Set the retention period in days. Backups older than this will be deleted.
RETENTION_DAYS=30
RETENTION_DAYS=30
RUN_SCRIPT="/var/www/html/php/run.php"
DAY=$(date "+%Y-%m-%d")


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


# Set the filename based on the current date
# Export configuration and data tables
DAY=$(date "+%Y-%m-%d")
php "$RUN_SCRIPT" backupGuiTables -t config -f "$BACKUP_DIR/config_tables-${DAY}.sql"
FILE_CFG_TABLES="$BACKUP_DIR/config_tables-${DAY}.sql"
php "$RUN_SCRIPT" backupGuiTables -t data -f "$BACKUP_DIR/data_tables-${DAY}.sql"
FILE_DATA_TABLES="$BACKUP_DIR/data_tables-${DAY}.sql"
php "$RUN_SCRIPT" backupGuiConfigurationFiles -f "$BACKUP_DIR/config_files-${DAY}.tar.gz"
FILE_CFG_FILES="$BACKUP_DIR/config_files-${DAY}.tar.gz"


# Path to the GUI's run.php script
# Cleanup old backups
RUN_SCRIPT="/var/www/html/php/run.php"
find "$BACKUP_DIR" -type f -mtime +"$RETENTION_DAYS" \( -name '*.sql' -o -name '*.tar.gz' \) -delete


echo "--- Starting VoIPmonitor GUI Backup for ${DAY} ---"
echo "Backup complete: $BACKUP_DIR"
</syntaxhighlight>


# Export the configuration and data tables as SQL dumps
=== Setup ===
# Note: -t config includes tables like users, sensors, alerts, and custom_config (dashboards)
# Note: -t data includes supporting data like saved reports
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 ---"
</syntaxhighlight>


=== Step 1: Make the Script Executable and Test It ===
Set the correct permissions so the script can be run.
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Make executable and test
chmod +x /usr/local/sbin/backup_voipmonitor_gui.sh
chmod +x /usr/local/sbin/backup_voipmonitor_gui.sh
</syntaxhighlight>
/usr/local/sbin/backup_voipmonitor_gui.sh
You can test the script by running it manually: <code>/usr/local/sbin/backup_voipmonitor_gui.sh</code>. It should create three new files in <code>/var/backups/voipmonitor_gui</code>.


=== Step 2: Schedule the Automated Backup with Cron ===
# Schedule daily at 3:30 AM
 
The final step is to create a cron job to run the script automatically every night.
 
'''Edit the system's crontab file:'''
<syntaxhighlight lang="bash">
crontab -e
crontab -e
# Add: 30 3 * * * /usr/local/sbin/backup_voipmonitor_gui.sh > /var/log/voipmonitor_backup.log 2>&1
</syntaxhighlight>
</syntaxhighlight>


'''Add the following line to the end of the file:'''
=== CLI Restore ===
 
This example will run the backup script every day at 3:30 AM.
<syntaxhighlight lang="bash">
30 3 * * * /usr/local/sbin/backup_voipmonitor_gui.sh > /var/log/voipmonitor_backup.log 2>&1
</syntaxhighlight>
* 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:'''
<syntaxhighlight lang="bash">
cd /var/www/html
php php/run.php backupGuiTables -t config -f /tmp/old_gui_config.sql
</syntaxhighlight>
 
'''New GUI Server:'''
<syntaxhighlight lang="bash">
cd /var/www/html
php php/run.php backupGuiTables -t config -f /tmp/new_gui_config.sql
</syntaxhighlight>
 
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:
 
<syntaxhighlight lang="bash">
# 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
</syntaxhighlight>
 
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 <code>/tmp/custom_config_only.sql</code> file:
 
<syntaxhighlight lang="bash">
nano /tmp/custom_config_only.sql
</syntaxhighlight>
 
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:


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
cd /var/www/html
cd /var/www/html
mysql -u voipmonitor_user -p voipmonitor < /tmp/custom_config_only.sql
</syntaxhighlight>
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:'''
<syntaxhighlight lang="bash">
cd /var/www/html
</syntaxhighlight>
'''2. Restore the configuration tables:'''
<syntaxhighlight lang="bash">
php php/run.php restoreGuiTables -t config -f /var/backups/voipmonitor_gui/config_tables-YYYY-MM-DD.sql
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
php php/run.php restoreGuiTables -t data -f /var/backups/voipmonitor_gui/data_tables-YYYY-MM-DD.sql
</syntaxhighlight>


'''3. Restore the Configuration Files:'''
# Restore config files
 
tar xzf /var/backups/voipmonitor_gui/config_files-YYYY-MM-DD.tar.gz -C /var/www/html/
Extract the backed-up PHP configuration files into your GUI's web root.
<syntaxhighlight lang="bash">
# Extract the archive, overwriting existing files
tar xzf /var/backups/voipmonitor_gui/config_files-YYYY-MM-DD.tar.gz
</syntaxhighlight>
 
=== Method 3: Manual MySQL Import ===
 
Alternatively, you can use the <code>mysql</code> command-line client to import the saved SQL dumps.
 
'''1. Restore the Database Tables:'''
<syntaxhighlight lang="bash">
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
</syntaxhighlight>
 
'''2. Restore the Configuration Files:'''
 
Extract the backed-up PHP configuration files into your GUI's web root.
<syntaxhighlight lang="bash">
# 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
</syntaxhighlight>
 
After restoring both the database and files, your GUI's configuration should be fully recovered.
 
=== Important: Cross-OS and Cloud Migration Considerations ===
 
When migrating VoIPmonitor to a new environment such as Azure or another cloud provider where the destination OS version may differ from the source, '''do NOT clone or copy binaries''' between servers. Instead, use a fresh installation approach:
 
'''Key Steps for Cross-OS Migration:'''
# '''Fresh Installation''': Install VoIPmonitor from scratch on the new server using the official installer for the new OS distribution
# '''Backup GUI Settings''': Use the GUI backup/restore feature to transfer users, sensors, alerts, dashboards, templates, and reports (see [[#Quick Backup via GUI Web Interface|above]])
# '''Backup Configuration Files''': Save <code>voipmonitor.conf</code> and GUI configuration files
# '''Database Migration''': Use mysqldump or a migration instance to transfer CDRs
# '''Copy Spool Directory''': Transfer <code>/var/spool/voipmonitor</code> (captures and recordings) using rsync
# '''GUI PHP Version Dependency''': The GUI application is PHP version dependent. When installing on the new server, download the GUI package that matches the PHP version on the destination OS. See [[Re-install_the_GUI|Reinstall the GUI]] for detailed guidance on handling PHP version changes.
 
{{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:
# Run a VoipMonitor migration instance using <code>voipmonitor-migrate.conf</code>
# Configure the migration instance to read from the old database
# Set the migration destination to a temporary backup database on the new server
# After migration completes, run a second migration instance to move data from the temporary database to the final destination database
# This approach handles schema version differences automatically
 
'''Solution 2: Use mysqldump --compatible Option'''
 
For smaller databases, you can use mysqldump with compatibility options:
<syntaxhighlight lang="bash">
# Example for MySQL 5.7 to 8.0 migration
mysqldump -u root -p --compatible=mysql57 voipmonitor > backup.sql
</syntaxhighlight>
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:
# Backing up GUI configuration tables
# Backing up configuration files
# Installing VoIPmonitor on the new server
# Restoring configuration on the new system
# 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:
<syntaxhighlight lang="bash">
cd /var/www/html
php php/run.php backupGuiTables -t config -f backup.zip
</syntaxhighlight>
</syntaxhighlight>


This command exports all GUI settings including:
== What IS and IS NOT Transferred ==
* User accounts and permissions
* Sensor definitions
* Capture rules
* Dashboard configurations
* Alert definitions
 
'''2. Backup Sniffer Configuration Files:'''
 
Copy the main configuration file:
<syntaxhighlight lang="bash">
cp /etc/voipmonitor.conf /tmp/voipmonitor.conf.backup
</syntaxhighlight>
 
'''3. Backup GUI Configuration File:'''
 
<code>configuration.php</code> contains GUI-specific settings. Copy it from your GUI directory:
<syntaxhighlight lang="bash">
cp /var/www/html/voipmonitor/configuration.php /tmp/configuration.php.backup
# Note: Adjust the path if your GUI is installed in a different location
</syntaxhighlight>
 
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|Sniffer Installation Guide]] for the sensor component and the [[GUI_installation|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:'''
<syntaxhighlight lang="bash">
cp voipmonitor.conf.backup /etc/voipmonitor.conf
</syntaxhighlight>
 
'''2. Restore the GUI Configuration File:'''
<syntaxhighlight lang="bash">
cp configuration.php.backup /var/www/html/voipmonitor/configuration.php
</syntaxhighlight>
 
'''3. Restore GUI Configuration Tables:'''
 
{{Warning|1=If you applied a <strong>trial license</strong> on the new system, you must <strong>exclude the 'system' table</strong> when restoring to preserve the trial license. Restoring the 'system' table will overwrite the trial license with the old system's license.}}
 
{{Note|The standard web interface restore does not provide an option to exclude specific tables. If you need to exclude the 'system' table to preserve a trial license, use the CLI method below.}}
 
<syntaxhighlight lang="bash">
cd /var/www/html
 
# Standard restore (overwrites all tables including license)
php php/run.php restoreGuiTables -t config -f backup.zip
 
# To exclude 'system' table (preserves trial license):
php php/run.php restoreGuiTables -t config -f backup.zip --exclude-table system
</syntaxhighlight>
 
'''4. Configure Sniffer Parameters:'''
 
Edit the sniffer configuration file for the new environment:
 
<syntaxhighlight lang="bash">
nano /etc/voipmonitor.conf
</syntaxhighlight>
 
Update these parameters to match the new server configuration:
 
<syntaxhighlight lang="ini">
# Update network interface for packet capture
interface = eth0
 
# Update spool directory path (if different)
spooldir = /var/spool/voipmonitor
 
# Adjust maxpoolsize based on new disk capacity
maxpoolsize = 1000000000
 
# Set server_bind if this is a central server for remote sensors
server_bind = 0.0.0.0
server_bind_port = 60024
</syntaxhighlight>
 
Alternatively, you can use the web interface to configure the backup file.
 
=== Step 4: Configure Remote Probes ===
 
If you have remote probes in a distributed (client-server) deployment, update the configuration on each probe to point to the new central server:
 
<syntaxhighlight lang="bash">
# On each remote probe
nano /etc/voipmonitor.conf
</syntaxhighlight>
 
Update the <code>server_destination</code> parameter:
 
<syntaxhighlight lang="ini">
# Update to the new central server IP
server_destination = NEW.CENTRAL.SERVER.IP
server_destination_port = 60024
</syntaxhighlight>
 
After updating, restart the probe service:
 
<syntaxhighlight lang="bash">
systemctl restart voipmonitor
</syntaxhighlight>
 
Verify the probe appears as connected in GUI → Settings → Sensors.
 
=== Step 5: Start and Verify ===
 
Start the service and verify it is functioning correctly:
<syntaxhighlight lang="bash">
systemctl start voipmonitor
systemctl status voipmonitor
</syntaxhighlight>
 
Monitor the logs to ensure the service starts without errors:
<syntaxhighlight lang="bash">
journalctl -u voipmonitor -f
</syntaxhighlight>
 
=== Step 6: Test with Subset of Traffic ===
 
Before fully migrating or decommissioning the old system:
 
# Configure network capture to monitor a subset of your traffic (using the [[Capture_rules|capture rules]] or by mirroring only specific VLANs/ports)
# Verify that calls are appearing in the GUI
# Check for RTP capture issues that were present on the old system
# Play back recorded calls to confirm audio quality
 
Once you are satisfied that the new system is functioning correctly:
 
# Expand monitoring to full traffic if needed
# Move your paid license to the new system:
## If you used a trial license on the new system, cancel the trial from voipmonitor.org
## Copy the paid license token from the old system to the new system via GUI → Settings → License
## Or navigate to voipmonitor.org, download the license key file, and upload to the new system
# Decommission the old VoIPmonitor installation:
## Stop the service: <code>systemctl stop voipmonitor</code>
## Disable the service: <code>systemctl disable voipmonitor</code>
## Verify the old system is no longer accessible (optional for security)
 
=== 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 [[#Migrating_VoIPmonitor_to_New_Hardware|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 [[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) ==
 
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:
# Backing up GUI configuration (must be done BEFORE starting migration)
# Restoring GUI configuration on the new server
# Running a migration instance using <code>voipmonitor-migrate.conf</code>
# 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:
 
# On the old GUI, navigate to '''GUI → Tools → Backup & restore'''
# Select ''':backup GUI: configuration tables''' to back up all database settings (users, sensors, capture rules, dashboards, etc.)
# Download the generated backup file
 
=== Step 2: Restore Configuration on New Hardware ===
 
On the NEW server:
 
# Install VoIPmonitor Sniffer and GUI following the standard installation guide
# 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 <code>voipmonitor.conf</code> with migration-specific options added.
 
'''Create the migration configuration file:'''
<syntaxhighlight lang="bash">
cp /etc/voipmonitor.conf /etc/voipmonitor-migrate.conf
</syntaxhighlight>
 
{{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 <code>voipmonitor-migrate.conf</code> and modify these settings to avoid conflicts:'''
<syntaxhighlight lang="ini">
# 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
</syntaxhighlight>
 
'''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:
 
<syntaxhighlight lang="bash">
# Start the migration instance
voipmonitor --config-file /etc/voipmonitor-migrate.conf
 
# Or using systemd (if configured)
systemctl start voipmonitor-migrate.service
</syntaxhighlight>
 
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 <code>voipmonitor.conf</code> configuration file.}}
 
== Troubleshooting: Backup Fails with "errno 28" (No Space Left on Device) ==
 
If the GUI backup feature fails with the error '''"Got errno 28 on write"''', this is a standard system message indicating '''"No space left on device"'''. This means the disk partition where MySQL creates temporary files during the backup process is full.
 
{| class="wikitable" style="background-color: #FFF3CD;"
|-
! colspan="2" style="background: #856404; color: white;" | Common Cause: Disk Full During Backup
|-
! Symptom
| Backup via '''GUI → Tools → Backup & restore''' fails with errno 28, even though other operations work.
|-
! Root Cause
| MySQL uses temporary files for backup operations. If the partition containing MySQL's temporary directory (default <code>/tmp</code>) or the data directory (<code>/var/lib/mysql</code>) is full, the backup fails.
|}
 
=== Diagnosis: Check Disk Space on All Partitions ===
 
<syntaxhighlight lang="bash">
df -h
</syntaxhighlight>
 
Check if the partition containing <code>/tmp</code> or <code>/var/lib/mysql</code> is full.
 
=== Resolution: Use Smaller "Configuration Tables" Backup ===
 
If you cannot immediately free up disk space, you can still back up your critical GUI settings by selecting the smaller ''':backup GUI: configuration tables''' option instead of the full data tables backup.


{| class="wikitable"
{| class="wikitable"
|-
|-
! Backup Type !! Size !! Contents !! Use Case
! Transferred !! NOT Transferred
|-
| '''Configuration Tables''' | Small (typically 1-10 MB) | Users, sensors, capture rules, alerts, dashboards, reports | Recommended for errno 28 issues. Contains all essential GUI settings.
|-
| '''Data Tables''' | Large (can be 100+ MB) | Supporting data like saved reports | Not critical for disaster recovery if space is limited.
|-
|-
| '''Configuration Files''' | Small (KB range) | PHP configuration files | Backup separately (tarball of GUI config files).
| User accounts, permissions, groups || '''Alert-to-sensor assignments''' (reconfigure manually)
|}
 
'''Steps to Perform Smaller Backup:'''
 
# Open the VoIPmonitor GUI web interface
# Navigate to '''GUI → Tools → Backup & restore'''
# Select ONLY ''':backup GUI: configuration tables'''
# Select ''':backup GUI: configuration files''' if needed
# Perform the backup
# Download the generated backup file to a safe location
 
This configuration tables backup contains all the critical settings needed to restore your GUI configuration after an upgrade or migration, while requiring much less disk space to generate.
 
=== Alternative Solutions ===
 
If you need to perform a full backup including data tables:
 
*'''Free up disk space:''' Check which partition is full using <code>df -h</code> and remove unnecessary files.
 
*'''Change MySQL temporary directory:''' If <code>/tmp</code> is full but other partitions have space, configure MySQL to use a different temporary directory. See [[Data_Cleaning]] for detailed instructions on MySQL tmpdir configuration.
 
For more information on disk space management and MySQL Error 28 troubleshooting, see [[Data_Cleaning#MySQL_Error_28:_No_Space_Left_on_Device|Data Cleaning Guide]].
 
== Troubleshooting: GUI Backup Breaks GTID Replication ==
 
If your MySQL/MariaDB database uses '''GTID (Global Transaction Identifier) replication''' and restoring a GUI configuration backup breaks replication, this is caused by the default mysqldump behavior which includes GTID information in the backup file.
 
{| class="wikitable" style="background-color: #FFF3CD;"
|-
|-
! colspan="2" style="background: #856404; color: white;" | GTID Replication Breaks After Backup Restore
| Sensor definitions || '''Report-to-sensor assignments''' (reconfigure manually)
|-
|-
! Symptom
| Alert/report definitions || '''Sensor user access permissions''' (reassign manually)
| Restoring a GUI configuration backup causes GTID-based replication to fail or become inconsistent.
|-
|-
! Root Cause
| Dashboards, capture rules, filters || CDR data, PCAP files
| mysqldump includes <code>SET @@GLOBAL.gtid_purged='...'</code> statements by default, which modify the GTID state on restore and break replication tracking.
|}
|}


=== Solution: Configure mysqldump to Exclude GTID Information ===
{{Note|1=Restore '''replaces''' data, it does NOT merge. Users/sensors with same ID are overwritten.}}


The GUI provides a setting to pass additional parameters to the mysqldump binary used during backup operations.
== Dashboard-Only Migration ==


'''Steps to Configure:'''
To transfer only dashboards between GUI instances without other settings.


# Open the VoIPmonitor GUI web interface
=== Simple Method (GUI) ===
# Navigate to '''Settings > System Configuration > Database'''
# Find the field labeled '''Extra parameters for mysqldump binary'''
# Enter the parameter: <code>--set-gtid-purged=OFF</code>
# Save the configuration at the bottom of the page
# Create a new backup using this setting. This backup can now be restored without breaking replication.


{{Note|1=The <code>--set-gtid-purged=OFF</code> parameter tells mysqldump to exclude GTID transactions from the SQL dump file. This prevents the restore operation from modifying the GTID state of the target server, preserving replication consistency.}}
Use standard '''Backup & restore''' - this transfers dashboards along with other config. Users are included.


=== What Happens Without This Setting ===
=== Advanced Method (SQL Extraction) ===


By default, mysqldump includes a statement like this in the dump file:
Dashboards are stored in the <code>custom_config</code> table.


<syntaxhighlight lang="sql">
<syntaxhighlight lang="bash">
-- GTID state at the beginning of the backup
# On source server: create backup
SET @@GLOBAL.gtid_purged='3E11FA47-71CA-11E1-9E33-C80AA9429562:1-5';
cd /var/www/html
</syntaxhighlight>
php php/run.php backupGuiTables -t config -f /tmp/old_config.sql
 
When you restore this dump on a server participating in GTID replication, this statement modifies the GTID state, which can cause:
 
* Replication conflicts between master and slave
* Error messages about inconsistent GTID state
* Replication thread stopping or failing to start
 
With <code>--set-gtid-purged=OFF</code>, this statement is not included in the backup, and replication remains unaffected.


=== Alternative: Manual mysqldump Workaround ===
# Extract only custom_config INSERT statements
grep "^INSERT INTO \`custom_config\`" /tmp/old_config.sql > /tmp/dashboards_only.sql


If you prefer not to use the GUI backup feature, you can manually dump and restore with the correct options:
# On target server: import
 
mysql -u voipmonitor_user -p voipmonitor < /tmp/dashboards_only.sql
'''Manual backup (recommended for GTID environments):'''
<syntaxhighlight lang="bash">
mysqldump -u root -p \
  --set-gtid-purged=OFF \
  voipmonitor \
  users sensors capture_rules alerts custom_config \
  > gui_config_backup.sql
</syntaxhighlight>
</syntaxhighlight>


'''Manual restore:'''
{{Note|Folder structures are NOT preserved. Recreate folders manually after import.}}
<syntaxhighlight lang="bash">
mysql -u root -p voipmonitor < gui_config_backup.sql
</syntaxhighlight>


This approach gives you full control over the mysqldump command and ensures GTID data is never included in the backup.
== Server Migration ==


=== Related Documentation ===
=== Fresh Installation Method (Recommended) ===


For more information on GTID replication concepts:
Best for EOL systems or when historical data is not needed.
* [[Mysql_master-slave_replication_hints|MySQL Master-Slave Replication Hints]]
* [[Mysql_master-master_replication_hints|MySQL Master-Master Replication Hints]]


== Migrating Alerts and Reports Between Cloud Tokens ==
# '''Backup on old server:'''
#* GUI config: '''Tools → Backup & restore''' → "configuration tables"
#* Sniffer config: <code>cp /etc/voipmonitor.conf /tmp/</code>
#* GUI PHP config: <code>cp /var/www/html/*/configuration.php /tmp/</code>
# '''Fresh install on new server''' (see [[Sniffer_installation]], [[GUI_installation]])
# '''Restore configuration:'''
#* GUI: '''Tools → Backup & restore''' → "restore"
#* Sniffer: <code>cp voipmonitor.conf.backup /etc/voipmonitor.conf</code>
#* Update <code>interface</code>, <code>spooldir</code>, <code>server_bind</code> for new environment
# '''Update remote probes''' (if distributed): Change <code>server_destination</code> to new server IP
# '''Test with subset of traffic''' before full cutover


This section describes how to transfer custom alerts, reports, dashboards, and other GUI configurations from one cloud token to another in the VoIPmonitor Cloud Service.
{{Tip|1=To preserve trial license on new system, use CLI restore with <code>--exclude-table system</code>}}


=== Background: Each Cloud Token Has Its Own Database ===
=== Data Migration Method ===


In the VoIPmonitor Cloud Service, each cloud token is associated with a separate cloud database instance. When you switch to a new cloud token, your custom configurations (alerts, reports, dashboards) remain in the old database and are not automatically transferred to the new token.
For transferring historical CDR data with minimal downtime. See [[Redundant_database]] for:
* '''Dump/Restore:''' Simple <code>mysqldump</code> with downtime
* '''Online Migration:''' Use <code>voipmonitor-migrate.conf</code> for zero-downtime sync


{{Note|Your custom alerts, reports, and other GUI configurations are stored in the cloud database. Switching cloud tokens means switching databases, which is why configurations appear missing after changing tokens.}}
=== Cross-OS / Cloud Migration ===


=== Migration Procedure Using Temporary Trial License ===
{{Warning|1=Do NOT clone binaries between different OS versions. Always perform fresh installation.}}


To migrate configurations from one cloud token to another, follow this step-by-step procedure:
* Download GUI package matching destination PHP version (see [[Re-install_the_GUI]])
* For database version mismatches, use migration instance instead of direct mysqldump


;Step 1: Contact VoIPmonitor Support
== Cloud Token Migration ==


* Contact VoIPmonitor support and request a temporary trial cloud license
Each cloud token has its own database. To migrate alerts/reports between tokens:
* Explain that you need to migrate configurations from an old cloud token to a new one
* Support will create a temporary cloud license for you to use during this process


;Step 2: Restore Old Cloud Database to Temporary License
# '''Contact VoIPmonitor support''' - request temporary trial cloud license
# '''Support restores''' old database to temporary license
# '''Export config''' from temporary license via '''Backup & restore'''
# '''Import config''' to new license via '''Backup & restore'''
# '''Restart sniffers:''' <code>systemctl restart voipmonitor</code>


* Request that VoIPmonitor support restore a database backup from your old cloud token to this temporary trial license
{{Note|Alert-to-sensor assignments must be reconfigured manually after migration.}}
* Once complete, you will have temporary access to the old database containing your original configurations


;Step 3: Access GUI with Temporary License
== Troubleshooting ==


* Log in to the VoIPmonitor Cloud GUI using your the temporary trial license credentials
=== Backup Fails with "errno 28" (Disk Full) ===
* Your original custom alerts, reports, and configurations should now be visible


;Step 4: Export Configuration from Old Database
MySQL needs temp space for backup operations.


* Navigate to '''GUI → Tools → Backup & restore'''
'''Solution:''' Use smaller "configuration tables" backup instead of "data tables":
* Select ''':backup GUI: configuration tables''' to back up all database settings
* Configuration tables: ~1-10 MB (contains all essential settings)
* This includes alerts, reports, dashboards, users, sensors, and other GUI configurations
* Data tables: 100+ MB (supporting data, not critical)
* Download the generated configuration file


;Step 5: Import Configuration to New License
Check disk space: <code>df -h</code> (look at <code>/tmp</code> and <code>/var/lib/mysql</code>)


* Log in to the VoIPmonitor Cloud GUI using your new, permanent cloud license
=== Backup Breaks GTID Replication ===
* Navigate to '''GUI → Tools → Backup & restore'''
* Select ''':restore GUI: configuration tables'''
* Upload and select the configuration file you downloaded from the temporary license


{{Warning|1=Restoring will overwrite existing GUI settings in the new license. Only perform this if the new license has minimal or no customizations, or if you want to replace them with the old configurations.}}
mysqldump includes GTID state by default, breaking replication on restore.


;Step 6: Restart All Sniffer Services
'''Solution:''' Configure mysqldump to exclude GTID:
 
# '''Settings → System Configuration → Database'''
After restoring the configuration, restart all sniffer services to force them to reload the updated configuration from the cloud database:
# Set '''Extra parameters for mysqldump binary:''' <code>--set-gtid-purged=OFF</code>
# Save and create new backup


Or manually:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Restart the voipmonitor service
mysqldump -u root -p --set-gtid-purged=OFF voipmonitor users sensors alerts custom_config > backup.sql
systemctl restart voipmonitor
 
# Verify the service is running
systemctl status voipmonitor
</syntaxhighlight>
</syntaxhighlight>


Your cloud sniffers should now be using the migrated configurations (alerts, reports, dashboards) from the old cloud token.
=== Alerts/Reports Missing After Upgrade ===
 
=== Important Notes ===
 
* '''This requires VoIPmonitor support intervention''' - Only support can restore database backups to a temporary license
* '''Contact support before switching tokens** - If you know you will be switching cloud tokens, consult with support about migration options before making the switch
* '''Temporary license has a limited lifespan** - Complete the migration promptly while the temporary license is active
* '''Alert-to-sensor assignments are NOT included** - After restoring, you may need to manually reassign alerts to specific sensors in the new GUI


=== What Gets Transferred ===
Restore from backup created before upgrade:
# '''Tools → Backup & restore''' → "restore" → upload pre-upgrade backup
# Reconfigure alert-to-sensor assignments manually


The configuration tables backup includes:
== See Also ==
* Alert definitions and thresholds
* Report definitions
* Dashboard configurations
* User accounts and permissions
* Sensor definitions
* Capture rules and filters
* Custom GUI settings


As noted in the [[#IMPORTANT:_What_IS_and_IS_NOT_Transferred|What IS and IS NOT Transferred]] section above, alert-to-sensor assignments and report-to-sensor assignments are not included in the backup and must be reconfigured manually after restoration.
* [[Redundant_database]] - Database replication and online migration
* [[Re-install_the_GUI]] - GUI reinstallation for PHP version changes
* [[Disaster_Recovery]] - Complete disaster recovery procedures
* [[Data_Cleaning]] - Disk space management


== AI Summary for RAG ==
== AI Summary for RAG ==


'''Summary:''' Guide for backing up VoIPmonitor GUI configuration. Two methods: (1) '''GUI method''' via '''GUI → Tools → Backup & restore''' for one-time backups - select "configuration tables" and "configuration files". (2) '''CLI method''' using <code>backupGuiTables</code> command with cron for automated daily backups. Restoration via GUI or CLI (<code>restoreGuiTables</code>). Critical: restore '''overwrites''' existing data. What IS transferred: user accounts, permissions, sensor definitions, alerts, dashboards. What is NOT transferred: alert-to-sensor assignments, report-to-sensor assignments, CDR/PCAP data. For dashboard-only migration: extract <code>custom_config</code> table. For cross-OS/cloud migration: perform fresh install and restore backup. For zero-downtime migration: use <code>voipmonitor-migrate.conf</code> with different <code>managerport</code>. '''Cloud Token Migration: Each cloud token has its own database. To migrate alerts/reports between tokens, contact support for temporary trial license, restore old database to temporary license, export config via Backup & Restore, import to new license, restart sniffers. Requires support intervention for database restore.''' '''Troubleshooting: If backup fails with errno 28 (disk full), use smaller "configuration tables" backup instead of "data tables". For GTID replication environments: Configure '''Settings > System Configuration > Database > Extra parameters for mysqldump binary''' with <code>--set-gtid-purged=OFF</code> to prevent backups from breaking GTID-based MySQL replication.'''
'''Summary:''' VoIPmonitor GUI configuration backup guide. Two methods: (1) GUI via '''Tools → Backup & restore''' for one-time backups, (2) CLI using <code>backupGuiTables</code>/<code>restoreGuiTables</code> commands with cron for automation. Backup includes users, sensors, alerts, dashboards, capture rules. Does NOT include: alert-to-sensor assignments, report-to-sensor assignments, CDR/PCAP data. Restore overwrites existing data. Dashboard-only migration: extract <code>custom_config</code> table. Server migration: fresh install recommended for EOL systems; use [[Redundant_database]] for data migration. Cloud token migration requires support intervention to restore old database to temporary license. Troubleshooting: errno 28 (disk full) - use smaller "configuration tables" backup; GTID replication - set <code>--set-gtid-purged=OFF</code> in mysqldump parameters.


'''Keywords:''' backup, restore, configuration, GUI, settings, users, sensors, capture rules, cron, automation, disaster recovery, dashboard, migration, upgrade, backupGuiTables, restoreGuiTables, custom_config, overwrite, EOL, fresh installation, voipmonitor-migrate.conf, cross-OS, cloud migration, cloud token, cloud database, alerts migration, reports migration, trial license, errno 28, no space left on device, disk full, GTID, global transaction identifier, replication, mysqldump参数, set-gtid-purged, MySQL replication break
'''Keywords:''' backup, restore, configuration, GUI settings, users, sensors, alerts, dashboards, capture rules, backupGuiTables, restoreGuiTables, custom_config, cron automation, migration, disaster recovery, cloud token, GTID replication, errno 28, disk full


'''Key Questions:'''
'''Key Questions:'''
* How do I back up my VoIPmonitor GUI before an upgrade?
* How do I back up VoIPmonitor GUI configuration?
* How do I schedule automated daily backups using cron?
* How do I schedule automated daily GUI backups?
* How do I restore my GUI configuration from a backup?
* How do I restore GUI settings from backup?
* Does this backup include my call recordings (CDRs/PCAPs)?
* What is and is not included in a GUI configuration backup?
* What IS and IS NOT transferred when restoring a backup?
* Does restore merge or overwrite existing data?
* Does the restore merge or overwrite existing data?
* How do I migrate only dashboards between GUI instances?
* How do I import only dashboards from one GUI to another?
* How do I migrate VoIPmonitor to a new server?
* How do I migrate VoIPmonitor to new hardware?
* How do I transfer alerts between cloud tokens?
* How do I migrate VoIPmonitor from an EOL operating system?
* Why does backup fail with errno 28?
* What is voipmonitor-migrate.conf and when should I use it?
* How do I prevent backups from breaking MySQL GTID replication?
* If alerts disappear after an upgrade, how do I restore them?
* What do I do if GUI backup fails with "errno 28" or "no space left on device"?
* How do I perform a backup when disk space is limited?
* How do I prevent GUI backups from breaking MySQL GTID replication?
* What is --set-gtid-purged=OFF and when should I use it?
* How do I migrate custom alerts and reports between cloud tokens?
* Why are my alerts missing after switching to a new cloud token?
* How do I transfer GUI configurations from one cloud database to another?

Latest revision as of 16:48, 8 January 2026


This guide covers backing up and restoring VoIPmonitor GUI configuration data (users, sensors, alerts, dashboards). It does not cover CDR/PCAP data backup.

Quick Reference

Task Method Command/Path
One-time backup GUI Tools → Backup & restore → select "configuration tables" + "configuration files"
Automated backup CLI php run.php backupGuiTables -t config -f backup.sql
Restore GUI Tools → Backup & restore → "restore"
Restore CLI php run.php restoreGuiTables -t config -f backup.sql

What Gets Backed Up:

  • Configuration Tables: Users, sensors, capture rules, alerts, dashboards, reports
  • Configuration Files: PHP config files (configuration.php)

⚠️ Warning: Restoring overwrites existing settings. Perform on fresh GUI or accept data loss.

GUI Backup (Quick Method)

Ideal for one-time backups before upgrades or migrations.

  1. Navigate to GUI → Tools → Backup & restore
  2. Select "backup GUI: configuration tables"
  3. Select "backup GUI: configuration files"
  4. Click backup and download the generated file

To Restore:

  1. Navigate to GUI → Tools → Backup & restore
  2. Select "restore"
  3. Upload the backup file

Automated CLI Backup

For production environments requiring scheduled backups.

Backup Script

Create /usr/local/sbin/backup_voipmonitor_gui.sh: 

#!/bin/bash
# VoIPmonitor GUI Configuration Backup Script

BACKUP_DIR="/var/backups/voipmonitor_gui"
RETENTION_DAYS=30
RUN_SCRIPT="/var/www/html/php/run.php"
DAY=$(date "+%Y-%m-%d")

mkdir -p "$BACKUP_DIR"

# Export configuration and data tables
php "$RUN_SCRIPT" backupGuiTables -t config -f "$BACKUP_DIR/config_tables-${DAY}.sql"
php "$RUN_SCRIPT" backupGuiTables -t data -f "$BACKUP_DIR/data_tables-${DAY}.sql"
php "$RUN_SCRIPT" backupGuiConfigurationFiles -f "$BACKUP_DIR/config_files-${DAY}.tar.gz"

# Cleanup old backups
find "$BACKUP_DIR" -type f -mtime +"$RETENTION_DAYS" \( -name '*.sql' -o -name '*.tar.gz' \) -delete

echo "Backup complete: $BACKUP_DIR"

Setup

# Make executable and test
chmod +x /usr/local/sbin/backup_voipmonitor_gui.sh
/usr/local/sbin/backup_voipmonitor_gui.sh

# Schedule daily at 3:30 AM
crontab -e
# Add: 30 3 * * * /usr/local/sbin/backup_voipmonitor_gui.sh > /var/log/voipmonitor_backup.log 2>&1

CLI Restore

cd /var/www/html
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

# Restore config files
tar xzf /var/backups/voipmonitor_gui/config_files-YYYY-MM-DD.tar.gz -C /var/www/html/

What IS and IS NOT Transferred

Transferred NOT Transferred
User accounts, permissions, groups Alert-to-sensor assignments (reconfigure manually)
Sensor definitions Report-to-sensor assignments (reconfigure manually)
Alert/report definitions Sensor user access permissions (reassign manually)
Dashboards, capture rules, filters CDR data, PCAP files

ℹ️ Note: Restore replaces data, it does NOT merge. Users/sensors with same ID are overwritten.

Dashboard-Only Migration

To transfer only dashboards between GUI instances without other settings.

Simple Method (GUI)

Use standard Backup & restore - this transfers dashboards along with other config. Users are included.

Advanced Method (SQL Extraction)

Dashboards are stored in the custom_config table. 

# On source server: create backup
cd /var/www/html
php php/run.php backupGuiTables -t config -f /tmp/old_config.sql

# Extract only custom_config INSERT statements
grep "^INSERT INTO \`custom_config\`" /tmp/old_config.sql > /tmp/dashboards_only.sql

# On target server: import
mysql -u voipmonitor_user -p voipmonitor < /tmp/dashboards_only.sql

ℹ️ Note: Folder structures are NOT preserved. Recreate folders manually after import.

Server Migration

Fresh Installation Method (Recommended)

Best for EOL systems or when historical data is not needed.

  1. Backup on old server:
    • GUI config: Tools → Backup & restore → "configuration tables"
    • Sniffer config: cp /etc/voipmonitor.conf /tmp/
    • GUI PHP config: cp /var/www/html/*/configuration.php /tmp/
  2. Fresh install on new server (see Sniffer_installation, GUI_installation)
  3. Restore configuration:
    • GUI: Tools → Backup & restore → "restore"
    • Sniffer: cp voipmonitor.conf.backup /etc/voipmonitor.conf
    • Update interface, spooldir, server_bind for new environment
  4. Update remote probes (if distributed): Change server_destination to new server IP
  5. Test with subset of traffic before full cutover

💡 Tip: To preserve trial license on new system, use CLI restore with --exclude-table system

Data Migration Method

For transferring historical CDR data with minimal downtime. See Redundant_database for:

  • Dump/Restore: Simple mysqldump with downtime
  • Online Migration: Use voipmonitor-migrate.conf for zero-downtime sync

Cross-OS / Cloud Migration

⚠️ Warning: Do NOT clone binaries between different OS versions. Always perform fresh installation.

  • Download GUI package matching destination PHP version (see Re-install_the_GUI)
  • For database version mismatches, use migration instance instead of direct mysqldump

Cloud Token Migration

Each cloud token has its own database. To migrate alerts/reports between tokens:

  1. Contact VoIPmonitor support - request temporary trial cloud license
  2. Support restores old database to temporary license
  3. Export config from temporary license via Backup & restore
  4. Import config to new license via Backup & restore
  5. Restart sniffers: systemctl restart voipmonitor

ℹ️ Note: Alert-to-sensor assignments must be reconfigured manually after migration.

Troubleshooting

Backup Fails with "errno 28" (Disk Full)

MySQL needs temp space for backup operations.

Solution: Use smaller "configuration tables" backup instead of "data tables":

  • Configuration tables: ~1-10 MB (contains all essential settings)
  • Data tables: 100+ MB (supporting data, not critical)

Check disk space: df -h (look at /tmp and /var/lib/mysql)

Backup Breaks GTID Replication

mysqldump includes GTID state by default, breaking replication on restore.

Solution: Configure mysqldump to exclude GTID:

  1. Settings → System Configuration → Database
  2. Set Extra parameters for mysqldump binary: --set-gtid-purged=OFF
  3. Save and create new backup

Or manually: 

mysqldump -u root -p --set-gtid-purged=OFF voipmonitor users sensors alerts custom_config > backup.sql

Alerts/Reports Missing After Upgrade

Restore from backup created before upgrade:

  1. Tools → Backup & restore → "restore" → upload pre-upgrade backup
  2. Reconfigure alert-to-sensor assignments manually

See Also

AI Summary for RAG

Summary: VoIPmonitor GUI configuration backup guide. Two methods: (1) GUI via Tools → Backup & restore for one-time backups, (2) CLI using backupGuiTables/restoreGuiTables commands with cron for automation. Backup includes users, sensors, alerts, dashboards, capture rules. Does NOT include: alert-to-sensor assignments, report-to-sensor assignments, CDR/PCAP data. Restore overwrites existing data. Dashboard-only migration: extract custom_config table. Server migration: fresh install recommended for EOL systems; use Redundant_database for data migration. Cloud token migration requires support intervention to restore old database to temporary license. Troubleshooting: errno 28 (disk full) - use smaller "configuration tables" backup; GTID replication - set --set-gtid-purged=OFF in mysqldump parameters.

Keywords: backup, restore, configuration, GUI settings, users, sensors, alerts, dashboards, capture rules, backupGuiTables, restoreGuiTables, custom_config, cron automation, migration, disaster recovery, cloud token, GTID replication, errno 28, disk full

Key Questions:

  • How do I back up VoIPmonitor GUI configuration?
  • How do I schedule automated daily GUI backups?
  • How do I restore GUI settings from backup?
  • What is and is not included in a GUI configuration backup?
  • Does restore merge or overwrite existing data?
  • How do I migrate only dashboards between GUI instances?
  • How do I migrate VoIPmonitor to a new server?
  • How do I transfer alerts between cloud tokens?
  • Why does backup fail with errno 28?
  • How do I prevent backups from breaking MySQL GTID replication?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Backing_Up_GUI_Configuration&oldid=10087"