Digium phones discover DPMA or Switchvox systems using multicast DNS (Bonjour), and provision directly from those systems using SIP MESSAGE - which eliminates the need for extra provisioning servers, and greatly simplifies system deployments for most users. In addition to this default provisioning method, Digium phones may also be provisioned over Option 66 to a DPMA or Switchvox system and will retain their full capabilities. And, in other instances, Digium phones may be provisioned to non-DPMA or non-Switchvox systems; in these cases, Digium phones will lose many of their features and act like regular-featured SIP phones only.
This page provides information about general provisioning information about Digium phones, primarily for situations where multicast DNS discovery of DPMA or Switchvox is not possible due to network design or because the phones are not being provisioned to the DPMA or Switchvox.
Digium phones can either retrieve their configuration directly from a DPMA or Switchvox system via SIP MESSAGE, or by being directed to an HTTP, HTTPs, FTP or FTPS host via DHCP Option 66. TFTP is not supported.
Here is an example Avahi services definition file that will point a phone to DPMA and/or Switchvox:
Note that serviceType may be defined as either switchvox or asterisk.
Here is a typical DHCP daemon configuration specifying Option 66:
Notice in this example the option:
That directive tells phones to contact the server http://server.example.com/proneprov/ for their configuration files.
If the boot-server directive does not specify a protocol, the Digium phone will fall back to using HTTP.
The phone will, upon receipt of the Option 66 option boot-server parameter, attempt to use its cURL application to retrieve, from the specified path, its configuration file. The phone will attempt to retrieve three files, in order. The successful retrieval of any one file will stop the process.
- <mac.cfg>, the MAC address of the phone, in all lower-case characters, dot cfg.
- <MAC.cfg>, the MAC address of the phone, in all upper-case characters, dot cfg.
- 000000000000.cfg, a "zeroes dot cfg" file. Note that this should not be used in a heterogenous network of vendor phones, as other vendor phones may also request a 000000000000.cfg file and the parameters between vendors are different and may run counter.
Multicast Firmware Management
Digium phones may have their firmwares managed, en masse, using multicast discovery and a server for file delivery. In the same manner in which Digium phones when used with the DPMA or Switchvox discover the available Asterisk or Switchvox server using Multicast DNS, Digium phones can also discover a firmware server using Multicast DNS. In order to facilitate this capability, we assume an existing Linux system running the Avahi and Apache daemons.
To begin, create a new file, e.g. firmware.service, and put it in /etc/avahi/services.
The contents of the file should resemble the following:
This file contains the following configuration parameters:
The name of the firmware service.
A carryover from Digium's existing service configuration for communicating with DPMA and Switchvox configuration servers; must be "_digiumproxy._udp"
The port number on which the Apache server is running to service firmware files
The base URL for the server (HTTP, HTTPs, FTP, FTPs) from which firmware files will be retrieved by the phone.
The version identifier of the provided firmware
The path and file that model D40 phones will retrieve
|D45File||string||The path and file that model D45 phones will retrieve|
The path and file that model D50 phones will retrieve
|D60File||string||The path and file that model D60 phones will retrieve|
|D62File||string||The path and file that model D62 phones will retrieve|
|D65File||string||The path and file that model D65 phones will retrieve|
The path and file that model D70 phones will retrieve
|D80File||string||The path and file that model D80 phones will retrieve|
The type of service provided; must be "firmware"
Once the file has been created in the /etc/avahi/services directory, the Avahi daemon will recognize it and Digium phones will be able to select it as a Configuration Server. If no other Digium Configuration Servers or Option 66 are present on the network, the phone will boot automatically to the firmware server, upgrade its firmware, reboot, and display a success screen:
If other Digium Configuration Servers (DPMA or Switchvox) or Option 66 are present on the network, the phone will boot to a screen requesting that the user select the server the phone should use.
XML Firmware Management
Within the XML configuration file, the phone receives configuration information, including information about firmware files to load. Firmware is managed using a <firmwares> configuration element, such as:
- Element lists the <firmwares> elements, each described by the following attributes.
- Network, if specified, allows the phone to load different firmware URLs depending on its own network address mask
D40, D45, D50, D60, D62, D65, D70
Model number of the Digium phone
Version string for the firmware. On boot, the phone will check the version string against an internal copy of the string, as previously loaded. If the strings differ, the phone will load the new firmware
http URL string
URL location of the phone firmware
Thus, if one wants to provision the firmware of a number of phones at one time, one can configure Option 66 to point to a location that specifies a 000000000000.cfg file with contents like the above example, boot the phone to the Option 66 supplied location, and wait. The phone will display "Updating Firmware from PBX." Once this begins, wait approximately 30 seconds and the phone will download the firmware file and reboot. When the phone reboots, it will display the following screen:
The phone's firmware load can be verified by viewing the Menu>About screen (press the Check Button twice):
Next, the phone should be manually returned to factory default settings. This can be accomplished by pressing the Menu or Check Button, selecting Advanced (5) from the Main Menu, Reset to Factory Defaults (2) from the Advanced menu and confirming the factory reset by pressing Yes or the Check Button.
Digium phones present Option 60, Vendor class identifier, when communicating with a DHCP service. The presentation is in the format:
DPMA and Switchvox Configuration when Multicast is Not Available
Digium phones, by default, attempt to discover DPMA and Switchvox servers using Multicast DNS. In many cases, Multicast DNS discovery is not possible; thus, Digium phones, beginning with phone firmware 1.1.3, can be directed to contact a DPMA or Switchvox server by Option 66 as provided by a DHCP daemon.
There are two methods to achieve this:
- Option 66 SIP MESSAGE Directive
- Option 66 config_server_url XML parameter
Option 66 SIP MESSAGE Directive
The Option 66 SIP MESSAGE Directive should be used in the case that all phones receiving Option 66 from the DHCP daemon are Digium phones. If phones other than Digium phones are going to be directed by this same Option 66, then this method should not be used.
To use Option 66 to tell Digium phones to contact a DPMA or Switchvox configuration server directly, using SIP MESSAGE, use a directive like:
This parameter is read by Digium phones, which, when seeing it, and noting the sip:proxy formatting, know to treat the specified server as a DPMA or Switchvox server, and not just as a location from which to retrieve XML files.
Option 66 config_server_url XML parameter
The Option 66 config_server_url XML parameter should be used in cases where more than one phone vendor's phones are to be provisioned by the Option 66 directive. In this case, Digium phones should be redirected by Option 66 directive as any other phone.
If all Digium phones are to contact the same server, or if only Digium phones are the ones reading the zeroes configuration files, then one would create a 000000000000.cfg file at the specified URL and populate it with a special configuration setting, config_server_url, new in the 1.1.3 phone firmware. Use of the <mac>.cfg or <MAC>.cfg files with the config_server_url configuration setting is also permissible, and recommended, for cases where more than one vendor's phones are being directed by Option 66.
Here is an example using the config_server_url setting for DPMA and Switchvox:
sip:proxy AT my DPMA or Switchvox server and port
Specifies the location which the Digium phone should contact for DPMA and Switchvox SIP MESSAGE provisioning
Here is an example using the config_server_url setting for standard XML (non-DPMA, non-Switchvox) Provisioning:
Specifies the URL string that the Digium phone's cURL application will call in order to retrieve the phone's configuration file
In both cases, the phone will store the location provided by the config_server_url - either the DPMA/Switchvox location or the location for retrieving the XML Provisioning file. Thus, once the phone has been provided the config_server_url location, the phone will store it and attempt to use it on subsequent boots, regardless of whether or not a server is actually available to serve provisioning from that location.
This is a change from previous versions of Digium phone firmware, where successful retrieval of a valid configuration was mandatory before the location were to be stored.
Further, in both cases, beginning with Digium phone firmware 1.1.3, it is also possible to specify a <firmwares> configuration block and network settings blocks - for dealing with different networks as well as setting proper VLAN assignments. If firmware is specified, and the specified firmware differs from the firmware the phone is currently running, the phone will load the specified firmware and reboot before proceeding. And, if VLAN assignment is made, then the phone will next assign itself to the specified VLAN and reboot. Finally, the phone will attempt to contact the specified configuration server, having loaded the correct firmware and assigned itself to the correct VLAN.
The configuration provided by the config_server_url parameter must be a complete configuration. If, for example, VLAN settings are defined in the pre-provisioning file but are not also redefined by the configuration retrieved from the config_server_url location, the phone will fall back to using phone defaults once its loads the configuration from the config_server_url. So, if one were to manually define a VLAN in the pre-provisioning and point to a config_server_url configuration that does not define the same manual VLAN, then the phone will fall back to its default, which is LLDP, upon retrieving the config from the config_server_url location.
A more complete example would resemble:
Digium phones, beginning with firmwares 1_5_0 (D80) and 2_3_0 (other models), validate the SSL for any cURL operations. This includes configuration file retrieval, for non-DPMA/Switchvox phones, as well as for retrieval, inside of DPMA/Switchvox environments, of firmware, ringtones, contacts files, blf items files, applications, etc. And, beginning with firmware 2_7_0 (non-D80), phones also validate SSL for 802.1X authentication. SSL Validation can be manually disabled from the phone's UI - or later disabled via an XML config parameter. But, this can present some chicken-and-egg challenges.
From a factory default state, Digium phones root CA bundle is the only means by which it can validate SSL. The root CA bundle is typically kept current with the Mozilla PEM bundle at the time of the firmware's building. So, for an initial validation, the phone, if it is directed to an HTTPs location, can only validate against a publicly signed server. The phones are capable of being fed additional root CA PEM payloads, which may be privately signed CAs, from within the phone's XML config file inside of the certs element. The phone will, on boot, combine any root CA payloads from its config file with the baked in Mozilla bundle to create the bundle that it uses for all SSL validation. Thus, phones, once they've been given an initial config file, can validate non-publicly signed SSL connections.
The problem is further complicated by time. Digium phones do not have a built in battery. Thus, from a factory default state, the phone has been programmed to set its clock to its firmware build date. The phone, if it's able to get on a network, will then attempt to set its clock using NTP. Beginning with firmware 2_7_0 (non-D80), phones are able to respond to DHCP Option 42 for NTP servers, and will utilize servers retrieved there in lieu of the phone's built-in server definitions: 0.digium.pool.ntp.org and 1.digium.pool.ntp.org. Once time has been retrieved, the phone will set its clock and continue the boot process. Subsequently, whenever the phone is rebooted, it will save off its current time and will, on on the next boot, use that time in lieu of the firmware's build-time. This provides a more accurate clock in the future for validating SSL.