System map (for administrators)

Where everything is on an installed AiPBX server and how to follow a problem from the portal to the file, process or log behind it. Everything here is on the server itself: it works without internet access. Paths are those of a standard install.sh installation; commands run as root (sudo).

Read it with Troubleshooting (symptom → fix) and Health (the automatic checks).

1. The big picture

 browser / app ──443──► nginx (TLS passthrough, picks by ALPN)
                         ├─ http/1.1, h2 ──► Apache 127.0.0.1:8443 (TLS)
                         │                   ├─ /            PHP portal (/opt/aipbx/web)
                         │                   ├─ /ws          Asterisk WebSocket 127.0.0.1:8088 (SIP for browsers/apps)
                         │                   ├─ /chat/ws     chat service 127.0.0.1:8086
                         │                   └─ /provision/  desk phone files (also over plain HTTP, port 80)
                         └─ no ALPN (TURNS) ──► coturn 5349 (media relay for WebRTC)
 desk phones ──5060 UDP/TCP, 5061 TLS──► Asterisk
 Asterisk ──AMI 127.0.0.1:5038──► portal (live state, originate, reload)
 Asterisk ──CURL / AudioSocket 127.0.0.1:8790/8791──► local AI service
 portal ──sudo──► /usr/local/sbin/aipbx-priv (the only root entry point)
 everything ──► MariaDB, database "asterisk"

Changes made in the portal are stored in the database first. Apply (top bar) writes the Asterisk files under /etc/asterisk/pbx/ and reloads Asterisk (section 5).

2. Source tree (/opt/aipbx)

/opt/aipbx is a git checkout of the release tag (cat /opt/aipbx/VERSION, git -C /opt/aipbx describe --tags). Updates replace it; do not edit files there by hand.

From a page to its code

Take the URL of the page (e.g. /phones) and follow:

1. web/src/routes.php → '/phones' => PhoneController::index
2. web/src/controllers/PhoneController.php → which service it calls (PhoneProvisionService)
3. web/src/services/PhoneProvisionService.php → the logic; vendor files in web/src/services/phones/
4. web/templates/views/phones/index.php → the HTML; web/assets/js/phones.js → the buttons' script
5. Texts: search the shown text in web/lang/en.php to get its key, then the key in the code
6. Who may open it: getModuleKeyForPage() in web/auth.php and System → Roles

grep -rn "something" /opt/aipbx/web/src finds the rest; error messages in the logs name the file and line.

3. Services

systemctl status <unit> shows whether it runs; journalctl -u <unit> -n 100 its recent log. Units marked "when switched on" only run when the page enables them.

4. Files on the server

Configuration and secrets

Never paste /etc/ai-pbx.env or settings.key into a ticket: they hold every secret. Losing settings.key makes the encrypted passwords in the database unreadable; it is in the backups.

Data

Logs

5. Apply: from the database to Asterisk

1. A page saves to the database and marks its area as pending (sys_pending_sync).
2. Apply (or php /opt/aipbx/web/src/asterisk_sync.php, which regenerates everything) runs the generators in web/src/sync/, writes each file atomically, keeps the previous one as .prev, and reloads only the Asterisk modules concerned. Calls are not dropped.
3. If a file cannot be written or Asterisk rejects it, the previous file is restored, the area stays pending and the error is shown and audit-logged.

To see what changed: diff /etc/asterisk/pbx/<file>.prev /etc/asterisk/pbx/<file>.

6. Database (asterisk)

mysql asterisk as root opens it. Main tables by area:

7. Scheduled jobs (/etc/cron.d/aipbx)

8. Root tools (/usr/local/sbin)

9. Debugging recipes

Start with aipbx-selftest and the portal's Health page; most broken services show there.

A page shows an error or a blank part

1. tail -f /var/log/apache2/aipbx_ssl_error.log and reload the page: the PHP error names file and line.
2. Browser developer tools → Console/Network: a failing /api/... call shows its JSON error.
3. Follow the page to its code (section 2).

Apply fails or a change does nothing

1. The error is shown on Apply and kept in Security → Audit log.
2. php /opt/aipbx/web/src/asterisk_sync.php regenerates everything and prints errors.
3. asterisk -rx "dialplan reload" / asterisk -rx "module reload res_pjsip.so" and check messages.log for syntax errors in /etc/asterisk/pbx/.

A call fails

1. asterisk -rvvv, make the call, read the dialplan steps (Executing [...]).
2. asterisk -rx "pjsip show contacts" — is the phone or trunk registered/reachable?
3. asterisk -rx "pjsip set logger on" (off again afterwards) shows the SIP messages; or capture: see Troubleshooting → Capturing SIP.
4. Call records: portal Reports, or SELECT * FROM asteriskcdr ORDER BY calldate DESC LIMIT 20;.

Browser or mobile app does not ring / no audio

1. asterisk -rx "pjsip show contacts" | grep webrtc — mobile endpoints are <ext>-mob-webrtc.
2. /var/log/apache2/aipbx_ssl_access.log: GET /ws with 101 = WebSocket opened (logged when it closes); 503 = Asterisk was not reachable at that moment.
3. Audio: WebRTC, NAT and TURN; /var/log/turnserver/turnserver.log.
4. App push and background: Troubleshooting → notifications.

Desk phone does not get its configuration

1. Network & devices → Phones: Show the phone's file shows exactly what it gets; Network settings shows the addresses the phones are told.
2. Network & devices → Phone logs: one tab each for the phone's own log (syslog), HTTPS, FTP, TFTP and DHCP, by IP or MAC.
3. On the server: journalctl -u aipbx-dnsmasq, /var/log/aipbx-ftp.log, files in /var/lib/aipbx/tftp.

Mail is not sent

mailq (queue), journalctl -u postfix -n 50; settings: System → Mail settings.

Fax

/var/log/fax_incoming.log, /var/log/fax_outgoing.log, asterisk -rx "fax show sessions".

Chat or AI

journalctl -u aipbx-chat -n 100, journalctl -u aipbx-ai -n 100; curl -s http://127.0.0.1:8790/v1/health for the AI service.

Login problems

/var/log/aipbx/web_login_failures.log; fail2ban-client status aipbx-web (banned addresses).

Time

chronyc tracking; phones: chronyc clients (when NTP server is on).

10. Where is …? (feature → code)