VICIdial Migration Guide: Move Your Dialer to New Hardware

Written by: Matt Beucler, CEO, Plura AI

Updated September 2026 · Covers VICIdial 2.14 (SVN 3939+, DB schema 1729), ViciBox 12.0.2, Asterisk 18.x/20.x-vici, MariaDB 10.11.

Key Takeaways

• A VICIdial migration is a sequenced project. Inventory the current build and schema version, back up the database and configs separately, restore to new hardware, update the server IP, rebuild conf files, and validate before decommissioning the old server.
• Schema version alignment is critical. Always verify db_schema_version in system_settings matches the installed code, and apply upgrade SQL scripts in strict sequence when moving to a newer VICIdial revision.
• IP changes affect carrier allow-lists, firewall rules, agent softphones, and external integrations. Update these dependencies before or during the maintenance window.
• Recordings, custom files, and configuration directories must be rsynced and ownership reset to asterisk:asterisk. A database restore alone leaves recording_log rows pointing at non-existent files.
• Operators ready to eliminate VICIdial infrastructure management can explore Plura AI’s managed AI Predictive Dialer as a complete replacement for legacy dialer stacks.

Step 1: Pre-Flight Inventory and Version Path

Pre-flight inventory tells you whether this project is a same-version move or a move-plus-upgrade. Before touching the new server, capture three items from the old one.

You need the server IP from /etc/astguiclient.conf, the VICIdial build number from the admin footer, and the database schema version. Together they define the path you follow next.

select db_schema_version from system_settings;

The db_schema_version stored in asterisk.system_settings is the most critical number for any VICIdial migration, because the installed code expects a specific value and will display a red admin banner reading “WARNING: Code expects DB schema version XXXX but found version YYYY” if the restored database does not match. Functionality breaks rather than failing cleanly. Agents can log in and campaigns appear intact while calls silently die.

The decision gate is straightforward. If the new server will run the same VICIdial SVN revision as the old one, this is a same-version move. Restore the database, update the IP, rebuild configs, and validate. If the new server will run a newer SVN revision, this is a move-plus-upgrade. Restore the database, apply upgrade SQL scripts in sequence to bring the schema forward, then proceed. Schema version thresholds map to marketing versions: approximately 1381 for VICIdial 2.8, approximately 1500 for 2.10, approximately 1600 for 2.12, and 1729 for the current 2.14 trunk as of late 2024.

Confirm the reference stack you are migrating to before you commit. ViciBox 12.0.2 runs openSUSE Leap 15.6, Asterisk 18, MariaDB 10.11, and PHP 8.2, with VICIdial 2.14 trunk around SVN 3939+ and DB schema 1729.¹ A working AlmaLinux 9.5 reference configuration from the VICIdial forum runs SVN 3939, DB schema 1729, Asterisk 18.26.0, and PHP 8.¹

Step 2: Backup, Done Properly

A clean backup is the safety net for every migration. Three categories of data require separate backup procedures: the MySQL database, the call recordings, and the configuration files. A database restore alone leaves recording_log rows pointing at files that do not exist on the new server, because VICIdial stores only the filename and path of a recording in the database, not the audio file itself.

Database backup:

mysqldump -u root -p --single-transaction --routines --triggers asterisk | gzip > asterisk-db-$(date +%Y%m%d-%H%M).sql.gz

Then run ADMIN_backup.pl on the database server:

perl /usr/share/astguiclient/ADMIN_backup.pl --debugX

Config backup as a separate tar:

cp -r /etc/asterisk /etc/asterisk.backup.$(date +%Y%m%d) tar czf /root/vicidial-configs-$(date +%Y%m%d).tar.gz /etc/asterisk /etc/astguiclient.conf /var/lib/asterisk/sounds /usr/share/astguiclient

Also capture the root crontab:

crontab -l > /root/crontab-backup-$(date +%Y%m%d).txt

A backup stored on the same box dies with the disk. Push the database dump and config tar to separate storage before proceeding. Verify the backup by restoring it to a scratch database and confirming recent rows exist in vicidial_closer_log for the last day.

Step 3: Restore and Schema Alignment

Restoring the database and aligning the schema prepares the new server to run production traffic. On the new server, drop and recreate the asterisk database with the correct character set, then import:

mysql -u root -p -e "DROP DATABASE IF EXISTS asterisk; CREATE DATABASE asterisk DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci;" zcat asterisk-db-*.sql.gz | mysql -u root -p asterisk

