Provisioning

This page has moved to https://wiki.sangoma.com/display/PHON/Provisioning

Overview

This applies to Sangoma's D-Series and P-Series telephones.

Sangoma phones discover DPMA, Switchvox, FreePBX, or PBXact 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, Sangoma phones may also be provisioned over Option 66 and will retain their full capabilities. And, in other instances, Sangoma phones may be provisioned to non-DPMA or non-Switchvox/FreePBX/PBXact systems; in these cases, Sangoma phones will lose many of their features and act like regular-featured SIP phones only.

This page provides information about general provisioning information about Sangoma phones, primarily for situations where multicast DNS discovery is not possible due to network design or because the phones are not being provisioned to a DPMA-bearing Sangoma phone system.

Initial Boot Process

At boot, a Sangoma phone will check to see if its config_server_url configuration setting is populated.  This setting is populated if the phone has been manually or by-process pointed at a configuration server during a previous boot cycle.  

If the setting is populated, the phone will continue to use this same configuration server for the current boot and any subsequent boots unless the phone is manually or by-configuration pointed at a different server.

If the setting is not populated, because the phone is in the factory state (initial shipment from Sangoma or after factory-reset operation), then the phone will look for configuration servers.  If only one configuration server is found, whether it be an mDNS advertised configuration server or an Option66 advertised configuration server, then the phone will, after a countdown, connect to that server and store and use it on the current and subsequent boots.

If more than one configuration server is found, either of the same or differing types, where the types are mNDS and Option66, then the phone will interrupt the boot process and the user will be required to manually select the configuration server to use.

Configuration Retrieval

Sangoma phones can either retrieve their configuration directly from DPMA 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:

<?xml version="1.0" standalone='no'?>
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
 <name>Sangoma Phones Server</name>
  <service>
     <type>_digiumproxy._udp</type>
        <port>5060</port>
        <txt-record>sipUrl=sip:proxy@server.example.com:5060;transport=udp</txt-record>
        <txt-record>serviceType=switchvox</txt-record>
  </service>
</service-group>

Note that serviceType may be defined as either switchvox or asterisk.

Here is a typical DHCP daemon configuration specifying Option 66:

Example DHCP daemon configuration specifying Option 66

ddns-update-style none;
option domain-name "example.com";
option domain-name-servers 192.168.0.1;
default-lease-time 600;
max-lease-time 7200;
authoritative;
log-facility local7;

option boot-server code 66 = string;

subnet 192.168.0.0 netmask 255.255.255.0 {
 range 192.168.0.10 192.168.0.255;
 option domain-name-servers 192.168.0.1;
 option domain-name "example.com";
 option routers 192.168.0.1;
 option broadcast-address 192.168.0.255;
 default-lease-time 600;
 max-lease-time 600;
 option boot-server "http://server.example.com/phoneprov/";
}

Notice in this example the option:

option boot-server "http://server.example.com/phoneprov/";

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

1. <mac.cfg>, the MAC address of the phone, in all lower-case characters, dot cfg.

2. <MAC.cfg>, the MAC address of the phone, in all upper-case characters, dot cfg.

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

Firmware Management

Multicast Firmware Management

Sangoma phones may have their firmwares managed, en masse, using multicast discovery and a server for file delivery. In the same manner in which Sangoma phones when used with DPMA discover the available server using Multicast DNS, Sangoma 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:

 Example firmware service Avahi definition

<?xml version="1.0" standalone='no'?>
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
    <name>Sangoma Phone Firmware Server</name>
    <service>
        <type>_digiumproxy._udp</type>
        <port>80</port>
        <txt-record>firmwareUrl=http://server.example.com/</txt-record>
        <txt-record>firmwareVersion=1_1_1_0_49993</txt-record>
        <txt-record>D40File=dphone/firmware_1_1_1_0_package/1_1_1_0_49993_D40_firmware.eff</txt-record>
        <txt-record>D50File=dphone/firmware_1_1_1_0_package/1_1_1_0_49993_D50_firmware.eff</txt-record>
        <txt-record>D70File=dphone/firmware_1_1_1_0_package/1_1_1_0_49993_D70_firmware.eff</txt-record>
        <txt-record>serviceType=firmware</txt-record>
    </service>
</service-group>

This file contains the following configuration parameters:

Once the file has been created in the /etc/avahi/services directory, the Avahi daemon will recognize it and Sangoma phones will be able to select it as a Configuration Server. If no other Sangoma 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 Sangoma Configuration Servers (DPMA-equipped servers such as Asterisk, Switchvox, FreePBX, or PBXact) 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:

 Firmwares Element Example

<?xml version="1.0" ?>
<config>
    <firmwares>
        <firmware model="D50" version="1_0_3_45441" url="http://10.10.4.11/firmware/1_0_3_45441_D50_firmware.eff" />
        <firmware model="D70" version="1_0_3_45441" url="http://10.10.4.11/firmware/1_0_3_45441_D70_firmware.eff" />
        <firmware model="D40" version="1_0_3_45441" url="http://10.10.4.11/firmware/1_0_3_45441_D40_firmware.eff" />
    </firmwares>
