VICIfast
All migrations

Migrating a self-hosted VICIdial box

Moving your own VICIdial box onto managed hosting: what carries over unchanged, what the new box does differently, and where the real work sits.

This is the simplest migration we do, because there is no translation step. You are already running VICIdial; so is the destination. Same admin screens, same agent screen, same hot keys, same campaign IDs, same dispositions, same reports. Nobody needs retraining.

What you are actually changing is who operates the box. That is worth being precise about, because a few things about the new box are genuinely different and they are the things that bite during a cutover.

What transfers

The same automated tooling that handles ViciBox sources handles any box with a standard VICIdial schema, which is what yours is. The mechanics are written up once on the ViciBox migration page - read that for the step-by-step. In short, the destination reads your /etc/astguiclient.conf for database credentials, streams a mysqldump over SSH, and imports it.

Across come your campaigns and their child tables, lists, leads, custom_<list> tables, agents and user groups, statuses and dispositions, your DNC list, inbound groups, DIDs and call menus, phone records with their SIP credentials intact, your full call and recording history including the _archive tables, your timeclock and audit logs, and any non-stock AGI scripts in /var/lib/asterisk/agi-bin. Recordings and voicemail follow in a background rsync afterwards.

What doesn't transfer

  • Carrier and trunk configuration. vicidial_carriers, vicidial_server_carriers and vicidial_server_trunks are never copied. You re-add your carriers on the new box.
  • Anything in /etc/asterisk. No file under it is copied. If you have hand-written dialplan, custom contexts or edited manager.conf, copy those off your old box yourself - they are yours to re-apply, and where they go on the new box is worth asking support about first. Do not plan on dropping your old files in place: VICIdial regenerates extensions-vicidial.conf and pjsip-vicidial.conf from the database, so anything you write into those is overwritten.
  • Box-identity tables - servers, system_settings, web_servers, conference and conference-template tables, screen colours. The new box owns its own.
  • The IP allowlist. vicidial_ip_lists and vicidial_ip_list_entries are cleared and allow_ip_lists is forced off.
  • Runtime state - hopper, live agents, auto calls, parked channels, sessions.
  • Any patch you made to VICIdial's own source. If you edited PHP or Perl under the VICIdial tree, that work does not survive. Re-apply it or find a supported way to do the same thing.

What actually changes about running it

This is the section to read twice. None of it changes how VICIdial works; all of it changes your muscle memory.

  • Patching stops being your job. OS updates, Asterisk, the VICIdial tree, firewall, TLS certificates, backups and monitoring move to us.
  • We can't adopt your existing box. The installer only runs on a clean Ubuntu 22.04 server - it refuses any machine that already has Asterisk, Apache, MariaDB, FreePBX, Issabel or Elastix on it. So even if you bring your own hardware, this is a move onto a fresh box with your data restored into it, not a takeover in place.
  • You still get root, but not by password. Boxes ship with PasswordAuthentication no and PermitRootLogin prohibit-password. You paste a public key into the server's SSH keys page in the dashboard and we sync it to /root/.ssh/authorized_keys. That file is rewritten in full on every sync, so hand-editing it does not stick - add keys through the dashboard. There is also a browser console, and sessions are recorded.
  • Asterisk is not a systemd service. There is no asterisk.service, and the SysV init script is deliberately removed. systemctl is-active asterisk will always tell you it is inactive even while calls are connected - the honest liveness check is whether asterisk -rx answers. Asterisk is supervised by a vicidial.service unit, and restarting that is the correct way to bounce it. Anything in your scripts or cron that restarts Asterisk directly needs rewriting; this is the single most common thing self-hosted operators trip over on day one.
  • Your database is not called asterisk. Each box gets a randomly named database and randomly named MariaDB users, written to /root/db_credentials.txt. MariaDB root uses socket authentication with no password and does not accept remote connections - for a GUI client, SSH-tunnel to localhost:3306 and authenticate as the per-box user. Any script of yours with a hard-coded database name or a remote root connection string needs updating.
  • The admin URL is not the one you know. The /vicidial and /agc aliases exist, but the URL you are handed is an obfuscated path on a random high port rather than plain /vicidial/admin.php on 443. Update bookmarks and anything that scrapes or links to the admin.
  • Recordings live at /var/spool/asterisk/monitorDONE, in per-format subdirectories, and are served over an Apache alias at /RECORDINGS/. Note that a nightly job deletes files under monitorDONE/ORIG older than a day; if you currently keep original un-mixed audio indefinitely, that is a change to raise before you cut over. The webroot is /var/www/html - if your old box was openSUSE-based it was /srv/www/htdocs, and anything hard-coding it needs a look.
  • You land on a newer VICIdial than you left. Boxes run the VICIdial 2.14 series taken from VICIdial's own SVN trunk at image-bake time, on Asterisk 22.5.1 and Ubuntu 22.04; the exact revision is recorded in servers.svn_revision. The restore deliberately keeps the destination's schema and imports your rows into it rather than restoring your older schema - otherwise the new box's PHP and Perl would be reading columns that no longer exist. Treat this as a version upgrade happening at the same time as the move.

