Basic Kamailio configuration

After installing Kamailio, there are three configuration templates in /etc/kamailio:

root@SystemY:/etc/kamailio# ls -l
total 72
-rw-r--r-- 1 root root  1745 Jan 19 10:08 dictionary.kamailio
-rw-r--r-- 1 root root 22631 Jan 19 10:08 kamailio-advanced.cfg
-rw-r--r-- 1 root root 14854 Jan 19 10:08 kamailio-basic.cfg
-rw-r--r-- 1 root root 22163 Jan 19 10:08 kamailio.cfg
-rw-r--r-- 1 root root  3737 Jan 19 10:08 kamctlrc

The file kamailio.cfg is very similar to (but slightly unexpectedly different from) kamailio-advanced.cfg, so I decided to put that to one side and start from the basic version instead:

root@SystemY:/etc/kamailio# mv kamailio.cfg kamailio-dist.cfg
root@SystemY:/etc/kamailio# cp kamailio-basic.cfg kamailio.cfg

I then edited kamailio.cfg (following the guidelines from the wiki) to add MySQL and Authentication support, by adding the lines:

#!define WITH_MYSQL
#!define WITH_AUTH

A little way below the first line #!KAMAILIO, but before any of the examples.

My first impression of working with Kamailio is that it was very odd having functional directives in the configuration file which start with the comment lead-in character '#'…

The next step in the wiki guidelines says "Obviously, for the above to really work, you need to install MySQL server and create the database required by Kamailio (see kamdbctl tool). You need also to add subscribers (username/password to subscriber database table). You can use kamctl tool for managing subscriber records."

So, I tried the kamdbctl tool, and got:

root@SystemY:/etc/kamailio# kamdbctl
ERROR: database engine not specified, please setup one in the config script

Two things went through my mind here:

1. Yes, I have specified a database engine - I've just put "WITH_MYSQL" into /etc/kamailio/kamailio.cfg
2. Okay, if that's not the configuration file you're complaining about, how about telling me which "config script" needs MySQL specifying in it?

Aha! Further down on the wiki page under kamdbctl is the comment "It uses the same configuration file like kamctl, respectively the kamctlrc."

So, that's the configuration file it would have been nice for the error message to tell me needs adjusting…

I uncommented the following parameters and set values for them:

## your SIP domain
SIP_DOMAIN=my_domain.net

## database type: MYSQL, PGSQL, ORACLE, DB_BERKELEY, DBTEXT, or SQLITE
# by default none is loaded
#
# If you want to setup a database with kamdbctl, you must at least specify
# this parameter.
DBENGINE=MYSQL

## database host
DBHOST=localhost

## database name (for ORACLE this is TNS name)
DBNAME=kamailio

## database read/write user
DBRWUSER="kamailio"

## password for database read/write user
DBRWPW="my_rw_password"

## database read only user
DBROUSER="kamailioro"

## password for database read only user
DBROPW="my_ro_password"

## database access host (from where is kamctl used)
DBACCESSHOST=127.0.0.1

## database super user (for ORACLE this is 'scheme-creator' user)
DBROOTUSER="root"

# user name column
USERCOL="username"

After saving the file, trying the kamdbctl command now gives:

root@SystemY:/etc/kamailio# kamdbctl
/usr/sbin/kamdbctl 4.4.0

usage: kamdbctl create <db name or db_path, optional> ...(creates a new database)

...etc...

So, it's now happy that it knows I want to use a database.

Let's try creating one:

root@SystemY:/etc/kamailio# kamdbctl create
MySQL password for root: 
INFO: test server charset
INFO: creating database kamailio ...
INFO: granting privileges to database kamailio ...
INFO: creating standard tables into kamailio ...
INFO: Core Kamailio tables succesfully created.
Install presence related tables? (y/n): y
INFO: creating presence tables into kamailio ...
INFO: Presence tables succesfully created.
Install tables for imc cpl siptrace domainpolicy carrierroute
                userblacklist htable purple uac pipelimit mtree sca mohqueue
                rtpproxy? (y/n): y
