Kamailio Handbook — English

How Kamailio is built on the inside.

[!IMPORTANT] This handbook is deliberately not a re-telling of the official docs. It assumes you already know what Kamailio is at a surface level and instead drills into the runtime, the message lifecycle, the script engine, KEMI, and the architectural tricks that make Kamailio behave the way it does. There is no module-by-module reference here.

Sources used:

asipto/kamailio-devel-guide — internals reference by the original maintainer; goes deep on data lumps, parser, memory, locking, RPC.
kamailio.org/wikidocs — for background and the surface-level API.
github.com/kamailio/kamailio — actual implementation in C, the final source of truth.
For Part 10 (IMS):
- lyatanski/ims — a cloud-native software IMS lab (Compose + Helm).
- anabelen-garcia/IMS-Kamailio-Tutorial — a single-VM academic Kamailio+FHoSS tutorial (UPM).
- Open5GS "VoLTE Setup with Kamailio IMS" — the upstream tutorial both descend from.

How a SIP request flows through Kamailio¶

flowchart LR
    In([SIP IN]) --> Parser[Parser]
    Parser --> Sanity[Sanity checks]
    Sanity --> RR[request_route]
    RR --> Mods[[Module functions<br/>tm · rr · auth · dispatcher · …]]
    Mods --> Decision{Stateful?}
    Decision -- yes --> TM[tm: create transaction]
    Decision -- no --> SL[sl: stateless forward]
    TM --> Out([SIP OUT])
    SL --> Out

    classDef io fill:#238636,stroke:#238636,color:#fff
    classDef core fill:#1f6feb,stroke:#1f6feb,color:#fff
    classDef mod fill:#bf8700,stroke:#bf8700,color:#fff
    classDef branch fill:#6e7681,stroke:#6e7681,color:#fff

    class In,Out io
    class Parser,Sanity,RR core
    class Mods,TM,SL mod
    class Decision branch

A single received SIP message walks through this pipeline. Most of what looks like "magic" in a Kamailio config is just deciding which way it branches — and the handbook unpacks every box above.

Table of contents¶

1. Preface¶

1.1 Introduction — signalling vs media, mental model, what to expect ✅
1.2 SIP in 60 seconds — transactions, dialogs, positive/negative ACK, role of a proxy ✅

2. The Runtime¶

2.1 Process model — main, attendant, timer, workers — what each one is for ✅
2.2 Memory architecture — pkg vs shm, the custom allocator, lifetime rules ✅
2.3 Concurrency primitives — locks, atomic ops, per-bucket sharding ✅
2.4 Lifecycle — startup, config reload, graceful shutdown ✅
2.5 Sizing & tuning — workers, memory, kernel knobs per traffic pattern (proxy / registrar / stateful / WS) ✅

3. SIP Message Lifecycle¶

3.1 Reception — sockets, listeners, how transport demultiplexes ✅
3.2 The parsed message — sip_msg struct, lazy header parsing, the cost model ✅
3.3 Lumps — how mutations are queued rather than applied (this is the speed trick) ✅
3.4 The routing engine — request_route, reply_route, onreply_route, branch_route, failure_route, event_route ✅
3.5 Forwarding and replies — assembling the outgoing message from buffer + lumps ✅

4. The Script Engine¶

4. Script engine — pointer chapter — thin map of where the script-engine machinery is documented across other chapters, plus the few internals (AST shape, pseudo-variable dispatch, return-value convention) that didn't fit elsewhere ✅

5. KEMI — embedded scripting¶

5.1 What problem KEMI solves — when the cfg DSL stops being enough ✅
5.2 The bridge — embedding Lua, Python, JS, Ruby into the C runtime ✅
5.3 Lifecycle — per-worker interpreter, what survives between messages, reload ✅
5.4 Tradeoffs — when KEMI wins, when native cfg wins, the hybrid pattern ✅

6. State, Transactions, Dialogs¶

6.1 Transactions (tm) — hash tables in shm, timer wheels, retransmission ✅
6.2 Dialogs — how dialog augments tm to track full calls ✅
6.3 The usrloc pattern — in-memory cache, DB sync, generalised ✅

7. Control Plane¶

7.1 RPC architecture — BINRPC vs JSON-RPC, the command registry, auth posture ✅
7.2 kamcmd — the operator's lever, the five commands you'll run constantly ✅
7.3 Event routes — programmable hooks into runtime lifecycle ✅

8. Cool architectural tricks¶

8.1 Topology hiding (topos) — rewriting calls so the topology vanishes ✅
8.2 Async transactions — t_suspend / t_continue for non-blocking flows ✅
8.3 htable — shared-memory hash tables as a poor man's Redis ✅
8.4 dispatcher — hash-based stickiness, gateway sets, failover algorithms ✅
8.5 dmq — distributed state sync between Kamailio instances ✅
8.6 Media — rtpengine — anchoring RTP, controlling the daemon from the config, RTP-bleed defence, SRTP/DTLS↔RTP, ICE/STUN, kernel-mode forwarding ✅
8.7 Capturing SIP over TLS — why wire capture fails on TLS/WSS, tapping decrypted SIP with siptrace, HEP, and live sngrep ✅

9. Security & Hardening¶

9.1 SIP attack surface & threat model — why a public UDP/5060 socket is exposed; the cost of an unauthenticated message; trust boundaries ✅
9.2 Defensive modules — sanity, secfilter, pike, topoh, digest auth — what each actually checks ✅
9.3 Dynamic blocklists: apiban & ipban — the stock kamailio.cfg antiflood (ipban htable + pike) and the apiban.org feed ✅
9.4 Fuzzing & a command-injection → RCE case study — fuzzing the parser; how a SIP header becomes a reverse shell, and where Kamailio is/isn't the vuln ✅

10. Kamailio in IMS¶

10.1 What IMS is and where Kamailio fits — 3GPP framing, CSCF roles, the reference-point model (Gm/Mw/Cx/Rx/Ro/ISC) ✅
10.2 The CSCF roles on Kamailio — P/I/S-CSCF, the ims_* modules, the two-pass registration flow, where state lives ✅
10.3 The Diameter side — cdp/cdp_avp, Cx/Rx/Ro, the peer state machine, async-in-the-worker ✅
10.4 What you still need around Kamailio — HSS, PCRF, OCS, DRA, rtpengine, DNS, core — the honest scope line ✅
10.5 A worked reference — a software IMS lab — the lyatanski/ims stack and a single-VM academic tutorial ✅

11. Reference¶

11.1 Process roles glossary — what each ps-visible process actually is ✅
11.2 Term map — quick glossary of Kamailio-specific terms ✅
11.3 What's new and what's in development — version landscape (5.8 → 6.0 → 6.1), new modules, archived modules, where to follow devel ✅

🇺🇦 Українська