kamailio:usage:k32-lua-routing

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

kamailio:usage:k32-lua-routing [2011/01/28 00:53] (current)
Line 1: Line 1:
 +====== SIP Routing Done In Lua with Kamailio ======
  
 +Starting with version 3.1.0, [[http://​www.kamailio.org|Kamailio SIP Server]] introduced support to run embedded Lua scripts.
 +
 +The development version (to become next major release, 3.2.0, sometime during 2011), exported more functions to be executed natively in Lua.
 +
 +This document shows how to install Kamailio development version from Git and do all SIP routing in Lua, for a quite complex configuration,​ running user authentication,​ accounting and location services.
 +
 +===== Install Kamailio Devel =====
 +
 +These guidelines are for Debian/​Ubuntu based distributions.
 +
 +==== Prerequisites ====
 +
 +To be able to follow the guidelines from this document you need **root** access.
 +
 +The following packages are required before proceeding to the next steps.
 +
 +  * __git__ client: apt-get install git-core - it is recommended to have the latest version, which might not be part of the distribution yet, but you can get it from: http://​git-scm.com/​
 +  * __gcc__ compiler: apt-get install gcc
 +  * __flex__ - apt-get install flex
 +  * __bison__ - apt-get install bison
 +  * __libmysqlclient15-dev__ - apt-get install libmysqlclient15-dev
 +  * __make__ - apt-get install make
 +  * __liblua5.1-dev__ - apt-get install liblua5.1-dev
 +
 +==== Getting sources from GIT ====
 +
 +First of all, you have to create a directory on the file system where the sources will be stored. ​
 +
 +<​code>​
 +  mkdir -p /​usr/​local/​src/​kamailio-dev
 +  cd /​usr/​local/​src/​kamailio-dev
 +</​code>​
 +
 +Download the sources from GIT using the following commands.
 +
 +<​code>​
 +  git clone --depth 1 git://​git.sip-router.org/​sip-router kamailio
 +  cd kamailio
 +</​code>​
 +
 +==== Compile and Install ====
 +
 +
 +We want to install MySQL and Lua extensions:
 +
 +<​code>​
 +make FLAVOUR=kamailio ​ include_modules="​db_mysql app_lua"​ cfg
 +make all
 +make install
 +</​code>​
 +
 +==== Create Database ====
 +
 +
 +To create the MySQL database, you have to use the database setup script:
 +
 +<​code>​
 +  /​usr/​local/​sbin/​kamdbctl create
 +</​code>​
 +
 +In order to create the database you need to specify the wanted db type (DBENGINE=MYSQL) in the 
 +
 +<​code>​
 +  /​usr/​local/​etc/​kamailio/​kamctlrc
 +</​code>​
 +
 +file. Call this script without any parameter to get some help for the usage. You will be asked for the domain name Kamailio (OpenSER) is going to serve (e.g., mysipserver.com) and the password of the '​root'​ MySQL user. The script will create a database named '​openser'​ containing the tables required by Kamailio (OpenSER). You can change the default settings in the kamctlrc file mentioned above.
 +
 +The script will add two users in MySQL:
 +
 +- **openser** - having the password '​openserrw',​ user which has full access rights to '​openser'​ database
 +
 +- **openserro** - having the password '​openserro',​ user which has read-only access rights to '​openser'​ database
 +
 +**__Do change the passwords for these two users immediately after the database is created.__**
 +
 +==== Create SIP Accounts ====
 +
 +A new account can be added using '​kamctl'​ tool via '​kamctl add <​username>​ <​password>'​.
 +
 +<​code>​
 +  kamctl add test testpasswd
 +</​code>​
 +
 +If you are asked for SIP_DOMAIN environment variable do one of the following option.
 +
 +<​code>​
 +  1.
 +  export SIP_DOMAIN=mysipserver.com
 +
 +  2.
 +  edit '/​usr/​local/​etc/​kamailio/​kamctlrc'​ and add:
 +  SIP_DOMAIN=mysipserver.com
 +</​code>​
 +
 +===== Kamailio Config =====
 +
 +This is the configuration file for Kamailio SIP server, it is needed to load the Kamailio modules and set their parameters. Then, the routing blocks just call Lua functions from **kamailio.lua** file.
 +
 +<code c>
 +#!KAMAILIO
 +#
 +# Kamailio (OpenSER) SIP Server v3.1 - default configuration script
 +#     - web: http://​www.kamailio.org
 +#     - git: http://​sip-router.org
 +#
 +# Direct your questions about this file to: <​sr-users@lists.sip-router.org>​
 +#
 +# Refer to the Core CookBook at http://​www.kamailio.org/​dokuwiki/​doku.php
 +# for an explanation of possible statements, functions and parameters.
 +#
 +# Several features can be enabled using '#​!define WITH_FEATURE'​ directives:
 +#
 +# *** To run in debug mode: 
 +#     - define WITH_DEBUG
 +#
 +# *** To enable mysql: ​
 +#!define WITH_MYSQL
 +#
 +# *** To enable authentication execute:
 +#     - enable mysql
 +#!define WITH_AUTH
 +#     - add users using '​kamctl'​
 +#
 +# *** To enable IP authentication execute:
 +#     - enable mysql
 +#     - enable authentication
 +#     - define WITH_IPAUTH
 +#     - add IP addresses with group id '​1'​ to '​address'​ table
 +#
 +# *** To enable persistent user location execute:
 +#     - enable mysql
 +#!define WITH_USRLOCDB
 +#
 +# *** To enable multi-domain support execute:
 +#     - enable mysql
 +#     - define WITH_MULTIDOMAIN
 +#
 +
 +#!define WITH_LUA
 +
 +####### Defined Values #########
 +
 +# *** Value defines - IDs used later in config
 +#!ifdef WITH_MYSQL
 +# - database URL - used to connect to database server by modules such
 +#       as: auth_db, acc, usrloc, a.s.o.
 +#!define DBURL "​mysql://​openser:​openserrw@localhost/​openser"​
 +#!endif
 +#!ifdef WITH_MULTIDOMAIN
 +# - the value for '​use_domain'​ parameters
 +#!define MULTIDOMAIN 1
 +#!else
 +#!define MULTIDOMAIN 0
 +#!endif
 +
 +# - flags
 +#   FLT_ - per transaction (message) flags
 +# FLB_ - per branch flags
 +#!define FLT_ACC 1
 +#!define FLT_ACCMISSED 2
 +#!define FLT_ACCFAILED 3
 +#!define FLT_NATS 5
 +
 +#!define FLB_NATB 6
 +#!define FLB_NATSIPPING 7
 +
 +####### Global Parameters #########
 +
 +#!ifdef WITH_DEBUG
 +debug=4
 +log_stderror=yes
 +#!else
 +debug=2
 +log_stderror=no
 +#!endif
 +
 +memdbg=5
 +memlog=5
 +
 +log_facility=LOG_LOCAL0
 +
 +fork=yes
 +children=4
 +
 +
 +/* port to listen to
 + * - can be specified more than once if needed to listen on many ports */
 +port=5060
 +
 +####### Modules Section ########
 +
 +# set paths to location of modules
 +#!ifdef LOCAL_TEST_RUN
 +mpath="​modules_k:​modules"​
 +#!else
 +mpath="/​usr/​local/​lib/​kamailio/​modules_k/:/​usr/​local/​lib/​kamailio/​modules/"​
 +#!endif
 +
 +#!ifdef WITH_MYSQL
 +loadmodule "​db_mysql.so"​
 +#!endif
 +
 +loadmodule "​mi_fifo.so"​
 +loadmodule "​kex.so"​
 +loadmodule "​tm.so"​
 +loadmodule "​tmx.so"​
 +loadmodule "​sl.so"​
 +loadmodule "​rr.so"​
 +loadmodule "​pv.so"​
 +loadmodule "​maxfwd.so"​
 +loadmodule "​usrloc.so"​
 +loadmodule "​registrar.so"​
 +loadmodule "​textops.so"​
 +loadmodule "​siputils.so"​
 +loadmodule "​xlog.so"​
 +loadmodule "​sanity.so"​
 +loadmodule "​ctl.so"​
 +loadmodule "​mi_rpc.so"​
 +loadmodule "​acc.so"​
 +
 +#!ifdef WITH_AUTH
 +loadmodule "​auth.so"​
 +loadmodule "​auth_db.so"​
 +#!endif
 +
 +#!ifdef WITH_LUA
 +loadmodule "​app_lua.so"​
 +#!endif
 +
 +# ----------------- setting module-specific parameters ---------------
 +
 +
 +# ----- mi_fifo params -----
 +modparam("​mi_fifo",​ "​fifo_name",​ "/​tmp/​kamailio_fifo"​)
 +
 +
 +# ----- tm params -----
 +# auto-discard branches from previous serial forking leg
 +modparam("​tm",​ "​failure_reply_mode",​ 3)
 +# default retransmission timeout: 30sec
 +modparam("​tm",​ "​fr_timer",​ 30000)
 +# default invite retransmission timeout after 1xx: 120sec
 +modparam("​tm",​ "​fr_inv_timer",​ 120000)
 +
 +
 +# ----- rr params -----
 +# add value to ;lr param to cope with most of the UAs
 +modparam("​rr",​ "​enable_full_lr",​ 1)
 +# do not append from tag to the RR (no need for this script)
 +modparam("​rr",​ "​append_fromtag",​ 0)
 +
 +
 +# ----- registrar params -----
 +modparam("​registrar",​ "​method_filtering",​ 1)
 +/* uncomment the next line to disable parallel forking via location */
 +# modparam("​registrar",​ "​append_branches",​ 0)
 +/* uncomment the next line not to allow more than 10 contacts per AOR */
 +#​modparam("​registrar",​ "​max_contacts",​ 10)
 +
 +
 +# ----- acc params -----
 +/* what special events should be accounted ? */
 +modparam("​acc",​ "​early_media",​ 0)
 +modparam("​acc",​ "​report_ack",​ 0)
 +modparam("​acc",​ "​report_cancels",​ 0)
 +/* by default ww do not adjust the direct of the sequential requests.
 +   if you enable this parameter, be sure the enable "​append_fromtag"​
 +   in "​rr"​ module */
 +modparam("​acc",​ "​detect_direction",​ 0)
 +/* account triggers (flags) */
 +modparam("​acc",​ "​log_flag",​ FLT_ACC)
 +modparam("​acc",​ "​log_missed_flag",​ FLT_ACCMISSED)
 +modparam("​acc",​ "​log_extra", ​
 + "​src_user=$fU;​src_domain=$fd;​dst_ouser=$tU;​dst_user=$rU;​dst_domain=$rd"​)
 +modparam("​acc",​ "​failed_transaction_flag",​ FLT_ACCFAILED)
 +
 +
 +# ----- usrloc params -----
 +/* enable DB persistency for location entries */
 +#!ifdef WITH_USRLOCDB
 +modparam("​usrloc",​ "​db_url",​ DBURL)
 +modparam("​usrloc",​ "​db_mode",​ 2)
 +modparam("​usrloc",​ "​use_domain",​ MULTIDOMAIN)
 +#!endif
 +
 +
 +# ----- auth_db params -----
 +#!ifdef WITH_AUTH
 +modparam("​auth_db",​ "​db_url",​ DBURL)
 +modparam("​auth_db",​ "​calculate_ha1",​ yes)
 +modparam("​auth_db",​ "​password_column",​ "​password"​)
 +modparam("​auth_db",​ "​load_credentials",​ ""​)
 +modparam("​auth_db",​ "​use_domain",​ MULTIDOMAIN)
 +#!endif
 +
 +
 +# ----- alias_db params -----
 +#!ifdef WITH_ALIASDB
 +modparam("​alias_db",​ "​db_url",​ DBURL)
 +modparam("​alias_db",​ "​use_domain",​ MULTIDOMAIN)
 +#!endif
 +
 +
 +#!ifdef WITH_LUA
 +# ----- app_lua params -----
 +modparam("​app_lua",​ "​load",​ "/​usr/​local/​etc/​kamailio/​kamailio.lua"​)
 +modparam("​app_lua",​ "​register",​ "​sl"​)
 +modparam("​app_lua",​ "​register",​ "​rr"​)
 +modparam("​app_lua",​ "​register",​ "​tm"​)
 +modparam("​app_lua",​ "​register",​ "​maxfwd"​)
 +modparam("​app_lua",​ "​register",​ "​registrar"​)
 +modparam("​app_lua",​ "​register",​ "​auth"​)
 +modparam("​app_lua",​ "​register",​ "​auth_db"​)
 +
 +modparam("​usrloc",​ "​preload",​ "​location"​)
 +#!endif
 +
 +
 +####### Routing Logic ########
 +
 +
 +# Main SIP request routing logic
 +# - processing of any incoming SIP request starts with this route
 +route {
 + if(!lua_runstring("​route_request([[MAIN]])"​))
 + {
 + xdbg("​SCRIPT:​ failed to execute lua script!\n"​);​
 + }
 + exit;
 +}
 +
 +branch_route[TEST] {
 + if(!lua_runstring("​route_branch([[TEST]])"​))
 + {
 + xdbg("​SCRIPT:​ failed to execute branch lua script!\n"​);​
 + }
 +}
 +
 +onreply_route[TEST] {
 + if(!lua_runstring("​route_reply([[TEST]])"​))
 + {
 + xdbg("​SCRIPT:​ failed to execute reply lua script!\n"​);​
 + }
 +}
 +
 +failure_route[TEST] {
 + if(!lua_runstring("​route_failure([[TEST]])"​))
 + {
 + xdbg("​SCRIPT:​ failed to execute failure lua script!\n"​);​
 + }
 +}
 +</​code>​
 +
 +Remarks:
 +  * each routing block only executes a specific Lua function, everything else is done inside Lua, like: authentication,​ registration,​ user location, a.s.o.
 +  * Lua submodules exported by **app_lua** are specified by module parameter **register**
 +  * **kamailio.lua** is loaded only once, at Kamailio startup
 +  * only specific functions defined in **kamailio.lua** are executed from **kamailio.cfg**. You can change to execute entire Lua scripts (even loaded every time at runtime) - check the readme of **app_lua** module for available options.
 +
 +===== Lua Script =====
 +
 +This is the Lua file you have to save in **/​usr/​local/​etc/​kamailio/​kamailio.lua**.
 +
 +<code lua>
 +-- SIP request routing
 +function route_request(name)
 + -- some initial debug messages
 + sr.dbg("​routing SIP request from Lua [" .. name .. "​]\n"​)
 + ruri = sr.pv.get("​$ru"​)
 + rdomain = sr.pv.get("​$rd"​)
 + furi = sr.pv.get("​$fu"​)
 + fdomain = sr.pv.get("​$fd"​)
 + tdomain = sr.pv.get("​$td"​)
 + method = sr.pv.get("​$rm"​)
 + srcip = sr.pv.get("​$si"​)
 + sr.dbg("​--- [" .. srcip .. "] (" .. method .. ") " .. furi .. " => " .. ruri .. "​\n"​)
 +
 + -- initial checks of SIP request
 + if sr.maxfwd.process_maxfwd(10) < 0 then
 + sr.sl.send_reply(483,"​Too Many Hops")
 + return
 + end
 +
 + -- route within dialog SIP requests
 + if not sr.pv.is_null("​$tt"​) then
 + if sr.rr.loose_route()>​0 then
 + if method=="​BYE"​ then
 + sr.setflag(1)
 + sr.setflag(3)
 + end
 + sr.tm.t_relay()
 + return
 + else
 + if method=="​ACK"​ then
 + if sr.tm.t_check_trans()>​0 then
 + sr.tm.t_relay()
 + return
 + else
 + return
 + end
 + end
 + sr.sl.send_reply(404,​ "Not here")
 + end
 + return
 + end
 +
 + -- only initial requests (no To tag)
 +
 + -- CANCEL processing
 + if method =="​CANCEL"​ then
 + if sr.tm.t_check_trans() > 0 then
 + sr.tm.t_relay()
 + end
 + return;
 + end
 +
 + if sr.tm.t_check_trans() == 0 then return end
 +
 + -- authentication
 + if method == "​REGISTER"​ then
 + -- authenticate the REGISTER requests
 + if sr.auth_db.www_authenticate(tdomain,​ "​subscriber"​) < 0 then
 + sr.auth.www_challenge(tdomain,​ 1);
 + return;
 + end
 +
 + if sr.pv.get("​$au"​) ~= sr.pv.get("​$tU"​) then
 + sr.sl.send_reply(403,​ "​Forbidden auth ID");
 + return;
 + end
 + else
 + -- authenticate if from local subscriber
 + if sr.is_myself( fdomain ) == true then
 + if sr.auth_db.proxy_authenticate(fdomain,​ "​subscriber"​) < 0 then
 + sr.auth.proxy_challenge(fdomain,​ 1)
 + return
 + end
 + if sr.pv.get("​$au"​) ~= sr.pv.get("​$fU"​) then
 + sr.sl.send_reply(403,​ "​Forbidden auth ID")
 + return
 + end
 + sr.auth.consume_credentials();​
 + -- caller authenticated
 + else
 + -- caller is not local subscriber, if callee is not as well,
 + -- do not become an open relay
 + if sr.is_myself(rdomain)==false then
 + sr.sl.send_reply(403,​ "Not relaying"​)
 + return
 + end
 + end
 + end
 +
 + -- record routing
 + sr.hdr.remove("​Route"​);​
 + if method == "​INVITE"​ or  method == "​SUBSCRIBE"​ then
 + sr.rr.record_route()
 + end
 + if method=="​INVITE"​ then
 + sr.setflag(1)
 + end
 +
 + -- non local destinations
 + if sr.is_myself(rdomain)==false then
 + sr.tm.t_relay()
 + return
 + end
 +
 + -- SIP registrar server
 + if method == "​REGISTER"​ then
 + if sr.registrar.save("​location"​) < 0 then
 + sr.sl.send_reply(500,​ "​Server error"​)
 + end
 + return
 + end
 +
 + if sr.pv.is_null("​$rU"​) then
 + -- request with no Username in RURI
 + sr.sl.send_reply(484,​ "​Address Incomplete"​)
 + return
 + end
 + -- SIP location server
 + if sr.registrar.lookup("​location"​) < 0 then
 + -- destination user offline
 + sr.sl.send_reply(404,​ "Not found"​)
 + return
 + end
 + if method=="​INVITE"​ then
 + sr.setflag(2)
 + end
 +
 + -- relay the request
 + sr.tm.t_on_branch("​TEST"​);​
 + sr.tm.t_on_reply("​TEST"​);​
 + sr.tm.t_on_failure("​TEST"​);​
 + if sr.tm.t_relay() < 0 then
 + sr.sl.send_reply(500,​ "​Server error"​)
 + end
 +end
 +
 +-- SIP branch routing
 +function route_branch(name)
 + sr.dbg("​routing SIP branch from Lua [" .. name .. "​]\n"​)
 +end
 +
 +-- SIP reply routing
 +function route_reply(name)
 + sr.dbg("​routing SIP reply from Lua [" .. name .. "​]\n"​)
 +end
 +
 +-- SIP failure routing
 +function route_failure(name)
 + sr.dbg("​routing SIP failure from Lua [" .. name .. "​]\n"​)
 +end
 +</​code>​
 +
 +Remarks:
 +  * the Lua file is quite small, it has about 150 lines, including empty lines and comments.
 +  * there are specific Lua functions for each of Kamailio'​s config routing blocks. The parameter **name** is just for debugging purposes in this particular case.
 +  * the functions for branch, reply and failure routing are just demo samples, to show how they can be used
 +  * here is nothing particular used from Lua that cannot be done with Kamailio configuration file language only, but it is a starting point that you can use when you need to benefit of Lua specific extensions
 +
 +===== References =====
 +
 +You can see Kamailio Lua API at:
 +  * http://​sip-router.org/​wiki/​api/​lua/​devel
 +
 +APP_LUA module documentation is available at:
 +  * http://​kamailio.org/​docs/​modules/​devel/​modules/​app_lua.html
 +
 +Lua Project web site:
 +  * http://​www.lua.org
 +
 +{{tag> kamailio}}


Copyright 2010-2020 Asipto.com