INFO: creating extra tables into kamailio ...
INFO: Extra tables succesfully created.
Install tables for uid_auth_db uid_avp_db uid_domain uid_gflags
                uid_uri_db? (y/n): y
INFO: creating uid tables into kamailio ...
INFO: UID tables succesfully created.

Not knowing at this stage the benefits or drawbacks of creating any of the extra tables, I answered "yes" to each of the questions on the basis that I don't care if tables exist in MySQL which then never get used, but I find out I want to use one, I'd like it to exist…

It would be nice if "successfully" were spelled correctly :)

So, heading back to the wiki, "You need also to add subscribers (username/password to subscriber database table). You can use kamctl tool for managing subscriber records."

Let's see what the kamctl tool does now:

root@SystemY:/etc/kamailio# kamctl
/usr/sbin/kamctl 4.4.0

Existing commands:

...etc...

There then follows a lengthy list of commands you can use with kamctl, including starting & stopping Kamailio (so, it sounds like I shouldn't be using the normal /etc/init.d/kamailio restart etc?).

The command for managing subscribers are:

• add <username> <password> ………. add a new subscriber (*)
• show <username> ……………….. show subscriber attributes (*)
• passwd <username> <passwd> ……… change user's password (*)
• rm <username> …………………. delete a user (*)
• sets <username> <attr> <val> ……. set string attribute (column value)
• setn <username> <attr> <val> ……. set numeric attribute (column value)

So, let's try adding a subscriber:

root@SystemY:/etc/kamailio# kamctl add Polycom 834622a413e3c42c2dd8080c226bee85
new user 'Polycom' added
root@SystemY:/etc/kamailio# kamctl show Polycom
*************************** 1. row ***************************
           id: 2
     username: Polycom
       domain: my_domain.net
     password: 834622a413e3c42c2dd8080c2
email_address: 
          ha1: 832a1c4706237713837a0bd8e6876e0f
         ha1b: 20be01352f53a20caea1487745b789f5
         rpid: NULL

Looks good so far…

Edit: No, that doesn't look so good - I specified a 32-character password (actually the MD5sum of "Polycom") and the database contains only 25 of them :(

And, sure enough, asking MySQL for the column definitions in the 'subscriber' table shows me that passwords are stored to only 25 characters length! BAH!

(The following continues as it was written before the above edit.)

Let's try starting Kamailio and see what I get in the log files:

root@SystemY:/etc/kamailio# kamctl start

INFO: Starting Kamailio : 

ERROR: PID file /var/run/kamailio.pid does not exist -- Kamailio start failed

Hm, well, of course the .pid file doesn't exist - I've just asked Kamailio to start, which should create it… Okay, let's go back to the standard way of starting services:

Uncomment the following in /etc/default/kamailio:

RUN_KAMAILIO=yes
USER=kamailio
GROUP=kamailio
CFGFILE=/etc/kamailio/kamailio.cfg

Start the service:

root@SystemY:/etc/kamailio# /etc/init.d/kamailio start
[....] Starting Kamailio SIP Server: kamailio:loading modules under config path: /usr/lib/x86_64-linux-gnu/kamailio/modules/
Listening on 
             udp: 127.0.0.1:5060
             udp: 213.138.113.127:5060
             tcp: 127.0.0.1:5060
             tcp: 213.138.113.127:5060
Aliases: 
             tcp: SystemY:5060
             tcp: SystemY.voxspan.net:5060
             tcp: localhost:5060
             tcp: localhost.localdomain:5060
             udp: SystemY:5060
             udp: SystemY.voxspan.net:5060
             udp: localhost:5060
             udp: localhost.localdomain:5060

. ok 

Now that's more like it :)

What's in the log file?

Well, there's a whole load of stuff in /var/log/messages and /var/log/syslog (not sure I like that, I'd prefer to get things in /var/log/kamailio.log or similar - I'll see how to change that, I think.

However, amongst the entries in /var/log/syslog are lots of:

Mar  1 15:04:58 systemy /usr/sbin/kamailio[15636]: ERROR: db_mysql [km_my_con.c:124]: db_mysql_new_connection(): driver error: Access denied for user 'kamailio'@'localhost' (using password: YES)

So, when I gave kamdbctl the root MySQL password, did it not set up the Kamailio users?

No, there's a kamailio database in MySQL, it contains a table subscribers, which has a single entry for the user Polycom, and there are MySQL users 'kamailio'@'localhost' and 'kamailioro'@'localhost' as well as the same usernames @'127.0.0.1'. The Mysql GRANT privileges also look okay.

So, that's not the problem…

Ah - the output from /etc/init.d/kamailio start is disappointingly misleading:

root@SystemY:/var/log# /etc/init.d/kamailio restart
[ ok ] Stopping Kamailio SIP Server: kamailio:.
[....] Starting Kamailio SIP Server: kamailio:loading modules under config path: /usr/lib/x86_64-linux-gnu/kamailio/modules/
Listening on 
             udp: 127.0.0.1:5060
             udp: aaa.bbb.ccc.ddd:5060
             tcp: 127.0.0.1:5060
             tcp: aaa.bbb.ccc.ddd:5060
Aliases: 
             tcp: SystemY:5060
             tcp: SystemY.my_domain.net:5060
             tcp: localhost:5060
             tcp: localhost.localdomain:5060
             udp: SystemY:5060
             udp: SystemY.my_domain.net:5060
             udp: localhost:5060
             udp: localhost.localdomain:5060

. ok 
root@SystemY:/var/log# /etc/init.d/kamailio status
[FAIL] Status of Kamailio SIP Server: :[....] kamailio is not running ... failed!

So, that encouraging-looking ok at the end of the output from the start command does not in fact mean that it successfully started and is running :(

Let's try turning on some debugging, and also get the logging to its own file, not to syslog.

Well, it appears that you can't tell Kamailio to log to its own file; you have to configure syslog to split it out instead. Oh well…

So, lines changed in /etc/kamailio/kamailio.cfg:

#!define WITH_DEBUG
log_stderror=no

Added to /etc/rsyslog.conf:

local0.*                        -/var/log/kamailio.log

See if it's worked:

root@SystemY:/etc# /etc/init.d/rsyslog restart
[ ok ] Stopping enhanced syslogd: rsyslogd.
[ ok ] Starting enhanced syslogd: rsyslogd.
root@SystemY:/etc# ls -l /var/log/kamailio.log
-rw-r-----  1 root        adm        0 Mar  1 15:30 kamailio.log
root@SystemY:/etc# /etc/init.d/kamailio restart
[ ok ] Stopping Kamailio SIP Server: kamailio:.
[....] Starting Kamailio SIP Server: kamailio:loading modules under config path: /usr/lib/x86_64-linux-gnu/kamailio/modules/
Listening on 
             udp: 127.0.0.1:5060
             udp: 213.138.113.127:5060
             tcp: 127.0.0.1:5060
             tcp: 213.138.113.127:5060
Aliases: 
             tcp: SystemY:5060
             tcp: SystemY.voxspan.net:5060
             tcp: localhost:5060
             tcp: localhost.localdomain:5060
             udp: SystemY:5060
             udp: SystemY.voxspan.net:5060
             udp: localhost:5060
             udp: localhost.localdomain:5060

. ok 
root@SystemY:/etc# ls -al /var/log/kamailio.log
-rw-r-----  1 root        adm   110238 Mar  1 15:31 kamailio.log

Success! We now have 110k of debug-level logs in a file separate from /var/log/messages and /var/log/syslog. Much neater.

Does it tell us what the problem with the MySQL users is?

Some way down the file I see:

Mar  1 15:31:08 SystemY kamailio: DEBUG: <core> [cfg.lex:1813]: pp_define_get(): ### returning define ID [DBURL] value ["mysql://kamailio:kamailiorw@localhost/kamailio"]

…which looks to me very much as though it's trying to use the default password of kamailiorw and not the password I defined in the config file…

root@SystemY:/etc/kamailio# grep -r kamailiorw .
./kamailio-basic.cfg:#!define DBURL "mysql://kamailio:kamailiorw@localhost/kamailio"
./kamailio-dist.cfg:#!define DBURL "mysql://kamailio:kamailiorw@localhost/kamailio"
./kamailio-advanced.cfg:#!define DBURL "mysql://kamailio:kamailiorw@localhost/kamailio"
./kamailio.cfg:#!define DBURL "mysql://kamailio:kamailiorw@localhost/kamailio"

Aha - I not only have to define the database user & password in /etc/kamailio/kamctlrc, but also in /etc/kamailio/kamailio.cfg - what a nice opportunity for change mismanagement :(

So, I edit /etc/kamailio/kamailio.cfg to contain:

#!define DBURL "mysql://kamailio:my_rw_password@localhost/kamailio"

…and try again:

root@SystemY:/etc/kamailio# /etc/init.d/kamailio start
[....] Starting Kamailio SIP Server: kamailio:loading modules under config path: /usr/lib/x86_64-linux-gnu/kamailio/modules/
Listening on 
             udp: 127.0.0.1:5060
             udp: aaa.bbb.ccc.ddd:5060
             tcp: 127.0.0.1:5060
             tcp: aaa.bbb.ccc.ddd:5060
Aliases: 
             tcp: SystemY:5060
             tcp: SystemY.my_domain.net:5060
             tcp: localhost:5060
             tcp: localhost.localdomain:5060
             udp: SystemY:5060
             udp: SystemY.my_domain.net:5060
             udp: localhost:5060
             udp: localhost.localdomain:5060

. ok 
root@SystemY:/etc/kamailio# /etc/init.d/kamailio status
[ ok ] Status of Kamailio SIP Server: :[....] kamailio is running.

So, it appears to have started :) It's only listening on IPv4 so far, but we'll come to IPv6 later (I hope - I assume it can do IPv6 these days?)

netstat also confirms I now have a listener on TCP and UDP ports 5060.

Let's trying configuring a phone to register to it and see what shows up in the log file:

Hm, 848 lines (529 DEBUG, 319 ERROR) in the first minute - the phone tried to register 11 times, unsuccessfully. I wonder what I missed…

Edit: After finding out that a 32-character password gets silently (GRRRRR…) truncated to 25 characters, I changed the password on the telephone, and in kamctl, to something shorter, but the problem still remains - the phone cannot register.

So, we've now run out of "Getting Started" documentation from the wiki, and although I've clearly managed to get Kamailio running, it's not exactly useful if it won't even accept a Register from a SIP phone. Let's try looking for some more documentation…

https://telnyx.com/sip-trunk-registration-kamailio/ suggests adding #!define WITH_USRLOCDB to the configuration file, however doing that (and then restarting Kamailio) still doesn't enable the phone to register.

Oh, the magic turns out to be #!define WITH_NAT, which has to go into /etc/kamailio/kamailio.cfg

(How many people don't have their phones behind a NAT connection…? Surely this should be the default assumption for a "Getting Started" guide… Come to that, why not just support NAT by default - what's going to go wrong if a non-NATted client then comes along and registers?)

So, I finally got Kamailio installed and configured to the point where a phone could register to it.

BTW: #!define WITH_USRLOCDB wasn't necessary - removing it still allows the phone to register, so until I found out a good reason to include this, it's staying out.

Next, let's see if I can get Kamailio to register to another SIP provider…

Oh, no, before we do that, let's find out if simply adjusting the length of the password field in the MySQL table definition allows us to use a more than 25-character-long password…

root@SystemY:/etc/kamailio# mysql -p kamailio
Enter password: 
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 463
Server version: 5.5.54-0+deb7u2-log (Debian)

mysql> alter table subscriber change password password varchar(64);
Query OK, 1 row affected (0.04 sec)
Records: 1  Duplicates: 0  Warnings: 0

mysql> update subscriber set password='834622a413e3c42c2dd8080c226bee85';
Query OK, 1 row affected (0.01 sec)
Rows matched: 1  Changed: 1  Warnings: 0

mysql> exit
Bye
root@SystemY:/etc/kamailio# /etc/init.d/kamailio restart

Reconfigure and restart phone

YES, it works :)

So, a simple change to the MySQL field definitions is all that's needed to allow >25 character SIP passwords.

So, on with getting Kamailio to register to another SIP provider…

Go up

Return to main index.