ViciDial Installation Guide From Scratch (2026, Step by Step)

ViciDial is the open-source contact centre suite that runs a very large share of the world's small and mid-size call centers. It is a predictive dialer, agent desktop, lead manager, recorder, and reporting system, and it costs nothing. It is also, by modern standards, an awkward piece of software with a dated interface and a configuration model that assumes you know Asterisk.

This guide gets you from an empty server to a live test call. Budget three to five hours for your first install and expect to redo it once.

Before you start: what you need

You also need a public IPv4 address. ViciDial behind NAT is possible but adds an entire category of one-way-audio problems you do not want on your first install.

Route A: ViciBox (recommended)

ViciBox is an openSUSE-based ISO with ViciDial and every dependency pre-integrated. It is what the developers test against, and it turns a day of dependency wrangling into an installer.

1. Boot the ISO

Download the current ViciBox ISO from the official ViciDial download page. On a VPS, upload it as a custom ISO or use your provider's "mount ISO" console feature. On bare metal, write it to a USB stick.

Install to disk with the default partitioning unless you have a reason to deviate. Set a strong root password at this stage.

2. First boot and network

Log in as root. Confirm the box has its public IP and can reach the internet:

ip addr show
ping -c 3 1.1.1.1

Set a hostname and make sure it resolves — Asterisk and MariaDB both complain otherwise:

hostnamectl set-hostname dialer.yourdomain.com
echo "127.0.0.1 dialer.yourdomain.com dialer" >> /etc/hosts

3. Run the installer

ViciBox ships an interactive installer that configures the database, Asterisk, and the web interface:

vicibox-install

Answer the prompts. For a single-server setup accept the defaults for the database and let it configure this machine as both database and telephony server. When asked for the server IP, give the public address.

4. Bring up the services

vicibox-express
systemctl enable --now mariadb apache2 asterisk

Then confirm the core processes are alive:

systemctl status asterisk
asterisk -rx "core show channels"

Route B: Manual install on Rocky Linux 9

Use this only if you have a specific reason — a corporate standard OS, or an existing server you cannot rebuild. You will be compiling Asterisk and installing roughly 60 Perl modules.

The broad sequence:

1. Install the base system with @development-tools, MariaDB, Apache, and Perl.
2. Compile DAHDI, then LibPRI, then Asterisk 13 or 16 (ViciDial pins to specific branches — check the current SVN notes before choosing).
3. Install the Perl dependencies via CPAN. This is the step that eats hours.
4. Check out ViciDial from its repository and run install.pl.
5. Import the database schema and run ADMIN_update_server_ip.pl.

The community-maintained scratch install documents on the ViciDial wiki are the authoritative reference and are updated more often than any blog post, including this one. Follow those for exact package lists.

Securing the box before it is on the internet

Every ViciDial install ships with well-known default credentials, and there are bots scanning for exactly this. Do these before your first coffee break.

Change the default logins

The web admin default is user 6666 with password 1234. Log into https://your-server/vicidial/admin.php and change it immediately. Then create a personal admin account and disable 6666 entirely.

Firewall everything except what you need

firewall-cmd --permanent --add-service=ssh
firewall-cmd --permanent --add-service=https
firewall-cmd --permanent --add-port=5060/udp
firewall-cmd --permanent --add-port=10000-20000/udp
firewall-cmd --reload

Better still: restrict SIP port 5060 to only your carrier's IP addresses and your agents' office IPs. An open 5060 on a public IP will receive registration brute-force attempts within hours.

firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="CARRIER_IP" port port="5060" protocol="udp" accept'

Install fail2ban

zypper install fail2ban    # or: dnf install fail2ban
systemctl enable --now fail2ban

Enable the asterisk and sshd jails. Toll fraud is the real risk here — a compromised dialer gets used to route thousands of dollars of premium-rate calls overnight, and the bill is yours.

Get HTTPS working

Agents' browsers will not grant microphone access to an insecure origin, so WebRTC softphone mode requires TLS. Point a domain at the server and:

certbot --apache -d dialer.yourdomain.com

Connecting your SIP carrier

This is where your provider's credentials go. In ViciDial: Admin → Carriers → Add A New Carrier.

You fill in three text boxes that are written verbatim into Asterisk's configuration.

Registration string

Only needed if your carrier uses registration rather than IP authentication:

register => YOUR_USERNAME:YOUR_PASSWORD@sip.yourprovider.com

Account entry

