Installation Guide¶

Requirements ¶

Hardware ¶

To run SIPIS without problems, your hardware should meet the following requirements depending on the number of expected users.

Up to 5000 users ¶

Any modern 64 bit CPU
4 GB RAM
30 GB of disk space

Up to 30000 users ¶

Any modern 64 bit CPU
8 GB RAM
80 GB of disk space

Over 30000 users ¶

Contact us for multiple server options. The limiting resource is not hardware but the number of sockets that can be used for connections.

Other requirements ¶

An installation of 64 bit Debian 12 Bookworm. We recommend a clean installation.
A valid (HTTPS) certificate for your SIPIS server.

Adding Repository ¶

Add our key and repository to Debian:

Execute the following command to install our public key:

wget -O - https://dist.acrobits.cz/debian/acrobits.gpg.key | apt-key add -
The fingerprint for our key is 1DB8 E683 A6F4 919B BFF1 6A7C FFCC BAF7 9FF5 CF45

Create a new file /etc/apt/sources.list.d/Acrobits.list with the following content:
```
deb http://username:password@dist.acrobits.cz/debian bookworm main
```

Note

You will get a username and password from Acrobits representative.

Note

The repository for bookworm has SIPIS version 4.x. If you use bullseye in the repository line instead of bookworm you can install SIPIS version 3.x. It is possible to install version 4.x on Debian 11 Bullseye using bookworm repository or version 3.x on Debian 12 Bookworm using bullseye repository (althoug the latter is not recommended).

Run apt-get update

Installing SIPIS ¶

Installing SIPIS is as simple as running:

apt-get install sipis

This will install our packages sipis, sipis-user and loadbalancer2 and their dependencies (mainly postgresql).

Configuring SIPIS ¶

After installation your SIPIS needs to be properly configured.

Setting up the database ¶

Warning

If your PostgreSQL installation already contains user sipis and database sipis, the following script will drop these and create new ones.

Version 4.x: Run the script /usr/share/sipis/installdb. This script will create user sipis in your database and generate a password for it. It will also create database sipis and will populate it with required tables.
Version 3.x: Choose a database password. Edit the script /usr/share/sipis/installdb, put your password there and run it. This script will create user sipis in your database, database sipis and will populate your database with required tables.

Configuring LoadBalancer2 ¶

The configuration is located in /etc/acrobits/LoadBalancer2/Settings.xml. If you do not use TLS as a transport, default configuration should work fine for you.

Note

LoadBalancer2 connects to sipis on 127.0.0.1:14998. If you change SIPIS listening address from the default one it will be necessary to change the configuration of Backend to reflect this change..

If you use TLS, uncomment the following tags in the configuration file: Tls, Certificate and PrivateKey. For the latter two, enter the path to your certificate file (which should include all necessary intermediate certificates) and to you key file.

Warning

Certificate and PrivateKey must be readable by user sipis. If your setup does not work, this is the first thing to look at.

Once you configure LoadBalancer2 and SIPIS, make sure LoadBalancer2 is enabled and started:

systemctl enable LoadBalancer2.service
systemctl restart LoadBalancer2.service

When you need to renew the certificates, replace the files with the new ones and run systemctl reload LoadBalancer2.service.

Configuring SIPIS ¶

Edit file /etc/sipis/Settings.xml. You can find full documentation here.

For the impatient ¶

Version 4.x: We recommend you set Administrator password and set an appropriate Name for your SIPIS.
Version 3.x: The only thing that needs to be set is the database password in the attribute OpenString of the Database element. Insert the password you used for the database. We also recommend you set Administrator password and set an appropriate Name for your SIPIS.

Common options ¶

In Server section choose a name to your SIPIS server. If you want more than one SIPIS servers sharing the database each of them must have a unique name. Change of this parameter will mean that SIPIS will not load its database entries (because it would think they belong to different SIPIS instance).

Address shows address where SIPIS listens to requests. We recommend keeping it 0.0.0.0 so that SIPIS listens on all interfaces. If you decide to change it, you will have to change the Backend settings for LoadBalancer2 and replace address 127.0.0.1 with your chosen address. Change of this parameter requires restart of SIPIS.

HttpServer is a built in HTTP server. It is by default accessible on http://your_server:5000/stats. If you want it to listen only on localhost, change 0.0.0.0 to 127.0.0.1. You can also change the port (in that case adjust the configuration when setting up HTTPS registrations – see the following section).

