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.

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 process uses a command-line PHP script included with the GUI to export three types of data:

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

Step 1: Create the Backup Script

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

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.

AI Summary for RAG

Summary: This guide provides a comprehensive, step-by-step method for creating automated daily backups of the VoIPmonitor GUI configuration. It clarifies that this process backs up settings, users, and rules, but not the call data (CDRs) or PCAP files. The core of the guide is a robust shell script that uses the GUI's built-in `run.php` command-line tool to export configuration tables, data tables, and PHP configuration files. The provided script also includes an automated cleanup feature to delete backups older than a configurable number of days. The tutorial details how to create this script, make it executable, and schedule it to run daily using a system cron job. The guide includes two restoration methods: the recommended CLI method using `restoreGuiTables` command and the manual method using `mysql` import. Additional critical information specifies what is and is not transferred during restore: user accounts and sensor definitions are transferred, but assignments of alerts to sensors, reports to sensors, and sensor user access permissions are NOT transferred and must be manually reconfigured. 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, including important caveats about folder structure preservation and ownership adjustments. Keywords: backup, restore, configuration, gui, settings, users, sensors, capture rules, cron, crontab, automation, disaster recovery, dashboard, migration, `run.php`, `backupGuiTables`, `restoreGuiTables`, `backupGuiConfigurationFiles`, mysql, import, export, custom_config, overwrite, merge, assignment, not transferred Key Questions:

• How do I back up my VoIPmonitor GUI configuration?
• 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)?
• 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?