Skip to main content

Linux installation

Linux Installation

Prerequisites

Our current supported operating systems include:

  • Ubuntu (versions 22, and 24)
  • Debian (versions 11 and 12)
  • CentOS 9
  • AlmaLinux (versions 8 and 9)
  • Rocky Linux (versions 8 and 9)

In many installations, there is a service running on the standard HTTP ports (80 and 443). If you wish to continue running the service on the host, you need to assign different ports to the PBX. You can do this by adding --http-port <port> and --https-port <port> to the startup parameters.

The PBX needs to have access to the public Internet for the activation of the license key and for installing software updates https://license.vodia.com for the license and https://portal.vodia.com for software updates). If you need to disconnect Internet access after installation, you will need a permanent key which is available upon special request.

Installation

In order to start the installation, you need to be logged in as system administrator to a shell (typically bash).

Download and run the install script for your operating system. Before running the install script, edit the install script if necessary and read the comments. You may choose to install different languages and make other modifications to the installation script that fit your purpose.

If you need to write a pidfile, you may do so by editing the OPTIONS variable in the installation script. You need to add --pidfile <filename> to the list of options. For normal installations, this is not neccessary.

Please note that you will might have to configure your firewall (iptables). Otherwise, you will not be able to access the web interface of the PBX and register phones.

After the PBX service is installed by the script, the username and password will be shown in the bash terminal.

We recommend that you reboot the server after the initial installation. This will make sure that everything will come up automatically in the case you have to restart the server. It will also make sure that there is only one PBX process running on the server.

After the PBX is working, you should make sure that there is some kind of automatic backup. If you are not using a cloud service provider that automatically generated snapshots, there is a Backup Script which you can use for that.

Universal Linux Install script for Ubuntu, Debian, CentOS, AlmaLinux and Rocky Linux:

#!/bin/bash
# Unified Vodia PBX installer for CentOS, Rocky Linux, AlmaLinux, Debian/Ubuntu

# Configuration variables
PBX_DIR=/usr/local/pbx
LANGUAGES="" # Add additional languages here, e.g. "de fr" , en and moh are always included
DOWNLOAD_PATH=https://portal.vodia.com/downloads/pbx

# Generate credentials
username="vodia"
pw_pass=$(cat /proc/sys/kernel/random/uuid)
md5_pass=$(echo -n "$pw_pass" | md5sum | awk '{print $1}')

# Detect OS and architecture
OS="unknown"
BITS=$(getconf LONG_BIT)

if [ -f /etc/redhat-release ]; then
if grep -qi "CentOS" /etc/redhat-release; then
OS="centos"
elif grep -qi "Rocky" /etc/redhat-release; then
OS="rocky"
elif grep -qi "AlmaLinux" /etc/redhat-release; then
OS="alma"
fi
elif [ -f /etc/debian_version ]; then
OS="debian"
if [ "$BITS" -ne "64" ]; then
echo "Debian/Ubuntu version only supports 64-bit"
exit 1
fi
fi

# Check if this is root
if [ "$EUID" -ne 0 ]; then
echo "This script must be run as root"
exit 1
fi

# Fix AlmaLinux 8 GPG Key (Only on AlmaLinux 8) ---
if [ "$OS" = "alma" ] && [ $(grep -oP '(?<=release )\d+' /etc/redhat-release) -eq 8 ]; then
echo "Detected AlmaLinux 8. Applying GPG key fix..."

# Remove old key (if exists)
sudo rpm -e gpg-pubkey-c21ad6ea-* 2>/dev/null || true

# Download and reimport the AlmaLinux GPG key
sudo curl -o /etc/pki/rpm-gpg/RPM-GPG-KEY-AlmaLinux https://repo.almalinux.org/almalinux/RPM-GPG-KEY-AlmaLinux
sudo rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY-AlmaLinux

# Clean and rebuild cache
sudo dnf clean all
sudo dnf makecache

echo "GPG key for AlmaLinux 8 has been fixed."
fi

# Install required dependencies
echo "Installing required dependencies..."
case "$OS" in
"centos"|"rocky"|"alma")
dnf install -y wget unzip
if [ "$OS" = "centos" ]; then
dnf install -y ntp
fi
;;
"debian")
apt-get update
apt-get install -y wget psmisc unzip libopus0
;;
*)
echo "Unsupported operating system"
exit 1
;;
esac