For a same-version move, the restore is complete. For a move-plus-upgrade, apply the upgrade SQL scripts from /usr/src/astguiclient/trunk/extras/ in order. SQL upgrade scripts cannot be skipped: a system at version 2.4 must run upgrade_2.6.sql, upgrade_2.8.sql, upgrade_2.10.sql, upgrade_2.12.sql, and upgrade_2.14.sql in sequence. Running only the latest script on an older database breaks the schema and is the most common cause of broken databases reported in the VICIdial forum SVN upgrade thread.

Run each script with the -f flag:

mysql -u root -p -f --database=asterisk < /usr/src/astguiclient/trunk/extras/upgrade_2.14.sql

The -f flag lets MySQL continue past harmless errors such as ERROR 1050 (table already exists) and ERROR 1060 (duplicate column name), because the upgrade scripts are designed to be re-runnable. Errors that are not safe to ignore include ERROR 1045 (access denied), ERROR 2002 (cannot connect to MySQL socket), ERROR 1114 (table full), and ERROR 1030 (disk full). Stop immediately if any of those appear.

After the import and any schema upgrades, confirm the schema version matches the installed code:

mysql -u cron -p1234 asterisk -e "select db_schema_version from system_settings;"

Step 4: IP Change Fallout

IP changes affect both VICIdial internals and external dependencies. Run ADMIN_update_server_ip.pl to update the server IP across all VICIdial database tables:

/usr/share/astguiclient/ADMIN_update_server_ip.pl --old-server_ip=OLD_IP --new-server_ip=NEW_IP --debugX

Then update VARserver_ip in /etc/astguiclient.conf:

sed -i "s/VARserver_ip=OLD_IP/VARserver_ip=NEW_IP/" /etc/astguiclient.conf

If the new server is assigned the same IP as the old one, both steps can be skipped.

ADMIN_update_server_ip.pl only realigns internal VICIdial database references. It does not touch astguiclient.conf’s VARserver_ip, and it does not update anything outside the VICIdial database. Four external dependencies break silently when the server IP changes and must be handled separately.

1. Carrier and trunk allow-lists. Carriers authenticating by source IP will reject calls with a 403 until the new address is whitelisted. Open the carrier ticket before the maintenance window. Carriers using SIP registrar credentials re-register once the conf is correct. IP-authenticated carriers require a human on the carrier side.
2. Firewall rules. Two firewall layers must allow the same traffic: the cloud provider’s external security group and the OS-level firewall (firewalld on ViciBox/openSUSE, firewall-cmd on AlmaLinux). Open UDP 5060, TCP 5060, and UDP 10000-20000 from the correct source ranges in both. Changes to one firewall layer do not affect the other, so when a port stops working both must be checked.
3. Agent softphone and proxy settings. Agent softphones are created in Admin > Phones with the server IP as the SIP server address, so a server IP change requires updating each softphone’s SIP server setting. Agents using ViciPhone (WebRTC) also need the SSL certificate and WebSocket listener on port 8089 re-established on the new hostname.
4. External integrations. CRM web forms, lead API connections, reporting feeds, and custom AGI scripts in /var/lib/asterisk/agi-bin/ that reference the old IP must be updated. Document all integrations that talk to VICIdial before migration day.

A stale conf file pointing at the old IP causes a silent failure. Asterisk starts and agents log in, but calls die at connect.

Step 5: Recordings and Custom Files

Recording and custom file migration keeps QA, compliance review, and reporting intact. Sync recordings from the old server to the new one before cutover, then run rsync again immediately before flipping DNS to catch the last few hours of audio:

rsync -avz --progress /var/spool/asterisk/monitorDONE/ NEW_SERVER:/var/spool/asterisk/monitorDONE/ rsync -avz --progress /var/spool/asterisk/monitor/ NEW_SERVER:/var/spool/asterisk/monitor/

Reset ownership after the sync:

chown -R asterisk:asterisk /var/spool/asterisk/monitorDONE/ chown -R asterisk:asterisk /var/spool/asterisk/monitor/

Recording files live under two directories. /var/spool/asterisk/monitor/ holds raw dual-channel WAV files, and /var/spool/asterisk/monitorDONE/ holds the ORIG, MP3, and FTP subdirectories. Ownership on monitorDONE must be asterisk:asterisk with 755 permissions. Incorrect permissions cause a common silent failure. The recording pipeline runs and the cron scripts execute, but no audio files appear in the admin screen.

Restore custom web files from /var/www/html/ only if they were manually modified. Confirm the recording format (WAV or MP3) matches between old and new servers so admin-screen playback does not break. Verify MIXMON_FORMAT in /etc/astguiclient.conf for codec consistency.

Step 6: Rebuild and Restart