With password set in Administrator section you can use the HTTP interface to execute actions.

You can change the lock file name in Lock section to match the name of your server if you wish.

Setting up HTTPS registration ¶

The device sends the SIP registration information to SIPIS using HTTPS. This uses SIPIS HTTP interface. To make this communication encrypted it is necessary to place either stunnel or HTTPS proxy (or equivalent) in front of SIPIS. Here we describe two options: stunnel and nginx. If you do not know which one to choose, use nginx method.

stunnel method ¶

Install stunnel
```
apt-get install stunnel
```
Copy file /usr/share/doc/sipis/snippets/stunnel_sipis.conf to /etc/stunnel directory.
Edit the file and set path to the key and certificate file for your server.

Note

Current example configuration file sets stunnel to listen on IPv4 only. Change accept line to accept = :::443 to make it listen on IPv6 too.

Edit /etc/default/stunnel4 and set ENABLED=1
Start stunnel
```
systemctl restart stunnel4.service
```

nginx method ¶

Install nginx

apt-get install nginx

Copy /usr/share/doc/sipis/snippets/nginx_sipis.conf into /etc/nginx/sites-enabled directory.

Note

Current example configuration file sets nginx to listen on IPv4 only. Add additional listen [::]:443 ssl; line to make it listen on IPv6 too.

Edit the file and set path to the key and certificate file for your server.
Reload nginx configuration
```
systemctl reload nginx
```

Control and Maintenance ¶

To start SIPIS run

systemctl start sipis.service

Note

To make SIPIS run automatically when your computer starts run systemctl enable sipis.service

To stop SIPIS run

systemctl stop sipis.service

to reload it after configuration change run

systemctl reload sipis.service

SIPIS produces a lot of log output. We provide logrotate configuration file so that logs are properly rotated. Debian has logrotate installed by default.

Firewall configuration ¶

Your SIPIS installation should be reachable from your customer’s devices on the following ports:

443/tcp
4998/udp
4998/tcp
24998/tcp

Your SIPIS should be able to connect to your SIP server on the port you use (typically 5060 or 5061 for TLS) and to pnm.cloudsoftphone.com on port 6552 (see note).

Notes on the individual ports usage.¶

443/tcp: This port is used by applications to register with SIPIS. Applications send HTTPS POST request with all the necessary information in the request body.
4998/udp: This port is used for heartbeat packets from applications to SIPIS. Based on this heartbeat signal SIPIS knows whether an application is running in foreground on a device or not and switches its behavior accordingly. Piggybacking on this heartbeat signal, applications also communicate their Device Tokens (identifiers used in native push services) to SIPIS and SIPIS sends information about missed calls back to applications.
4998/tcp and 24998/tls: These ports are used for handling pushed SIP calls and SIP SIMPLE messages. Connections over these ports carry SIP signaling traffic between applications and SIPIS. If you application is configured to communicate with your PBX over TLS then the application will also use port 24998/tls to communicate with SIPIS; otherwise it will use port 4998/tcp.

System tuning ¶

If you expect that your SIPIS will be used by more than 10000 users, we recommend you to change the following settings for optimal performance:

The first thing you may need to change are the limits on open file descriptors and on local port range.

Kernel parameter net.ipv4.ip_local_port_range shows which ports are used as a local port for outgoing connections. The default value on Debian system is 32768 60999. You may want to increase the range using sysctl (do not forget to set it in syysctl.conf so that it is applied on restarts).

The second limit is a limit on open file descriptors. Default limit on open files is 1024. Installed SIPIS has this set to 20480 but if you expect more users, you may need to increase it too. The current limit is set in file /usr/lib/systemd/system/sipis@.service. Changes in this file are overwritten on every upgrade so you should use systemd overriding mechanisms to set it to something bigger.

If your SIPIS machine hosts tens of thousands of users that use UDP, your system can start dropping UDP packets. To mitigate this, you should increase net.ipv4.udp_mem parameter (using sysctl). Doubling the default values (those are based on system memory) usually seems to be enough.

If you installed an older version of SIPIS, you may get the following error from the database: ERROR: integer out of range. The usual culprit is rowid column in the data table. You will want to change it to bigint using the following command when connected to sipis database: ALTER TABLE data ALTER COLUMN rowid TYPE BIGINT. New versions of sipis have this set to bigint when creating a new database but we do not change it on upgrades automatically.