# Create PBX directory if it doesn't exist
if [ ! -d "$PBX_DIR" ]; then
echo "Creating PBX directory at $PBX_DIR"
mkdir -p "$PBX_DIR"
fi
cd "$PBX_DIR" || exit 1

VERSION=$(wget -qO- https://vodia.nyc3.cdn.digitaloceanspaces.com/builds/latest.txt) ## e.g. 69.5.7

# Download and extract language files
for i in $LANGUAGES moh; do
echo "Downloading language files for $i..."
wget -q "$DOWNLOAD_PATH/audio/audio_$i.zip"
unzip -q "audio_$i.zip"
rm "audio_$i.zip"
done

# Download PBX executable and data file
echo "Downloading PBX executable..."
case "$OS" in
"centos"|"rocky"|"alma")
wget -q "$DOWNLOAD_PATH/centos$BITS/pbxctrl-centos$BITS-$VERSION"
;;
"debian")
wget -q "$DOWNLOAD_PATH/debian64/pbxctrl-debian64-$VERSION"
;;
esac

wget -q "$DOWNLOAD_PATH/dat/pbxctrl-$VERSION.dat"

# Rename and set permissions
mv "pbxctrl-centos$BITS-$VERSION" pbxctrl 2>/dev/null || mv "pbxctrl-debian64-$VERSION" pbxctrl
mv "pbxctrl-$VERSION.dat" pbxctrl.dat
chmod a+rx pbxctrl

# Configure firewall and SELinux (for RHEL-based systems)
if [ "$OS" = "centos" ] || [ "$OS" = "rocky" ] || [ "$OS" = "alma" ]; then
echo "Configuring firewall and SELinux..."
systemctl stop firewalld 2>/dev/null
systemctl disable firewalld 2>/dev/null

if [ -f /etc/selinux/config ]; then
sed -i 's/^SELINUX=.*$/SELINUX=permissive/' /etc/selinux/config
setenforce 0
status=$(getenforce)
echo "SELinux was set to $status"
fi
fi

# Install service
echo "Installing PBX service..."
case "$OS" in
"rocky"|"alma"|"centos")
# For all modern RHEL-based systems (Rocky 9+, Alma 9+, CentOS Stream 9+), use systemd
if [[ "$OS" =~ ^(rocky|alma)$ ]] ||
[[ "$OS" == "centos" && $(grep -oP '(?<=release )\d+' /etc/redhat-release) -ge 9 ]]; then
# Systemd service for modern RHEL-based systems
cat > /etc/systemd/system/pbx.service <<EOF
[Unit]
Description=Vodia PBX
After=network.target

[Service]
ExecStart=$PBX_DIR/pbxctrl --dir $PBX_DIR --no-daemon
Type=simple
RestartSec=5
Restart=always

[Install]
WantedBy=multi-user.target
EOF

chmod a+rx /etc/systemd/system/pbx.service
systemctl daemon-reload
systemctl enable pbx

# Create setup.json before starting
echo "Creating setup.json with initial credentials..."
cat <<EOF > $PBX_DIR/setup.json
{ "settings": { "pw_pass": "$md5_pass", "pw_user": "$username", "email_global":"cloud" } }
EOF
systemctl start pbx
else
# Traditional init.d service for older systems
# For Rocky/Alma/CentOS 8, we'll use systemd anyway as it's more reliable
if [[ "$OS" =~ ^(rocky|alma)$ ]] || [[ "$OS" == "centos" && $(grep -oP '(?<=release )\d+' /etc/redhat-release) -eq 8 ]]; then
cat > /etc/systemd/system/pbx.service <<EOF
[Unit]
Description=Vodia PBX
After=network.target

[Service]
ExecStart=$PBX_DIR/pbxctrl --dir $PBX_DIR --respawn
Type=forking

[Install]
WantedBy=multi-user.target
EOF

chmod a+rx /etc/systemd/system/pbx.service
systemctl daemon-reload
systemctl enable pbx

# Create setup.json before starting
echo "Creating setup.json with initial credentials..."
cat <<EOF > $PBX_DIR/setup.json
{ "settings": { "pw_pass": "$md5_pass", "pw_user": "$username", "email_global":"cloud" } }
EOF
systemctl start pbx
else
# Only for CentOS 7 will we attempt to use init.d
if [ -f /etc/init.d/functions ]; then
cat > /etc/init.d/pbx <<EOF
#!/bin/bash
#
# pbx This takes care of starting and stopping the Vodia PBX.
#
# chkconfig: - 20 80
# description: Vodia PBX PBX

