AiPBX
Features Install Videos Mobile Docs Live demo Contact Sponsor on GitHub UpCloud ($250 Free Credit) YouTube GitHub
ODOO Connect AiPBX with Odoo CRM & ERP — manage calls & customers in one place. Try Odoo Free →
Home / Documentation / Desk phones (provisioning)

Desk phones (provisioning)

Provisioning → 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 (including the D865), Cisco SPA, Poly and NEC DT700/DT800 (models listed on the page). Cisco's enterprise 7900/8800 series (CallManager firmware) are supported too, but they need firmware, an Asterisk patch and a folder of shared files that AiPBX cannot ship: see Cisco 7900 / 8800 series. A 7900 that is still running SCCP firmware is switched to Cisco's SIP load as part of provisioning — name the load for each model on the settings tab, and restart the phone once so it reads its file.

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

Adding phones

WayHow
One phone+ → MAC address (any format: 00:15:65:AA:BB:CC, 001565aabbcc), model, extension
Many phonesCSV import: one phone per line, mac,model,extension (; or tab also work, a header line is skipped). Model is the name on the page (Yealink T46U), its short name (T46U) or its key (yealink-t46u). A known MAC is updated.
Waiting phonesA phone that asked by MAC address but is not known yet (see Zero touch below) is listed under Waiting phones with its MAC, vendor, IP and User-Agent; pick a model and an extension and press ✓.
Found on the networkThe discovery engine (Phones found on the network, below) records phones it sees on the network without asking anybody; press ✓, ignore them, or let an extension pool provision them.

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).

Phones found on the network (discovery)

A phone does not have to be typed in. The discovery engine (engine/, a Python module the install puts on a 5-minute cron entry) looks at the network and records what it found under Discovered on the network at the top of the page; from there a phone is one click, or none at all.

SourceSends packets?What it sees
AiPBX's DHCP lease filenophones that took an address from AiPBX's own DHCP server
the ARP tablenoanything on the local segment that talked recently
dnsmasq's DHCP lognophones that asked for DHCP, even after the lease file was rotated or dnsmasq restarted
a bounded ARP sweepyesthe same as the ARP table, but for every address, so an idle phone answers too

Only a MAC whose prefix is a desk-phone vendor (PhoneModels::OUI) counts: laptops, printers, access points and the PBX itself are filtered out, and anything unrecognised is not even recorded. The sweep is off by default (it is the only source that puts traffic on the wire) and bounded to 1024 addresses per network, two networks and about 30 seconds per run; the rest of a network is left for the next run.

What happens to a discovered phone:

StateHow it gets there
Newthe engine saw it. On the page: ✓ Provision this phone (pick the model and an extension), or ✗ Ignore.
Ignoredan administrator said no. It stays on the page, and the automatic step never touches it again.
Provisioneda phone exists for that MAC. It is shown as a phone that is on the network.
Was a phone, now deletedthe phone was deleted. Nothing re-creates it on its own; ✓ provisions it again if you mean it.

Automatic provisioning happens only when you ask for it, in Provisioning → Phones → Discovery:

  • Extension pool (e.g. 5000-5099): a discovered phone takes the next extension in the pool that is an active SIP user without a phone yet. Empty: every phone is only recorded, and you press ✓ yourself.
  • Model per vendor (e.g. yealink=yealink-t46u): the MAC tells us who made the phone, never which model it is, so a vendor without a line here is never provisioned automatically.

A MAC that is already a phone is never provisioned again — not by the automatic step, and not by ✓, which refuses and says so. Only a phone seen in the last 24 hours is taken automatically, at most 25 per run, and the whole path goes through the same code as the +, the CSV import and the waiting list, so tokens, admin passwords, vendor templates and the TFTP export all keep working the same way.

On a shell: php web/bin/aipbx_phone_discovery.php status shows what the engine saw and what the settings would do about it (read-only), and python3 -m aipbx_engine check (as www-data) verifies the engine could run.

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:

VendorWhere
YealinkSettings → Auto Provision → Server URL
GrandstreamMaintenance → Upgrade and Provisioning → Config Server Path (HTTPS)
FanvilMaintenance → Auto Provision → Server Address (HTTPS)
SnomSetup → Advanced → Update → Setting URL: the copied URL
Cisco SPAAdmin login → Advanced → Voice → Provisioning → Profile Rule: the copied URL
PolySettings → Provisioning Server: server type HTTPS, the copied URL as server address
NECThe phone's file (configuration) server setting, or DHCP option 66: the copied URL
Cisco 79xx/88xx (CallManager)Not a URL: these phones ask their server for SEP<MAC>.cnf.xml by name, so they are pointed at the PBX by DHCP option 150 and read the file from the TFTP folder. See Cisco 7900 / 8800 series.

