The 8 Mistakes That Kill VICIdial Migrations (And a 30-Point Cutover Checklist)

I've watched maybe a dozen VICIdial migrations go sideways over the years. It's always the same pattern: someone picks a weekend, exports the campaigns, re-points DNS, and spends the next 72 hours firefighting things they didn't think about. Forgotten callback records. Timezone mismatches that shift every scheduled report by three hours. Agent phones that can't register because nobody opened port 5060 on the new firewall.

Migrating a live call center is brutal. Every minute of downtime is agents sitting idle and leads going stale. This guide focuses on the specific things that go wrong and the checklist that prevents them.

Before You Touch Anything: The Assessment

The assessment phase takes 3-5 days and most people try to skip it. Don't. You need a complete picture of what you're migrating.

Document your server inventory. Run the basics -- CPU, memory, disk, OS version, VICIdial build number, Asterisk version, MySQL version and database size. You'll need these to spec the target environment.

Snapshot your configurations. Export Asterisk configs from /etc/asterisk/, dump your critical VICIdial tables (system_settings, servers, campaigns, inbound_groups, call_times, server_carriers), and capture both root and asterisk user crontabs.

Record every campaign's settings. For each active campaign, document dial method, auto dial level, adaptive settings, answering machine detection config, local caller ID, transfer settings, call times, DNC settings, drop action, and hopper configuration. Export it all:

mkdir -p /tmp/migration-audit
cp -r /etc/asterisk/ /tmp/migration-audit/asterisk-conf/
crontab -l > /tmp/migration-audit/crontab-root.txt

Inventory your integrations. Every system that talks to VICIdial: CRM connections, lead sources (API, FTP, manual), reporting feeds, recording access methods, custom AGI scripts, external monitoring. Find custom scripts:

find /var/lib/asterisk/agi-bin/ -name "*.php" -o -name "*.pl" -o -name "*.py" | sort

Baseline your performance. Record 30 days of call volumes, contact rates, average duration, and agent counts. These are your comparison numbers post-migration. Save them in a file you won't lose.

The Data Export That Everyone Gets Wrong

Lead Data

Export everything, not just active leads. Historical data matters for analytics and compliance.

mysql asterisk -e "SELECT * FROM vicidial_list" > /tmp/migration-export/leads_full.tsv

Verify: count rows in the export file and compare to the database count. They must match exactly. Custom fields need their own export:

for table in $(mysql asterisk -N -e "SHOW TABLES LIKE 'custom_%'"); do
    mysql asterisk -e "SELECT * FROM $table" > "/tmp/migration-export/${table}.tsv"
done

Recordings

Call recordings are the largest data set and the most commonly forgotten. Calculate your storage first:

du -sh /var/spool/asterisk/monitor/

For large archives, rsync is your friend:

rsync -avz --progress /var/spool/asterisk/monitor/ \
  user@new-server:/var/spool/asterisk/monitor/

For smaller sets, compress by month for manageable file sizes. For long-term, push to S3 with STANDARD_IA storage class.

DNC Lists and Dispositions

Don't forget your internal DNC list, per-campaign DNC lists, system dispositions, and campaign-specific dispositions. Count them before and after import for verification.

Carrier and DID Migration

Carrier migration has the longest lead time. Start early.

Document everything for each carrier: carrier name, account number, concurrent channels, per-minute rates, DID inventory, contract end date, porting authorization requirements.

Understand porting timelines:

Porting Type	Typical Duration
Between major carriers	5-10 business days
Toll-free numbers	5-15 business days
Wireless to VOIP	7-14 business days
Between VOIP providers	3-7 business days

Test trunk connectivity before migration day. Register the new trunks, verify with asterisk -rx "sip show peers", and place test calls. Don't discover on cutover morning that the codec settings are wrong.

The 8 Pitfalls That Kill Migrations

Pitfall 1: Forgetting callback records. Agents schedule callbacks throughout the final week. If you don't export and import those records during cutover, those leads vanish. Export active callbacks as part of your cutover process.

Pitfall 2: Timezone mismatches. New server in a different timezone means every callback, call time restriction, and scheduled report shifts. Set the timezone explicitly before configuring anything:

timedatectl set-timezone America/New_York
mysql -e "SELECT @@global.time_zone, @@session.time_zone, NOW();"