Rebuilding configuration files and restarting services activates the new environment. In Admin > Servers > Modify Server, set Rebuild Conf Files = Y. This setting triggers VICIdial to regenerate Asterisk dialplan, channel, and peer config files from the database around the new IP address. Alternatively, force an immediate rebuild:

/usr/share/astguiclient/AST_conf_update.pl --debugX

Restart services in this order: MariaDB first, then Apache, then Asterisk.

systemctl restart mariadb systemctl restart apache2 systemctl restart asterisk

Verify astguiclient processes are running:

screen -ls ps aux | grep -E "AST_manager_send|AST_manager_listen" | grep -v grep

Both AST_manager_send and AST_manager_listen must appear. Confirm the Keepalive cron is present and running, because the Keepalive cron is what triggers VICIdial’s config regeneration and keeps the dialer processes alive.

Step 7: Validation and Rollback

Admin Validation

• Log in to /vicidial/admin.php and confirm no schema mismatch banner appears.
• Verify campaigns, lists, users, and reports load without database errors.
• Confirm db_schema_version in System Settings matches the installed code.

Agent Validation

• Log an agent in to /agc/vicidial.php.
• Place a test outbound call and watch RTP flow in both directions.
• Set a disposition and confirm it saves.
• Confirm recording playback works in the admin screen.

Dialer Validation

• Run asterisk -rvvv and confirm SIP trunks are registered with asterisk -rx "sip show registry".
• Confirm all expected processes appear in screen -ls and ps aux.
• Check /var/log/astguiclient/ for keepalive and dial script errors.
• Verify cron jobs are running: grep -i vicidial /var/log/cron.

Rollback planning protects live campaigns during cutover. Keep the old server powered off but intact. Keep the old VICIdial system running in a paused state for at least 48 hours after cutover (with parallel running and a phased ramp recommended for longer) before decommissioning. Do not delete old server data for at least 30 days. If validation fails and calls are down with no fix in sight within 15-30 minutes, restore DNS to the old server IP, re-activate campaigns on the old box, and re-sync any leads created on the new server. Restore the old server if validation fails and no fix is in sight within 15-30 minutes.

Book a live demo with Plura to see what a dialer stack looks like when the infrastructure is managed for you.

Step 8: Troubleshooting Reference

If validation fails, use the table below to map the most common post-migration symptoms to their likely causes and fixes. Work through it in order, starting with the schema banner, because a schema mismatch can mask other symptoms.

Symptom	Likely Cause	Fix
Red admin banner: “Code expects DB schema version XXXX but found YYYY”	Schema mismatch between restored database and installed code	Run missing upgrade SQL scripts in sequence with the -f flag. Re-query db_schema_version to confirm.
Agents cannot log in; admin page blank	Wrong file ownership, missing PHP MySQL extension, or database connection failure	Check file ownership (wwwrun:www on openSUSE, apache:apache on AlmaLinux). Verify DB credentials in astguiclient.conf. Restart MariaDB then Apache.
No dialing; calls rejected with 403	Carrier IP allow-list not updated for new server address	Open carrier ticket to whitelist new IP. For SIP registrar auth, confirm sip-vicidial.conf points to the correct host and reload Asterisk.
Calls connect but audio is one-way	externip or external_media_address in sip.conf/pjsip.conf not updated; RTP ports blocked	Update externip or external_signaling_address to the new public IP. Confirm UDP 10000-20000 is open on both the cloud security group and OS firewall.
Recordings missing from admin screen	Incorrect ownership on /var/spool/asterisk/monitorDONE/ or recording cron not running	Run chown -R asterisk:asterisk /var/spool/asterisk/monitorDONE/. Verify recording move cron scripts are present and executing.
Wrong IP in generated conf files after rebuild	VARserver_ip in astguiclient.conf not updated, or ADMIN_update_server_ip.pl not run	Run sed -i "s/VARserver_ip=OLD_IP/VARserver_ip=NEW_IP/" /etc/astguiclient.conf. Re-run ADMIN_update_server_ip.pl. Trigger AST_conf_update.pl.
Custom scripts missing or returning errors	AGI scripts in /var/lib/asterisk/agi-bin/ or custom web files not transferred	Rsync /var/lib/asterisk/agi-bin/ from the old server. Restore custom files from /var/www/html/ backup. Check PHP 8.2 compatibility if upgrading ViciBox version.

When a Like-for-Like Migration Is the Wrong Answer

The runbook above assumes you want to keep running VICIdial. If your actual goal is to stop managing VICIdial infrastructure entirely, the steps you just read highlight the operational load that a like-for-like move carries forward.

