Kamailio SIP edge (kamailio)
SIP edge of the Navin telephony: SIP over UDP, TCP and TLS for the carriers and the phones, WebSocket over TLS for the WebRTC softphones, anti-flood, anti-bruteforce, NAT handling, per tenant call limits and the dispatcher towards the Asterisk pools and LiveKit SIP. The tenant routing lives in hash tables filled by Navin Enterprise through JSONRPC and replicated by DMQ between the instances.
Generated from catalog/services/kamailio.yaml: do not edit by hand.
Summary
| |
|---|
| Version | 5.7.4 |
| Use | install and configure |
| Layer | functional (AI catalog) |
| Category | Network |
| Installation methods | package |
| External connection | no |
| Sandbox only | no |
Licence
| |
|---|
| SPDX identifier | GPL-2.0-or-later |
| Licence policy | licence exception |
| Licence exception | LEX-025 (pending, awaiting the client) |
| Licence note | GPL-2.0-or-later: a separate program reached through SIP and its JSONRPC interface; no Kamailio code is linked into Navin. The offline bundle redistributes the distribution packages with their notices and sources. |
| Platform component | kamailio |
Packages and artifacts
A package the project of the service publishes (its image, its binary archive, its Python or OS package) carries the licence of the service; a third-party package carries the licence written on its row, read from the official upstream metadata.
| Kind | Package | Version | Licence | Details |
|---|
| OS package | kamailio | version of the configured repository | GPL-2.0-or-later | Debian family (apt) |
| OS package | kamailio-autheph-modules | version of the configured repository | GPL-2.0-or-later | Debian family (apt) |
| OS package | kamailio-tls-modules | version of the configured repository | GPL-2.0-or-later | Debian family (apt) |
| OS package | kamailio-websocket-modules | version of the configured repository | GPL-2.0-or-later | Debian family (apt) |
| OS package | python3 | version of the configured repository | PSF-2.0 | Debian family (apt) |
Supported systems and architectures
| Method | Operating systems | Architectures |
|---|
package | Debian family (apt) | x86_64, aarch64 (not restricted by the descriptor) |
- No
package method on the RHEL family (dnf): No maintained Kamailio package exists in RHEL or EPEL 9 and 10: the RPM packages are published by the Kamailio project only (rpm.kamailio.org), a third party repository the offline bundle does not carry. Place the SIP edge on Ubuntu 24.04 (universe: Kamailio 5.7.4) or Debian 13 (Kamailio 6.0.1).
- Method
package on the Debian family (apt) limited to Ubuntu 24.04, Debian 13: Only Ubuntu 24.04 (5.7.4) and Debian 13 (6.0.1) ship a Kamailio the rendered configuration is validated against; Debian 12 (5.6.4) and Ubuntu 22.04 (5.5.4) lack the modules and parameters it uses.
Units of the distribution masked by the method package: kamailio.service. The postinst of the packages starts them with the stock configuration: right after the install the agent stops, disables and masks them (task systemd.mask, only when their unit file belongs to an installed package), and the component runs from its own unit navin-<service>-<component>.service. The uninstall only unmasks them.
Certified host systems: RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). The host preflight accepts these systems (other releases of a known family give a warning, end of life releases are refused) and the x86_64 and aarch64 architectures.
Prerequisites
Host
The descriptor declares no host preflight check.
Programs the commands and checks of the service start on the host, outside the managed roots: add them to allowed_commands of the agent (see Security of the Navin agent), else the agent refuses them with command_not_allowed: /usr/bin/python3, /usr/sbin/kamailio, /usr/sbin/kamcmd.
Network and ports
| Component | Port name | Port | Opened in the host firewall |
|---|
kamailio | sip | 5060/udp | yes |
kamailio | sip_tcp | 5060/tcp | yes |
kamailio | sips | 5061/tcp | yes |
kamailio | wss | 7443/tcp | yes |
kamailio | jsonrpc | 5071/tcp | yes |
kamailio | metrics | 5073/tcp | yes |
kamailio | dmq | 5062/tcp (mode ha) | yes |
Services and connections needed
Details and resolution: see Dependencies.
Installation methods and modes
| Method | Default | What the method uses |
|---|
package | yes | the OS packages of the descriptor, installed by the package manager of the host |
Components
| Component | Kind | Installation methods | Ports |
|---|
Kamailio (kamailio) | master | package | 5060/udp, 5060/tcp, 5061/tcp, 7443/tcp, 5071/tcp, 5073/tcp, 5062/tcp (mode ha) |
Single (single) (default)
One SIP edge: a single point of failure for the calls.
What the mode deploys:
| Component | Placement |
|---|
kamailio | min 1, max 1 |
High availability (ha)
Two or more active instances sharing their hash tables and call counters by DMQ; the carriers and phones reach them by DNS SRV, several addresses or a network load balancer.
What the mode deploys:
| Component | Placement |
|---|
kamailio | min 2, recommended 2 |
Install this service
The install wizard of the Navin Manager plans, validates and runs the installation; you need the services:install permission on the cluster.
-
Open the wizard. In Clusters, choose the row action Install services of the target cluster. The wizard opens on its first step, Service.
-
Choose the service. On the Service step, select Kamailio SIP edge. The card shows the licence GPL-2.0-or-later and the dependencies the installation needs.
-
Choose the hosts and the mode. On the Hosts step, tick the hosts, then choose the Mode: single (default), ha. Each mode deploys the components listed in Installation methods and modes.
-
Bind the dependencies. On the Bindings step, choose for each dependency (asterisk, livekit_sip, rtpengine) Install with the platform or Use an existing connection; an optional dependency can stay on No binding.
-
Configure. On the Configure step, review the parameters (see Configuration parameters). Passwords left empty with a generated default are generated and sealed by the Manager.
-
Review and install. On the Install step the Manager validates the plan and shows the installation order; when it says "The plan is valid. Ready to install.", choose Install. A highly available mode is installed only when its HA checks pass.
-
Verify. The operation ends when the health checks of every instance pass (see Health checks); the service then shows as running in Services.
High availability
Prerequisites
| Prerequisite | Must be highly available | Modes | Description |
|---|
asterisk | yes | ha | A pool of two Asterisk nodes or more, so the dispatcher has a next active node for every tenant. |
Topology per mode
| Modes | Highest catalog level | Distribution | Quorum component | Fault domains | Description |
|---|
single | standalone (standalone) | single (single) | - | 1 | One SIP edge: its loss stops every call and registration. |
ha | ha (ha) | active-active (active-active) | - | 2 | Active instances with the same hash tables (DMQ); the carriers and phones use another address when one is lost. |
Notes
- Entry redundancy is outside Kamailio: DNS SRV records naming every instance, several signalling addresses declared at the carrier, or a network load balancer for SIP. A virtual IP is not universal (it needs a shared L2 segment or a cloud mechanism) and is not configured here.
- DMQ replicates the hash tables and the dialog profiles (call counters per tenant), not the transactions nor the TCP, TLS and WebSocket connections: the dialogs routed by a lost instance fail on their next request (Record-Route names it), phones and softphones register again on another instance.
- A restarted instance gets the tables of a running peer at start (dmq_init_sync); a whole restart empties them until Navin Enterprise reconciles (core.uptime).
Configuration parameters
Network
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
SIP port (sip_port) | port | 5060 | - | no | no | yes | SIP over UDP and TCP for the carriers and the phones (public). |
SIP TLS port (tls_port) | port | 5061 | - | no | no | yes | SIP over TLS (public), bound while TLS is on. |
WSS port (wss_port) | port | 7443 | - | no | no | yes | SIP over secure WebSocket for the WebRTC softphones of the portal (public), bound while TLS is on. |
JSONRPC port (admin_port) | port | 5071 | - | no | no | yes | JSONRPC at /RPC (HTTPS while TLS is on) on the admin address. The host firewall opens it to the hosts of the cluster only and Kamailio answers 403 to any source outside the admin networks. |
Metrics port (metrics_port) | port | 5073 | - | no | no | yes | Prometheus metrics at /metrics (xhttp_prom) on the admin address, apart from JSONRPC. |
DMQ port (dmq_port) | port | 5062 | - | no | no | yes | Replication between the instances (KDMQ over TCP), opened to the hosts of the cluster only; Kamailio refuses a KDMQ request that does not come from a DMQ node. (ha) |
SIP address (listen_address) | string | (empty) | - | no | no | yes | Address the SIP, TLS and WSS listeners bind to; empty: the address of the host. (scope host) |
Advertised address (advertised_address) | string | (empty) | - | no | no | yes | Public address or name written in Via and Record-Route when the host is behind a 1:1 NAT; empty: none. (scope host) |
Admin address (admin_address) | string | (empty) | - | no | no | yes | Address of the JSONRPC and metrics listeners; empty: the address of the host. (scope host) |
Security
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
Admin networks (admin_networks) | list | [] | - | no | no | no | CIDR networks allowed on JSONRPC besides the host itself, for example the addresses of the Navin Enterprise nodes (10.0.0.21/32); any other source gets 403. |
Metrics networks (metrics_networks) | list | [] | - | no | no | no | CIDR networks allowed on /metrics besides the host itself; empty: every source the host firewall lets in (the hosts of the cluster). |
TLS (tls_enabled) | bool | true | - | no | no | yes | SIP over TLS, WSS for the softphones and HTTPS on JSONRPC and the metrics, with the certificate issued by the Manager CA (key 0640 root and the kamailio group). Off: SIP over UDP and TCP and plain HTTP only, no softphone. |
Public certificate (tls_public_cert_file) | string | (empty) | - | no | no | no | Path of a certificate trusted by the browsers and the carriers (full chain, PEM) used instead of the Manager certificate; empty: the Manager certificate. (advanced) |
Public certificate key (tls_public_key_file) | string | (empty) | - | no | no | no | Path of the key of the public certificate, readable by the kamailio group. (advanced) |
Carrier CAs (tls_client_ca_file) | string | /etc/ssl/certs/ca-certificates.crt | - | no | no | no | CA bundle verifying the carriers reached over SIP TLS. (advanced) |
Softphone secret (ephemeral_secret) | password | generated | - | no | yes | yes | Shared secret of auth_ephemeral, generated and kept in the Manager vault; Navin Enterprise reads it from the vault and gives the browser the user <expiry>:<extension> and the password base64(HMAC(secret, user)). |
Softphone HMAC (ephemeral_algorithm) | enum | sha256 | sha1, sha256, sha384, sha512 | no | no | yes | Hash of the HMAC of the ephemeral credentials (auth_ephemeral sha_algorithm). |
Softphone credential lifetime (ephemeral_max_ttl_s) | int | 3600 | min 60, max 86400 | no | no | no | Longest validity accepted for ephemeral credentials, in seconds; an expiry further ahead is refused with 403. |
Nonce secret (auth_nonce_secret) | password | generated | - | no | yes | yes | Secret of the digest nonces (auth secret), shared by the instances so a challenge of one is valid on the others. |
Failures before ban (ban_failures) | int | 10 | min 2, max 1000 | no | no | no | Refused authentications (401 or 407 with credentials, 403) of an external address before it is banned (table ipban). |
Ban duration (ban_time_s) | int | 900 | min 60, max 604800 | no | no | no | Seconds an address stays in ipban after its last failure. |
Flood threshold (pike_density) | int | 30 | min 5, max 10000 | no | no | no | Requests of one external address per 2 seconds before pike bans it (carriers and internal nodes are exempt). |
Scanner user agents (scanner_user_agents) | list | ["friendly-scanner", "sipvicious", "sipcli", "sip-scan", "VaxSIPUserAgent", "pplsip", "sundayddr", "iWar", "SIVuS", "smap"] | - | no | no | no | User-Agent fragments of known SIP scanners: their requests are dropped without answer and the source is banned. |
Routing
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
Internal transport (internal_transport) | enum | udp | udp, tcp | no | no | yes | Transport towards the Asterisk and LiveKit SIP nodes of the dispatcher. |
Dedicated pools (dedicated_sets) | json | [] | - | no | no | no | Dispatcher sets of the dedicated pools: a list of {set (100 or more), destinations [host:port]}; Navin Enterprise routes a dedicated tenant to its set in tenant_domains and did_routes. |
Probe interval (probe_interval_s) | int | 10 | min 2, max 300 | no | no | no | Seconds between two SIP OPTIONS probes of each destination. |
Failed probes (probe_failures) | int | 3 | min 1, max 20 | no | no | no | Failed probes before a destination is marked down. |
Successful probes (probe_successes) | int | 2 | min 1, max 20 | no | no | no | Successful probes before a destination is active again. |
Destinations tried (dispatcher_attempts) | int | 3 | min 1, max 10 | no | no | no | Destinations of the set tried for one call (the tenant node first, then the next active ones on 408, 500 or 503). |
Limits
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
Default concurrent calls (default_max_calls) | int | 0 | min 0 | no | no | no | Concurrent calls of a tenant absent from tenant_limits; 0: no limit. |
Default calls per second (default_cps) | int | 0 | min 0 | no | no | no | Calls per second of a tenant absent from tenant_limits; 0: no limit. |
Dialog lifetime (max_call_duration_s) | int | 14400 | min 60, max 86400 | no | no | no | Seconds after which a dialog without BYE leaves the call counters. |
Tuning
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
Workers (workers) | int | 8 | min 1, max 64 | no | no | yes | SIP worker processes per UDP listener and for TCP. (recommended max(4, min(32, host.cpu_count * 2))) |
Maximum connections (max_connections) | int | 4096 | min 64, max 200000 | no | no | yes | TCP, TLS and WebSocket connections at most. |
Shared memory (MB) (shm_mb) | int | 256 | min 64, max 16384 | no | no | yes | Shared memory of Kamailio (transactions, dialogs, hash tables). |
Private memory (MB) (pkg_mb) | int | 16 | min 8, max 512 | no | no | yes | Private memory of each Kamailio process. |
Log level (log_level) | int | 2 | min -3, max 3 | no | no | no | Kamailio debug level: -3 alert to 3 debug, 2 info. |
Dependencies
For each active dependency the Manager takes the first of: the binding chosen in the wizard; a service of the same installation that provides it; a service already installed in the cluster; the only connection of the expected type. Otherwise an optional dependency stays unbound, and a required one is added to the installation in its default mode (the column below names the catalog service added).
| Binding | Provided by | Connection type | Endpoint | Optional | When nothing is bound | Description |
|---|
asterisk | asterisk | - | sip | no | asterisk is added to the installation | Shared Asterisk pool: every node is a destination of the dispatcher set 1, probed by SIP OPTIONS. |
livekit_sip | livekit-sip | - | sip | yes | stays unbound (optional) | LiveKit SIP gateway: its nodes form the dispatcher set 2, the target of the numbers routed to the ai branch. |
rtpengine | rtpengine | - | ng | yes | stays unbound (optional) | Optional media relay: with it, Kamailio anchors the RTP of the calls that are not WebRTC (rtpengine_manage). |
Endpoints
| Endpoint | Scheme | Component | Port | Path | TLS parameter | Binding parameters | Binding secrets | Provisioning command |
|---|
sip | sip | kamailio | 5060 (sip_port) | - | - | transports, ephemeral_algorithm | ephemeral_secret | - |
sips | sips | kamailio | 5061 (tls_port) | - | tls_enabled | - | - | - |
wss | wss | kamailio | 7443 (wss_port) | - | tls_enabled | - | - | - |
Commands
| Command | Component | Target | Description |
|---|
Dispatcher destinations (dispatcher_list) | kamailio | every host | Lists the sets, destinations and states of the dispatcher (A active, I inactive, D disabled, P probed). |
Drain a destination (dispatcher_state) | kamailio | every host | Sets the state of a destination on every instance: d drains it (disabled: no new call and no probe, the dialogs in progress end normally), a puts it back. A dispatcher reload or a restart brings every destination back. |
Reload the dispatcher (dispatcher_reload) | kamailio | every host | Reloads dispatcher.list without restarting Kamailio. |
Dump a hash table (htable_dump) | kamailio | first host | Prints the entries of one routing table (read only). |
Uptime (uptime) | kamailio | every host | core.uptime of every instance: a restart empties the hash tables until Navin Enterprise reconciles them. |
Validate the configuration (validate) | kamailio | every host | Runs kamailio -c on the rendered configuration. |
Command parameters
| Command | Parameter | Type | Default | Required | Description |
|---|
dispatcher_state | Set (set) | int | - | yes | Dispatcher set (1 Asterisk, 2 LiveKit SIP, 100 or more dedicated). |
dispatcher_state | Destination (destination) | string | - | yes | URI as listed, for example sip:pbx1.example.internal:5070. |
dispatcher_state | State (state) | enum | d | no | d drains, a puts back. |
htable_dump | Table (table) | enum | did_routes | no | Hash table to print. |
Health checks
Liveness (per instance)
| Component | Check | Details |
|---|
kamailio | TCP {{ config.listen_address or host.ip or '127.0.0.1' }}:{{ config.sip_port }} | 20 retries; interval 1 s; timeout 3 s |
kamailio | HTTP {{ ('https://' ~ host.fqdn) if config.tls_enabled else ('http://' ~ (config.admin_address or host.ip or '127.0.0.1')) }}:{{ config.metrics_port }}/metrics | Expected 200; Expected kamailio_; 20 retries; interval 1 s; timeout 3 s |
Readiness (service check)
| Check | Details |
|---|
/usr/sbin/kamcmd -s unix:{{ paths.data }}/kamailio_ctl dispatcher.list | Expected SET; 10 retries; interval 3 s; timeout 10 s |
Preflight checks
| Check | Type | Meaning | Severity | Components |
|---|
sip_port_free | port_free {"param": "sip_port"} | port 5060 free on the host | blocking | every component |
admin_port_free | port_free {"param": "admin_port"} | port 5071 free on the host | blocking | every component |
Backup and restore
JSON export of the routing tables (tenant_domains, did_routes, trunk_hosts, tenant_limits) of the first instance through JSONRPC; the restore writes them back with htable.sets and htable.seti. Navin Enterprise stays the source of truth and reconciles them anyway; the transient ipban table is not kept.
| |
|---|
| Format | kamailio-htables |
| Component | kamailio |
| Files | {{ backup.dir }}/htables.json |
| Restore test | yes |
| Instances stopped for the restore | yes |
Uninstall
Paths removed when the data is purged: {{ paths.data }}, {{ paths.log }}.
Upstream documentation