Pitfall 3: DNS propagation delays. Agents access the dialer by hostname. You update DNS. For the next 2-48 hours, some agents hit the old server, some hit the new one. Drop DNS TTL to 60 seconds at least 48 hours before cutover. Or have agents use the IP directly during transition.

Pitfall 4: Recording codec mismatch. Old server records in WAV, new server configured for GSM. Pre-migration recordings won't play. Check MIXMON_FORMAT in /etc/astguiclient.conf on both sides.

Pitfall 5: Missing firewall rules. Required ports: 80/443 (web), 5060 (SIP), 10000-20000 (RTP media), 8089 (WebRTC if used), 3306 (MySQL if remote). Miss one and you get one-way audio, no agent login, or silent calls.

Pitfall 6: Cron job differences. VICIdial relies heavily on cron for keepalive processes, call logging, and cleanup. Verify every entry:

crontab -l | grep -E "(AST_manager_send|ADMIN_keepalive|AST_cleanup|AST_DB_dead)"

Missing one means ghost sessions, calls stop logging, or the hopper stops filling.

Pitfall 7: Not testing under load. Five test agents work fine. Fifty production agents doing 200 dials/hour? That's 2.8 calls per second hitting your Asterisk box. Simulate production load before committing to cutover.

Pitfall 8: No rollback plan. Keep the old system running (paused) for at least 48 hours post-cutover. Don't delete old data for 30 days. Document exactly how to re-point DNS and reactivate old campaigns. You need to be able to roll back within 30 minutes.

The Parallel Running Period

Never cut over cold. Run both systems simultaneously for a week minimum.

Week 1: Build and configure new environment
Week 2: Load data, configure campaigns, test internally
Week 3: Run 5-10 agents on new system alongside old
Week 4: Expand to 50% of agents
Week 5: Full cutover

During the parallel period, validate daily:

• Call volume on new system matches expected proportion
• Connect rates within 10% of old system
• AMD accuracy comparable or better
• Drop rates within compliance limits (under 3%)
• All dispositions recording correctly
• Recordings being saved and accessible
• CRM integration functioning
• Lead loading working
• Callbacks firing correctly
• DNC checks working
• Caller ID displaying correctly
• Transfer destinations connecting

The 30-Point Cutover Checklist

Print this. On paper. On migration day.

Pre-Cutover (Evening Before)

1. Confirm all DIDs ported and routing correctly
2. Verify SIP trunks registered on new server
3. Run final lead data sync
4. Verify lead counts match between systems
5. Confirm campaigns configured and paused on new system
6. Test outbound calling on each carrier with test numbers
7. Test inbound routing on each DID
8. Verify recording works (test call, confirm file on disk)
9. Confirm CRM integration URLs updated
10. Distribute new credentials to all agents

Cutover Morning

1. Pause all campaigns on old system
2. Wait for all active calls to complete
3. Run final disposition sync
4. Export and import callback records
5. Verify callback import count
6. Start agent logins on new system
7. Activate campaigns one at a time
8. Monitor first 10 calls per campaign
9. Verify agents connecting to live humans
10. Check drop rate under 3% after first 100 calls

Post-Cutover Verification (First 2 Hours)

1. Real-time reporting populating
2. Recordings being saved
3. Transfer functionality working (blind and warm)
4. Caller ID displaying correctly on test callbacks
5. DNC checking functional
6. Lead API loading working
7. Cron jobs running
8. Server load acceptable
9. Old system fully stopped
10. Migration-complete notification sent to stakeholders

Post-Migration: Day 1 Through Day 30

Day 1 variances to expect: total calls within 15% of baseline (agents are adjusting), contact rate within 20%, drop rate must stay under 3%.

Week 1 daily checks: call volumes trending toward baseline, connect rates stabilizing, AMD accuracy verified, recording storage growing at expected rate, no carrier error patterns, agent feedback collected.

Day 30 review: compare 30 days of post-migration data to the pre-migration baseline you captured in the assessment phase. Post-migration performance should meet or exceed pre-migration levels.

If you planned a move to ViciStack's managed infrastructure, the optimization work that comes with migration typically pushes connect rates 50-100% above pre-migration baselines. Most migrations complete in 2-3 weeks with zero production downtime. The migration itself doesn't have to be the hard part. The hard part is everything you forgot to document about the old system.

Talk to ViciStack about your migration -- we respond within 5 minutes during business hours.

Originally published at https://vicistack.com/blog/vicidial-hosted-migration-checklist/