Files are served over both HTTP and HTTPS. Copy URL gives the provisioning address of the phone's region (Provisioning → Regions); when that is plain HTTP, an HTTPS button gives the one under the portal's name. HTTP on an internal address needs nothing from the phone, but the file, with its SIP password, travels unencrypted. HTTPS needs the phone to reach that name and trust its certificate.

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

VendorPer-phone file(s)Shared file (not served)
Yealink<mac>.cfgy0000000000xx.cfg
Grandstreamcfg<mac>.xml (or cfg<mac>)cfg.xml
Fanvil<mac>.cfgf0<model>.cfg
Snomsnom<model>-<MAC>.htm (plug and play) or snom-<mac>.xml (setting URL)snom<model>.htm
Cisco SPAspa<mac>.xmlspa<model>.cfg
Poly<mac>.cfg (master file, names the next one) and phone<mac>.cfg (settings)000000000000.cfg
Cisco 79xx/88xxSEP<MAC>.cnf.xmlSIPDefault.cnf.xml, Softkeys.xml, DialTemplate.xml
NECdt-<mac>.cfg (master), dt-<mac>-phone.cfg, dt-<mac>-local.cfgdt-000000000000.cfg, dt-sip.cfg

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 Provisioning → Regions 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. Provisioning → Regions (the general addresses above the regions) takes IP addresses instead (empty: the domain):

FieldWritten to / used for
SIP server (registration)the registrar in every vendor's file
Outbound proxythe outbound proxy of the line (Yealink, Grandstream, Fanvil, Snom, Poly, Cisco SPA, NEC), same port as the SIP server; empty: none
Provisioning addresswhere phones fetch their files, e.g. 192.168.1.70 (no scheme: HTTP), 192.168.1.70:8080 or https://pbx.example.com:8443: the per-phone URLs on the page and DHCP option 66/160
NTP servera name or an IP address (NEC: IP address only); this server's IP with NTP server on under Network services
Syslog serverwhere phones send their log (UDP 514), an IPv4 address (NEC); this server's IP with Syslog on under Network services: read on Troubleshooting → Phone logs

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.

Provisioning settings

Provisioning settings on Provisioning → Phones holds what every phone gets unless its region sets its own (see Regions): SIP transport, SRTP, codecs and their order, time zone, phone language, the request limit per IP, Also write the phones' files into the TFTP/FTP folder and the Cisco firmware loads (Cisco 7900 / 8800). The addresses phones are given and the allowed networks are on Provisioning → Regions since 1.70.0.

What is written to the phone

SettingValue
SIP serverthe SIP server of the phone's region or the general one (Provisioning → Regions), else the installation's domain (the same setting as the links in e-mails: PORTAL_DOMAIN, else the external domain on PBX Settings), never the address the phone used
Outbound proxythe Outbound proxy of the region or the general one (empty: none)
TransportUDP, TCP or TLS, from the region or Provisioning settings; the port is the region's SIP port, else the PBX's port for that protocol (PBX Settings, default 5060 / 5061). A region with SIP over TLS on port 443 gets TLS on 443
Accountthe extension number as user and authentication name, its SIP password, the user's name as display name
SRTPoff, optional or required
Codecsthe selected ones, in the order Opus, G.722, PCMA, PCMU, G.729. A phone without Opus uses the next one it has
TimeNTP server and the offset of the chosen time zone
Languagethe phone's display language
Voicemail*97 on the message key
Keysthe user's key layout (below)
Admin passwordthe phone's own web admin password

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.

VendorRe-provision (pjsip_notify.conf)Reboot
Yealinkyealink-check-cfgyealink-reboot
Grandstreamgrandstream-check-cfg— (restarts after re-provisioning anyway)
Fanvilfanvil-check-cfgfanvil-reboot
Snomsnom-check-cfgsnom-reboot
Cisco SPAsipura-check-cfg (resync)linksys-cold-restart
Polypolycom-check-cfg— (restarts by itself when the new settings need it)
NECnec-check-sync (the phone restarts and reads its file)—

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:

TypeNumberOn the phone
BLFextension to watchlamp shows free / ringing / busy; pressing calls, a ringing key picks up with *21 + extension
Speed dialany numbercalls it
Call parkparking slotparks / retrieves
Do not disturb—toggles DND
Line— or a device-only extensionthe account's line key (usually key 1); with a device-only extension, one more account on that key

A second number on the phone. A Line key may name a device-only extension (a shared line, the lobby number). The phone then registers that extension as one more account next to the user's own line: calls to it ring on that key, and pressing the key calls out from it. The same extension can sit on several phones; all of them ring. Only device-only extensions can be put on a key, so a key cannot make a phone register as another person. The web phone and the mobile app stay on the user's own number.