### BEGIN INIT INFO
# Provides: pbx
# Required-Start: \$network \$local_fs \$remote_fs
# Required-Stop: \$network \$local_fs \$remote_fs
# Should-Start: \$syslog \$named ntpdate
# Should-Stop: \$syslog \$named
# Short-Description: start and stop the Vodia PBX
### END INIT INFO

. /etc/init.d/functions
. /etc/sysconfig/network

PBX_DIR=$PBX_DIR
prog=\$PBX_DIR/pbxctrl
lockfile=/var/lock/subsys/pbxctrl
OPTIONS="--dir \$PBX_DIR --respawn"

start() {
[ "\$EUID" != "0" ] && exit 4
[ "\$NETWORKING" = "no" ] && exit 1
[ -x \$prog ] || exit 5

echo -n \$"Starting \$prog: "
daemon \$prog \$OPTIONS
RETVAL=\$?
echo
[ \$RETVAL -eq 0 ] && touch \$lockfile
return \$RETVAL
}

stop() {
[ "\$EUID" != "0" ] && exit 4
echo -n \$"Shutting down \$prog: "
killproc \$prog
RETVAL=\$?
echo
[ \$RETVAL -eq 0 ] && rm -f \$lockfile
return \$RETVAL
}

case "\$1" in
start) start ;;
stop) stop ;;
status) status \$prog ;;
restart|force-reload) stop; start ;;
try-restart|condrestart)
if status \$prog > /dev/null; then
stop
start
fi ;;
reload) exit 3 ;;
*) echo \$"Usage: \$0 {start|stop|status|restart|try-restart|force-reload}"; exit 2 ;;
esac
EOF

chmod a+rx /etc/init.d/pbx
chkconfig --add pbx
chkconfig --level 3 pbx on

# Create setup.json before starting
echo "Creating setup.json with initial credentials..."
cat <<EOF > $PBX_DIR/setup.json
{ "settings": { "pw_pass": "$md5_pass", "pw_user": "$username", "email_global":"cloud" } }
EOF
service pbx start
else
echo "ERROR: /etc/init.d/functions not found and this appears to be CentOS 7"
echo "Falling back to systemd even though this is CentOS 7"

cat > /etc/systemd/system/pbx.service <<EOF
[Unit]
Description=Vodia PBX
After=network.target

[Service]
ExecStart=$PBX_DIR/pbxctrl --dir $PBX_DIR --respawn
Type=forking

[Install]
WantedBy=multi-user.target
EOF

chmod a+rx /etc/systemd/system/pbx.service
systemctl daemon-reload
systemctl enable pbx

# Create setup.json before starting
echo "Creating setup.json with initial credentials..."
cat <<EOF > $PBX_DIR/setup.json
{ "settings": { "pw_pass": "$md5_pass", "pw_user": "$username", "email_global":"cloud" } }
EOF
systemctl start pbx
fi
fi
fi
;;
"debian")
# Init.d service for Debian
cat > /etc/init.d/pbx <<EOF
#!/bin/bash
#
# pbx This takes care of starting and stopping the Vodia PBX.
#
### BEGIN INIT INFO
# Provides: pbx
# Required-Start: \$remote_fs \$syslog
# Required-Stop: \$remote_fs \$syslog
# Should-Start: \$portmap
# Should-Stop: \$portmap
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: Vodia PBX
# Description: Vodia PBX is a software-based private branch
# exchange (PBX) for devices that support the SIP
# protocol. It provides telephony services as well
# as associated services like provisioning devices
# for telephony.
### END INIT INFO

PBXNAME=pbxctrl
PBXEXE=$PBX_DIR/pbxctrl
PBXDIR=$PBX_DIR

case "\$1" in
start)
echo -n "Starting PBX daemon"
\$PBXEXE --dir \$PBXDIR --respawn || return=\$rc_failed
echo -e "\$return"
;;
stop)
echo -n "Shutting down PBX daemon:"
killall \$PBXNAME || return=\$rc_failed
echo -e "\$return"
;;
restart)
\$0 stop && \$0 start || return=\$rc_failed
;;
status)
echo -n "Checking for service pbx: "
systemctl status pbx
;;
*)
echo "Usage: \$0 {start|stop|status|restart}"
exit 1
esac

test "\$return" = "\$rc_done" || exit 1
exit 0
EOF

chmod a+rx /etc/init.d/pbx
update-rc.d pbx defaults

