Kamailio Examples

Working kamailio.cfg files and KEMI Lua scripts for the many roles a Kamailio server can take: registrar, proxy, load balancer, session border controller, WebRTC gateway and capture node. Every example is self contained and can be read on its own.

Start with a barebone server Browse the repository

Examples target Kamailio v5.x. Older wiki-sourced configurations have been updated, but module parameters still vary between minor releases, so check them against the module documentation for the version you run.

Core SIP features

Message handling, registration, transactions, dialogs and routing basics.

Barebone SIP server Minimal SIP server that parses and answers messages, with no relay, proxy or NAT logic. REGISTER handling Answering REGISTER requests with 200 OK without touching a location database. Register and user location Storing and looking up contacts in the USRLOC service. Stateful transactions Transaction stateful processing with the tm module. Stateful dialogs Tracking calls end to end with the dialog module. Relay with flags Relaying requests and branching behaviour off per-transaction flags. Record routing Staying in the path of sequential in-dialog requests. Topology hiding Masking internal routing information from the far end.

Routing and proxying

Distributing and steering traffic between endpoints, domains and carriers.

SIP load balancer Dispatcher based distribution across a pool of SIP endpoints. Edge proxy Border facing proxy for inter-domain routing. Private identities Handling P-Asserted-Identity and related private headers. Carrier routing Least cost and carrier selection with the carrierroute module.

NAT and media

Traversing NAT and relaying RTP through RTPProxy or RTPEngine.

NAT traversal Detecting NATed clients and fixing contacts, Via and SDP. NAT handling in Lua KEMI Lua NAT logic split into reusable helper modules. RTPProxy Media relay with the legacy RTPProxy engine. RTPEngine media proxy RTPEngine as media proxy, including the systemd unit. RTPEngine bridge on failure Falling back to a second media node when the first one fails.

WebRTC

Browsers talking to browsers and to the PSTN over WSS and DTLS-SRTP.

WebRTC to WebRTC over WebSocket WSS registrar and signalling for browser to browser calls. WebRTC to WebRTC with RTPEngine Browser to browser calls with RTPEngine handling DTLS-SRTP. WebRTC to SIP Gatewaying browser calls to plain SIP endpoints. WebRTC to SIP on IPv4 and IPv6 Dual stack gateway with address family bridging in the media plane. WebRTC with PostgreSQL and RTPEngine Full WebRTC stack backed by PostgreSQL. WebRTC with PostgreSQL and RTPProxy The same stack using RTPProxy for media.

Lua and KEMI scripting

Moving the routing logic out of kamailio.cfg and into Lua.

Minimal Lua config The smallest working KEMI Lua routing script. Load balancer in Lua Endpoint selection written as Lua functions. SBC with authentication Session border controller logic with digest authentication. SBC with authentication and encryption The authenticated SBC extended with TLS and SRTP. Registrar with permissions Authorising registrations against a permission set. RTPEngine daisy chaining Passing media through more than one RTPEngine instance. MOS with RTPEngine Reading RTCP derived quality scores back into the routing script. Stateful dialogs with RTPEngine Dialog tracking plus media control from Lua. SQLite from Lua Querying an SQLite backend inside the routing script.

Call handling and accounting

Forking, early media, CDRs and voice quality measurement.

Forking Parallel and serial forking towards several destinations. Early media Dealing with 183 Session Progress and early SDP. Accounting CDR generation with the acc module. MOS with the acc module Writing quality scores alongside the CDR record. MOS from RTP statistics Deriving MOS from RTCP reports collected by RTPEngine.

Databases

Persisting subscribers, location and state.

MySQL user storage Subscriber storage on MySQL, including kamctlrc setup. PostgreSQL location storage USRLOC persisted in PostgreSQL. Redis Location and accounting records held in Redis.

Security, tracing and control

TLS, packet capture and remote control interfaces.

TLS only TLS transport configuration and verification with openssl s_client. SIP capture over HEP Trace node and capture node using the HEP protocol. HOMER and heplify-server A full capture stack with HOMER, heplify-server and MariaDB. JSON-RPC Driving Kamailio over the JSON-RPC control interface. Async call control with EVAPI Handing routing decisions to an external Node.js application.

Testing

Driving the configurations with synthetic traffic.

SIPp scenarios UAC and UAS scenarios for re-INVITE, UPDATE, CANCEL, BYE and failure cases.

Operational notes

Reference material that applies across the examples.

Agents and user agents SIP user agents, B2BUAs, call centre and bot agents, and how they map onto these configurations. kamctl debugging Inspecting and manipulating a running server with kamctl. kamcmd debugging Runtime RPC commands with kamcmd. sipsak debugging Probing a server with sipsak.

Running an example

Each directory holds the configuration plus, where relevant, dispatcher lists, database seed files, Lua modules and SIPp scenarios. To try one out:

git clone https://github.com/altanai/kamailioexamples.git
cd kamailioexamples/<example>

# sanity check the configuration before loading it
kamailio -c -f kamailio.cfg

# run it in the foreground with debug output
kamailio -f kamailio.cfg -DD -E

Adjust listen, alias, mpath and any database URLs to match your host before starting the server. The kamctl, kamcmd and sipsak notes cover inspecting a running instance.