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.

tip

In cloud environments like AWS or Azure, where public IPs are typically associated with network resources (e.g., load balancers, network interfaces) rather than directly assigned to virtual machines, configure the IP Routing List to private public to enable proper traffic flow. Find more information here.

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

Something went wrong? Re-run the install script?​

Before running the install script again, ensure you've cleaned up any existing PBX installation files.


##stop the service
systemctl stop pbx
OR
service pbx stop

## remove the working directory
rm -rf /usr/local/pbx

## remove the service startup file
##Ubuntu and Debian
rm -rf /etc/init.d/pbx

## CentOS, AlmaLinux, and Rocky Linux
rm -rf /etc/systemd/system/pbx.service

You can now re-run the install script to install the Vodia PBX

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.

Next Steps ??​

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

Last updated on