Installation Guide ================== .. contents:: :local: :depth: 3 .. _sipis-requirements: 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 ```````````````` 1. Any modern 64 bit CPU 2. 4 GB RAM 3. 30 GB of disk space Up to 30000 users ````````````````` 1. Any modern 64 bit CPU 2. 8 GB RAM 3. 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 .................. 1. An installation of 64 bit Debian 12 Bookworm. We recommend a clean installation. 2. A valid (HTTPS) certificate for your SIPIS server. .. _sipis-adding-repo: Adding Repository ----------------- Add our key and repository to Debian: 1. Execute the following command to install our public key: .. code-block:: bash 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** 2. 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). 3. Run ``apt-get update`` Installing SIPIS ----------------- Installing SIPIS is as simple as running: .. code-block:: bash 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: .. code-block:: bash 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 :doc:`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 :doc:`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 `````````````` 1. Install ``stunnel`` .. code-block:: bash apt-get install stunnel 2. Copy file ``/usr/share/doc/sipis/snippets/stunnel_sipis.conf`` to ``/etc/stunnel`` directory. 3. 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. 4. Edit ``/etc/default/stunnel4`` and set ``ENABLED=1`` 5. Start stunnel .. code-block:: bash systemctl restart stunnel4.service nginx method ```````````` 1. Install ``nginx`` .. code-block:: bash apt-get install nginx 2. 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. 3. Edit the file and set path to the key and certificate file for your server. 4. Reload nginx configuration .. code-block:: bash systemctl reload nginx Control and Maintenance ----------------------- To start SIPIS run .. code-block:: bash systemctl start sipis.service .. note:: To make SIPIS run automatically when your computer starts run ``systemctl enable sipis.service`` To stop SIPIS run .. code-block:: bash systemctl stop sipis.service to reload it after configuration change run .. code-block:: bash 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 :ref:`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.