Kamailio Handbook — Українська

Як Kamailio влаштований зсередини.

[!IMPORTANT] Цей посібник свідомо не переказує офіційну документацію. Передбачається, що ви вже знаєте, що таке Kamailio на поверхні. Натомість тут — занурення в рантайм, життєвий цикл повідомлень, движок скриптів, KEMI та архітектурні фішки, які формують поведінку Kamailio. Розділу «модуль за модулем» тут не буде.

Використані джерела:

asipto/kamailio-devel-guide — посібник з внутрішнього устрою від оригінального мейнтейнера; глибоко про data lumps, парсер, пам'ять, локи, RPC.
kamailio.org/wikidocs — фонова інформація та поверхневе API.
github.com/kamailio/kamailio — реальна імплементація в C, фінальне джерело істини.
Для Part 10 (IMS):
- lyatanski/ims — cloud-native софтовий IMS-стенд (Compose + Helm).
- anabelen-garcia/IMS-Kamailio-Tutorial — академічний single-VM-туторіал Kamailio+FHoSS (UPM).
- Open5GS «VoLTE Setup with Kamailio IMS» — upstream-туторіал, від якого обидва походять.

Як SIP-запит проходить через Kamailio¶

flowchart LR
    In([SIP IN]) --> Parser[Парсер]
    Parser --> Sanity[Sanity-перевірки]
    Sanity --> RR[request_route]
    RR --> Mods[[Функції модулів<br/>tm · rr · auth · dispatcher · …]]
    Mods --> Decision{Stateful?}
    Decision -- так --> TM[tm: створити транзакцію]
    Decision -- ні --> SL[sl: stateless-форвард]
    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

Одне отримане SIP-повідомлення проходить через цей конвеєр. Більшість того, що в конфізі Kamailio виглядає «магічно», — це просто вибір гілки на цьому шляху. Цей посібник розбирає кожен прямокутник вище.

Зміст¶

1. Передмова¶

1.1 Вступ — сигналізація проти медіа, ментальна модель, чого чекати ✅
1.2 SIP за 60 секунд — транзакції, діалоги, positive/negative ACK, роль проксі ✅

2. Рантайм¶

2.1 Процесна модель — main, attendant, timer, воркери: для чого кожен ✅
2.2 Архітектура пам'яті — pkg vs shm, кастомний алокатор, правила життєвого циклу ✅
2.3 Примітиви конкурентності — локи, atomic-операції, per-bucket шардинг ✅
2.4 Життєвий цикл — старт, перезавантаження конфігу, graceful shutdown ✅
2.5 Sizing & tuning — воркери, пам'ять, kernel-кнопки під паттерн трафіку (proxy / registrar / stateful / WS) ✅

3. Життєвий цикл SIP-повідомлення¶

3.1 Прийом — сокети, слухачі, як транспорт демультиплексує ✅
3.2 Розпарсене повідомлення — структура sip_msg, lazy-парсинг заголовків, ціна ✅
3.3 Lumps — як мутації чергуються, а не застосовуються одразу (це і є той самий speed-trick) ✅
3.4 Движок маршрутизації — request_route, reply_route, onreply_route, branch_route, failure_route, event_route ✅
3.5 Форвардинг і відповіді — складання вихідного повідомлення з buffer'а та lump'ів ✅

4. Движок скриптів¶

4. Script engine — pointer-розділ — тонка карта де про script-engine-машинерію написано в інших розділах, плюс ті кілька внутрішніх деталей (форма AST, диспетчеризація псевдо-змінних, конвенція return-value) що нікуди не вмістилися ✅

5. KEMI — embedded scripting¶

5.1 Яку проблему вирішує KEMI — коли cfg DSL перестає вистачати ✅
5.2 Bridge — як Lua, Python, JS, Ruby вбудовуються в C-рантайм ✅
5.3 Lifecycle — per-worker-інтерпретатор, що переживає повідомлення, reload ✅
5.4 Tradeoffs — коли виграє KEMI, коли native cfg, гібридний патерн ✅

6. Стан, транзакції, діалоги¶

6.1 Транзакції (tm) — хеш-таблиці у shm, timer wheels, retransmission ✅
6.2 Діалоги — як dialog доповнює tm для відстеження повного виклику ✅
6.3 Патерн usrloc — in-memory кеш, DB-sync, узагальнено ✅

7. Control plane¶

7.1 Архітектура RPC — BINRPC vs JSON-RPC, command registry, auth ✅
7.2 kamcmd — важіль оператора, п'ять команд для повсякдення ✅
7.3 Event routes — програмовані хуки в життєвий цикл рантайму ✅

8. Архітектурні фішки¶

8.1 Topology hiding (topos) — переписування виклику так, щоб топологія зникла ✅
8.2 Async-транзакції — t_suspend / t_continue для неблокуючих сценаріїв ✅
8.3 htable — хеш-таблиці у спільній пам'яті як «бідний Redis» ✅
8.4 dispatcher — hash-based stickiness, набори шлюзів, failover-алгоритми ✅
8.5 dmq — синхронізація стану між інстансами Kamailio ✅
8.6 Медіа — rtpengine — анкорінг RTP, керування демоном з конфіга, захист від RTP-bleed, SRTP/DTLS↔RTP, ICE/STUN, kernel-mode-форвардинг ✅
8.7 Захоплення SIP через TLS — чому wire-capture не працює на TLS/WSS, тап розшифрованого SIP через siptrace, HEP і живий sngrep ✅

9. Безпека і hardening¶

9.1 Поверхня атаки SIP і модель загроз — чому публічний UDP/5060-сокет відкритий; ціна неавтентифікованого повідомлення; межі довіри ✅
9.2 Захисні модулі — sanity, secfilter, pike, topoh, digest-auth — що насправді перевіряє кожен ✅
9.3 Динамічні блок-листи: apiban та ipban — стоковий antiflood у kamailio.cfg (htable ipban + pike) і фід apiban.org ✅
9.4 Fuzzing і кейс command-injection → RCE — fuzzing парсера; як SIP-заголовок стає reverse-shell, і де Kamailio є/не є вразливим ✅

10. Kamailio в IMS¶

10.1 Що таке IMS і де тут Kamailio — 3GPP-фреймінг, ролі CSCF, модель reference-points (Gm/Mw/Cx/Rx/Ro/ISC) ✅
10.2 Ролі CSCF на Kamailio — P/I/S-CSCF, модулі ims_*, двопрохідний flow реєстрації, де живе стан ✅
10.3 Сторона Diameter — cdp/cdp_avp, Cx/Rx/Ro, peer state machine, async-у-воркері ✅
10.4 Що ще треба навколо Kamailio — HSS, PCRF, OCS, DRA, rtpengine, DNS, ядро — чесна межа ✅
10.5 Робочий референс — софтовий IMS-стенд — стек lyatanski/ims і академічний single-VM-туторіал ✅

11. Довідник¶

11.1 Глосарій ролей процесів — хто є хто в ps-виводі ✅
11.2 Карта термінів — швидкий глосарій Kamailio-specific ✅
11.3 Що нового і що в розробці — версійний ландшафт (5.8 → 6.0 → 6.1), нові модулі, заархівовані, де стежити за devel ✅

🇬🇧 English