# Create setup.json before starting
echo "Creating setup.json with initial credentials..."
cat <<EOF > $PBX_DIR/setup.json
{ "settings": { "pw_pass": "$md5_pass", "pw_user": "$username", "email_global":"cloud","sys_name": "Vodia Cloud PBX" } }
EOF
service pbx start
;;
esac

# Function to get IP addresses
get_ip_addresses() {
echo "Your PBX URL is:"
# Get all non-loopback IPv4 addresses
ip -o -4 addr show 2>/dev/null | awk '{print $4}' | cut -d'/' -f1 | while read ip; do
echo " http://$ip"
done
# Also check for public IP if available
public_ip=$(curl -s ifconfig.me 2>/dev/null)
if [[ $public_ip =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
echo " http://$public_ip (Public IP)"
fi
}

# Display installation summary
echo ""
echo "=== Vodia PBX Installation Complete ==="
echo "PBX Directory: $PBX_DIR"
echo "Version: $VERSION"
echo
get_ip_addresses
echo ""
echo "You can access the PBX web interface with:"
echo "Username: $username"
echo "Password: $pw_pass"
echo ""
echo "Important notes:"
if [ "$OS" = "centos" ] || [ "$OS" = "rocky" ]; then
echo "- You might need to configure your firewall settings"
echo "- Consider 'systemctl stop firewalld' and 'systemctl disable firewalld' if needed"
fi
echo "- Make sure to change the default credentials after first login"
echo ""

Steps to Install the PBX Service:

  • Create an installation script using the provided Universal Linux Install Script.
  • Set the appropriate permissions for the script.
  • Run the script.
vi install.sh
chmod a+x install.sh
./install.sh
  • Upon successful installation, the following message will be displayed, containing the version, URL(s) to access the PBX, and the credentials.
=== Vodia PBX Installation Complete ===
PBX Directory: /usr/local/pbx
Version: 69.5.7

Your PBX URL is:
http://127.0.0.1
http://159.223.126.93
http://10.10.0.5
http://10.116.0.6
http://159.223.126.93 (Public IP)

You can access the PBX web interface with:
Username: vodia
Password: your pbx web password

Raspberry Pi:

  • Navigate to http://www.raspberrypi.org/downloads and download the Raspbian IMG and follow the installation process on this thread.
  • After the IMG has been installed SSH into your raspberry PI. The default login for Raspbian is "root" and password "raspberry".
$ wget http://portal.vodia.com/downloads/pbx/install-mini3.sh
$ chmod a+x install-mini3.sh
$ sudo ./install-mini3.sh

Follow the directions after the .sh script has been initiated.

Useful Commands

After the installation you can check if the PBX is running using the following command:

ps -C pbxctrl

You can start , stop and restart the service using the following command:

systemctl start pbx
systemctl stop pbx
systemctl restart pbx

You can also check the staus of the PBX service

systemctl status pbx
● pbx.service - LSB: Vodia PBX
Loaded: loaded (/etc/init.d/pbx; generated)
Active: active (running) since Mon 2025-04-07 15:43:20 UTC; 3s ago
Docs: man:systemd-sysv-generator(8)
Process: 2326 ExecStart=/etc/init.d/pbx start (code=exited, status=0/SUCCESS)
Tasks: 2 (limit: 1108)
Memory: 87.1M
CPU: 3.123s
CGroup: /system.slice/pbx.service
├─2328 /usr/local/pbx/pbxctrl --dir /usr/local/pbx --respawn
└─2329 /usr/local/pbx/pbxctrl --dir /usr/local/pbx --no-daemon

Software Updates

Once the service is installed, you can update the software through the web interface. The procedure is the same for all operating systems. It is important that the executable has the name "pbxctrl" and can be moved and deleted by the PBX process.

Uninstalling the Software

You can uninstall the software by deleting the working directory of the PBX (usually /usr/local/pbx) and by deleting the script pbx in the /etc/init.d directory.

Installing in the Cloud

There is a large range of service providers that can run the Vodia PBX. In this section shows examples on how to install the PBX in the cloud.

Installing Linux's Version of Vodia's IP PBX on AWS (Amazon Web Service) Instance

(AWS Templates)

Some AWS Linux templates don't by default come with swap space. This can cause random crashes of the PBX service, e.g. when cron jobs are running in the background. Please make sure that during the installation you set up swap space for the instance.

Digital Ocean

Google Cloud

OVH

Next Steps ??

Appropriate backups are critical. Please consult the backup documentation here.