What you rebuild

  1. Every carrier and trunk, and the outbound routing that used them.
  2. Your carrier's IP allowlist, pointed at the new box's IP. Nothing dials until this lands.
  3. Custom dialplan you kept outside the database.
  4. Phone endpoints, if your agents use hardphones. Migrated phones other than the platform's own 6666 are switched to PJSIP with the WebRTC template.
  5. External integrations that addressed the old box directly - a CRM reading its MySQL, webhooks, monitoring checks, dashboards, bookmarks.

Order of operations

  1. Inventory first. Check the size of /var/spool/asterisk/monitorDONE, list anything non-stock in /var/lib/asterisk/agi-bin, and diff /etc/asterisk against a clean VICIdial install so you know exactly what you hand-wrote. Do this before you order anything.
  2. Provision the destination. It has to be genuinely fresh - the restore aborts if it finds more than a hundred rows of call history already on it. That takes about 40 seconds.
  3. Run the read-only probe from the server's migration screen. It inventories your tables, counts, recording sizes and non-stock AGI scripts and hands you a manifest. Nothing is written to your box.
  4. Book a window and drain. Log every agent out and set every campaign inactive. The copy will not start otherwise.
  5. Run the migration, then rebuild your trunks on the new box while the recordings rsync runs in the background.
  6. Update the carrier IP allowlist, then DNS. Test before agents come back.
  7. Keep the old box until you have finished testing. It is your only real rollback.

About downtime

There is no zero-downtime version of this. Dialing stops when you drain the source and resumes when your carrier has accepted the new IP - that window contains the database copy, the restore, your trunk rebuild and your carrier's allowlist turnaround, and only the last one is outside your control.

It is also worth knowing that you cannot rehearse by half-migrating: the restore only runs on a fresh destination, so if you dial real campaigns on the new box to try it out, you have used up the box the migration needed. Rehearse on a separate server if you want a dry run, and treat the real move as a single scheduled cutover.

What to test before you point agents at it

  • Campaign, list and lead counts match the manifest the probe gave you
  • One outbound call on every trunk you rebuilt
  • One inbound call to every DID and in-group, including IVR paths
  • A recording completes, lands in monitorDONE and plays back from the report
  • An agent logs in on the phone they will actually use
  • Your non-stock AGI scripts are present and executable
  • A report over a pre-cutover date range matches the old box's numbers
  • Your DNC count matches
  • Anything of yours that ran on a cron or a timer still runs - check it explicitly rather than assuming

Next steps

More migrations

Same VICIdial. We just run the box.

Get a dedicated VICIdial server in 40 seconds. Free for 7 days.

See pricing