Desk phones (provisioning)

Network & devices → Phones sets up SIP desk phones without typing anything on them: the phone fetches its configuration over HTTPS from AiPBX and registers with the right extension, keys and settings. Supported: Yealink, Grandstream, Fanvil, Snom, Cisco SPA, Poly and NEC DT700/DT800 (models listed on the page).

The page is admin-only, like Users and Firewall: the provisioning URLs it shows hand out the SIP password of the extension.

Adding phones

Each phone gets:

• a provisioning URL with a random token: https://<portal>/provision/<token>/ (Copy URL);
• its own web admin password (generated, kept encrypted; the lock button shows it). It is written to the phone, so the factory password stops working after the first provisioning.

New URL replaces the token; the old URL stops working at once (use it when a URL leaked).

Pointing a phone at AiPBX

Per-phone URL (works everywhere). Enter the copied URL as the provisioning / auto-provision server in the phone's web interface:

The phone then asks for its own file under that URL; AiPBX checks that the MAC in the file name is the phone's:

Cisco SPA phones only ask for a MAC-based name when their Profile Rule says so, so zero touch (below) needs the Profile Rule set once.

Zero touch (DHCP option 66). Fill Allowed networks in Network settings with your phone networks (e.g. 192.168.10.0/24) and hand out https://<portal>/provision/ (or the provisioning address, below) as option 66. Phones inside these networks then ask for their MAC-based file directly; a known MAC gets its configuration, an unknown one appears under Waiting phones. AiPBX can also be that DHCP server for a phone network or VLAN, or serve TFTP next to your own DHCP server: see Network services.

Server addresses (networks without DNS)

Phone networks often have no DNS or no internet access, so a phone cannot resolve the PBX's name. Network & devices → Network settings → Addresses for desk phones takes IP addresses instead (empty: the domain):

Re-provision the phones after changing them. /provision/ is also answered over plain HTTP (no redirect to HTTPS), for phones that cannot do HTTPS to an IP address or do not follow a redirect; the allowed networks and the per-phone token still apply. With an IP over HTTPS the certificate does not match the address: most phones accept that, some need HTTP.

TFTP / FTP. For phones that read their file from TFTP or FTP (NEC), tick Also write the phones' files into the TFTP/FTP folder: every assigned phone's file (dt-<mac>.cfg, <mac>.cfg, …) is written into the folder of Network services and kept current — right after a change on this page and every 5 minutes (bin/provision_tftp.php, so a SIP password changed elsewhere follows). Files of removed phones are deleted, and all of them when the option is switched off. The files contain the SIP password; TFTP and FTP answer only the allowed networks.

What is written to the phone

Show the phone's file (the file icon in a phone's row) opens exactly what the phone downloads, one tab per file (Poly: the master file and the settings file), with a copy button. The SIP and admin passwords are hidden; users who may edit phones can show them, which is written to the audit log. A phone without an active user gets no file, so the button is shown only for assigned phones.

Changes reach a phone at its next configuration download. Re-provision (↻) sends it a SIP NOTIFY through Asterisk so it reloads at once; Reboot (⏻) restarts it. Both need the phone to be registered.

Key layout

Phone keys (from the Phones page, or the ⊞ button on Extensions) draws the keys of the user's phone model, plus one page per expansion module where the model takes one. Each key has a type, a number and a label:

Empty keys are cleared on the phone, so a key removed on the page disappears from the phone too. Copy to other users gives the same layout to several users at once ("the same 15 keys for the sales team").

Limits in this first version:

• Grandstream: only the first 7 multi-purpose keys are written (the P-values of later keys and of the GXP2200EXT module differ by model and firmware).
• Fanvil: expansion modules are not written yet; codecs stay at the phone's defaults.
• Snom: keys are one list (fkey 0…): the D7 module keys follow the phone's own keys. Park keys are orbit keys.
• Cisco SPA: line keys use Extended Function (fnc=blf+sd+cp, sd, prk, dnd), SPA500S keys Unit_<n>_Key_<k>. Three preferred codecs at most; Opus is not offered.
• Poly: keys use line key reassignment; BLF keys watch the number, speed dial and park keys are automata entries of the same list (they dial without a lamp). Expansion module keys follow the phone's own keys.
• NEC: the file follows NEC's data file template for DT700/DT800 group by group. The phone checks every value against its schema and rejects the whole file when one is out of range (syslog: XmlConfig: configuration is invalid, then it restarts), so AiPBX keeps to the schema: the NTP and syslog servers are written only as IP addresses (a name is left empty), the display name is the extension (no spaces allowed), all six codecs get a distinct rank, the time zone is whole hours with daylight saving off. The admin password is not written: the phone's menu takes digits only, so it keeps its own (6633222 by default). Telnet stays on. Keys are not written (the phone keeps its own line key layout). The phone's firmware files are NEC's and are not part of AiPBX. Turkish is not among the phone's languages, English is used instead. The phone reads three files: dt-<mac>.cfg is its master file (as NEC's dt-000000000000.cfg) and only names the data file dt-<mac>-phone.cfg, which holds the settings; a data file under the master name is not applied (the phone logs data config file name is unavailable). Line ends are Unix (LF); the phones read them as well as NEC's CRLF. After the data file the phone reads dt-<mac>-local.cfg, its local override (settings changed on the phone's menu); AiPBX writes it too, in the phone's own format with the same values, so an old local file cannot override AiPBX's settings and the phone does not log a missing file. The local file starts with <VERSION Version="n"/>: the phone applies it only when n is higher than the version it applied last. AiPBX keeps n per phone and raises it by one whenever any of the three files changes (a setting, the SIP password, the server address …); an unchanged file keeps its number. Numbering starts at 3, above the version-2 files the first phones were set up with. When files are copied to another file server by hand, copy all three after every change. The file server (where the phone fetches dt-<mac>.cfg) cannot be set from the file: set it in the phone's menu (FTP, user NECSDT700) or by DHCP.

Logging and protection

• Every request is logged (time, MAC, file, result, IP, User-Agent); the last 50 are on the page, rows are kept 90 days. Passwords and tokens are never logged.
• Rate limit: requests per minute per IP address (default 60); more get HTTP 429.
• Allowed networks: when set, phones outside them get nothing, not even with a valid URL. When empty, only the per-phone URLs work (from anywhere, e.g. home workers), and MAC-based file names are refused.
• Apache's access log records request paths, which contain the token of a per-phone URL. Keep access to the server's logs as restricted as access to the portal.

Adding a vendor

The templates live in web/src/services/phones/: a PhoneTemplate subclass per vendor (file names, rendering, NOTIFY events), the models with their key counts in PhoneModels, and the NOTIFY sections in asterisk-config/pjsip_notify.conf. Values go through PhoneTemplate::clean() (line-based files) or PhoneTemplate::xml() (XML), so a name or label cannot add settings.