VendorWrittenAccounts
Yealinkaccount.N.*, the key's line = N2 (T31G), 4 (T33G), 12 or 16 on the larger models
Snomidentity idx="N", the key's context="N"4 (D315, D715), 12 on the others
Grandstreamaccounts 2 to 4 (P401…, P501…, P601…); the phone puts each on its next line key by itself2 (GRP2612), 4 on the others

A key beyond what the model registers, or one whose extension is no longer device only, falls back to the user's own line. Other vendors keep a single account. The Grandstream P-values are from the vendor's list and not yet confirmed on a phone.

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) on Troubleshooting → Phone logs; 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 conf/asterisk/pjsip_notify.conf. Values go through PhoneTemplate::clean() (line-based files) or PhoneTemplate::xml() (XML), so a name or label cannot add settings.

Regions

Provisioning → Regions gives groups of phones their own addresses and settings, for example one set inside your network and another for phones outside it. Installations start with Internal (the default) and External. You can add more, rename them and delete any but the default; a region that still has phones stays until they are moved.

You choose the region on each phone. A new phone starts in the default region, however it was added: the form, CSV import, discovery or the automatic pool.

Each region can set the SIP server, SIP port, outbound proxy, address for phone files, transport, SRTP, codecs, NTP, syslog, time zone and language. An empty field takes the general value, so a region changes nothing until you fill it. Write none in the proxy or syslog field when these phones should use none.

Some limits:

  • A phone has to reach the server once. It learns its first address from DHCP, plug and play or a URL you enter; the region's settings arrive with its file.
  • Outside phones need more than this. The server's NAT settings, firewall and certificate have to be right too.
  • Allowed networks stay general. To give a region its own SIP port, add a transport for it first (System → Transports).
  • TCP is written for Yealink, Grandstream, Fanvil, Snom, Cisco SPA and Poly. NEC and Cisco CallManager phones stay on UDP when TCP is chosen, as their values for it are not confirmed.

SIP over TLS on port 443

Some networks let TLS out only on 443. Tick SIP over TLS on port 443 on the region of those phones: they get TLS and port 443, and nginx on 443 hands their connections to Asterisk's TLS transport instead of the portal or the TURN server. nginx cannot read inside TLS, so it tells a phone from a browser in one of two ways:

  • By the region's own name (best). Give the region a SIP server name of its own, for example sip1.example.com for one region and sip2.example.com for another, with the portal on sip.example.com. Each name must point to this server in DNS. A connection that names it goes to Asterisk; everything else on 443 stays as it was, so browsers and the apps keep TURN on 443 from those networks too. The phones are known by that name, so save the region and press Apply. With Let's Encrypt, press Renew now on the Certificates page once the name points here: one certificate then carries all the names, for phones that check it (Certificates).
  • By address, when the region has no name of its own (empty, an IP address or the portal's name): list the addresses or networks of those phones, separated by commas. A TLS connection from them that asks for no web protocol goes to Asterisk. Browsers ask for none when they use TURN either, so from these addresses TURN on 443 does not work.

Either way the phones' calls still need their audio (RTP over UDP) to get through, and Asterisk sees them as 127.0.0.1: fail2ban does not block them and address checks do not apply.

Checking it on the server:

  • /etc/nginx/aipbx-sip443/names.conf and addresses.conf hold the lists the regions wrote. An update writes them again from the saved regions.
  • /var/log/nginx/stream.log: a phone's connection shows backend=unix:/run/aipbx-sip443.sock. backend=127.0.0.1:15349 means it went to the TURN server: the name or address is not in the lists. A registered phone keeps its connection open, so its line appears when the connection ends.
  • asterisk -rx "pjsip show contacts": the phone appears with a 127.0.0.1 contact and transport=TLS.

Tried on a live installation (v1.71.1): a Snom desk phone registers over 443 with a region name in another domain than the portal's. Calls with audio from a network that allows only 443 are not tried yet.

Model settings

Provisioning → Phones → Model settings adds settings to the files of every phone of one model, one name = value per line; # starts a comment. A setting AiPBX also writes takes the value given here, whatever its case, and the file holds only that value. On Snom, name.2 means idx 2 of a setting and fkey.0 sets a function key. They are kept in the database, so updates keep them. Available for NEC, Yealink, Grandstream and Poly.

Snom models also take Snom's own XML, single lines or a whole file, so you can paste from Snom's documentation. Attributes such as perm and a key's label reach the phone:

<language perm="RW">Deutsch</language>
<fkey idx="0" context="active" label="Boss" perm="">speed 100</fkey>

For example, to make NEC phones dial known numbers without waiting:

line.1.digitmap = [36789]xxx|1[3-9]xxx|0[2-58]xxxxxxxxx|x.T|[*]x.T|[#]x.T

Names and values go to the phone as they are, so a wrong one can stop a phone working: try a new setting on a model with one phone first where you can. Phones read them when they next fetch their configuration, usually at a restart. Delete the lines to go back to what AiPBX writes.

View or edit this page on GitHub

On This Page