[cloudyvoice]
type=friend
host=sip.yourprovider.com
username=YOUR_USERNAME
secret=YOUR_PASSWORD
fromuser=YOUR_USERNAME
fromdomain=sip.yourprovider.com
context=trunkinbound
insecure=port,invite
qualify=yes
nat=no
canreinvite=no
disallow=all
allow=ulaw
allow=alaw
dtmfmode=rfc2833

A few of these matter more than they look:

• disallow=all then allow=ulaw — pin your codec explicitly. Letting Asterisk negotiate freely is how you end up transcoding and burning CPU.
• canreinvite=no keeps media flowing through your server, which you need for recording.
• insecure=port,invite lets the carrier send calls in without re-authenticating.
• nat=no is correct only on a public IP with no NAT. Behind NAT, set nat=force_rport,comedia and configure externip.

Dialplan entry

This is what actually places the call. The _91NXXNXXXXXX pattern means "9, then 1, then a valid North American number" — the leading 9 is ViciDial's dial prefix, stripped by ${EXTEN:1}.

exten => _91NXXNXXXXXX,1,AGI(agi://127.0.0.1:4577/call_log)
exten => _91NXXNXXXXXX,n,Dial(SIP/cloudyvoice/${EXTEN:1},,tTo)
exten => _91NXXNXXXXXX,n,Hangup()

For international dialing with a 9 prefix and full E.164 numbers:

exten => _9X.,1,AGI(agi://127.0.0.1:4577/call_log)
exten => _9X.,n,Dial(SIP/cloudyvoice/${EXTEN:1},,tTo)
exten => _9X.,n,Hangup()

Reload Asterisk after saving:

asterisk -rx "sip reload"
asterisk -rx "dialplan reload"
asterisk -rx "sip show registry"
asterisk -rx "sip show peers"

You want to see your carrier peer as OK with a latency figure.

Creating your first campaign

1. Add a phone (agent extension)

Admin → Phones → Add A New Phone. Each agent seat needs one. Set the extension, a strong secret, and Server IP to your server. For browser-based agents using WebRTC, set the protocol accordingly; for a desktop softphone like Zoiper or MicroSIP, use SIP.

2. Add a user

Admin → Users → Add A New User. Give a user ID, password, full name, and a user group. Set the user level — level 1 is a plain agent, level 9 is full admin.

3. Add a campaign

Admin → Campaigns → Add A New Campaign. The settings that actually matter on day one:

4. Load leads

Admin → Lists → Add A New List, then use the lead loader to upload a CSV. Map your columns to ViciDial's fields — at minimum phone_number, and ideally first_name, last_name, and any custom fields your script needs.

5. Make a test call

Log an agent in at https://your-server/agc/vicidial.php, choose the campaign, and place a manual call to your own mobile. Verify:

• Two-way audio with no delay or echo
• The call appears in Real-Time Report
• A recording is produced if enabled
• Dispositioning the call returns the agent to ready state

If you get one-way audio, the answer is almost always NAT or firewall RTP ports. If you get no audio at all, check codecs.

Tuning the predictive dialer

Once manual dialing works, move to RATIO and raise the auto-dial level slowly. The relationship you are managing:

• Too low — agents sit idle, cost per contact rises.
• Too high — calls connect with no agent free, the caller hears silence, and the call is dropped. This is the abandon rate, and it is legally capped in several jurisdictions (commonly 3% in the UK and under Ofcom rules; the US FTC applies its own limits to covered telemarketing).

Start at 1.0, move to 1.5, then 2.0, watching the drop percentage in the real-time report. ADAPT_HARD_LIMIT will manage this automatically against a target abandon rate once you have enough call volume for the statistics to mean anything — generally a few hundred calls per hour.

Common problems and their actual causes

For anything Asterisk-level, the console is the fastest diagnostic:

asterisk -rvvv

Then place a call and read what actually happens.

Backups

The database is your business. Leads, recordings, dispositions, and agent history all live in MariaDB.

mysqldump --single-transaction -u root -p asterisk | gzip > /backup/vici-$(date +%F).sql.gz

Put that in cron nightly and copy it off the server. A dialer with no backup is one failed disk away from losing every lead and call record you own.

Where to go next

• How to start a call center with $200 — the full budget context for this build.
• VoIP fundamentals: SIP, codecs, and DIDs — what the settings above actually mean.
• Bandwidth and audio quality for call centers — sizing your connection properly.
• Compliance: TCPA, DNC, and GDPR — before your first live campaign.

When you are ready to point the carrier entry at real minutes, our rate directory is public and searchable, and accounts start at a $10 top-up with no monthly commitment.