Font Size: 14 18 24 30 / Show Hotkeys
OpenSIPS as SIP-Server for video conference systems

OpenSIPS as SIP-Server for video conference systems

PDF-Version (optimized for print)


General

Period

October 2016 - July 2017

SW Version

The test was made with the software version 2.2.4 of OpenSIPS. At the end of the testing period was a more stable version (2.3.0) available, which was not used for reasons of comparability.

Device Class

OpenSIPS stands for Open SIP Server, i.e. OpenSIPS is a open source implementation of a SIP-Server. Thus it is a part of the client server architecture of SIP protocols. The online presence of OpenSIPS is available at http://www.opensips.org.

Functionalities

OpenSIPS includes numerous functionalities, for example SIP registrar, SIP router / proxy, SIP redirect server and much more. A complete list can be found at http://opensips.org/About/Features. OpenSIPS serves as central structure, for example the management of SIP devices, the simplification of dialstrings or the spam protection. There were wide-ranging adjustment possibilities by prefabricated modules and a own script language.

Hardware

OpenSIPS runs on a Linux based system. Debian 8 ("jessie" ) was used in this test.

top of page

Installation / Configuration

Repository vs. manual installation

It should be noted that the increased effort of the installation / configuration at Open Source always has to be mentioned. Therefor the usage of the official repositorys to receive the packages is advisable. The officially available repositorys are for Debian/Ubuntu, Rehat/CentOS/Fedora. Of course the repositorys are equipped with a key, which should be imported before to ensure the authenticity of the packages. A great benefit at the usage of repositorys is the possibility to install individual modules as packages easily in the follow-up without compiling everything again.

Alternatively, or if a repository can not be used, tarballs or checkout via GIT/SVN are available. The compiling via the supplied tool menuconfig (launchable by make menuconfig) is very possible. It may be both Compile Flags (for example support for IPv6, TCP, TLS) or the to be used modules (for example database linkage for MySQL, Presence, XMPP-support) can be choosed. Of course the reliance to the other (external) packages have to be dissolved manually. In general necessary are for example the development library by ncurses (libncurses5-dev)and the packages flex,bison and m4.

Basic settings

First of all, it has to be ensured that the Linux-based system possess correct settings for the DNS. Thus, the values /etc/hosts,/etc/hostname and /etc/resolv.conf have to be checked and if necessary, changed. The most important paths to the configuration files are (at installation via a repository):

In both of the files /etc/opensips/opensipsctlrc and /etc/opensips/osipsconsolerc are a series of fundamental settings with default values. Important is, to configure the desired SIP domain and the database connection with the relevant login details. The database and the database-user do not have to exist and will be created later (see the next section "database"). In the test, the SIP-domain osips.vcc.test.tu-dresden.de and as database MySQL were used on the same Linux-system. Further settings were left on the default values.

Database

By means of the tool opensipsdbctl create the database, the database-user and the appropriate permissions will be created in accordance with requirements of /etc/opensips/opensipsctlrc.
It should be noted here that at the usage of OpenSIPS Control Panels (see relevant section) further tables in the database have to be added.

Configuration file / Script set

A central configuration file is existing for OpenSIPS under /etc/opensips/opensips.cfg, which contains for example to be used IP-addresses, a register of to be used modules, settings for the moduels (inter alia, database connection , filepaths) and the setting for the logging. An essential component is the routing-script, which will go through every request for example register-request or invite-request and which can be customized very precisely to the needed requirements.

The preparation of such a configuration file can be done by the tool osipsconfig. It generates depending on the desired purpose and a first list of requirements (see the black box on the right side) a configuration-/script template. The template has to be changed to the local conditions by setting up the specific positions, which are marked with # CUSTOMIZE ME. Affected are, for example the IP-address, the database connection and the filepaths.

listen=udp:141.30.abc.xyz:5060 # CUSTOMIZE ME
listen=tcp:141.30.abc.xyz:5060 # CUSTOMIZE ME
listen=tls:141.30.abc.xyz:5061 # CUSTOMIZE ME

It is recommended to indicate the module domain, to distinguish particularly the local domains:

####### Modules Section ########

loadmodule "domain.so"
modparam("domain", "db_url", "mysql://user:pw@host/db-name")
modparam("domain", "db_mode", 0) # No caching for debug
modparam("domain", "domain_table", "domain")
modparam("domain", "domain_col", "domain")

Log files

Until the productive operation it is very valuable to have informations in the log files as many as possible, because regularly the few bugs and problems can not be seen and be bypassed in advance. It is therefore sensible to do the following entry to the file/etc/opensips/opensips.cfg:

####### Global Parameters #########

log_level=4
log_stderror=no
log_facility=LOG_LOCAL1

