Run it safely / Scaling & capacityAll pages
Run it safely

Scaling & capacity

How far one server goes (measured), what uses up its capacity, and how to grow: more Asterisk instances, kernel media forwarding, a separate database, more servers.

Measured
60 calls on 2 vCPU
Per active call
≈0.35% of one core
Asterisk per server
1 to 4 instances
Failover
≈3 s, automatic

How the system scales

Kamailio is the only address phones and carriers ever see. Behind it, a pool of identical Asterisk instances does the actual phone work. All instances read the same MariaDB database (users, registrations, voicemail, IVR menus, queues), so any instance can take any call, and you add capacity by adding instances to the pool. Phones and carriers never notice.

Asterisk pool (dispatcher set 1)SIPdispatcherNGrealtimePhonesBrowsers · carriersrtpengineAll audioKamailioDispatcherAsterisk 1127.0.0.1:5080Asterisk 2127.0.0.1:5081Asterisk 3–4:5082 · :5083Extra node10.0.0.5:5080MariaDBShared by allAI agentAudioSocket
The Asterisk pool. Instances 1–4 run on this server; extra nodes are Asterisk servers elsewhere on your private network.
ComponentRoleHow it scales
KamailioSIP edge for phones, browsers and carriers: security, NAT, routing. Holds no call state of its own.Very light (≈1% of a core at 60 calls). One edge serves many Asterisk servers.
rtpengineRelays and, for browsers, converts audio (WebRTC ⇄ phone codecs).Userspace by default; enable kernel forwarding for far less CPU per call.
Asterisk poolCalls, IVRs, queues, voicemail, recording. All instances read the same database, so any instance can take any call.Add instances (per server or more servers) to the dispatcher set; calls spread by Call-ID, an instance that fails is skipped automatically.
MariaDBUsers, registrations, routing, IVR flows, queues, call records, dashboard data.Move to its own server or a managed database; add a replica for reporting.
AI agentTalks to callers through AudioSocket; uses the organization's speech / LLM provider.Raise AVR_MAX_CALLS or run more agent processes; most of its work is waiting on providers.
DashboardWeb app plus a background worker.Run several processes behind the web server. One process (database lock) detects events and sends webhooks; every process works the job queue (SELECT … FOR UPDATE SKIP LOCKED), so transcription and analysis spread across them.

Measured capacity

Load test on an AWS c6a.large (2 vCPU, 4 GB RAM), two Asterisk instances, rtpengine in userspace (kernel forwarding off), call recording on.

Concurrent callsResultAsteriskrtpengineKamailioCall path total
60 (G.711, two-way audio)60 of 60 passed12.6% of one core7.0%1.4%≈21% of one core
  • ≈0.35% of one CPU core per active call for the whole call path; memory steady at about 1.2 GB used.
  • Method: scripts/selftest.py echo calls (each sends tone audio and checks it comes back), started from the server itself 0.6 s apart, measured with pidstat every 5 s. The test callers' own CPU is excluded.
  • Kamailio's flood protection works per source address: one address that opens dozens of calls per second is banned. Real traffic comes from many phones and carriers; load tests must ramp up slowly.

What uses up a server

Four things decide how many calls one server carries. Look at your own call mix against each before you pick a size.

FactorWhy it mattersWhat helps
Media relayEvery audio packet of every call passes through rtpengine. In userspace that is CPU work per packet, and it grows with the number of calls.Kernel forwarding: ENABLE_KERNEL_RTP="yes".
TranscodingA browser leg speaks Opus; Asterisk only speaks G.711. rtpengine converts between them, which costs far more CPU than relaying.Fewer browser legs, or more CPU. Measure your own mix.
Asterisk channelsEach instance has its own audio port range (400 ports, about 200 channels). IVR, queue music, voicemail and recording all run in Asterisk.More instances: ASTERISK_INSTANCES up to 4, then more servers.
DiskRecording writes three WAV files per recorded call, continuously, while the call lasts.A fast disk with room to grow; see Recordings and storage.

Limits in the default configuration

LimitDefaultRaise it by
Audio ports per Asterisk instance400 ports ≈ 200 channelsMore instances (ASTERISK_INSTANCES, up to 4 per server) or more servers
Calls per server (2 instances)≈ 400 channels: ≈200 calls between two parties (two channels each), or ≈400 one-channel calls (IVR, voicemail, waiting in queue, AI agent)Same as above
AI agent conversations50 at once per agent process (AVR_MAX_CALLS)Raise the setting, add agent processes; check provider rate limits
rtpengine ports30000–40000 (≈2,500 call legs)Widen RTP_PORT_MIN / RTP_PORT_MAX (and the firewall)
Kamailio workerschildren=8, tcp_children=8; 256 MB shared memoryRaise children in kamailio.cfg and SHM_MEMORY in /etc/default/kamailio
Outbound calls per extension20 per minute (OUTBOUND_MAX_PER_MIN)A fraud guard, not a capacity limit; raise it for auto-diallers
Bandwidth≈87 kbit/s per direction per G.711 leg (≈20 Mbit/s each way for 100 calls with two legs)Network sizing

