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

Source: https://srvscripts.com/guides/install-vicidial-vicibox/
Updated: 2026-10-06
Publisher: srvScripts (https://srvscripts.com/)

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

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

- Boot from the ISO and choose **Install ViciBox**. If there are several disks, pick the boot disk.

- Confirm that the target disk will be wiped. The installer copies the system, reboots and shows a login prompt.

- Log in as `root`. The first-boot wizard starts: choose language, keyboard, accept the licence, set the timezone and a strong root password.

- Let it install updates if the server has internet access.

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

- 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

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

- Complete the Initial Setup screen: server IP, timezone and system settings.

- Create phones (Admin > Phones) for agents and register a softphone or ViciPhone to test.

- Add your carrier (Admin > Carriers) with the account details from your provider, and test an outbound call.

- 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](/guides/vicidial-no-one-in-your-session/).

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](https://docs.vicibox.com/en/latest/) · [ViciBox Express install](https://docs.vicibox.com/en/latest/installation/phase2/express.html) · [VICIdial SVN checkout](https://wiki.vicidial.org/doku.php?id=svn)

**Related:** [SIP Ports Firewall Rules: 4 Setups for CSF, firewalld and pfSense](/guides/sip-ports-firewall/) · [SIP Firewall Rules Generator: iptables, nftables, UFW, firewalld, CSF and pfSense](/tools/voip-firewall-generator/) · [Erlang Calculator: How Many SIP Channels (Erlang B) or Call Centre Agents (Erlang C)](/tools/erlang-calculator/) · [fail2ban for Asterisk and FreePBX: Block SIP Password Guessing](/guides/fail2ban-asterisk-freepbx/) · [Disable SIP ALG: 7 Router Fixes for One-Way Audio and Dropped Calls](/guides/disable-sip-alg/)

**See also:** [VICIdial “No one is in your session” Error: 8 Checks to Fix It](/guides/vicidial-no-one-in-your-session/)

## Frequently asked questions

### What is the default VICIdial admin login on ViciBox?

Username 6666 and password 1234, per the ViciBox Express documentation. Change it right after the first login.

### Should I use vicibox-express or vicibox-install?

vicibox-express installs database, web and telephony on one server and suits fewer than about 20 agents or a proof of concept. Use vicibox-install to build a cluster with separate roles.

### What OS is ViciBox based on?

openSUSE Leap. The ISO includes everything VICIdial needs, so you do not install the OS separately.

### Why does ViciPhone need an SSL certificate?

ViciPhone is a WebRTC phone. Browsers only allow WebRTC and secure WebSockets with a valid certificate, so run vicibox-ssl with a real FQDN.

### How many screen sessions should a working ViciBox show?

The Express docs say screen -ls should eventually show 11 sockets in /run/screens/S-root, which can take up to 5 minutes after boot.