Furthermore there has to be indicated on the Linux-based system what local1 exactly means. This is why the entry in /etc/rsyslog.confis needed, to redirect the issues into the file:

local1.* -/var/log/opensips.log

Rsyslog has to be restarted afterwards.

Start as service vs. manual start

For a first testing, a manual start is still practicable, but the start as service should be preferred at a frequent usage of OpenSIPS. For the manual start of OpenSIPS as service, two files have to be changed:

The usage take place by /etc/init.d/opensips {start|stop|restart|force-reload|status}. Especially with /etc/init.d/opensips status a first analysis of problems is may be possible.

DNS records

To be found by SIP-devices via the SIP-domain, DNS-records are necassary for OpenSIPS. In this case, direct A-records and also SRV-records make sense:

Not all combinations are reasonable at the indicated SRV-records. The choosing options are coming from the possible encoding and the transport protocol. Useful variants for _tcp are for example just:

It is recommendable to think about the appropriate reserve DNS-entries and to check the DNS-entries for the SIP-devices.
top of page

Operation

OpenSIPS Control Panel

The OpenSIPS Control Panel is a php based graphical user interface. OpenSIPS Control Panel is developed separately and is available under http://controlpanel.opensips.org/ as Tarball or SVN Checkout.

There are some package dependencies, so libapache2-mod-php5, php5, php5-cli, php5-gd, php5-mysql, php-pear, php5-xmlrpc have to be installed. The OpenSIPS Control Panel needs also some other modules which can be installed via pear: pear install MDB2, pear install MDB2#mysql, pear install log

The integration into Apache2 happens for example via Alias- and Directory-statements at /etc/apache2/apache2.conf:

### OpenSips Control Panel ###

<Directory /somewhere/opensips-cp/web>
Options Indexes FollowSymLinks MultiViews
AllowOverride None
</Directory>

<Directory /somewhere/opensips-cp>
Options Indexes FollowSymLinks MultiViews
AllowOverride None
Require ip 141.30.abc.xyz/32
</Directory>

Alias /opensips-cp /somewhere/opensips-cp/web

With these settings OpenSIPS Control Panel can be achieved under host/opensips-cp, in which host the DNS name of the computer is, where OpenSIPS is setted up. During testing it was the same computer on which OpenSIPS runs. It should be noted that, the files of OpenSIPS Control Panel got enough rights (for example www-data) and Apache2 has to be reloaded at the end.

A further important point is the necessity of the setting

short_open_tag=On

into the file php.ini, so that the php-scripts work.

Moreover, diverse extensions of the existing database on the computer with OpenSIPS are required. There are therefore prefabricated tables ocp_admin_privileges.mysql, cdrs.mysqland tables.mysql, which have to be inserted into the data base of OpenSIPS. The first administrativ user of OpenSIPS Control Panel will be registered at the table ocp_admin_priviliges via

INSERT INTO ocp_admin_privileges values('admin','passwort',md5('admin:passwort'),'all','all')

Besides the adjustments of the database, the database connection at config/db.inc.php and config/boxes.global.inc.php at the OpenSIPS fifo-queue have to be specified at the OpenSIPS Control Panel. The OpenSIPS fifo-queue will be defined at /etc/opensips/opensips.cfg under the fifo management.

As the last set-up point, the entry at /etc/crontab is senseful for the statics:

* * * * * root cd /somewhere/opensips-cp/cron_job/; php get_opensips_stats.php > /dev/null

The OpenSIPS Control Panel can be used in many different ways. So is, inter alia, the entry of SIP domains, the creation of accesses / accounts, the notification of active and past calls and the direct access on various modules / tables of the data base possible. As the SIP domain, the related ip-address should be also indicated every time (see the screenshot below). Here it should be noted, that not all files of the database / modules are depicted in the OpenSIPS Control Panel, but a few menu items can be programmed.

A debugging is without a direct data base access and access on the log-files from OpenSIPS hardly possible.

Settings at the SIP device

The necassary settings at the SIP device remain within limits as expected. It is to be noted, that the devices which control another protocols (for example H.323), first of all activate SIP as protocol. Also the "eavesdropping" on port 5060 or 5061 for incoming calls can be missed quickly.

The necassary settings at the SIP device are including:

Control options / troubleshooting