Several Asterisk instances

One server can run 1 to 4 Asterisk instances. They are identical: the same dialplan, the same PJSIP configuration, the same number map and the same database. Running more than one spreads the work over more CPU cores and gives you failover on a single server.

config.env, then re-run from step 40Shell
ASTERISK_INSTANCES=3sudo ./install.sh --from 40
Instancesystemd unitConfig folderSIP (loopback)Asterisk RTP ports
1asterisk/etc/asterisk508010000–10399
2voip-asterisk@2/etc/asterisk-2508110400–10799
3voip-asterisk@3/etc/asterisk-3508210800–11199
4voip-asterisk@4/etc/asterisk-4508311200–11599
  • Kamailio's dispatcher table (set 1) is filled automatically; you do not edit it by hand.
  • Each instance has its own run, spool and log folders; logs are in /var/log/asterisk*/messages.log.
  • Lowering ASTERISK_INSTANCES and re-running stops and disables the instances above the new number. Their calls end, so do it outside busy hours.
  • Users added with the dashboard or scripts/add-user.sh are live on every instance immediately. Voicemail is stored in the database, so any instance plays any message.

How calls are spread

RequestDispatcher ruleWhy
REGISTERHash of the user (To URI)A user always registers on the same instance, so the sign-in challenge it issued stays valid.
INVITEHash of the Call-IDCalls spread evenly; the retried INVITE that answers a challenge has the same Call-ID, so it reaches the instance that sent the challenge.

Registrations are shared: a phone that registered on instance 1 can be rung by instance 3, because every contact is stored in the database with the Path back through Kamailio.

What happens when an instance fails

Kamailio sends a SIP OPTIONS probe to every instance every 10 seconds. Two missed probes in a row mark it inactive. A call that is sent to an instance that does not answer is retried on the next one, so callers wait a moment instead of failing. In testing, killing one of two instances moved new calls over within about 3 seconds, and the instance rejoined by itself when it was restarted.

CallerCallerKamailioKamailioAsterisk 2Asterisk 2Asterisk 1Asterisk 1OPTIONS (probe)every 10 s1401 / 200: alive2Asterisk 2 stopsINVITECall-ID hashes to instance 24INVITEno answer5INVITE (next destination)6180 / 200 OK72 missed probes: instance 2 marked inactive
An instance stops. The call that was meant for it is retried on the next instance; probing then takes it out of the pool.
Watch the poolShell
sudo kamcmd dispatcher.list      # FLAGS: AP = active, IP = inactivesudo kamcmd dispatcher.reload    # re-read the table after a change

Asterisk on other servers

When four instances on one server are not enough, add Asterisk servers on your private network. Kamailio, rtpengine and the database stay where they are; the new nodes join the same dispatcher set.

config.env on the Kamailio serverShell
ASTERISK_EXTRA_NODES="10.0.0.5:5080 10.0.0.6:5080"   # ip:port of each extra AsteriskKAM_INT_IP="10.0.0.2"                                # Kamailio's private address the nodes can reach

What each extra node needs

Same templatesinstall
Install the same Asterisk templates on the node, with AST_BIND_IP set to its private IP.
Database accessnetwork
Its ODBC connection points at the shared MariaDB: MariaDB must listen on the private address (bind-address) and have a database user for the node's IP.
Reach Kamailionetwork
The node must reach Kamailio's SIP port and rtpengine's control (NG) port on KAM_INT_IP.
Audionetwork
rtpengine must reach the node's RTP ports.

Browser calls and transcoding

Asterisk only ever handles plain G.711 audio. Browsers speak WebRTC: encrypted audio (DTLS-SRTP), ICE, and usually the Opus codec. rtpengine handles that on each browser leg, so the cost depends on your mix:

CallWork for rtpengine
Desk phone or carrier ⇄ desk phone or carrierRelay only (plain RTP).
Browser ⇄ anythingEncryption on the browser leg, plus Opus ⇄ G.711 conversion when the browser cannot use G.711.
Browser ⇄ browserBoth legs are browser legs: twice the work of one.
Test a transcoded callShell
python3 scripts/webrtc_call.py --url wss://DOMAIN:4443 --domain DOMAIN \  --ext 1001 --pw PASS --ca /etc/voip-stack/tls/ca.crt --opus-only

