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.
| Component | Role | How it scales |
|---|---|---|
| Kamailio | SIP 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. |
| rtpengine | Relays and, for browsers, converts audio (WebRTC ⇄ phone codecs). | Userspace by default; enable kernel forwarding for far less CPU per call. |
| Asterisk pool | Calls, 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. |
| MariaDB | Users, registrations, routing, IVR flows, queues, call records, dashboard data. | Move to its own server or a managed database; add a replica for reporting. |
| AI agent | Talks 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. |
| Dashboard | Web 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 calls | Result | Asterisk | rtpengine | Kamailio | Call path total |
|---|---|---|---|---|---|
| 60 (G.711, two-way audio) | 60 of 60 passed | 12.6% of one core | 7.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.pyecho calls (each sends tone audio and checks it comes back), started from the server itself 0.6 s apart, measured withpidstatevery 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.
| Factor | Why it matters | What helps |
|---|---|---|
| Media relay | Every 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". |
| Transcoding | A 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 channels | Each 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. |
| Disk | Recording 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
| Limit | Default | Raise it by |
|---|---|---|
| Audio ports per Asterisk instance | 400 ports ≈ 200 channels | More 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 conversations | 50 at once per agent process (AVR_MAX_CALLS) | Raise the setting, add agent processes; check provider rate limits |
| rtpengine ports | 30000–40000 (≈2,500 call legs) | Widen RTP_PORT_MIN / RTP_PORT_MAX (and the firewall) |
| Kamailio workers | children=8, tcp_children=8; 256 MB shared memory | Raise children in kamailio.cfg and SHM_MEMORY in /etc/default/kamailio |
| Outbound calls per extension | 20 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.
ASTERISK_INSTANCES=3sudo ./install.sh --from 40| Instance | systemd unit | Config folder | SIP (loopback) | Asterisk RTP ports |
|---|---|---|---|---|
| 1 | asterisk | /etc/asterisk | 5080 | 10000–10399 |
| 2 | voip-asterisk@2 | /etc/asterisk-2 | 5081 | 10400–10799 |
| 3 | voip-asterisk@3 | /etc/asterisk-3 | 5082 | 10800–11199 |
| 4 | voip-asterisk@4 | /etc/asterisk-4 | 5083 | 11200–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_INSTANCESand 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.share live on every instance immediately. Voicemail is stored in the database, so any instance plays any message.
How calls are spread
| Request | Dispatcher rule | Why |
|---|---|---|
REGISTER | Hash of the user (To URI) | A user always registers on the same instance, so the sign-in challenge it issued stays valid. |
INVITE | Hash of the Call-ID | Calls 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.
sudo kamcmd dispatcher.list # FLAGS: AP = active, IP = inactivesudo kamcmd dispatcher.reload # re-read the table after a changeAsterisk 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.
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 reachWhat each extra node needs
Same templatesinstall- Install the same Asterisk templates on the node, with
AST_BIND_IPset 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:
| Call | Work for rtpengine |
|---|---|
| Desk phone or carrier ⇄ desk phone or carrier | Relay only (plain RTP). |
| Browser ⇄ anything | Encryption on the browser leg, plus Opus ⇄ G.711 conversion when the browser cannot use G.711. |
| Browser ⇄ browser | Both legs are browser legs: twice the work of one. |
python3 scripts/webrtc_call.py --url wss://DOMAIN:4443 --domain DOMAIN \ --ext 1001 --pw PASS --ca /etc/voip-stack/tls/ca.crt --opus-onlyRecordings 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 day | Per day | Per 30 days | Per 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_DAYScopies (default 14). Size the backup disk for that, or lowerKEEP_DAYSand copy each night's archive to object storage. - Put
/var/spool/voip-recordingson its own disk for large sites, so a full recordings disk cannot stop the database.
du -sh /var/spool/voip-recordings /var/backups/voip-stackdf -h /var/spool/voip-recordingsAI 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.
AVR_MAX_CALLS=50After 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
| Deployment | Concurrent calls | Suggested setup | Basis |
|---|---|---|---|
| Small (one branch, clinic) | up to 60 | 1 server, 2 vCPU / 4 GB, 2 Asterisk instances | Measured |
| Medium (bank contact centre) | up to ≈200 | 1 server, 4 vCPU / 8 GB, 4 Asterisk instances, rtpengine kernel forwarding, database on its own disk | Estimated |
| Large (several sites, many agents) | ≈400+ | Edge server (Kamailio + rtpengine), 2+ Asterisk servers in the dispatcher set, separate database server with backups, 2+ dashboard processes | Estimated |
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.
More Asterisk instances on the same server
SetASTERISK_INSTANCESinconfig.envand runsudo ./install.sh --from 40. Each instance gets its own SIP port and audio range and joins the dispatcher automatically.Kernel media forwarding
SetENABLE_KERNEL_RTP="yes"and runsudo ./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; checkjournalctl -u rtpengine-daemonafter enabling it.Separate database
Point every component at a dedicated or managed MariaDB on a private network; keep automated backups and test restores.More servers
Add Asterisk servers (same configuration, same database) to Kamailio's dispatcher set withASTERISK_EXTRA_NODES. Kamailio health-checks them and stops using one that fails.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 (setJOB_CONCURRENCYper 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:
python3 scripts/selftest.py echo --host DOMAIN --ext 1001 --pw PASSpidstat -u -C 'asterisk|rtpengine|kamailio' 5 # pidstat is in the sysstat package