Post has been edited after publishing with updated content and Kamailio modules .
Since kamailio has a modular architecture with core components and modules to extend the functionality , this article will be discussing few of the essential modules in Kamailio.
Few categories of modules discoverable via apt-cache search kamailio
- kamailio – very fast and configurable SIP proxy
- kamailio-autheph-modules – authentication using ephemeral credentials module for Kamailio
- kamailio-berkeley-bin – Berkeley database module for Kamailio – helper program
- kamailio-berkeley-modules – Berkeley database module for Kamailio
- kamailio-carrierroute-modules – carrierroute module for Kamailio
- kamailio-cnxcc-modules – cnxcc modules for Kamailio
- kamailio-cpl-modules – CPL module (CPL interpreter engine) for Kamailio
- kamailio-dbg – very fast and configurable SIP proxy [debug symbols]
- kamailio-dnssec-modules – contains the dnssec module
- kamailio-erlang-modules – earlang modules for Kamailio
- kamailio-extra-modules – extra modules for Kamailio
- kamailio-geoip-modules – contains the geoip module
- kamailio-ims-modules – IMS module for Kamailio
- kamailio-java-modules – contains the app_java module
- kamailio-json-modules – Json parser and jsonrpc modules for Kamailio
- kamailio-kazoo-modules – kazoo modules for Kamailio
- kamailio-ldap-modules – LDAP modules for Kamailio
- kamailio-lua-modules – contains the app_lua module
- kamailio-memcached-modules – interface to memcached server
- kamailio-mono-modules – contains the app_mono module
- kamailio-mysql-modules – MySQL database connectivity module for Kamailio
- kamailio-outbound-modules – Outbound module for Kamailio
- kamailio-perl-modules – Perl extensions and database driver for Kamailio
- kamailio-postgres-modules – PostgreSQL database connectivity module for Kamailio
- kamailio-presence-modules – SIMPLE presence modules for Kamailio
- kamailio-purple-modules – Provides the purple module, a multi-protocol IM gateway
- kamailio-python-modules – contains the app_python module
- kamailio-radius-modules – RADIUS modules for Kamailio
- kamailio-redis-modules – Redis database connectivity module for Kamailio
- kamailio-sctp-modules – sctp module for Kamailio
- kamailio-snmpstats-modules – SNMP AgentX subagent module for Kamailio
- kamailio-sqlite-modules – SQLite database connectivity module for Kamailio
- kamailio-tls-modules – contains the TLS kamailio transport module
- kamailio-unixodbc-modules – unixODBC database connectivity module for Kamailio
- kamailio-utils-modules – Provides a set utility functions for Kamailio
- kamailio-websocket-modules – Websocket module for kamailio
- kamailio-xml-modules – XML based extensions for Kamailio’s Management Interface
- kamailio-xmpp-modules – XMPP gateway module for Kamailio
The first set under explanation is Usrloc and Register module which take care of user persistance in Database and handling an incoming register request with authentication and validation.
Usrloc Module
keeps a user location table and provides access to the table for other modules
Parameters:
- nat_bflag
- user_column
- domain_column
- contact_column
- expires_column
- q_column
- callid_column
- cseq_column
- methods_column
- flags_column
- cflags_column
- user_agent_column
- received_column
- socket_column
- path_column
- ruid_column
- instance_column
- server_id_column
- connection_id_column
- keepalive_column
- partition_column
- use_domain
- desc_time_order
- timer_interval
- db_url
- db_mode
- db_load
- db_insert_update
- matching_mode
- cseq_delay
- fetch_rows
- hash_size
- preload
- db_update_as_insert
- db_check_update
- timer_procs
- xavp_contact
- db_ops_ruid (int)
- handle_lost_tcp (int)
- close_expired_tcp (int)
- expires_type (int)
- db_raw_fetch_type (int)
- db_insert_null (int)
- skip_remote_socket (int)
- db_timer_clean (int)
- server_id_filter (int)
RPC Commands
ul.dump
ul.lookup table AOR
ul.rm table AOR
ul.rm_contact table AOR contact
ul.flush
ul.add
ul.db_users
ul.db_contacts
ul.db_expired_contacts
Statistics
users
contacts
expires
registered_users
Functions
ul_register_domain(name)
ul_insert_urecord(domain, aor, rec)
ul_delete_urecord(domain, aor)
ul_delete_urecord_by_ruid(domain, ruid)
ul_get_urecord(domain, aor)
ul_lock_udomain(domain)
ul_unlock_udomain(domain)
ul_release_urecord(record)
ul_insert_ucontact(record, contact, expires, q, callid, cseq, flags, cont, ua, sock)
ul_delete_ucontact (record, contact)
ul_get_ucontact(record, contact)
ul_get_all_ucontacts (buf, len, flags)
ul_update_ucontact(contact, expires, q, callid, cseq, set, res, ua, sock)
ul_bind_ursloc( api )
ul_register_ulcb(type ,callback, param)
ul_get_num_users()
Registrar
SIP registration processing logic can be defined here .
Path support – off , lazy , strict ( RFC 3327)
GRU ( Globally Routbale User agent URIs) support – public , temporary ( RFC 5627)
Dependencies :
- usrloc – User Location Module.
- sl – Stateless Replies.
Parameters :
- default_expires
- default_expires_range
- expires_range
- min_expires
- max_expires
- default_q
- realm_prefix
- append_branches
- aor_avp (str)
- case_sensitive
- received_avp (str)
- received_param
- max_contacts
- retry_after
- sock_flag
- sock_hdr_name
- method_filtering
- use_path
- path_mode
- path_use_received
- path_check_local
- reg_callid_avp
- xavp_cfg
- xavp_rcd
- gruu_enabled
- outbound_mode
- regid_mode
- flow_timer
- contact_max_size
Functions :
save(domain, [, flags [, uri]])
lookup(domain [, uri])
lookup_branches(domain)
registered(domain [, uri [, match_option [, match_action]]])
add_sock_hdr(hdr_name)
unregister(domain, uri[, ruid])
reg_fetch_contacts(domain, uri, profile)
reg_free_contacts(profile)
Event Routes :
event_route[usrloc:contact-expired]
Statistics :
max_expires
max_contacts
default_expires
accepted_regs
rejected_regs
Ref : http://kamailio.org/docs/modules/stable/modules/registrar.html
Dialog
Keep track of current dialogs also provides API support . It can be loaded and used like given below .
loadmodule "dialog.so"
..
# ---- dialog params ----
modparam("dialog", "enable_stats", 1)
modparam("dialog", "dlg_flag", 4)
modparam("dialog", "event_callback", "ksr_dialog_event")
Parameters :
- enable_stats (integer)
- hash_size (integer)
- rr_param (string)
- dlg_flag (integer)
- timeout_avp (string)
- default_timeout (integer)
- early_timeout (integer)
- noack_timeout (integer)
- end_timeout (integer)
- dlg_extra_hdrs (string)
- dlg_match_mode (integer)
- detect_spirals (integer)
- db_url (string)
- db_mode (integer)
- db_update_period (integer)
- db_fetch_rows (integer)
- db_skip_load (integer)
- table_name (string)
- call_id_column (string)
- from_uri_column (string)
- from_tag_column (string)
- to_uri_column (string)
- to_tag_column (string)
- from_cseq_column (string)
- to_cseq_column (string)
- from_route_column (string)
- to_route_column (string)
- from_contact_column (string)
- to_contact_column (string)
- from_sock_column (string)
- to_sock_column (string)
- h_id_column (string)
- h_entry_column (string)
- state_column (string)
- start_time_column (string)
- timeout_column (string)
- sflags_column (string)
- toroute_name_column (string)
- vars_table_name (string)
- vars_h_id_column (string)
- vars_h_entry_column (string)
- vars_key_column (string)
- vars_value_column (string)
- profiles_with_value (string)
- profiles_no_value (string)
- bridge_controller (string)
- bridge_contact (string)
- initial_cbs_inscript (int)
- send_bye (int)
- wait_ack (int)
- ka_timer (int)
- ka_interval (int)
- ka_failed_limit (int)
- timeout_noreset (int)
- timer_procs (int)
- enable_dmq (int)
- track_cseq_updates (int)
- lreq_callee_headers (string)
- event_callback (str) –
- name of the function in the kemi configuration file (embedded scripting language such as Lua, Python, …) to be executed instead of event_route[…] blocks. The function receives a string parameter with the name of the event, the values are: ‘dialog:start’, ‘dialog:end’, ‘dialog:failed’. It is also executed if ‘$dlg_ctx(timeout_route)’ is set
function ksr_dialog_event(evname)
KSR.info("===== dialog module triggered event: " .. evname .. "\n");
if (evname == "dialog:end") or (evname == "dialog:failed") then
logger.log("info", "in dialog event callback with event-name - " .. evname .. " start CDR process ")
if not cdrProcess.post() then
logger.log("err", "Failed")
else
logger.log("info", "successfully posted")
core.exit()
end
end
end
- h_id_start (int)
- h_id_step (int)
Functions :
set_dlg_profile(profile,[value])
unset_dlg_profile(profile,[value])
is_in_profile(profile,[value])
get_profile_size(profile,[value],size)
dlg_isflagset(flag)
dlg_setflag(flag)
dlg_resetflag(flag)
dlg_bye(side)
dlg_refer(side, address)
dlg_manage()
dlg_bridge(from, to, op)
dlg_get(callid, ftag, ttag)
is_known_dlg()
dlg_set_timeout(timeout [, h_entry, h_id])
dlg_set_timeout_by_profile(profile, [value], timeout)
dlg_set_property(attr)
dlg_remote_profile(cmd, profile, value, uid, expires)
dlg_set_ruri()
Statistics :
active_dialogs
early_dialogs
processed_dialogs
expired_dialogs
failed_dialogs
RPC Commands :
dlg.list
dlg.list_ctx
dlg.dlg_list
dlg.dlg_list_ctx
dlg.terminate_dlg
dlg.end_dlg
dlg.profile_get_size
dlg.profile_list
dlg.bridge_dlg
Exported Variables :
$DLG_count
$DLG_status
$DLG_lifetime
$dlg(…)
$dlg_ctx(…)
$dlg_var(key)
Event Routes :
event_route[dialog:start] , event_route[dialog:end] , event_route[dialog:failed]
UAC module
This set deals with RTP proxy and RTP engine which are used for proxing media streams via kamailio server .
RTP Proxy
Used to proxy the media stream . Example : Sippy RTPproxy , ngcp-rtpproxy-ng . Multiple RTP proxies can be used for load distribution and balancing . RTP proxy can also operated in bridging mode to setup bridge signalling between multiple network interfaces. It does not support transcoding.
Parameters :
- rtpproxy_sock – binds a ip and port for rtp proxy
modparam(“rtpproxy”, “rtpproxy_sock”, “udp:localhost:12221”) - rtpproxy_disable_tout – when rtp proxy is disabled then timeout till when it doesnt connect
- rtpproxy_tout – timeout to wait for reply
- rtpproxy_retr – num of retries after timeout
- nortpproxy_str – sets the SDP attribute used by rtpproxy to mark the message’s SDP attachemnt with information that it have already been changed
default value is “a=nortpproxy:yes\r\n” and others like “a=sdpmangled:yes\r\n” - timeout_socket (string)
- ice_candidate_priority_avp (string)
- extra_id_pv (string)
- db_url (string)
- table_name (string)
- rtp_inst_pvar (string)
Functions
set_rtp_proxy_set(setid) – Sets the Id of the rtpproxy set to be used for the next unforce_rtp_proxy(), rtpproxy_offer(), rtpproxy_answer() or rtpproxy_manage() command
rtpproxy_offer([flags [, ip_address]]) – to make the media pass through RTP the SDP is altered. Value of flag can be
1 – append first Via branch to Call-ID when sending command to rtpproxy.
2 – append second Via branch to Call-ID when sending command to rtpproxy. See flag ‘1’ for its meaning.
3 – behave like flag 1 is set for a request and like flag 2 is set for a reply
a – flags that UA from which message is received doesn’t support symmetric RTP. (automatically sets the ‘r’ flag)
b – append branch specific variable to Call-ID when sending command to rtpproxy
l – force “lookup”, that is, only rewrite SDP when corresponding session already exists in the RTP proxy
i, e – direction of the SIP message when rtpproxy is running in bridge mode. ‘i’ is internal network (LAN), ‘e’ is external network (WAN). Values ie , ei , ee and ii
x – shortcut for using the “ie” or “ei”-flags, to do automatic bridging between IPv4 on the “internal network” and IPv6 on the “external network”. Differentiated by IP type in the SDP, e.g. a IPv4 Address will always call “ie” to the RTPProxy (IPv4(i) to IPv6(e)) and an IPv6Address will always call “ei” to the RTPProxy (IPv6(e) to IPv4(i))
f – instructs rtpproxy to ignore marks inserted by another rtpproxy in transit to indicate that the session is already gone through another proxy. Allows creating a chain of proxies
r – IP address in SDP should be trusted. Without this flag, rtpproxy ignores address in the SDP and uses source address of the SIP message as media address which is passed to the RTP proxy
o – flags that IP from the origin description (o=) should be also changed.
c – flags to change the session-level SDP connection (c=) IP if media-description also includes connection information.
w – flags that for the UA from which message is received, support symmetric RTP must be forced.
zNN – perform re-packetization of RTP traffic coming from the UA which has sent the current message to increase or decrease payload size per each RTP packet forwarded if possible. The NN is the target payload size in ms, for the most codecs its value should be in 10ms increments, however for some codecs the increment could differ (e.g. 30ms for GSM or 20ms for G.723).
ip_address denotes the address of new SDP
such as : rtpproxy_offer(“FRWOC+PS”) is
rtpengine_offer(“force trust-address symmetric replace-origin replace-session-connection ICE=force RTP/SAVPF”);
route {
...
if (is_method("INVITE"))
{
if (has_body("application/sdp"))
{
if (rtpproxy_offer()) t_on_reply("1");
} else {
t_on_reply("2");
}
}
if (is_method("ACK") && has_body("application/sdp")) rtpproxy_answer();
...
}
onreply_route[1] {
if (has_body("application/sdp")) rtpproxy_answer();
}
onreply_route[2] {
if (has_body("application/sdp")) rtpproxy_offer();
}
rtpproxy_answer([flags [, ip_address]])- rewrite SDP to proxy media , it can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
rtpproxy_destroy([flags]) – tears down RTP proxy session for current call. Flags are ,
1 – append first Via branch to Call-ID
2 – append second Via branch to Call-ID
b – append branch specific variable to Call-ID
t – do not include To tag to “delete” command to rtpproxy thus causing full call to be deleted
unforce_rtp_proxy()
rtpproxy_manage([flags [, ip_address]]) – Functionality is to use predfined logic for handling requests
If INVITE with SDP, then do rtpproxy_offer()
If INVITE with SDP, when the tm module is loaded, mark transaction with internal flag FL_SDP_BODY to know that the 1xx and 2xx are for rtpproxy_answer()
If ACK with SDP, then do rtpproxy_answer()
If BYE or CANCEL, or called within a FAILURE_ROUTE[], then call unforce_rtpproxy().
If reply to INVITE with code >= 300 do unforce_rtpproxy()
If reply with SDP to INVITE having code 1xx and 2xx, then do rtpproxy_answer() if the request had SDP or tm is not loaded, otherwise do rtpproxy_offer()
This function can be used from ANY_ROUTE.
rtpproxy_stream2uac(prompt_name, count) – stream prompt/announcement pre-encoded with the makeann command. The uac/uas suffix selects who will hear the announcement relatively to the current transaction – UAC or UAS. Also used for music on hold (MOH).
Params : prompt_name – path name of the prompt to stream
count – number of times the prompt should be repeated. When count is -1, the streaming will be in loop indefinitely until the appropriate rtpproxy_stop_stream2xxx is issued.
Example rtpproxy_stream2xxx usage
if (is_method("INVITE")) {
rtpproxy_offer();
if (is_audio_on_hold()) {
rtpproxy_stream2uas("/var/rtpproxy/prompts/music_on_hold", "-1");
} else {
rtpproxy_stop_stream2uas();
};
};
rtpproxy_stream2uas(prompt_name, count)
rtpproxy_stop_stream2uac()- Stop streaming of announcement/prompt/MOH
rtpproxy_stop_stream2uas()
start_recording()
Exported Pseudo Variables
$rtpstat
RPC Commands
rtpproxy.enable
rtpproxy.list
RTP Engine
media streams to be proxied via an RTP proxy.
loadmodule "rtpengine.so"
...
# ----- rtpengine params -----
modparam("rtpengine", "db_url", DBURL)
modparam("rtpengine", "table_name" , "rtpengine")
modparam("rtpengine", "rtpengine_allow_op", 1)
modparam("rtpengine", "queried_nodes_limit", 4)
modparam("rtpengine", "rtpengine_retr", 2)
modparam("rtpengine", "rtp_inst_pvar", "$avp(RTP_INSTANCE)")
modparam("rtpengine", "setid_default", 1)
modparam("rtpengine", "mos_min_pv", "$avp(mos_min)")
modparam("rtpengine", "mos_min_at_pv", "$avp(mos_min_at)")
modparam("rtpengine", "mos_min_packetloss_pv", "$avp(mos_min_packetloss)")
modparam("rtpengine", "mos_min_jitter_pv", "$avp(mos_min_jitter)")
modparam("rtpengine", "mos_min_roundtrip_pv", "$avp(mos_min_roundtrip)")
modparam("rtpengine", "rtpengine_tout_ms", 300)
source : https://github.com/sipwise/rtpengine
Parameters
- rtpengine_sock (string)
- rtpengine_disable_tout (integer)
- rtpengine_tout_ms (integer)
- rtpengine_allow_op (integer)
- queried_nodes_limit (integer)
- rtpengine_retr (integer)
- extra_id_pv (string)
- setid_avp (string)
- force_send_interface (string)
- read_sdp_pv (string)
- write_sdp_pv (string)
- rtp_inst_pvar (string)
- hash_table_size (integer)
- hash_table_tout (integer)
- db_url (string)
- table_name (string)
- setid_col (string)
- url_col (string)
- weight_col (string)
- disabled_col (string)
- setid_default (integer)
- mos_min_pv (string)
- mos_min_at_pv (string)
- mos_min_packetloss_pv (string)
- mos_min_jitter_pv (string)
- mos_min_roundtrip_pv (string)
- mos_max_pv (string)
- mos_max_at_pv (string)
- mos_max_packetloss_pv (string)
- mos_max_jitter_pv (string)
- mos_max_roundtrip_pv (string)
- mos_average_pv (string)
- mos_average_packetloss_pv (string)
- mos_average_jitter_pv (string)
- mos_average_roundtrip_pv (string)
- mos_average_samples_pv (string)
- mos_A_label_pv (string)
- mos_min_A_pv (string)
- mos_min_at_A_pv (string)
- mos_min_packetloss_A_pv (string)
- mos_min_jitter_A_pv (string)
- mos_min_roundtrip_A_pv (string)
- mos_max_A_pv (string)
- mos_max_at_A_pv (string)
- mos_max_packetloss_A_pv (string)
- mos_max_jitter_A_pv (string)
- mos_max_roundtrip_A_pv (string)
- mos_average_A_pv (string)
- mos_average_packetloss_A_pv (string)
- mos_average_jitter_A_pv (string)
- mos_average_roundtrip_A_pv (string)
- mos_average_samples_A_pv (string)
- mos_B_label_pv (string)
- mos_min_B_pv (string)
- mos_min_at_B_pv (string)
- mos_min_packetloss_B_pv (string)
- mos_min_jitter_B_pv (string)
- mos_min_roundtrip_B_pv (string)
- mos_max_B_pv (string)
- mos_max_at_B_pv (string)
- mos_max_packetloss_B_pv (string)
- mos_max_jitter_B_pv (string)
- mos_max_roundtrip_B_pv (string)
- mos_average_B_pv (string)
- mos_average_packetloss_B_pv (string)
- mos_average_jitter_B_pv (string)
- mos_average_roundtrip_B_pv (string)
- mos_average_samples_B_pv (string)
Functions
set_rtpengine_set(setid[, setid])
rtpengine_offer([flags])
rtpengine_answer([flags])
rtpengine_delete([flags])
rtpengine_query([flags])
rtpengine_manage([flags])
start_recording([flags])
stop_recording([flags])
Exported Pseudo Variables
$rtpstat
RPC Commands
rtpengine.reload
rtpengine.enable proxy_url/all 0/1
rtpengine.show proxy_url/all
rtpengine.ping proxy_url/all
rtpengine.get_hash_total
This set deals with HTTP and Websocket adapters to handle web pone based ( such as webRTC) calls on kamailio
XHTTP
Provides basic HTTP/1.0 server functionality .
SIP requires a Content-Length header for TCP transport. But most HTTP clients do not set the content length for normal GET requests. Therefore, the core must be configured to allow incoming requests without content length header:
tcp_accept_no_cl=yes
Parameters :
url_skip : if there is a match , event route is not executed
modparam(“xhttp”, “url_skip”, “^/RPC2”)
url_match : if there is no match , event route is not executed
modparam(“xhttp”, “url_match”, “^/sip/”)
event_Callback : function in the kemi configuration file (embedded scripting language such as Lua, Python) to be executed instead of event_route[xhttp:request] block
Example :
modparam(“xhttp”, “event_callback”, “ksr_xhttp_event”)
and the event callback function implemented in Lua
function ksr_xhttp_event(evname)
KSR.info(“===== xhttp module triggered event: ” .. evname .. “\n”);
return 1;
end
Function
xhttp_reply(code, reason, ctype, body) – Send back a reply with content-type and body.
event_route[xhttp:request] {
xhttp_reply("200", "OK", "" , "");
or
xhttp_reply("403", "Forbidden", "", "");
}
Event Routes
xhttp:request
The event route is executed when a new HTTP request is received.
event_route[xhttp:request] {
xhttp_reply(“200”, “OK”, “text/html”, “<html><body>OK – [$si:$sp]</body></html>”);
}
Websocket Module
provide websocket ( ws and wss) support to kamailio ( RFC 6455). Handles handshaking, management (including connection keep-alive), and framing for the SIP and MSRP WebSocket sub-protocols (RFC 7118 and RFC 7977).
-tbd
