Kamailio¶

This step depends on installing the Ruby on Rails application, which bootstraps the database. Kamailio shares this database with the front end.

Kamailio is a SIP router. We are only concerned with a small subset of the SIP protocol. We only use Kamailio for SIP registration, user endpoint location and media proxy coordination. It has various database drivers for persistence, which makes the design very modular.

Create a read only database user in postgres. For appropriate security, say no to all the prompts about superuser, roles, databases.

su - postgres
createuser -E -P -e kamailio ( make a nice long password, you never have to type it in )
psql production

Now for some SQL permissions

GRANT SELECT ON dbaliases,domain_attrs,domains,users,version TO kamailio;
\q
exit

Install the correct package repo , then install the following packages. The version of Kamailio in production at ostel.co as of this writing is 4.1. Prior versions have incompatible configuration syntax and will not work with the example configuration provided.

apt-get update
apt-get install kamailio kamailio-tls-modules kamailio-postgres-modules kamailio-utils-modules

Install rtpproxy for NAT traversal.

Copy the Kamailio configuration file for the same version you have installed (linked at the end of this document) to /etc/kamailio/kamailio.cfg

cd /etc/kamailio
mv kamailio.cfg kamailio.cfg.bak
wget https://dev.guardianproject.info/attachments/download/1330/kamailio.cfg

Edit the DBURL variable to that of the database connection information you created above. It should look something like

#!define DBURL "postgres://kamailio:0000000000000000@127.0.0.1/webapp_production" 

Edit /etc/default/kamailio to the following recommended values. You may need to change these during performance tuning.

#
# Kamailio startup options
#

# Set to yes to enable kamailio, once configured properly.
RUN_KAMAILIO=yes

# User to run as
USER=kamailio

# Group to run as
GROUP=kamailio

# Amount of shared and private memory to allocate
# for the running Kamailio server (in Mb)
SHM_MEMORY=512
PKG_MEMORY=32

# Config file
CFGFILE=/etc/kamailio/kamailio.cfg

# Enable the server to leave a core file when it crashes.
# Set this to 'yes' to enable Kamailio to leave a core file when it crashes
# or 'no' to disable this feature. This option is case sensitive and only
# accepts 'yes' and 'no' and only in lowercase letters.
# On some systems it is necessary to specify a directory for the core files
# to get a dump. Look into the kamailio init file for an example configuration.
#DUMP_CORE=yes

TLS¶

By default Kamailio uses a self signed SSL certificate. If you would like to use an SSL certificate signed by a commercial Certificate Authority, you must generate a CSR and purchase a certificate from a vendor. When you have the certificate copy it to /etc/kamailio/ssl/ and edit the file /etc/kamailio/tls.cfg to point to that certificate.

There are significantly higher resource requirements for running a SIP server with SSL if compared to a web server with HTTPS. While low by contemporary standards, the amount of RAM needed for a server with > 1000 concurrent users is four to six times the default configuration. The TLS module also happens to be buggy. Alterations to any of the configuration could result in a crashing server.

Networking security and NAT Configuration¶

If you are new to anything VoIP (not just Kamailio and ostel.co) you will quickly understand that NAT is the largest challenge faced by all VoIP applications. Kamailio is no exception. We have already installed rtpptoxy, which places the burden of NAT traversal on the server side and simplifies the client config. For most cases this is all you need.

If your server is also behind NAT, or has network connections to multiple networks (for example a public IP and a private IP) you must do some additional configuration to allow clients to connect.

If your server has multiple network interfaces, you must choose the interface that connects to the public Internet. This usually happens by default, though you can ensure it binds to the correct interface by changing the following line in /etc/kamailio/kamailio.cfg in the global parameters section, where <ethX> is the name of your public network interface. This is commonly "eth0", though some servers differ (on mine it is called eth1). This value must be set for the ostel.co configuration and cannot be set to "all interfaces" (0.0.0.0/0)

listen <ethX>

As of this writing, Kamailio has a security limitation in the core configuration. If you wish to only allow secure SIP signaling, you must force the server to only listen on TCP port 5061 (the secure SIP default). Kamailio lacks the option to enforce this policy. The recommended method is to use Linux iptables to reject incoming traffic to TCP/UDP port 5060 from every IP address except for localhost. Add the following rules to iptables where <1.1.1.1> is your server's public IP address and save this configuration to load at reboot.

iptables -A INPUT -s 127.0.0.1/8 -d <1.1.1.1>/32 -p tcp -m tcp --dport 5060 -j ACCEPT
iptables -A INPUT -s 127.0.0.1/8 -d <1.1.1.1>/32 -p udp -m udp --dport 5060 -j ACCEPT
iptables -A INPUT -s 0.0.0.0/0 -d <1.1.1.1>/32 -p tcp -m tcp --dport 5060 -j REJECT --reject-with icmp-port-unreachable
iptables -A INPUT -s 0.0.0.0/0 -d <1.1.1.1>/32 -p udp -m udp --dport 5060 -j REJECT --reject-with icmp-port-unreachable
iptables-save > /etc/iptables.save

Create a file at /etc/network/if-up.d/iptables with the following contents to have your iptables rules loaded at system startup

#!/bin/bash
iptables-restore < /etc/iptables.save

Give the script the permission to run

chmod 755 /etc/network/if-up.d/iptables

Start Kamailio

/etc/init.d/kamailio start

Read the output from the startup script. If it did not print out an error, check if kamailio is running with the following

kamctl stats

If it's running, cool! If not, it's time to debug kamailio.

The recommended way to start Kamailio in a production system is with monit

At this point you should have all the core services running, but you don't have any users! This requires using the web interface to create a new user. Proceed to the Unicorn setup instructions. Don't forget to set your SMTP server as documented in the previous Ruby on Rails section.

Official Kamailio documentation