For operators whose actual goal is to stop managing VICIdial infrastructure entirely, a like-for-like move re-creates the same operational overhead on newer hardware. You still manage schema versions, patch Asterisk, maintain MyISAM tables, update carrier IP allow-lists, and track CVEs against a self-managed stack.

Plura AI’s AI Predictive Dialer is the exit path for operators in that position. It runs on Plura’s own FCC-licensed carrier infrastructure and is the VICIdial replacement built for high-volume outbound teams that need to maximize talk time without managing the stack underneath it.

Compare plans and rates side by side.

Frequently Asked Questions

What Is the Difference Between a VICIdial Same-Version Move and a Move-Plus-Upgrade?

A same-version VICIdial move dumps the asterisk database (all vicidial_* tables) and rsyncs the /etc/asterisk and /var/lib/asterisk/agi-bin config files (along with recordings) to new hardware running the identical VICIdial version, without forcing an upgrade. The schema version in the restored database already matches what the installed code expects, so no upgrade SQL scripts are needed. The migration steps are: restore the database, update the server IP, rebuild conf files, restart services, and validate.

A VICIdial move-plus-upgrade restores the database on the new server, installs a newer VICIdial SVN revision, and then upgrades the database schema to match the new code. Because the code expects a higher db_schema_version than the restored database contains, the upgrade SQL scripts from /usr/src/astguiclient/trunk/extras/ must be applied in sequence to bring the schema forward. Skipping any script in the sequence or running only the latest one on an older database produces a broken installation. The schema version check with select db_schema_version from system_settings; is the deciding input for which path applies.

Why Do Carrier Trunks Stop Working After a VICIdial Server Migration?

This expands on the carrier allow-list issue in Step 4. Most SIP carriers authenticate outbound calls by the source IP address of the originating server. When the server moves to new hardware with a new IP, the carrier’s allow-list still contains the old address. Every outbound INVITE from the new server arrives from an IP the carrier does not recognize, and the carrier returns a 403 Forbidden response. The call never connects.

As noted in Step 4, IP-authenticated carriers reject calls from the new address with a 403. The fix requires opening a ticket with the carrier to whitelist the new server IP before or during the maintenance window. Carriers using SIP registrar credentials (username and password) rather than IP authentication re-register automatically once the Asterisk configuration is correct and Asterisk restarts. Carriers using IP authentication require a human on the carrier side to update the allow-list.

What Happens If the VICIdial Schema Version Does Not Match the Installed Code?

VICIdial displays the schema mismatch banner described in Step 1. The system does not fail cleanly. Agents can log in, campaigns appear to load, and the dialer may start, but functionality breaks in ways that are not immediately obvious: dispositions may not save, reports may return database errors, and call flows may die silently. The only correct fix is to run the missing upgrade SQL scripts in sequence with the -f flag until the db_schema_version in system_settings matches what the installed code expects. There is no undo for ALTER TABLE statements, so the only rollback path if the upgrade SQL fails is restoring from the pre-migration mysqldump backup.

How Long Should the Old VICIdial Server Be Kept Available After Migration?

Keep the old server powered off but intact and restorable for at least 30 days after cutover, as covered in Step 7. Keep the old VICIdial system running in a paused state for at least 48 hours after cutover (with parallel running and a phased ramp recommended for longer) before decommissioning, and make sure the three-tier validation checklist has passed. The old server is the rollback path if validation fails or if a problem surfaces in the first days of production that cannot be resolved quickly. Keeping it available also allows data reconciliation: any leads, dispositions, or callbacks created on the new server during a failed cutover can be compared against the old server’s state before a decision is made about which dataset to trust.

What Is the Correct Service Restart Order After a VICIdial Migration?

The correct order is MariaDB first, then Apache, then Asterisk. MariaDB must be running before Apache attempts to serve the VICIdial PHP application, and both must be running before Asterisk’s AGI scripts can connect to the database. After Asterisk starts, the Keepalive cron cycle picks up the astguiclient processes within approximately one minute. Verify that AST_manager_send and AST_manager_listen both appear in ps aux output, and confirm the expected processes are listed in screen -ls. A missing Keepalive cron entry is a common migration pitfall that causes the dialer to appear healthy while predictive dialing never starts.

---

Read Next

• How to Replace VICIdial: Step-by-Step Migration Guide (2026)
• No-Code VICIdial Alternative: The Operator’s Migration Guide
• Why Switch From VICIdial? The 2026 Business Case
• VICIdial vs Dialpad: Outbound Call Center Leaders Guide
• VICIdial Pros and Cons: The Operator’s Decision Guide