Docs / Devices

Desk phones

Onyx Voice sets up desk phones for you. You tell it which phone belongs to which extension (by the phone's MAC address), the phone fetches its settings from the server, and from then on it keeps them up to date by itself. This chapter covers the makes and models Onyx knows, adding phones, the provisioning address, plug-and-play and DHCP option 66, programmable keys, the phone book, DECT bases with handsets, firmware, encrypted calls and hot desks.

Everything here is on two console pages: Desk phones (per tenant) and Phone firmware (for the whole server).

Supported phones

Onyx writes the settings file in each maker's own format. The Model list on the Desk phones page holds these models:

Only two models have been checked on real hardware so far: the Grandstream GXP2135 and GXP1625. Every other template is built from the maker's own provisioning documentation and has not yet been tried on the device. Test one phone of a new model before you roll out a whole office, and tell your supplier what you find.

A model that is not in the list usually works if you pick a listed model of the same family: phones of one family read the same file format. The page says so under the Model field ("Other models of the same family usually work too.").

Some things Onyx does not provision yet:

• Fanvil W710 and Snom M500 DECT systems, and the Gigaset N720. They are not in the list.
• Grandstream HT adapters get one account, on the first port.
• Poly phones get no phone book, and their keys can watch extensions and park slots but not hold speed dials (see Keys).

What a phone gets

When a phone fetches its settings it gets:

• its SIP account (a generated username and password, see extensions), registering to the server name the phone used to fetch the file, on the SIP port (UDP), or on the SIP TLS port when calls are encrypted;
• the person's name and extension number on the screen, and key 1 as their own line;
• the voicemail key and message light, dialling *97;
• the tenant's time zone, with daylight saving, and a time server (the Time server for phones setting, pool.ntp.org by default);
• the tenant's phone admin password for the phone's own web page;
• the company phone book, where the make supports it;
• automatic answer for pages and intercom calls (see features);
• the programmed keys, and firmware if you assigned some;
• an instruction to check back for changes once a day (except Fanvil, see Pushing settings and restarting).

Because the phone registers to the name or address it fetched its settings from, point phones at an address they can reach the server on and keep reaching it. The server needs a fixed address (see network).

The provisioning address

Each tenant has its own secret provisioning address. You find it on the Desk phones page, card Provisioning address:

• Address (HTTP), for example http://pbx.example.com/p/2f8kq0w7hz4m1c6r9t3b5n8x/. Use this one for phones in the office.
• Address (HTTPS), the same over HTTPS. It is only for phones that trust the server's certificate (see certificates).
• Phone admin password, the password Onyx sets on every phone's web page for this tenant (user name admin on most makes).
• Short notes on where each make takes the address (Yealink, Poly, Grandstream, Cisco).

The address uses the host name you opened the console with. If you signed in as https://pbx.example.com but the phones cannot resolve that name, use the server's address instead: http://10.0.0.20/p/2f8kq0w7hz4m1c6r9t3b5n8x/.

The settings files contain SIP passwords, so Onyx protects them three ways:

1. A file is only served under the tenant's secret address.
2. It is only served for a MAC address you have assigned. Unknown phones get "not found" and are listed under Phones waiting to be added.
3. It is only served to phones on the local networks. By default that is the Local networks server setting. To allow other networks, set Phones may fetch settings from (provisioning.allowed_nets) on Server settings, card Desk phone provisioning: a comma-separated list of networks such as 10.0.0.0/24,10.0.5.0/24, empty for the local networks, or any for the internet. A refused phone gets "forbidden" and the service log notes "Provisioning request ... refused".

If the address leaks, click New secret address (and click again to confirm). Onyx makes a new address and the old one stops working at once. Every phone then has to be pointed at the new address, by DHCP or by hand, because phones remember the address they were given.

Phones outside the office

A phone at someone's home can be provisioned from the internet once you allow it with any (or with that site's network) in Phones may fetch settings from. Plain HTTP sends the phone's SIP password unencrypted across the internet, so use the HTTPS address with a certificate the phone trusts. The phone also needs to reach the server's SIP and audio ports from outside (see network).

