AiPBX Documentation
Administrator documentation for AiPBX on 64-bit Linux (Ubuntu 26.04 LTS+, Debian 13+, Raspberry Pi OS 64-bit, and Armbian on x86_64 & ARM64). Start with the installation guide, then use the pages below while configuring the system.
🖥️ Live demo: aipbx.bid/demo shows every page of the portal with made-up data, without installing anything.
💡 Quick Diagnosis: When something does not work, start with the 🗺️ system map (where everything is) and 🛠️ troubleshooting (symptom → fix).
🚀 Getting started
| Page | What it covers |
|---|---|
| 🚀 Installation & updating | Requirements, one-line installer, certificates, ports, aipbx-update |
| 📦 Incus or LXD container | Running the normal install in a system container, networking, snapshots |
| 📺 Video: Installation | Step-by-step setup on YouTube: English · Türkçe · Deutsch |
| 📺 Video: Menu tour | Every screen of the portal on YouTube: English · Türkçe · Deutsch |
| 🖥️ Portal basics | The Apply workflow, edit dialogs, ordering lists, copying records |
| 💾 Backups, recovery & rollback | Reproducible daily backups (aipbx-backup), disaster recovery restore commands, and zero-downtime automated upgrade rollback (aipbx-update) |
| 🛠️ CLI & Server commands | Terminal utilities (aipbx-update, aipbx-backup, aipbx-restore, aipbx-selftest, aipbx-cert, SSO recovery) |
| 🏗️ Architecture | Components, traffic flow, security model |
📞 Telephony
| Page | What it covers |
|---|---|
| 🌐 Trunks | Connection modes, inbound DID trimming, transit routing, outbound caller ID normalization, copy / rename / order |
| 🚫 Blacklist & Spam blocker | Inbound spam blocking, AstDB sub-microsecond lookup, wildcards/patterns, drop/busy/congestion/announcement actions |
| 📤 Outbound routes | Dial patterns, number manipulation, trunk failover, route groups, RFC 6442 / RFC 6443 Geolocation emergency headers |
| 🎛️ Outbound and inbound call normalization | Rules for dialled numbers per device (mobile, desk, web), rules for incoming numbers per trunk, ready-made rules per country, E.164, SIP headers |
| 📥 Inbound routes (DIDs) | DID matching, destinations, fax DIDs |
| ⚙️ PBX Settings | Every tab of System → PBX Settings and where each is explained |
| 📟 Extensions | The extension form, copying a SIP password, per-extension SIP settings (transport, DTMF, SRTP, NAT, codecs) |
| 🛣️ Transports | Where Asterisk listens for SIP: ports, TCP and TLS, your own transports |
| 🎛️ Advanced Configuration | Your own Asterisk options, objects and file text that survive regeneration and updates, versions, generated files changed by hand |
| 📠 Fax users and numbers | Fax Units, the number a fax goes out with, several and shared numbers, Fax Settings, who can delete |
| 📠 Fax cover page | One cover template for the organisation, logo, preview as a fax |
| 🔢 How numbers change on a call | The order of every number setting on routes, trunks and normalization pages, with a diagram |
| 💻 Custom Dialplan | Custom Asterisk context injection, syntax validator, internal aggregator, recipe templates (Intercom, Spy, Paging, DISA) |
| ☎️ Desk phones | Provisioning Yealink, Grandstream, Fanvil, Snom, Cisco SPA and Poly phones over HTTPS, CSV import, waiting phones, phones found on the network, key layouts (BLF, speed dial, park), re-provision, regions, SIP over TLS on port 443 |
| 📒 Phonebook | Shared company contacts, LDAP phonebook for desk phones (name search, caller name), contacts from Active Directory / OpenLDAP with the ldap-sync plugin |
| 🔵 Cisco 7900 / 8800 series | Cisco's enterprise phones (CallManager firmware): the SEP<MAC>.cnf.xml AiPBX writes, the firmware, the usecallmanager.nz Asterisk patch and the shared files you provide |
| 🖧 Network settings | The server's network cards, and moving every address after an IP change in one step |
| 🔐 VPN server and client | WireGuard or OpenVPN: let phones and laptops reach the PBX through a tunnel (including Yealink OpenVPN .tar packages with vpn.cnf + keys), and connect the PBX to another network by uploading a profile |
| 🛡️ Reverse proxy setup | Deploying behind Nginx, Caddy, Traefik, HAProxy, Apache; WebRTC WebSocket proxying, trusted proxies, and SIP/RTP bypass |
| 📡 Network services | DHCP (option 66/150/160) TFTP and read-only FTP for desk phones on a phone network or VLAN, leases, the options for your own DHCP server, an NTP server and phone logs (syslog) by IP or MAC |
| 🩺 Health checks | The server watches itself (services, trunks, disk, certificate, backup …), alarm e-mails, the daily summary with yesterday's calls, aipbx-selftest |
| 🎙️ Call recordings | Where recordings live, automatic MP3 conversion, playback |
| 🎧 Queues and the agent screen | Queue setup, static and dynamic agents, breaks, waiting calls and manual callbacks |
| ☎️ Manual queue callbacks | Press 1 while waiting, confirmation announcement, agent callback list, automatic removal after a conversation, troubleshooting |
| 📊 Reports | Call reports with trunks and direction, Queue Report Centre, PDF and Excel export |
| 🔊 Sounds & languages | Custom sounds, the Turkish prompt packages (six formats), regenerating a prompt |
| 🌍 Translating | Interface languages, adding or correcting a translation with scripts/i18n.py, mobile app texts, prompts in other languages |
| 📹 Video calls | Video between the web phone, the Android app and desk video phones; the one video codec; bandwidth |
| 🗓️ Video meetings | Scheduled browser rooms, SFU/Follow-Talker, guest links, invitations, join windows and calendar downloads |
| 🎧 WebRTC, NAT and TURN | Browser and app audio across NAT, external IP, TURNS on 443, troubleshooting silent calls |
| 🗄️ External databases & IVR data steps | Read-only MySQL/PostgreSQL connections, encrypted credentials, real-time IVR caller/DTMF data lookups and call branching |
| 🎚️ PBX fine tuning & maintenance | Jitter buffer, SIP protocol timers (T1, B, Max-Forwards), 10-minute SIP debug, safe night restart window, spoken status messages |
| 🐧 Linux OS & kernel tuning | Network sysctl (RTP buffers, MPTCP disable), SIP ALG blacklist, real-time CPU scheduling, OOM protection, needrestart shielding |
🔐 Users and security
| Page | What it covers |
|---|---|
| 👥 Users & roles | Adding users and invitations, the admin account, built-in roles, permissions, My Phone |
| 🛡️ Security | Firewall (common and per-card rules), the Sign-in page (Security → Sign-in: sign-in check, sign-in alerts, SSO-only), fail2ban, the aipbx-priv root helper, Apache sandbox |
| 🔒 Privileged job state | Root-owned status, network rollback data and validated upload snapshots |
| 📜 Privileged job logs | Root log ownership, portal read access and rotation |
| 🖧 Network ports & firewall | Complete matrix of all TCP/UDP ports, public vs LAN scopes, NAT guidelines, UFW/firewalld/iptables recipes |
| 🛡️ Threat model & attack surface | Security architecture, SIP exposure boundaries, WebRTC/TURNS credentials, recording retention, mobile push tokens, and AI least privilege guardrails |
| ⚖️ GDPR, KVKK & data privacy | Optional regulatory presets (KVKK, GDPR, CCPA/FCC, HIPAA, PCI-DSS, LGPD), pre-call opt-in/opt-out, periodic beep, retention purge, SAR export, Right to Erasure, and Cloud AI lock |
| 📜 Certificates | One certificate for portal, TURNS and SIP-TLS; Let's Encrypt, upload, renewals |
| 💡 Busy lamps (BLF) | Desk phone keys for colleagues, do-not-disturb, forwarding and queue login; pickup; voicemail lamp |
| Mail relay and e-mail templates (fax, voicemail, invitations, password e-mails) | |
| 🗄️ File storage | Chat attachments on the local disk or in an S3-compatible bucket (AWS S3, MinIO, Wasabi, Backblaze B2), moving existing files |
| 🔑 REST API v1 & outbound webhooks | Stateless /api/v1/* endpoints, OpenAPI 3.1 spec, Bearer API keys (apbx_...), scopes, IP allowlists, and HMAC-SHA256 signed webhooks |
| ⏱️ Scheduled tasks | Sandboxed background shell, PHP and Python scripts on a cron schedule (aipbx-task, systemd-run), run history, bell alarms |
| 🛠️ Troubleshooting | The Troubleshooting menu (SIP traffic .pcap/calls/ladder/live, problem recording, registrations, call quality, phone logs), changes not applied, calls hung up, sounds not found |
🔌 Plugins
Optional integrations are enabled under Integration → Plugin Catalog (/plugins). Official plugins ship in AiPBX's plugins/ directory; community plugins are installed from the opt-in signed catalog or as uploaded ZIPs. See each guide for its minimum version and installation method:
| Page | Plugin slug | What it covers |
|---|---|---|
| 🧩 Plugin system & developer guide | — | The bundled plugin catalog (plugins/), plg_* database tables, enabling/disabling integrations (google-auth, ms-teams, …), and building custom .zip plugins |
| 🔑 Corporate SSO: OpenID Connect & SAML 2.0 (Plugins) | oidc-auth, saml-auth | Enterprise Single Sign-On (SSO) with Microsoft Entra ID (Azure AD), Okta, Keycloak, Authentik, Google Workspace, and ADFS with JIT auto-provisioning |
| 🤖 Auto dialer & AMD campaigns (Plugin) | auto-dialer | Automated outbound calling campaigns with Answering Machine Detection (AMD), queue free-agent pacing, voicemail drop, and CSV call results |
| 🪪 Caller Name (CNAM) Lookup (Plugin) | cnam | Inbound caller name lookup: local phonebook & extensions first, then BulkVS, Telnyx, Twilio, Vonage, OpenCNAM, SignalWire, NumVerify, AbstractAPI or Custom URL with 30-day cache |
| 💬 SMS & MMS Messaging (Plugin) | sms | Two-way text and multimedia messaging via Twilio, Vonage, Plivo, Telnyx, Bandwidth, Sinch, VoIP.ms or BulkVS with multi-user team inboxes, contacts, and SSRF-shielded attachments |
| 🎙️ AI Voicemail Transcription & Summary (Plugin) | ai-voicemail | Automated Whisper audio transcription and LLM executive summaries, urgency classification, action-item extraction, and PCI-DSS PII masking |
| 🌐 SIP Provider Templates (Plugin) | provider-templates | 1-click SIP trunk creation from community carrier profiles (Twilio, Telnyx, A1, Drei, etc.) with pre-configured PJSIP NAT, timers, and codec flags |
| 🌐 Website call widget (Plugin) | web-widgets | "Call us" button for websites (WebRTC in the browser), call-back form, allowed websites and limits, WordPress plugin |
| ☁️ Cloud AI services (Plugin) | ai-cloud, ai-voicemail | Accounts of cloud AI providers (Gemini/Gemma, OpenAI, Azure, Deepgram, Groq, NVIDIA NIM, Qwen, any OpenAI-compatible service), cloud speech to text, language models, voicemail transcription |
| 🗣️ Cloud TTS (Plugin) | ai-tts | Text to speech with Google, Amazon Polly, Azure, ElevenLabs or OpenAI; saving announcements |
| 🧠 Local AI models (Plugin) | ai-models | AI models on the PBX itself (EMA Lightning Turkish TTS): the runtime, downloading models, the aipbx-ai service and its API |
| 🎛️ AI applications (Plugin) | ai-apps | AI features with their own numbers that take calls: announcements with values (caller, lookup address) |
| 🛰️ External AI agents | AI → External agents | A voice agent of another service at a SIP address as a call destination; hand-over to a person by REFER, call limit, fallback |
| ✨ Dialplan editor / AI assistant (Community plugin, @shido6) | ai-assistant | Plain-language PBX changes with a preview before apply, the audit trail, undo, and the Echo box that answers questions from this server's own data |
| 📡 Signaling capture | Troubleshooting → SIP capture settings | What res_hep sends to the local aipbx-signaling daemon, the pbx_signaling_events table, .pcap capture files, and retention (off by default) |
| 📮 Voicemail | PBX settings → Voicemail | Mailboxes, listening (\*97/\*98, portal, apps, e-mail), message limits and PIN rules |
| 📈 Call quality | Troubleshooting → Call quality | Packet loss in both directions and jitter per trunk and extension from RTCP; a health check alarms when audio is lost |
📱 Mobile apps
The 🤖 Android and 🍎 iOS apps are built by GitHub Actions and attached to each GitHub Release. Users sign in with their portal username and password (plus 2FA when enabled), by scanning the QR code on My Phone, or with the link in their invitation e-mail.
🗺️ Roadmap & Specifications
| Page | What it covers |
|---|---|
| 📜 SDD Guide & Constitution | Specification-Driven Development (SDD) guide, core architectural rules (zero regressions, circuit breakers, pure generators), and living specifications index (Specs 001, 002, 003) |
| 🗺️ Roadmap | Planned work across future waves with detailed requirements and milestone criteria |
The Roadmap distinguishes delivered features from proposals and larger future projects.