</config>

• 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

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.

Remote Restart

See Sangoma Phones Remote Restart and Reconfigure

Option 60

Sangoma phones present Option 60, Vendor class identifier, when communicating with a DHCP service. The presentation is in the format:

sangoma_model_firmwareversion

or:

digium_model_firmwareversion

e.g.

sangoma_P310_3_0_7

Configuration when Multicast is Not Available

Sangoma phones, by default, attempt to discover DPMA-equipped servers using Multicast DNS. In many cases, Multicast DNS discovery is not possible; thus, Sangoma phones, beginning with phone firmware 1.1.3, can be directed to contact a DPMA-equipped server by Option 66 as provided by a DHCP daemon.

There are two methods to achieve this:

1. Option 66 SIP MESSAGE Directive

2. 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 Sangoma phones. If phones other than Sangoma phones are going to be directed by this same Option 66, then this method should not be used, unless you can differentiate Option 66 based on MAC address prefixes.

To use Option 66 to tell Sangoma phones to contact a DPMA or Switchvox configuration server directly, using SIP MESSAGE, use a directive like:

option boot-server "sip:proxy@server.example.com:5060";

This parameter is read by Sangoma 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, Sangoma phones should be redirected by Option 66 directive as any other phone.

If all Sangoma phones are to contact the same server, or if only Sangoma 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:

 config_server_url Setting Example for DPMA and Switchvox

<?xml version="1.0" ?>
<config>
    <setting id="config_server_url" value="sip:proxy@server.example.com:5060" />
</config>

and

Here is an example using the config_server_url setting for standard XML (non-DPMA) Provisioning:

 config_server_url Setting Example for XML Provisioning

<?xml version="1.0" ?>
<config>
    <setting id="config_server_url" value="https://user:pass@server.example.com:443/phones" />
</config>

In both cases, the phone will store the location provided by the config_server_url - either the DPMA/ 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 Sangoma phone firmware, where successful retrieval of a valid configuration was mandatory before the location were to be stored.

Further, in both cases, beginning with Sangoma 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:

 config_server_url Setting Example for XML Provisioning with Firmware and Network Settings

<?xml version="1.0" ?>
<config>
    <setting id="config_server_url" value="https://user:pass@server.example.com:443" network_id="1" />
    <setting id="config_server_url" value="https://user:pass@otherserver.example.com:443" network_id="2" />
    <setting id="config_server_url" value="https://user:pass@otherotherserver.example.com:443" network_id="3" />
    <setting id="network_vlan_discovery_mode" value="MANUAL" network_id="1" />
    <setting id="network_vlan_id" value="5" network_id="1" />
    <setting id="network_vlan_discovery_mode" value="LLDP" network_id="2" />
    <setting id="network_vlan_discovery_mode" value="NONE" network_id="3" />
    <setting id="sip_qos" value="3" network_id="1" />
    <setting id="rtp_qos" value="6" network_id="1" />
    <setting id="sip_qos" value="3" network_id="2" />
    <setting id="rtp_qos" value="6" network_id="2" />
    <setting id="sip_dscp" value="24" />
    <setting id="rtp_dscp" value="46" />
    <networks>
        <network id="1" display_name="Internal" cidr="192.168.8.0/24" />
        <network id="2" display_name="External" cidr="10.0.0.0/8" />
        <network id="3" display_name="All Networks" cidr="0.0.0.0/0" />
    </networks>
    <firmwares network_id="1">
        <firmware model="D50" version="1_1_3_0_99999" url="http://192.168.0.11/firmware/1_1_3_0_99999_D50_firmware.eff" />
        <firmware model="D70" version="1_1_3_0_99999" url="http://192.168.0.11/firmware/1_1_3_0_99999_D70_firmware.eff" />
        <firmware model="D40" version="1_1_3_0_99999" url="http://192.168.0.11/firmware/1_1_3_0_99999_D40_firmware.eff" />
    </firmwares>
    <firmwares network_id="2">
        <firmware model="D50" version="1_1_3_0_99999" url="http://10.10.4.11/firmware/1_1_3_0_99999_D50_firmware.eff" />
        <firmware model="D70" version="1_1_3_0_99999" url="http://10.10.4.11/firmware/1_1_3_0_99999_D70_firmware.eff" />
        <firmware model="D40" version="1_1_3_0_99999" url="http://10.10.4.11/firmware/1_1_3_0_99999_D40_firmware.eff" />
    </firmwares>
    <firmwares network_id="3">
        <firmware model="D50" version="1_1_3_0_99999" url="http://server.example.com/backupstuff/1_1_3_0_99999_D50_firmware.eff" />
        <firmware model="D70" version="1_1_3_0_99999" url="http://server.example.com/backupstuff/1_1_3_0_99999_D70_firmware.eff" />
        <firmware model="D40" version="1_1_3_0_99999" url="http://server.example.com/backupstuff/1_1_3_0_99999_D40_firmware.eff" />
    </firmwares>
</config>

SSL Considerations

Sangoma 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 phones, as well as for retrieval, inside of DPMA 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, Sangoma 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.  Sangoma 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.