Adding a phone

To add a desk phone:

1. Open Desk phones and click Add a desk phone. (From an extension's page, Add a desk phone (auto setup) opens the same form.)
2. Extension: the person the phone belongs to. Only user extensions are listed.
3. MAC address: from the label under the phone. Any format works (80:5E:C0:12:34:56, 805EC0123456, with dashes).
4. Model: pick the model, grouped by family.
5. Label: optional, for example "Reception desk".
6. Click Add phone.

Onyx answers "Phone added. Point it at the provisioning address (or reboot it if it already is)." Then do one of these:

• Let DHCP hand out the address (see DHCP option 66) and plug the phone in.
• Plug the phone in at factory settings and let plug-and-play find the server.
• Enter the address on the phone's web page: Yealink under Settings > Auto Provision > Server URL; Poly under Settings > Provisioning Server (type HTTP); Grandstream under Maintenance > Upgrade and Provisioning > Config Server Path, without http://; Cisco MPP under Voice > Provisioning > Profile Rule, as the address followed by $MA.xml.

The new phone shows under Provisioned phones with one of these states:

A MAC address can only belong to one phone. To move a phone to another person, remove the device from the old extension (on the extension's page, under Phones) and add it again.

You can also add a phone from the command line with onyx device add <tenant> <number> --kind provisioned --mac <mac> --model <model> (see cli).

Plug-and-play

A Yealink, Grandstream, Fanvil, Snom or Htek phone at factory settings sends a plug-and-play request to the local network when it starts. Onyx answers it with the right tenant's provisioning address, so the phone needs no setup at all. Poly, Cisco, CyberData and Gigaset devices do not ask this way: use DHCP or enter the address.

Which tenant answers:

1. If the MAC is assigned in a tenant, that tenant.
2. Otherwise the tenant in Tenant for new plug-and-play phones (provisioning.pnp_tenant), on Server settings.
3. Otherwise, if the server has only one tenant, that one.
4. Otherwise the phone gets no answer, and the service log says it is "not assigned and no tenant takes new phones".

A phone that is answered but not assigned shows up on that tenant's Desk phones page under Phones waiting to be added, with its MAC, make, the phone's own description, its address and Last asked. To take it on:

1. Click Assign. The add form opens with the MAC filled in and the models of that make offered.
2. Pick the Extension and Model and click Add phone.
3. Restart the phone (power it off and on). It asks again, gets its settings and registers.

Ignore removes a phone from the list. It comes back if it asks again.

Plug-and-play works on the network segments the server is connected to, because the request is a multicast that routers do not pass on. Phones on another network need DHCP option 66 or the address entered by hand. It also needs:

• Plug-and-play (provisioning.pnp) set to on (the default) on Server settings;
• the phone's network allowed by Phones may fetch settings from;
• port 5062/udp open in the server firewall. Server › Network warns when it is closed; Reset to phone system ports opens it.

On a cluster, only the active server answers (see high-availability).

DHCP option 66

Most phones ask the DHCP server for option 66 (Poly also reads option 160) when they start, and use it as their provisioning address. To set it up:

1. Copy Address (HTTP) from the Desk phones page.
2. On the DHCP server for the phones' network, set option 66 to that address. For Poly phones, set option 160 to the same address too.
3. Restart the phones.

With several tenants on one network, option 66 can only point at one tenant's address. Use a separate network (or VLAN) per tenant, or enter the address on each phone.

Cisco MPP phones at factory settings ask option 66's server for a model file Onyx does not answer. Set their Profile Rule by hand instead, as described in Adding a phone.

Network, LLDP and voice VLANs

Onyx turns LLDP on in Yealink, Grandstream GRP and Grandstream GXP phones (it is the factory default, but an earlier phone system may have turned it off). It does not set a VLAN on any phone: if your switch hands out a voice VLAN with LLDP-MED, the phone takes it from the switch. Put DHCP option 66 on the voice VLAN's DHCP scope, since that is where the phone asks. Other makes keep their own LLDP and VLAN settings.

Keys: BLF, speed dial and park

Phones with programmable keys get key 1 as the person's own line, then the keys you set. To set them:

1. On Desk phones, click Keys next to the phone.
2. For each key choose the type, the number and an optional label:
   • Extension (BLF): watches a colleague's extension. The light shows when they are on the phone; pressing it calls them. To pick up their ringing call, dial ** and their extension (Yealink and Cisco keys do this when pressed while it rings).
   • Speed dial: dials the number (an extension, a feature code or an outside number).
   • Park slot: watches a parking slot (by default 701 to 720). It lights while a call is parked there; pressing it picks the call up.
3. Add a key for more, the x to remove one, then Save keys.

The number may contain digits, *, # and +, up to 32 characters. A label is up to 20 plain characters; without one, the key shows the person's name for an extension, or the number. A phone takes at most 100 keys. If the phone is online, saving also pushes the keys to it ("Keys saved and pushed to the phone."); otherwise it picks them up at its next settings check.

A key can also watch a time condition's manual override: an Extension (BLF) key on *27 or *28 followed by the time condition's number lights while it is forced closed or open, and pressing it switches the override (see attendants).

What each make does with the keys:

Phone book

Phones that support it get the tenant's phone book: every enabled user extension and ring group, plus the outside contacts from Contacts (one entry per number, with the number's label in brackets when it is not the work number), sorted by name (see contacts). It is set up on Yealink (desk phones and DECT bases), Grandstream GRP and GXP, Cisco MPP, Fanvil, Snom D and Htek phones. Poly, Snom M, Gigaset and CyberData devices do not get it.

Phones fetch the phone book again by themselves, so a new colleague or contact reaches them without you doing anything. It is served under the provisioning address, so the same network rules apply.

Time zone

Phones show the tenant's time zone (the Time zone set for the tenant, see tenants), including daylight saving, using Time server for phones to keep the clock right. Each make takes the zone its own way. Two have limits:

• Snom phones and Snom M bases take a zone code for common zones (the US zones, London and Berlin). In other zones a Snom D phone gets the plain UTC offset without daylight saving, and a Snom M base gets no zone at all.
• Htek phones only get a zone for Los Angeles, Denver, Phoenix, Chicago, New York, London and Berlin. Elsewhere set the zone on the phone.

Phone admin password

Every tenant has one admin password for its phones' web pages, made when the tenant first uses provisioning and shown under Phone admin password. Onyx writes it into every phone's (and DECT base's) settings, so each fetch sets it again. Use it to sign in to a phone's web page when you need to look at it. There is no button to change it.

Pushing settings and restarting

Phones check for changes once a day: Yealink, Grandstream, Htek, Snom, Cisco, Gigaset and the Snom C520 every 24 hours from their last check, Poly and CyberData at 03:00. Fanvil phones get no daily check from Onyx: they pick up changes when you push settings or restart them.

To apply a change now, click Push settings next to the phone. Onyx sends the phone a SIP NOTIFY and it fetches its settings at once ("Settings pushed: the phone fetches them now."). Yealink, Grandstream, Poly, Cisco, Snom, Htek and Gigaset devices re-read their settings without restarting; Fanvil phones restart to do it. CyberData devices take no remote signal, so the button is not shown for them.

Reboot restarts the phone. It is not offered for Poly, Fanvil and CyberData, which have no separate restart signal.

Both only work while the phone is registered. Otherwise the console says "The phone is not registered right now, so it cannot be reached. It picks up changes on its next daily check or reboot."

Firmware

Onyx can keep phones on a firmware version you chose. Phone makers do not allow their firmware to be shipped with Onyx, so you add each file once yourself, from the maker's own site. Only system administrators can add, assign and delete firmware; tenant administrators can see the library.

To add firmware:

1. Open Phone firmware. The card Where to get firmware links to each maker's download page and says which file to take.
2. Under Add firmware, choose the Vendor and type the Version as the maker names it (for example 96.86.0.70).
3. Either paste the direct link to the file into Download address and click Download to the server (the server fetches it itself, so a large file never passes through your browser), or choose the file under Or upload a file and click Upload file.

Take the file the phone itself asks for. Grandstream and Htek releases come as a .zip: unzip it and add the file inside (for example grp2610fw.bin), because these phones ask for a fixed file name. Cisco needs a Cisco login to download the .loads file. File names may contain letters, digits, dots, dashes and underscores; a file must be between 1 KB and 1 GB.

To roll it out, pick the model in Assign to model... next to the file in the Firmware library. Every phone of that model, in every tenant, upgrades at its next settings check; push settings to start sooner. A model has one firmware at a time: assigning another replaces it. Unassign stops managing that model's firmware (phones keep what they have). Delete removes the file. The library shows each file's size, the models using it and the start of its SHA-256 checksum, so you can compare it with the maker's.

Without assigned firmware, phones keep whatever version they have.

DECT bases and handsets

On a DECT system each handset is its own extension. You add every handset with the base's MAC address:

1. Click Add a desk phone, pick the handset's Extension, enter the base's MAC address and choose the base model (for example W70B).
2. Two more fields appear:
   • Handset number: the base's slot for this handset. Leave it empty for the next free one.
   • Handset IPUI: the handset's DECT identity, 10 hexadecimal digits (on the handset's label or its Info screen).
3. Click Add phone. Repeat for each handset.

The base fetches one file with all its handsets. A base belongs to one tenant. On the Provisioned phones list each handset shows as the base model with "handset" and its slot number, and its IPUI. Handsets cannot be hot desks or encrypted. DECT bases register over plain SIP (UDP).

Encrypted calls

A phone can make its calls encrypted: SIP over TLS to the server's SIP TLS port (5061 by default) and the audio as SRTP. To turn it on, click Encrypt calls next to the phone. Plain calls turns it off again.

The phone gets its new settings at its next settings fetch, but the server expects encrypted audio from it at once, so the phone's calls fail until it has them. Click Push settings straight after.

Onyx can set encrypted calls up on:

• Yealink desk phones (not DECT bases);
• Poly VVX and Edge E;
• Grandstream GXP and GRP;
• Cisco MPP;
• Snom D phones and the PA1+.

For any other model the console refuses: "Onyx cannot set up the ... for encrypted calls yet. Configure TLS and SRTP on the phone by hand and add it as a SIP phone instead."

Certificates matter here. With a Let's Encrypt or other trusted certificate (see certificates), an encrypted phone is told to register to the server's name (the Server name setting), so the name on the certificate matches; that name must resolve on the phones' network. With a self-signed certificate, Onyx tells Yealink phones to accept it; whether other makes accept a certificate they do not trust depends on the phone, so a trusted certificate is the safe choice. See security for encryption across the whole system.

Hot desks

A hot desk is a shared phone. Anyone dials *55 on it and enters their extension and voicemail PIN to make it theirs; *56 gives it back (see features). On Desk phones:

• Make it a hot desk and Make it a normal phone switch a phone between the two.
• A hot desk shows "Hot desk" and who is logged in, or "nobody logged in".
• Log in… logs a person in from the console, the same as *55 at the desk; whoever was logged in elsewhere is moved here. Log out logs them out.

While someone is logged in, the phone's next settings fetch shows their name and labels. The SIP account stays the desk's own.

When a phone does not set itself up

• It is not listed under Phones waiting to be added and stays "Never fetched settings". The phone is not reaching the address. Check the address on the phone (Grandstream without http://), DHCP option 66, that port 80 is open on the server firewall, and that its network is allowed in Phones may fetch settings from. On Server › Logs & diagnostics, card Logs, search the service log for the phone's MAC (twelve characters, lower case, no separators) or its IP address: unassigned phones are logged by MAC, refused requests by address.
• It is listed under Phones waiting to be added although you added it. The MAC you typed differs from the one the phone reports. Click Assign on the waiting entry instead.
• It fetched its settings but stays offline. The phone cannot register to the name or address it fetched from, or its SIP traffic is blocked. See troubleshooting.
• A change does not show. Click Push settings, or restart the phone.