Recordings and storage

With RECORD_CALLS="yes", every recorded call produces three WAV files in /var/spool/voip-recordings: the caller's side, the other side, and both mixed. Separate sides let a transcript tell who said what. Each organization's Admin decides which calls are recorded (all, inbound, outbound or none) under Organization settings.

Phone audio is 8 kHz, so a 16-bit mono WAV file is 16 KB per second. Three files make about 2.9 MB per recorded minute. This is an estimate from the file format; check it against your own server with du.

Recorded minutes per dayPer dayPer 30 daysPer year
1,000≈2.9 GB≈86 GB≈1.1 TB
5,000≈14 GB≈430 GB≈5.3 TB
20,000≈58 GB≈1.7 TB≈21 TB
  • RECORDING_DAYS (default 30) deletes files older than that every day; the dashboard's Data retention setting applies on top. Keep both in line with what you must keep.
  • The nightly backup archives the whole recordings folder again each night (it is not incremental) and keeps KEEP_DAYS copies (default 14). Size the backup disk for that, or lower KEEP_DAYS and copy each night's archive to object storage.
  • Put /var/spool/voip-recordings on its own disk for large sites, so a full recordings disk cannot stop the database.
Check usageShell
du -sh /var/spool/voip-recordings /var/backups/voip-stackdf -h /var/spool/voip-recordings

AI agent concurrency

Each AI agent process accepts up to AVR_MAX_CALLS conversations at once (default 50) and rejects new ones beyond that, writing max calls (…) reached to its log. Most of a conversation is spent waiting for the speech and language-model providers, so the agent itself uses little CPU; the practical limit is usually your providers' rate limits and latency.

/etc/voip-stack/avr.envConfig
AVR_MAX_CALLS=50

After a change, run sudo systemctl restart avr. A restart ends the AI conversations in progress. Check the log with tail -f /var/log/avr/avr.log.

Database

MariaDB holds everything the call engines and the dashboard share: users, registrations, routing, IVR flows, queues, call records and dashboard data. Registrations are written on every phone sign-in and refresh, and call records on every call, so the database sees steady small writes.

  • Each dashboard process keeps a pool of 5 database connections.
  • A cron job removes registrations every 5 minutes whose Asterisk stopped before it could expire them.
  • For larger sites, put the database on its own disk first, then on its own server or a managed MariaDB on the private network.
  • Whatever you choose, keep the nightly backup and test a restore (see Restore).

Sizing guide

DeploymentConcurrent callsSuggested setupBasis
Small (one branch, clinic)up to 601 server, 2 vCPU / 4 GB, 2 Asterisk instancesMeasured
Medium (bank contact centre)up to ≈2001 server, 4 vCPU / 8 GB, 4 Asterisk instances, rtpengine kernel forwarding, database on its own diskEstimated
Large (several sites, many agents)≈400+Edge server (Kamailio + rtpengine), 2+ Asterisk servers in the dispatcher set, separate database server with backups, 2+ dashboard processesEstimated

Estimates leave CPU headroom and assume mostly desk-phone and carrier calls. Run the same load test on your hardware before go-live.

Growing step by step

Take these in order; each one is cheaper than the next.

  1. More Asterisk instances on the same server

    Set ASTERISK_INSTANCES in config.env and run sudo ./install.sh --from 40. Each instance gets its own SIP port and audio range and joins the dispatcher automatically.
  2. Kernel media forwarding

    Set ENABLE_KERNEL_RTP="yes" and run sudo ./install.sh --from 20. rtpengine's kernel module (DKMS) then relays audio inside the Linux kernel instead of a userspace process. This module has not been tested in our own builds; check journalctl -u rtpengine-daemon after enabling it.
  3. Separate database

    Point every component at a dedicated or managed MariaDB on a private network; keep automated backups and test restores.
  4. More servers

    Add Asterisk servers (same configuration, same database) to Kamailio's dispatcher set with ASTERISK_EXTRA_NODES. Kamailio health-checks them and stops using one that fails.
  5. More dashboard processes

    Start additional dashboard processes (on other ports or servers, same database) and list them in the web server's upstream; the default install runs one. The background work needs no extra setup: one process becomes the leader through a database lock and all processes share the job queue (set JOB_CONCURRENCY per process, default 2).

Load testing your own server

Measure before go-live, on the hardware you will use. Start echo calls from several machines (Kamailio bans a single address that opens calls too fast), ramp up slowly, and record CPU per process:

One echo call, and per-process CPU while the test runsShell
python3 scripts/selftest.py echo --host DOMAIN --ext 1001 --pw PASSpidstat -u -C 'asterisk|rtpengine|kamailio' 5    # pidstat is in the sysstat package

Next steps