Operating System Ubuntu

How to Install OpenSIPS Control Panel 9.4 on Ubuntu 26.04 LTS

Install OpenSIPS Control Panel 9.4 on Ubuntu 26.04 LTS with Apache, PHP and MariaDB, and connect it to OpenSIPS 4.0 through the database and the MI interface.

This guide installs OpenSIPS Control Panel (OCP) 9.4.0 on Ubuntu 26.04 LTS with Apache, PHP and MariaDB, next to an OpenSIPS 4.0 server from the project's own APT repository. At the end you can sign in at /cp, provision OpenSIPS modules through the database, and send Management Interface commands to the SIP server from the browser. The same steps work on Ubuntu 24.04 LTS; only the repository suite name differs.

Ubuntu 16.04 and the Control Panel 6.x and 7.x releases that ran on it are long out of support. Control Panel versions are tied to OpenSIPS versions, so pick the pair first.

Choose matching versions

Control PanelOpenSIPSStatus
9.4.04.0Maintained (OpenSIPS 4.0 until December 2027)
9.3.63.6 LTSMaintained (OpenSIPS 3.6 until May 2028)
9.3.5 and older3.5 and olderEnd of life

This guide uses 9.4.0 with OpenSIPS 4.0. For the long-term-support pair, replace 4.0 with 3.6 in the repository line and 9.4.0 with 9.3.6 in the download.

Requirements

  • Ubuntu 26.04 LTS or 24.04 LTS on amd64 (the OpenSIPS repository only builds for that architecture).
  • A user with sudo rights (the examples use deploy) on a server at 203.0.113.10.
  • If OpenSIPS and its database already run elsewhere, skip steps 2 to 4 and point the panel at that database and MI endpoint instead.

Step 1: Install Apache, PHP and MariaDB

sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install -y apache2 libapache2-mod-php php php-cli php-mysql php-gd php-curl php-pear php-apcu mariadb-server curl unzip

These are the PHP extensions the Control Panel's installation guide lists. Ubuntu 26.04 installs PHP 8.5 and Ubuntu 24.04 installs PHP 8.3.

Step 2: Install OpenSIPS from the official repository

Add the repository key and source. On Ubuntu 24.04 use noble instead of resolute.

sudo curl -fsSL https://apt.opensips.org/opensips-org.gpg -o /usr/share/keyrings/opensips-org.gpg
echo "deb [signed-by=/usr/share/keyrings/opensips-org.gpg] https://apt.opensips.org resolute 4.0-releases" | sudo tee /etc/apt/sources.list.d/opensips.list
sudo apt-get update

Install the server, the MySQL/MariaDB database module with its schema files, the HTTP modules that provide the Management Interface, and the command-line tool:

sudo apt-get install -y opensips opensips-mysql-module opensips-mysql-dbschema opensips-http-modules opensips-cli

Step 3: Create the OpenSIPS database

opensips-cli creates the opensips database, its tables and the database user that OpenSIPS and the Control Panel share. It needs an administrative database account with a password; on Ubuntu the MariaDB root account only accepts socket logins, so create a temporary one:

sudo mysql -e "CREATE USER 'ocpsetup'@'localhost' IDENTIFIED BY 'CHANGE-ME-ADMIN'; GRANT ALL PRIVILEGES ON *.* TO 'ocpsetup'@'localhost' WITH GRANT OPTION;"

Create the database. The tool's default user is opensips with the well-known password opensipsrw; override it with your own in database_url. You are prompted for the password of ocpsetup.

opensips-cli -o database_admin_url=mysql://ocpsetup@localhost \
  -o database_url=mysql://opensips:CHANGE-ME-DB@localhost \
  -x database create

Remove the temporary account afterwards:

sudo mysql -e "DROP USER 'ocpsetup'@'localhost';"

If your OpenSIPS script uses database-backed modules, put the same user and password into the db_url settings in /etc/opensips/opensips.cfg.

Step 4: Enable the Management Interface over HTTP

The Control Panel talks to OpenSIPS through JSON-RPC, served by the httpd and mi_http modules. Add these two lines to the module section of /etc/opensips/opensips.cfg, in this order:

loadmodule "httpd.so"
loadmodule "mi_http.so"

By default httpd listens on 127.0.0.1 port 8888 and mi_http answers under /mi, which is exactly the endpoint the Control Panel's default configuration expects. Keep it on the loopback address: the interface has no authentication. Check the configuration, restart and test:

sudo opensips -c -f /etc/opensips/opensips.cfg
sudo systemctl enable opensips
sudo systemctl restart opensips
curl -s -X POST -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","method":"ps","id":1}' http://127.0.0.1:8888/mi

