# 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.

URL: https://trustane.com/blog/connect-existing-vicidial-server
By Trustane. Published 2026-11-05, updated 2026-11-09.

> **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.conf` holds the database name, user, password, host and port, and VICIdial's paths.
> - VICIdial's defaults are `asterisk` / `cron` / `1234` on port 3306, but hardened installs change them. The box we measured used a five-digit port.
> - `servers.server_id` is 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.php` answers 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.

```bash
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](https://trustane.com/blog/move-vicidial-server-what-to-copy) for why this matters again at migration.

![VICIdial server record with Server ID and Server IP Address highlighted](https://trustane.com/media/441d59bd5beebe14-1600x318.webp "Admin, Servers: two fields that look simpler than they are")

1. **Server ID**: a short name. Handle it as text.
2. **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.

![Checklist of five things to read from a VICIdial server instead of assuming](https://trustane.com/media/5341c6e8e43d0d93-1600x752.webp "What to read, and what to assume nothing about")

## In the Trustane console

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

![Trustane Migrate in page with the host, SSH port, SSH user and Check my dialer button highlighted](https://trustane.com/media/bf68393e6c267ef2-1600x395.webp "Migrate in, step 1: connect")

1. **Host / IP of your existing dialer**: the address that answers, not the one in `servers`.
2. **SSH port**: the one your box listens on, which may not be 22.
3. **SSH user**: a user that can read `/etc/astguiclient.conf`.
4. **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:

```bash
ssh -o PreferredAuthentications=publickey -o BatchMode=yes host true
```

> **Prove a disconnect**
> Connect, read a page, disconnect, then try to log in again. The last step must fail with `Permission denied`, and `authorized_keys` must no longer hold the key. A disconnect not proven by a failed login is not done. Also beware a `grep -v ... && mv` removal: when the file holds only that key, `grep` exits 1 and the `mv` is skipped.

## 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](https://trustane.com/vicidial-wallboard) before you move anything. If you are weighing a move, start at [migrate](https://trustane.com/migrate), or look at [VICIdial hosting](https://trustane.com/vicidial-hosting) and [pricing](https://trustane.com/vicidial-pricing). You can also [contact us](https://trustane.com/contact) with your VICIdial version.

VICIdial is a trademark of its owner. Trustane is an independent hosting provider.
