Install VICIdial with ViciBox 12: Express Setup, SSL and Firewall

Short answer: The supported way to install VICIdial is the ViciBox ISO (ViciBox 12, based on openSUSE Leap). Boot the ISO, run the first-boot wizard, set a static IP with yast lan, update with zypper up, then run vicibox-express for a single-server system (under about 20 agents) or vicibox-install for a cluster. Log in at http://your-server-ip > Administration with the default 6666 / 1234, change that password at once, then add a real SSL certificate with vicibox-ssl and lock down the firewall.

Applies to ViciBox 12 (openSUSE Leap based)

Steps checked against the official ViciBox 12 documentation (linked below) on 6 October 2026; not yet run on our lab servers. ViciBox file names and versions change between point releases, so check the download link in the docs before you start.

ViciBox or a scratch install?

VICIdial is a large set of Perl and PHP scripts, a MariaDB database and Asterisk with VICIdial-specific patches. You can assemble that yourself, but the project packages everything as ViciBox, an installable ISO. The ViciBox documentation describes three server roles plus an optional fourth: database (MariaDB), web (Apache), telephony (Asterisk) and archive (VSFTPd). An express install puts the first three on one machine.

A scratch install means checking out the code from the project’s Subversion server and building the rest yourself. The VICIdial wiki gives the checkout command and target directory:

mkdir -p /usr/src/astguiclient && cd /usr/src/astguiclient
svn checkout svn://svn.eflo.net:3690/agc_2-X/trunk

That is only the VICIdial code. You also need a patched Asterisk (the project publishes its patches under download.vicidial.com/asterisk-patches/, with folders up to Asterisk 18 at the time of writing), MariaDB, Apache with PHP, the required Perl modules, and the cron jobs and screen sessions that ViciBox sets up. Choose scratch only if you must run a specific OS and are ready to support it yourself; this guide follows the ViciBox route.

Hardware and media

Minimum and recommended specs from the ViciBox documentation:

Use	CPU	RAM	Storage
Minimum	4 cores, 2.0 GHz+	8 GB	160 GB
Recommended single server	4 cores, 2.0 GHz+	16 GB	500 GB
Dedicated database, 150 agents	8 cores, 2.0 GHz+	32 GB	500 GB
Dedicated database, 300 agents	16 cores, 3.0 GHz+	64 GB	500 GB NVMe

The docs recommend SSDs, RAID1 and ECC memory (ECC especially on the database). There are two ISOs: the standard image for a single drive, hardware RAID, SAN boot or a VM guest, and an MD RAID image that builds software RAID1 across two drives. The ISO is a hybrid image: write it to USB with Rufus or ImageUSB, or attach it to a VM.

Phase 1: install ViciBox

1. Boot from the ISO and choose Install ViciBox. If there are several disks, pick the boot disk.
2. Confirm that the target disk will be wiped. The installer copies the system, reboots and shows a login prompt.
3. Log in as root. The first-boot wizard starts: choose language, keyboard, accept the licence, set the timezone and a strong root password.
4. Let it install updates if the server has internet access.
5. On the MD RAID image, confirm the RAID setup. If it complains about existing data, the docs suggest clearing the drive with wipefs -fa /dev/sdX (this destroys everything on that disk; double-check the device name).
6. When you reach the command prompt, remove the media and reboot.

Phase 1.5: static IP and updates

VICIdial ties its configuration to the server’s LAN and WAN IP, so set a static address before installing it. Use YaST:

yast lan

Edit the interface (Statically Assigned IP Address, address and mask), set the hostname and DNS servers on the Hostname/DNS tab, and add a single default gateway on the Routing tab. For clusters, give every server a unique hostname; the docs suggest names like DB1, web1, dialer1. Log out and back in so the prompt shows the new hostname, then test:

ping -4 -c 3 example.com

Install updates, which also updates the ViciBox installer used in phase 2, and reboot:

zypper up
reboot

Phase 2: run vicibox-express

For a single server:

vicibox-express
# answer Y to start, wait for the prompt, then:
reboot

After the reboot, confirm the VICIdial background processes are running. The docs say it can take up to 5 minutes before screen -ls shows 11 Sockets in /run/screens/S-root:

screen -ls
asterisk -r     # you should see processes such as sendcron logging in and out; type quit to leave

Open http://your-server-ip in a browser, click Administration and log in with username 6666 and password 1234. You should land on the VICIdial Initial Setup screen.

For a cluster, run vicibox-install on each server instead and answer its questions about each server’s role. The ViciBox “Cluster” page walks through it.

First configuration

1. Change the 6666 password immediately, then give that user full admin permissions as the docs suggest, or create your own admin user and disable 6666.
2. Complete the Initial Setup screen: server IP, timezone and system settings.
3. Create phones (Admin > Phones) for agents and register a softphone or ViciPhone to test.
4. Add your carrier (Admin > Carriers) with the account details from your provider, and test an outbound call.
5. Create a campaign, a user and a small test list, and log in as an agent to make sure the agent phone is called into the session. If you get “No one is in your session”, see our fix guide.

The ViciBox docs deliberately stop at the server side. For campaigns, lists and agent use, the project points to its Manager and Agent manuals.

Hardening: SSL, firewall and exposure

SSL certificate

ViciBox ships a self-signed certificate as a placeholder. ViciPhone (the WebRTC agent phone) needs a valid certificate. The server must first be reachable by a fully qualified domain name over HTTP. Then:

vicibox-ssl
# enter the e-mail address and FQDN, confirm, enable the certificate and the renewal crontab
asterisk -rx "http show status"

vicibox-ssl requests a Let’s Encrypt certificate and configures Apache and Asterisk to use it. The http show status check confirms Asterisk loaded the certificate for WebSockets.

Firewall

ViciBox uses firewalld with three zones: public (the internet), trusted (your LAN; everything allowed) and external (approved remote IPs). Out of the box it runs in VoIP Black List mode, loading a community list of known SIP abusers from root’s crontab:

@reboot /usr/bin/VB-firewall --voipbl --noblack --quiet
0 */6 * * * /usr/bin/VB-firewall --voipbl --noblack --quiet

A blacklist alone still leaves SIP open to everyone else. The docs’ stronger option is the ViciDial White List (run vicibox-firewall and select it), optionally with the Dynamic Portal, which lets remote agents add their own IP by logging in on a separate HTTPS page (port 446 by default, opened with firewall-cmd --permanent --zone=public --add-port=446/tcp and firewall-cmd --reload). In whitelist mode, remove every service from the public zone except dhcpv6-client and rtp.

Port guidance from the ViciBox docs:

Port	Purpose	Who should reach it
UDP 5060	SIP signalling	Only your carriers’ signalling IPs and your agents
UDP 10000-20000	RTP audio (from /etc/asterisk/rtp.conf)	Open; carriers send audio from many IPs
TCP 80 / 443	Web interface	Agents and admins; force HTTPS
TCP 8089	WebSocket (WSS) for ViciPhone	Agents; treat it as a control port
TCP 446	Dynamic Portal	Remote agents, if you use the portal

The docs warn that the large VoIP Black List (50,000+ entries) can make firewalld hang after network changes in yast lan. Their advice: stop firewalld, make the change, then reboot so the list loads cleanly.

If the public IP changes later, run vicibox-externip and then update the server’s external IP under Admin > Servers and any DNS records.

Official documentation: ViciBox 12 documentation · ViciBox Express install · VICIdial SVN checkout

Related: SIP Ports Firewall Rules: 4 Setups for CSF, firewalld and pfSense · SIP Firewall Rules Generator: iptables, nftables, UFW, firewalld, CSF and pfSense · Erlang Calculator: How Many SIP Channels (Erlang B) or Call Centre Agents (Erlang C) · fail2ban for Asterisk and FreePBX: Block SIP Password Guessing · Disable SIP ALG: 7 Router Fixes for One-Way Audio and Dropped Calls

See also: VICIdial “No one is in your session” Error: 8 Checks to Fix It

Frequently asked questions

Maintenance record

This guide changes servers, data or security settings, so we re-check it against current versions on a fixed schedule. Take a backup or snapshot before you start.

Maintained by

srvScripts editorial team

Supported versions

ViciBox 12 (openSUSE Leap based)

Last full review

6 Oct 2026

Next review

4 Apr 2027