The reply is a JSON document listing the OpenSIPS processes.

Step 5: Download the Control Panel

cd /tmp
curl -fL -o opensips-cp-9.4.0.zip https://github.com/OpenSIPS/opensips-cp/archive/9.4.0.zip
unzip -q opensips-cp-9.4.0.zip
sudo mv opensips-cp-9.4.0 /var/www/html/opensips-cp
sudo chown -R www-data:www-data /var/www/html/opensips-cp

Apache needs write access to parts of this tree, which is why it is owned by www-data.

Step 6: Configure Apache

Only the web sub-directory may be reachable from a browser. Create /etc/apache2/conf-available/opensips-cp.conf:

<Directory /var/www/html/opensips-cp/web>
    Options Indexes FollowSymLinks MultiViews
    AllowOverride None
    Require all granted
</Directory>
<Directory /var/www/html/opensips-cp>
    Options Indexes FollowSymLinks MultiViews
    AllowOverride None
    Require all denied
</Directory>
Alias /cp /var/www/html/opensips-cp/web
<DirectoryMatch "/var/www/html/opensips-cp/web/tools/.*/.*/(template|custom_actions|lib)/">
    Require all denied
</DirectoryMatch>
sudo a2enconf opensips-cp
sudo apache2ctl configtest
sudo systemctl restart apache2

Step 7: Create the Control Panel tables and set the database password

The panel stores its own data (administrators, permissions, monitored statistics, box definitions) in extra tables inside the opensips database:

sudo mysql -Dopensips < /var/www/html/opensips-cp/config/db_schema.mysql

Then open /var/www/html/opensips-cp/config/db.inc.php and set the connection values to match step 3:

$config->db_driver = "mysql";
$config->db_host = "localhost";
$config->db_port = "";
$config->db_user = "opensips";
$config->db_pass = "CHANGE-ME-DB";
$config->db_name = "opensips";

Step 8: Install the statistics cron jobs

The panel samples OpenSIPS statistics every minute and prunes them hourly. The shipped cron file runs both jobs as root; the installation guide tells you to change that to the web server user. This command rewrites the user while installing the file:

sed 's/ root (cd/ www-data (cd/' /var/www/html/opensips-cp/config/tools/system/smonitor/opensips_stats_cron | sudo tee /etc/cron.d/opensips_stats_cron
sudo systemctl restart cron

If you installed the panel somewhere other than /var/www/html/opensips-cp, correct the path in that file as well.

Step 9: Sign in and secure the panel

Browse to http://203.0.113.10/cp and sign in with user admin and password opensips, the account created by the schema file. Then:

  1. Change the admin password immediately in the administrator management tool.
  2. Open Boxes in the admin tools and check the default box. Its MI connector is json:127.0.0.1:8888/mi, which matches step 4.
  3. Run a command such as ps or uptime in the MI Commands tool to confirm the panel reaches OpenSIPS.
  4. Put the site behind HTTPS and restrict /cp to your own addresses in the Apache configuration. Two-factor login can be enabled with $config->twoFactor = true; in config/globals.php.

Tools are switched on and off in config/modules.inc.php. A tool is only useful when the corresponding OpenSIPS module is loaded and reads its data from the database.

Troubleshooting

  • Blank page or PHP errors: read /var/log/apache2/error.log. A missing PHP extension from step 1 is the most common cause.
  • Login fails with a database error: verify the values in db.inc.php with mysql -u opensips -p opensips.
  • MI commands time out: repeat the curl test from step 4. If it fails, the httpd and mi_http modules are not loaded or OpenSIPS is not running.
  • Statistics charts stay empty: check that /etc/cron.d/opensips_stats_cron exists, names www-data, and that statistics sampling is enabled for the box.

Frequently asked questions

Does the Control Panel have to run on the SIP server?

No. It only needs network access to the OpenSIPS database and to each server's MI endpoint, and one panel can manage several OpenSIPS boxes grouped into systems. In that case bind httpd to a private address and firewall the port.

Can I use PostgreSQL instead of MariaDB?

Yes. Load config/db_schema.pgsql with psql, install the PHP PostgreSQL extension and set db_driver to pgsql.

Why does a change in the panel not affect running calls?

The panel writes to the database. OpenSIPS modules cache their tables in memory and need a reload, which most tools trigger over MI. That is why a working MI connector matters.

Where is the documentation for each tool?

The project keeps per-tool pages for the 9.x series on the Control Panel documentation site.

Share story:

Continue reading other guides on How VPS.