The article describes how to add simple database support for the Kamailio 3.1.0 server. As the database ext files are used. Activities described here are following the basic Kamailio server installation, described in the article Installing Kamailio 3.1 on debian lenny.
We are trying this as the part of our performance tests.
Preparation of the Kamailio text files
Well, after some testing, there are at least two ways how to create required text files, do it manually or use kamdbctl. I've had worried with the manual way a quite long time, cause there is no information about that, steps are descirbed next. But using the kamdbctl look very comfortable. So if you are looking for simple solution, just jump over the next chapter to kamdbctl part.
1. Manual steps required to create dbtext files
We have to prepare set of text files which will be used as a simple database. I will place a new dbtext dir inside of the default kamailio dir which will host the text files
cd /etc/kamailio mkdir dbtext
Now we have to create text file named version :
cd dbtext vim version
and write there following lines, so the content of the version file look:
table_name(str) table_version(int) subscriber:6 location:6 aliases:6
number should be, at least for subscriber line, equal to six, because than error message about bad subscriber version table is returned.
Now we create the text file named subscriber, which will host user definitions with passwords
vim subscriber
and write user accounts, in my case for users jan and palo:
username(str) password(str) ha1(str) domain(str) ha1b(str) rpid(str) jan:pass1:xxx:jan.sk:xxx:ZZZZ palo:pass2:xxx:palo.sk:xxx:ZZZZ
Testing and problems
1) Configuration is ok, auth db is configured, but no version file exist
May 13 14:09:01 pstest /usr/sbin/kamailio[29068]: ERROR: db_text [dbt_lib.c:307]: could not load database from file [version] May 13 14:09:01 pstest /usr/sbin/kamailio[29068]: ERROR: db_text [dbt_base.c:203]: table version does not exist! May 13 14:09:01 pstest /usr/sbin/kamailio[29068]: ERROR: <core> [db.c:366]: error in db_query May 13 14:09:01 pstest /usr/sbin/kamailio[29068]: ERROR: <core> [db.c:405]: querying version for table subscriber May 13 14:09:01 pstest /usr/sbin/kamailio[29068]: ERROR: auth_db [authdb_mod.c:252]: error during table version check. May 13 14:09:01 pstest /usr/sbin/kamailio[29068]: ERROR: <core> [route.c:1161]: fixing failed (code=-1) at cfg:/etc/kamailio/kamailio.cfg:436 May 13 14:09:01 pstest /usr/sbin/kamailio[29068]: ERROR: <core> [route.c:1161]: fixing failed (code=-1) at cfg:/etc/kamailio/kamailio.cfg:443 May 13 14:09:01 pstest /usr/sbin/kamailio[29068]: ERROR: <core> [route.c:1161]: fixing failed (code=-1) at cfg:/etc/kamailio/kamailio.cfg:489
2) Configuration is ok, auth db is configured, but bad subscriber table version is defined inside of the version file
May 13 14:16:58 pstest /usr/sbin/kamailio[29111]: ERROR: <core> [db.c:408]: invalid version 3 for table subscriber found, expected 6 (check table structure and table "version") May 13 14:16:58 pstest /usr/sbin/kamailio[29111]: ERROR: auth_db [authdb_mod.c:252]: error during table version check. May 13 14:16:58 pstest /usr/sbin/kamailio[29111]: ERROR: <core> [route.c:1161]: fixing failed (code=-1) at cfg:/etc/kamailio/kamailio.cfg:436 May 13 14:16:58 pstest /usr/sbin/kamailio[29111]: ERROR: <core> [route.c:1161]: fixing failed (code=-1) at cfg:/etc/kamailio/kamailio.cfg:443 May 13 14:16:58 pstest /usr/sbin/kamailio[29111]: ERROR: <core> [route.c:1161]: fixing failed (code=-1) at cfg:/etc/kamailio/kamailio.cfg:489
setup subcriber version to six
3) no subscriber file for an user, solution create a subscriber file with correct user
May 13 14:18:29 pstest /usr/sbin/kamailio[29158]: ERROR: db_text [dbt_lib.c:307]: could not load database from file [subscriber] May 13 14:18:29 pstest /usr/sbin/kamailio[29158]: ERROR: db_text [dbt_base.c:203]: table subscriber does not exist! May 13 14:18:29 pstest /usr/sbin/kamailio[29158]: ERROR: auth_db [authorize.c:99]: failed to query database
2. Using kamdbctl to generate required DBTEXT files
We have to specify parameters using of which required dbtext files will be created. Therefore we need to edit the /etc/kamailio/kamctlrc file.
I will add or uncomment following lines. I would like to use dbtext files for some simple testing, so I will do not put all lines which should enable some advanced features. Final version of kamctlrc should look like:
# your sip domain
SIP_DOMAIN=ps.sip.uniza.sk
# specify to use DBTEXT as a DB
DBENGINE=DBTEXT
# where file will be stored/generated
DB_PATH="/etc/kamailio/dbtext"
USERCOL="username"
# this we may uncomment
#INSTALL_EXTRA_TABLES=ask
# If to install presence related tables.
#INSTALL_PRESENCE_TABLES=ask
# Kamailio standard modules
STANDARD_MODULES="standard acc lcr domain group permissions registrar usrloc msilo
alias_db uri_db speeddial avpops auth_db pdt dialog dispatcher
dialplan"
# Kamailio extra modules
#EXTRA_MODULES="imc cpl siptrace domainpolicy carrierroute userblacklist htable purple"
## type of aliases used: DB - database aliases; UL - usrloc aliases
## - default: none
ALIASES_TYPE="DB"
## control engine: FIFO or UNIXSOCK
## - default FIFO
CTLENGINE="FIFO"
## path to FIFO file
#OSER_FIFO="FIFO"
OSER_FIFO='/tmp/kamailio_fifo'
## verbose - debug purposes - default '0'
VERBOSE=1
## do (1) or don't (0) store plaintext passwords
## in the subscriber table - default '1'
STORE_PLAINTEXT_PW=0
## OPENSER START Options
## PID file path - default is: /var/run/kamailio.pid
PID_FILE=/var/run/kamailio.pid
and now run kamdbctl create, which generate required files
pstest:/etc/kamailio# kamdbctl create
database engine 'dbtext' loaded
INFO: creating DBTEXT tables at: /etc/kamailio/dbtext ...
Creating core table: version
Creating core table: acc
Creating core table: dbaliases
Creating core table: domain
Creating core table: grp
Creating core table: uri
Creating core table: speed_dial
Creating core table: lcr_gw
Creating core table: lcr_rule
Creating core table: lcr_rule_target
Creating core table: pdt
Creating core table: subscriber
Creating core table: location
Creating core table: re_grp
Creating core table: trusted
Creating core table: address
Creating core table: missed_calls
Creating core table: usr_preferences
Creating core table: aliases
Creating core table: silo
Creating core table: dialog
Creating core table: dispatcher
Creating core table: dialplan
Install presence related tables? (y/n): n
Install tables for imc cpl siptrace domainpolicy carrierroute userblacklist htable purple? (y/n): n
Inside of the /etc/kamailio/dbtext folder there are following files
cd dbtext/ pstest:/etc/kamailio/dbtext# ls -al total 100 drwxr-xr-x 2 root root 4096 2011-05-16 09:42 . drwxr-xr-x 3 root root 4096 2011-05-16 09:42 .. -rw-r--r-- 1 root root 122 2011-05-16 09:42 acc -rw-r--r-- 1 root root 76 2011-05-16 09:42 address -rw-r--r-- 1 root root 254 2011-05-16 09:42 aliases -rw-r--r-- 1 root root 90 2011-05-16 09:42 dbaliases -rw-r--r-- 1 root root 415 2011-05-16 09:42 dialog -rw-r--r-- 1 root root 128 2011-05-16 09:42 dialplan -rw-r--r-- 1 root root 104 2011-05-16 09:42 dispatcher -rw-r--r-- 1 root root 48 2011-05-16 09:42 domain -rw-r--r-- 1 root root 77 2011-05-16 09:42 grp -rw-r--r-- 1 root root 237 2011-05-16 09:42 lcr_gw -rw-r--r-- 1 root root 105 2011-05-16 09:42 lcr_rule -rw-r--r-- 1 root root 94 2011-05-16 09:42 lcr_rule_target -rw-r--r-- 1 root root 254 2011-05-16 09:42 location -rw-r--r-- 1 root root 122 2011-05-16 09:42 missed_calls -rw-r--r-- 1 root root 60 2011-05-16 09:42 pdt -rw-r--r-- 1 root root 44 2011-05-16 09:42 re_grp -rw-r--r-- 1 root root 149 2011-05-16 09:42 silo -rw-r--r-- 1 root root 148 2011-05-16 09:42 speed_dial -rw-r--r-- 1 root root 128 2011-05-16 09:42 subscriber -rw-r--r-- 1 root root 86 2011-05-16 09:42 trusted -rw-r--r-- 1 root root 82 2011-05-16 09:42 uri -rw-r--r-- 1 root root 120 2011-05-16 09:42 usr_preferences -rw-r--r-- 1 root root 942 2011-05-16 09:42 versio
Do not forget restart your kamailio server.
Problem:
After restart of the kamailio, its process is not running, and there are some error messages:
ERROR: db_text [dbt_lib.c:307]: could not load database from file [version] ERROR: db_text [dbt_base.c:203]: table version does not exist! ERROR: <core> [db.c:366]: error in db_query ERROR: <core> [db.c:405]: querying version for table subscriber ERROR: auth_db [authdb_mod.c:252]: error during table version check. ERROR: <core> [route.c:1161]: fixing failed (code=-1) at cfg:/etc/kamailio/kamailio.cfg:436 ERROR: <core> [route.c:1161]: fixing failed (code=-1) at cfg:/etc/kamailio/kamailio.cfg:443 ERROR: <core> [route.c:1161]: fixing failed (code=-1) at cfg:/etc/kamailio/kamailio.cfg:489
So, open version file (/etc/kamailio/dbtext), and there are lines, which does not comform with the rest of file (yellow)
table_name(string) table_version(int) acc:4 active_watchers:9 address:4 aliases:1004 carrierfailureroute:2 carrier_name:1 carrierroute:3 cpl:1 dbaliases:1 dialog:5 dialplan:1 dispatcher:4 domain:1 domain_name:1 domainpolicy:2 dr_gateways:3 dr_groups:2 dr_gw_lists:1 dr_rules:3 globalblacklist:1 grp:2 id(int,auto) lcr_id(int) gw_name(string) grp_id(int) ip_addr(string) hostname(string,null) port(int,null) uri_scheme(int,null) transport(int,null) strip(int,null) tag(string,null) weight(int,null) flags(int) defunct(int,null) htable:1 imc_members:1 imc_rooms:1 id(int,auto) lcr_id(int) prefix(string,null) from_uri(string,null) grp_id(int) priority(int) lcr_gw:1 lcr_rule:1 lcr_rule_target:1 location:1004 matrix:1 missed_calls:3 mtree:1 pdt:1 presentity:3 pua:6 purplemap:1 re_grp:1 rls_presentity:0 rls_watchers:1 silo:5 sip_trace:2 speed_dial:2 subscriber:6 trusted:5 uacreg:1
so delete them manually and restart kamailio server, errors should disappear.
Adding a new user
Now we should be able to use kamctl command to create, delete and modify users of our system as we usually do when Mysql is used. So I will create a user with name palo and its password with:
kamctl add palo passwd
Problem
After running kamctl tool, there a new problem appear:
kamctl add palo passwd
database engine 'DBTEXT' loaded
Control engine 'FIFO' loaded
is_user: user counter=/usr/share/kamailio/dbtext/openser is not a directory INFO: user 'palo' already exists
tool is pointing to some old, openser folder (/usr/share/kamailio/dbtext/openser) which is probably successor from openser and which, of course does exists in kamailio, and there is INFO telling us that the user already exist, which is not true.
So make a symlink of your current folder with text files pointing to missing, but requested folder, in my case:
ln -s /etc/kamailio/dbtext/ /usr/share/kamailio/dbtext/openser
Now the lines seems ok, but new problems arise, probably therefore that module from openser to kamilio was not updated. If I will add a new user with
pstest:/etc/kamailio/dbtext# kamctl add jano jano
a problem is reported that email is missing (openserctl required it before)
database engine 'DBTEXT' loaded
Control engine 'FIFO' loaded
is_user: user counter=0
check_db_alias: alias counter=0
email_address cannot be empty or null
ERROR: introducing the new user 'jano' to the database failed
and if I will add email address, kamctl does not understand, because this field the kamctl does not use anymore
pstest:/etc/kamailio/dbtext# kamctl add jano jano jano@jano database engine 'DBTEXT' loaded Control engine 'FIFO' loaded -- command 'add|passwd|rm' - manage subscribers add <username> <password> .......... add a new subscriber (*) passwd <username> <passwd> ......... change user's password (*) rm <username> ...................... delete a user (*)
Solution
To solve this problem the code have to be updated probably, but I'm not expect it very soon 🙂 And we can not use kamctl utility of course. Anyway, we helped ourself with DBTEXT file sctructure.
We may solve it easily by adding the subscriber data manually. Open subscriber file
vim /etc/kamailio/dbtext/subscriber
and add line, one for each new user
1:jan:jan.sk:password:jan.sk:xxx:xxx:ZZZZ
Configuration of the Kamailio to use of DB text files
Loading required module
Main module which allows to work with text file dataase is the DB_TEXT module, whose documentation is here. So as the first thing we have to load the module. I will help myself with directives
First I will define
#!define WITH_DBTEXT
Then we define DBURL parameter which is defining path where the DBTEXT text files are located
#!ifdef WITH_DBTEXT # - database URL - used to connect to database server by modules such # as: auth_db, acc, usrloc, a.s.o. #!define DBURL "text:///etc/kamailio/dbtext" #!endif
and I will load main db_text. so module if WITH_DBTEXT is defined
#!ifdef WITH_DBTEXT loadmodule "db_text.so" #!endif
Modyfing base Kamailio Configuration
Modyfying AUTH DB
Now we configure Kamailio to use text files for authentication, so define (put in or uncomment if it exist)
#!define WITH_AUTH
and then the folloing configuration is
#!ifdef WITH_AUTH
modparam("auth_db", "db_url", DBURL)
modparam("auth_db", "calculate_ha1", yes)
modparam("auth_db", "password_column", "password")
modparam("auth_db", "user_column", "username")
modparam("auth_db", "domain_column", "domain")
modparam("auth_db", "load_credentials", "")
modparam("auth_db", "use_domain", MULTIDOMAIN)
#!endif
We do not have to modify main route logic, as we have defined directive WITH_AUTH and inside of the Kamailio 3.1 is preconfigured config file, which will do the rest, so an user will be asked for authentication during registration and generating Invites.
Testing
Use your favorite client and try to register with good and bad password. It should work! I was sucesfull
kamctl ul show
database engine 'DBTEXT' loaded
Control engine 'FIFO' loaded
entering fifo_cmd ul_dump
Domain:: location table=512 records=1 max_slot=1
AOR:: jan
Contact:: sip:jan@158.193.139.235:62250;rinstance=ce646a6fb1eb935a Q=
Expires:: 3184
Callid:: Yjg2NmM3NjI3M2NkMDllMTY1NjBmMzVjZjUwMjU0NWQ.
Cseq:: 2
User-agent:: Bria Professional release 2.4 stamp 49381
State:: CS_NEW
Flags:: 0
Cflag:: 0
Socket:: udp:158.193.139.51:5060
Methods:: 5087
FIFO command was:
:ul_dump:openser_receiver_1534
Modyfying USRLOC
Then we have to configure modules and its parameters. First we will enable usrloc used for user storage
So put or uncomment following line
#!define WITH_USRLOCDB
and we should find that, if this is defined then following parameters are used (same as we may do when MySql is used):
#!ifdef WITH_USRLOCDB
modparam("usrloc", "db_url", DBURL)
modparam("usrloc", "db_mode", 2)
#!endif