There are a lot of possibilities and places where errors / problems can be found in connection with OpenSIPS:

  • At the SIP device: Depending on the device, it will for example show notifications to the registration status on the web interface.
  • Via netstat –tulpn | grep opensips: Testing, if OpenSIPS is waiting at the correct port for incoming SIP Requests.
  • At the logs: In /var/logs/opensips.log a lot of processes can be traced at a high log level. There are also the used modules / functions for each case:



  • At the OpenSIPS Control Panel: There is the possibility for example, that running calls in the subitem dialogue and finished calls in the subitem CDR Viewer may be reviewed:




  • At the database: At the database of OpenSIPS are for example failed calls in the table missedCalls and registered SIP devices can be found in the table location.
  • Via the command-line tool: Serverstatics are accessible via opensipsctl monitor and registered SIP devices via opensipsctl ul show or opensipsctl online:


  • Call possibilities

    In principle, the calls have to be devided in accordance with the registration status of the involved SIP devices and in accordance with used transport protocol.

    On the sending and on the receiving site of the call, TCP / UDP or TLS can be used in each case, if OpenSIPS is configured accordingly. In this case 9 variants are conceivable, whereby OpenSIPS is assuming every time the possible necessary log switching in the signalling.

    Regarding the registration status 3 variants are conceivable:

    top of page

    Usage of TLS / certificate management

    To use encoded signalling via TLS, a according module has to be configured at OpenSIPS and there has to be created at least one certificate.

    The certificates will be applied at DFN-PKI. To that, it is necessary to create a certifacte request for each case via openssl. The requirements to the certificate should be taken account:

    Certifacte for OpenSIPS:

    Ceriticates for SIP devices:

    It is important, that the DFN-PKI master certificate at OpenSIPS and the SIP devices will be lodged as trustworthy CA so that a validation can be performed.

    The involvement of the certificates takes place at /etc/opensips/opensips.cfg. Potentially available lines with modparam("proto_tls", ...) have to be commented out, because meanwhile everything is located at the module tls_mgm:

    ####### Modules Section ########

    loadmodule "proto_tls.so"
    ## manuell auskommentiert, da Parameter nicht verfuegbar:
    ## modparam("proto_tls","verify_cert", "1")
    ## modparam("proto_tls","require_cert", "0")
    ## modparam("proto_tls","tls_method", "TLSv1")
    ## modparam("proto_tls","certificate", "/etc/opensips/tls/user/user-cert.pem")
    ## modparam("proto_tls","private_key", "/etc/opensips/tls/user/user-privkey.pem")
    ## modparam("proto_tls","ca_list", "/etc/opensips/tls/user/user-calist.pem")

    ## manuell hinzugefuegt:
    loadmodule "tls_mgm.so"

    modparam("tls_mgm","db_url", "mysql://user:pw@host/db-name")

    modparam("tls_mgm","verify_cert", "1")
    modparam("tls_mgm","require_cert", "1")
    modparam("tls_mgm","tls_method", "TLSv1")
    modparam("tls_mgm","certificate", "/etc/opensips/tls/user-dfnpki/user-cert.pem")
    modparam("tls_mgm","private_key", "/etc/opensips/tls/user-dfnpki/user-privkey-new.pem")
    modparam("tls_mgm","ca_list", "/etc/opensips/tls/user-dfnpki/user-calist.pem")
    modparam("tls_mgm","ca_dir", "/etc/opensips/tls/user-dfnpki/")

    The file with the private key should be available without passphrase otherwise a start as service is not possible because there can`t be entered a password.
    If there are not enough certificates for all SIP devices (require_cert) or they are not verifiable (verify_cert), the corresponding switch has to be set on "0". The review of the SIP devices is not possible via the certificate but the connection establishment is encoded.

    Because the DFN-PKI certificates are slightly bigger, the devices require during testing more than 100 ms at the TLS handshake with OpenSIPS. Within this, there were accidental disconnections at the call establishment. Thus, the following parameters have to be changed:

    modparam("tls_mgm","tls_send_timeout", zeitwert)
    modparam("tls_mgm","tls_handshake_timeout", zeitwert)

    TLS connection will be distinguished between incoming TLS connections to OpenSIPS (server_domain) and outgoing TLS connections from OpenSIPS (client_domain). Depending on the socket (IP address: Port) different settings can be made:

    modparam("tls_mgm","server_domain","1=141.30.67.218:5061")
    modparam("tls_mgm","verify_cert", "1:1")
    modparam("tls_mgm","require_cert", "1:1")
    modparam("tls_mgm","tls_method", "1:TLSv1")
    modparam("tls_mgm","certificate", "1:/etc/opensips/tls/user-dfnpki/user-cert.pem")
    modparam("tls_mgm","private_key", "1:/etc/opensips/tls/user-dfnpki/user-privkey-new.pem")
    modparam("tls_mgm","ca_list", "1:/etc/opensips/tls/user-dfnpki/user-calist.pem")
    modparam("tls_mgm","ca_dir", "1:/etc/opensips/tls/user-dfnpki/")

    modparam("tls_mgm","client_domain","2=141.30.67.247:5061")
    modparam("tls_mgm","verify_cert", "2:1")
    modparam("tls_mgm","require_cert", "2:1")
    modparam("tls_mgm","tls_method", "2:TLSv1")
    modparam("tls_mgm","certificate", "2:/etc/opensips/tls/user-dfnpki/user-cert.pem")
    modparam("tls_mgm","private_key", "2:/etc/opensips/tls/user-dfnpki/user-privkey-new.pem")
    modparam("tls_mgm","ca_list", "2:/etc/opensips/tls/user-dfnpki/user-calist.pem")
    modparam("tls_mgm","ca_dir", "2:/etc/opensips/tls/user-dfnpki/")

    These distinctions are particularly useful, if OpenSIPS has to manage multiple SIP domains and can be contacted via different IP addresses. Then it will be ensured, that the used certificate also fits to the SIP domain, which is currently used.

    top of page

    Usage of other modules / scripting

    This section describes in an exemplary the procedure how OpenSIPS can be adapted to the own needs. Helpful for the scripting are the documentations of the available variables, functions and statements:

    Domain module

    The domain module was already inserted in the chapter configuration file / script set at /etc/opensips/opensips.cfg:

    ####### Modules Section ########

    loadmodule "domain.so"
    modparam("domain", "db_url", "mysql://user:pw@host/db-name")
    modparam("domain", "db_mode", 0) # No caching for debug
    modparam("domain", "domain_table", "domain")
    modparam("domain", "domain_col", "domain")

    It allows to enter SIP domains in the data base or via the OpenSIPS Control Panel. The indicated SIP domains will be recognised as "local". Each call will be tested, that at least one site is local (caller, callee).

    Dialplan module

    The module dialplan enables the transcription of strings, typically the request URI. It controlles the string matching (matching operator = 0) and the regex matching (matching operator = 1). The indication of the rules are made via the database or the OpenSIPS Control Panel:

    The usage of /etc/opensips/opensips.cfg at the routing script is made via dp_translate("0","$ru/$ru");
    In that connection,$ru stands for request URI and indicates the first value that all rules have to be controlled with dialplan ID = 0.
    For example for the usage of the first rule is here to see (extract from the log file):

    Protection of the SIP devices/ measures for the spam protection

    It is common ground that unprotected SIP devices fall victim to SIP spam calls which also become more as at H.323. Targets of the attackers are mostly the free cost usage of the telephone or the generating of high costs via the infiltrated VoIP platform. At video conference systems the expense is mostly not given (except there is a connection into the ISDN world), but the SIP spam calls are disturbing or blocking the normal communication substantially. To be protected, a simple spam protection could be established with OpenSIPS.

    To begin with, the SIP devices should be not longer directly reachable from "outside" via the Port 5060/ 5061 after the registration at OpenSIPS, as otherwise OpenSIPS could be bypassed at the signalling. At some devices it can be directly stopped, otherwise it has to be realized by the help of firewalls, ACL`s etc. Therefore the signalling via OpenSIPS is enforced, the media streams (RTP / SRTP) will continue to be established directly via dynamically negotiated ports between the SIP devices.

    The majority of the SIP spam calls have the form numbers@ip-address as To-URI. These will continue to come at OpenSIPS and could be transmitted to the appropriate device. That is why for example a block of the SIP spam calls with the IP address as SIP domain is possible. The necassary lines in the routing script from /etc/opensips/opensips.cfg were as follows:

    if ($td == "141.30.67.218") {
    xlog("Dropped Spam-Call to $tu\n");
    exit;
    }

    At this point $td is the SIP domain at the To-URI ($tu). If OpenSIPS is reachable via multiple IP addresses, the term has to be correspondingly adjusted. Of course, more aspects of the SIP spam calls can be considered, but during the test the simple spam protection showed already a sufficient effect:

    In this scenario the regular calls have to be made by name/alias@SIP-Domäne, whereby the SIP domain is a DNS name.

    top of page

    Conclusion

    The installation / configuration of OpenSIPS is unfortunately not self-explanatory, but the documentation is well suited. The way to the operational capability of OpenSIPS requires still a lot time, especially because the methode "trial & error" have to be used many times.
    The separate OpenSIPS Control Panel facilitates the typical operations, but it is not a complete replacement for the database access or the work with the console.
    Many entities, where the mistakes can be found require a certain overview and thus appropriate training period.
    The certificate management can be used effectively, especially because the certificates can be taken up via the DFN-PKI easy, fast and reliable.
    The induction into the script language, work with the console etc. is absolutely essential. Numerous modules and the possibility of self-development offers a great scope. For example is a simple spam protection for SIP devices viable .

    top of page