Telco SIP Simulator — Kamailio + MySQL Lab

A dockerized lab environment that simulates a telco SIP setup using Kamailio 5.6 with MySQL-backed authentication and user location, plus prefix-based dispatcher routing with failover. Intended as a teaching / lab playground, not a production deployment.

Architecture

• Kamailio 5.6 SIP server (container, host networking). Listens on TCP and UDP, on 127.0.0.1:5060 and <your_public_ip>:5060.
• MySQL 8.0.33 (container). Exposes port 3399 on the host. Schema name: kamailio_telco_simulator.
• Dispatcher routes calls by phone-number prefix to backend SIP servers, with automatic failover. Group 4 in the example config handles prefix 19002098* and forwards to a LiveKit backend.

Repository layout

simulator-telco/
├── kamailio/
│   ├── kamailio.cfg                  # Main Kamailio config (custom routing + dispatcher)
│   ├── kamctlrc                      # kamctl/kamdbctl runtime config
│   ├── dispatcher.list               # Dispatcher backend list
│   ├── docker-compose.yaml           # Run Kamailio
│   └── docker-compose-create-db.yaml # One-shot: wait for MySQL, create schema, then start Kamailio
└── mysql-setup/
    └── docker-compose.yaml           # Run MySQL on port 3399

Prerequisites

• Docker Engine and Docker Compose v2.
• A Linux host. Both Compose files use network_mode: host, which is only fully supported on Linux. On Windows or macOS run inside a Linux VM.

Quick start

1. Edit configuration first. The repo ships with placeholders that will not work as-is. See Configuration below.
2. Start MySQL:

   cd mysql-setup
   docker compose up -d

3. Create the Kamailio schema (one-shot — it waits for MySQL, runs kamdbctl create, then starts Kamailio in foreground):

   cd ../kamailio
   docker compose -f docker-compose-create-db.yaml up

   When the schema is created, stop this container with Ctrl+C.
4. Start Kamailio normally:

   docker compose up -d

5. Add a SIP user (example):

   docker exec -it kamailio kamctl add alice secretpass

Configuration

You must replace the placeholders below before deploying. The values must stay consistent across the listed files.

Placeholder	Replace with	Files
your_password	A real strong DB password	kamailio/kamailio.cfg, kamailio/kamctlrc, kamailio/docker-compose-create-db.yaml, mysql-setup/docker-compose.yaml
your_public_ip	The host's public IPv4	kamailio/kamailio.cfg (in listen= directives and the LiveKit dispatcher target comment)

Other values you may want to change:

• SIP_DOMAIN and the alias= directive — currently simulator.bytebuffer.co.
• Dispatcher backends — edit kamailio/dispatcher.list and the route[ROUTING_DISPATCH] block in kamailio/kamailio.cfg.
• DB port 3399 — change in both mysql-setup/docker-compose.yaml and the DBURL/DBPORT settings in kamailio.cfg and kamctlrc.

Routing logic (kamailio.cfg)

• route[ROUTING_DISPATCH] — selects a backend via the dispatcher module. In the shipped config, requests with a prefix matching 19002098* are dispatched to group 4 in round-robin order, with t_on_failure("2") armed for failover.
• onreply_route[1] — sets flag 15 on incoming 1xx/2xx replies so the failure route knows the backend already responded and failover should be suppressed.
• failure_route[2] — on a 3xx/4xx/5xx/6xx upstream failure, calls ds_next_dst() to try the next backend. When the dispatcher list is exhausted it returns 503 Service Unavailable to the caller.

Other custom tweaks vs. the upstream 5.6 default config:

• WITH_MYSQL, WITH_AUTH, WITH_USRLOCDB enabled.
• tm fr_timer lowered from 30 s to 3 s for faster failover.
• tm local_ack_mode set to 1.

Caveats

• Placeholders your_password and your_public_ip are not valid values. Replace them before starting the services.
• dispatcher.list only ships group 1 (sip:127.0.0.1:5060). Group 4 referenced by route[ROUTING_DISPATCH] is not populated — add your backend(s) there before dispatcher routing will actually work.
• The aggressive 3 s fr_timer is suited to fast on-LAN backends; raise it if your upstream is slower.
• mysql-setup/mysql/ is the MySQL data volume and is git-ignored. Deleting it wipes all users/registrations.

License

No license has been declared yet. Add a LICENSE file before any public reuse.