Connecting an existing VICIdial server: the surprises we found
What connecting an existing VICIdial server to a console taught us: read the database settings from the box, treat server_id as a name, expect a 401.

To the point
To connect a running VICIdial server to a console, read the facts from the box itself instead of asking a person to type them in. Five things on a real server differ from what most code assumes.
/etc/astguiclient.confholds the database name, user, password, host and port, and VICIdial's paths.- VICIdial's defaults are
asterisk/cron/1234on port 3306, but hardened installs change them. The box we measured used a five-digit port. servers.server_idis a short name, not a number.- Every user's allowed API functions default to
ALL_FUNCTIONS, so choose the account that adds leads explicitly. - Over https,
admin.phpanswers 401 when healthy: VICIdial asks for its own login.
Read the box, do not ask the customer
The database tells you the version, schema, cluster shape, campaigns and API users. We connect servers we never built, so the box is the only source of truth. Everything below would have been wrong had we written the code from assumptions.
The five surprises
1. The MySQL port may not be 3306
VICIdial's installer offers fixed defaults: database asterisk, user cron, password 1234, port 3306. Hardened installs change them. The box we measured, from our earlier fleet, had a random password and a five-digit port. A connection test that assumes the defaults reports "database down" on a healthy server, so read them from the box.
DB=$(awk -F"=>" '/VARDB_database/{gsub(/[ \t;]/,"",$2);print $2}' /etc/astguiclient.conf)
The same file has VARDB_user, VARDB_pass, VARDB_server and VARDB_port. As root, mysql -e over the local socket confirms you read the right values.
2. server_id is a name
It reads like a number, but the manual calls it just a nickname, up to 10 characters (page 268). On the box we measured it was vicibox. Code that casts it to an integer fails quietly or matches the wrong row. Treat it as a string.
3. Many users can add leads
The API functions a user may call are a column on vicidial_users, and its default for every user is ALL_FUNCTIONS. What limits adding leads is user level 8 or higher plus Modify Leads (page 494). We expected one match and got six. Pick the account by name if you have a convention, fall back to a generic API account only when you must, and record which one you chose.
4. The box's own address may not be reachable
servers.server_ip is what the box believes its address is. Behind NAT, or on a cloud server with a mapped public address, you cannot connect to it. VICIdial keeps a separate field, External Server IP, for the outside address its web phones use (page 253). Keep two facts: the address that answered your connection, and the one the box calls itself. See what we copy and what we never copy for why this matters again at migration.

- Server ID: a short name. Handle it as text.
- Server IP Address: what the box thinks its address is, not necessarily the one you reach.
5. A 401 is the healthy answer
We checked the web interface by requesting admin.php. Over https it answered 401: VICIdial asks for its own login, the HTTP authentication prompt. Whether plain http redirects to https is up to the web server's setup, not VICIdial. A check that insists on 200 flags every working server as broken. Accept 401 on https, and treat a refused connection, a 5xx or a certificate error as real failures.

In the Trustane console
Connecting asks for four things and reads the rest from the box.

- Host / IP of your existing dialer: the address that answers, not the one in
servers. - SSH port: the one your box listens on, which may not be 22.
- SSH user: a user that can read
/etc/astguiclient.conf. - Check my dialer: reads the box and shows what it found.
How the credential is handled
Connecting needs one credential, once. It installs the managed key's public half in authorized_keys, and then it is discarded. A stored root password for a customer's dialer is a liability whether or not you use it again.
Use key authentication after the first login and check it works before you disable anything else. This returns 0 only if the key works on its own:
ssh -o PreferredAuthentications=publickey -o BatchMode=yes host true
What we read, and what we did not test
The db_schema_version in system_settings is the number that matters for compatibility. The version string and svn_revision are advisory: the installer writes the revision from svn info at the last install or upgrade, and 0 when it was installed without a checkout. A server whose server_updater row has stopped updating is what admin.php calls frozen; count it out of capacity.
We measured one ViciBox from our earlier fleet, with its own hardening. A hand-built Ubuntu install keeps astguiclient.conf in the same place, because VICIdial's scripts read that fixed path, though its Apache and PHP layouts may differ. We have not verified every hosting company's firewall, and a network that blocks our address will fail to connect.
Questions people ask
Do I need to type in my database details?
No. They are read from the box, and typing them in is how they get wrong.
Is it safe on a production floor?
Once connected, the read-only pages are safe to open on a live floor, which is why we read first.
Next steps
See what a connected server looks like with the wallboard before you move anything. If you are weighing a move, start at migrate, or look at VICIdial hosting and pricing. You can also contact us with your VICIdial version.
VICIdial is a trademark of its owner. Trustane is an independent hosting provider.
Sources
- Migration ground truth from one hardened ViciBox in our earlier fleet, 2026-09-11
- VICIdial installer defaults, install.pl r4037 lines 86 to 92
- VICIdial Manager Manual 2.14, pages 253, 268 and 494
- OpenSSH manual, sshd_config
- Cover photo by Brett Sayles on Pexels
Managed VICIdial hosting


