Private branch exchange of the Navin telephony: PJSIP behind Kamailio, dialplan, queues, voicemail, ConfBridge, MixMonitor recordings, ARI, AMI, CDR and CEL events and Prometheus metrics. One node, or a pool of independent nodes behind the Kamailio dispatcher. The tenants, extensions, trunks, IVR and queues are delivered by Navin Enterprise through AMI, never by the Manager.
Generated from catalog/services/asterisk.yaml: do not edit by hand.
Summary
| |
|---|
| Version | 20.6.0 |
| 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-only WITH Asterisk-linking-protocols-exception |
| Licence policy | licence exception |
| Licence exception | LEX-024 (pending, awaiting the client) |
| Licence exceptions of its dependencies | LEX-027 (pending, awaiting the client), LEX-028 (pending, awaiting the client) |
| Licence note | GPL-2.0-only with the Asterisk linking and protocols exception (LICENSE of Asterisk 20.6.0: linking with OpenSSL allowed, AMI, AGI and ARI applications need not be GPL): a separate program used through its network interfaces (SIP, AMI, ARI); no Asterisk code is linked into Navin. The offline bundle redistributes the Ubuntu packages with their notices and sources. |
| Platform component | asterisk |
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.
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 Asterisk LTS package exists for RHEL: EPEL 8 and EPEL 9 ship Asterisk 18.26.4, whose upstream support ended on 2025-10-20, and EPEL 10 ships none. Place the PBX nodes on Ubuntu 24.04 (universe: Asterisk 20.6.0).
- Method
package on the Debian family (apt) limited to Ubuntu 24.04: Debian 12 and 13 ship no asterisk package and Ubuntu 22.04 ships 18.10, out of upstream support since 2025-10-20.
Units of the distribution masked by the method package: asterisk.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
- at least 1024 MB of memory (blocking,
memory).
- at least 5120 MB free for
/var/lib/navin (warning, disk).
- a synchronized clock (warning,
time_sync).
Network and ports
| Component | Port name | Port | Opened in the host firewall |
|---|
asterisk | sip_udp | 5070/udp | yes |
asterisk | sip_tcp | 5070/tcp | yes |
asterisk | sip_tls | 5072/tcp | yes |
asterisk | ari_http | 8088/tcp | yes |
asterisk | ari_http_local | 8088/tcp | no |
asterisk | ari_tls | 8089/tcp | yes |
asterisk | ami | 5038/tcp | yes |
asterisk | ami_local | 5038/tcp | no |
asterisk | ami_tls | 5039/tcp | yes |
asterisk | rtp | 10000-19999/udp | 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 |
|---|
Asterisk node (asterisk) | master | package | 5070/udp, 5070/tcp, 5072/tcp, 8088/tcp, 8088/tcp, 8089/tcp, 5038/tcp, 5038/tcp, 5039/tcp, 10000-19999/udp |
Single node (single) (default)
One Asterisk node.
What the mode deploys:
| Component | Placement |
|---|
asterisk | min 1, max 1 |
Pool behind Kamailio (pool)
Two or more independent Asterisk nodes, each one a destination of the Kamailio dispatcher; Navin Enterprise delivers the configuration of a tenant to every node of its pool.
What the mode deploys:
| Component | Placement |
|---|
asterisk | 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 Asterisk PBX. The card shows the licence GPL-2.0-only WITH Asterisk-linking-protocols-exception 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), pool. Each mode deploys the components listed in Installation methods and modes.
-
Bind the dependencies. On the Bindings step, choose for each dependency (cdr_db) 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
Topology per mode
| Modes | Highest catalog level | Distribution | Quorum component | Fault domains | Description |
|---|
single | standalone (standalone) | single (single) | - | 1 | One node: its loss stops every call until it is restored. |
pool | ha (ha) | active-active (active-active) | - | 2 | Independent nodes behind the Kamailio dispatcher: new calls go to the other nodes as soon as the OPTIONS probe of the dispatcher marks a node down; the active calls of a lost node are lost. |
Notes
- No call state is shared between the nodes of a pool: the active calls of a lost node are lost, only the new calls are routed to the other nodes.
- Navin Enterprise delivers the configuration of each tenant to every node of its pool through AMI (CreateConfig, UpdateConfig) and activates it with the reload commands. The *_navin.conf files are not files of the descriptor: prepare.sh creates them empty when absent at each start, so a configuration apply never writes them.
- Package: Ubuntu 24.04 universe, Asterisk 20.6.0. Asterisk 20 LTS is in security fix only support since 2026-10-19 and reaches its end of life on 2027-10-19 (docs.asterisk.org, Asterisk Versions): plan the move to Asterisk 22 LTS (end of life 2029-10-16) before. Security updates of universe packages come with Ubuntu Pro (ESM Apps). Debian 12 and 13 ship no Asterisk package; Ubuntu 22.04 ships Asterisk 18, out of support: the planner refuses these nodes (packages_releases) and the version pin makes apt refuse it.
- The Ubuntu package enables and starts asterisk.service with /etc/asterisk: the agent disables and masks it after installing the packages (distribution_units), and prepare.sh still refuses to start the node of the Manager while that unit runs.
- The HTTP server of Asterisk has no source filter: ARI and /metrics are protected by the private administration address (a public one is refused at start), the host firewall of the hardened installation, the ARI password and TLS; AMI also filters its sources (permit of admin_networks). /metrics needs no password.
- Modules not loaded (modules.conf): chan_sip and the other channel drivers except PJSIP, app_system and func_shell (shell from the dialplan), pbx_spool (call files), realtime and ODBC back ends, the other CDR and CEL back ends, res_http_post, phone provisioning, SNMP, HEP, STIR/SHAKEN.
Configuration parameters
Network
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
SIP port (sip_port) | port | 5070 | - | no | no | yes | SIP port (UDP and TCP) of the internal signalling network, reached from Kamailio only (ADR-0173). |
SIP TLS port (sip_tls_port) | port | 5072 | - | no | no | yes | SIP over TLS port, open only when TLS is on. |
SIP address (sip_address) | string | (empty) | - | no | no | yes | Address of the internal signalling network the SIP transports bind to; empty: the address of the host. |
Administration address (admin_address) | string | (empty) | - | no | no | yes | Address of the administration network AMI, ARI and /metrics listen on; empty: the address of the host. Never a public address. |
HTTP port (http_port) | port | 8088 | - | no | no | yes | HTTP port of ARI and /metrics on the administration address; on the loopback only when TLS is on. |
HTTPS port (https_port) | port | 8089 | - | no | no | yes | HTTPS port of ARI and /metrics on the administration address (TLS on). |
AMI port (ami_port) | port | 5038 | - | no | no | yes | Asterisk Manager Interface port on the administration address; on the loopback only when TLS is on. |
AMI TLS port (ami_tls_port) | port | 5039 | - | no | no | yes | AMI over TLS port on the administration address (TLS on). |
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
First RTP port (rtp_start) | int | 10000 | min 1024, max 19000 | no | no | yes | First UDP port of the RTP, SRTP and DTLS-SRTP range; the range ends at 19999 (ADR-0173). |
External media address (external_media_address) | string | (empty) | - | no | no | no | Public address announced in SDP when the host is behind a NAT (external_media_address of the transports); empty: none. (advanced) |
STUN server (stun_server) | string | (empty) | - | no | no | no | STUN server (host:port) used to gather the ICE candidates of WebRTC calls; empty: host candidates only. (advanced) |
Security
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
SIP source networks (sip_networks) | list | ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"] | - | no | no | no | Networks allowed to send SIP to Asterisk (PJSIP acl): the Kamailio and LiveKit SIP hosts. Every other source is refused. |
Administration source networks (admin_networks) | list | ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"] | - | no | no | no | Networks allowed to log in to AMI (permit of manager.conf, the loopback is always allowed). |
TLS (tls_enabled) | bool | false | - | no | no | yes | Serve SIP over TLS, ARI and /metrics over HTTPS and AMI over TLS with the certificate of the Manager CA; the plain HTTP and AMI listeners then stay on the loopback of the host. SRTP (res_srtp) is always available. |
ARI user (ari_username) | string | navin | ^[a-z][a-z0-9_-]{2,31}$ | no | no | no | ARI user of Navin Enterprise (ari.conf). |
ARI password (ari_password) | password | generated | - | no | yes | no | Password of the ARI user, generated, never shown. |
AMI user (ami_username) | string | navin | ^[a-z][a-z0-9_-]{2,31}$ | no | no | no | AMI user of Navin Enterprise (manager.conf), classes config, command, system, call, reporting, originate, agent and dialplan. |
AMI secret (ami_secret) | password | generated | - | no | yes | no | Secret of the AMI user, generated, never shown. |
Call records
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
CDR and CEL in PostgreSQL (cdr_database) | bool | false | - | no | no | yes | Also write every CDR and CEL record into the PostgreSQL database of the binding cdr_db (cdr_pgsql, cel_pgsql), a durable copy owned by the infrastructure. The AMI events (cdr_manager, cel_manager) stay on. |
Tuning
| Parameter | Type | Default | Allowed values | Required | Secret | Restart | Description |
|---|
Maximum calls (max_calls) | int | 0 | min 0, max 100000 | no | no | no | Maximum number of simultaneous channels of the node (maxcalls), 0 for no limit; the quotas per tenant are applied by Kamailio and Navin Enterprise. |
Tone country (tone_country) | enum | fr | fr, be, ch, de, uk, us | no | no | no | Call progress tones played by default (indications.conf). |
Default language (default_language) | string | en | ^[a-z]{2}(_[A-Z]{2})?$ | no | no | no | Language of the prompts when a channel sets none (the English core sounds are installed). |
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 |
|---|
cdr_db | postgresql | postgresql | sql | yes | stays unbound (optional) | Optional PostgreSQL database receiving a durable copy of the CDR and CEL records (cdr_pgsql, cel_pgsql) when cdr_database is on. |
Endpoints
| Endpoint | Scheme | Component | Port | Path | TLS parameter | Binding parameters | Binding secrets | Provisioning command |
|---|
ari | http | asterisk | 8088 (http_port) | /ari | - | username | password | - |
ari_tls | https | asterisk | 8089 (https_port) | /ari | tls_enabled | username | password | - |
ami | ami | asterisk | 5038 (ami_port) | - | - | username | secret | - |
ami_tls | ami+tls | asterisk | 5039 (ami_tls_port) | - | tls_enabled | username | secret | - |
sip | sip | asterisk | 5070 (sip_port) | - | - | transports | - | - |
sip_tls | sips | asterisk | 5072 (sip_tls_port) | - | tls_enabled | transports | - | - |
Commands
| Command | Component | Target | Description |
|---|
Node status (status) | asterisk | every host | Version, uptime, active channels and calls of every node. |
PJSIP contacts (pjsip_contacts) | asterisk | every host | Registered contacts and their qualify state on every node. |
PJSIP endpoints (pjsip_endpoints) | asterisk | every host | Endpoints loaded on every node (delivered by Navin Enterprise). |
Active channels (channels) | asterisk | chosen host | Active channels of one node. |
Reload the configuration (reload) | asterisk | every host | Reloads the configuration of every node without cutting the calls (core reload). |
Graceful restart (graceful_restart) | asterisk | chosen host | Restarts one node once its last call has ended, refusing new calls meanwhile (core restart gracefully). Drain the node in the Kamailio dispatcher first. (asks for confirmation) |
Health checks
Liveness (per instance)
| Component | Check | Details |
|---|
asterisk | TCP {{ config.sip_address or host.ip or '127.0.0.1' }}:{{ config.sip_port }} | 60 retries; interval 2 s; timeout 3 s |
asterisk | HTTP http://{{ config.admin_address or host.ip or '127.0.0.1' }}:{{ config.http_port }}/metrics | Expected 200; Expected asterisk_core_uptime_seconds; 30 retries; interval 2 s; timeout 5 s |
asterisk | HTTP https://{{ host.fqdn }}:{{ config.https_port }}/metrics | Expected 200; Expected asterisk_core_uptime_seconds; 30 retries; interval 2 s; timeout 5 s |
Readiness (service check)
| Check | Details |
|---|
{{ paths.etc }}/check.sh | 10 retries; interval 3 s; timeout 60 s |
Preflight checks
| Check | Type | Meaning | Severity | Components |
|---|
memory | memory_mb {"min": 1024} | at least 1024 MB of memory | blocking | every component |
disk | disk_free_mb {"path": "/var/lib/navin", "min": 5120} | at least 5120 MB free for /var/lib/navin | warning | every component |
sip_port_free | port_free {"param": "sip_port"} | port 5070 free on the host | blocking | every component |
ami_port_free | port_free {"param": "ami_port"} | port 5038 free on the host | blocking | every component |
http_port_free | port_free {"param": "http_port"} | port 8088 free on the host | blocking | every component |
time_sync | time_sync {} | a synchronized clock | warning | every component |
Backup and restore
Archive of the configuration directory (system files and the *_navin.conf files of Navin Enterprise), the astdb database, the keys and the voicemail spool of the first node. The recordings are not kept: Navin Enterprise moves them to SeaweedFS.
| |
|---|
| Format | asterisk-files |
| Component | asterisk |
| Files | {{ backup.dir }}/asterisk.tar.gz |
| Restore test | yes |
| Instances stopped for the restore | yes |
Uninstall
Paths removed when the data is purged: {{ paths.data }}, {{ paths.log }}.
Upstream documentation