Skip to end of metadata
Go to start of metadata

Overview

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.

Configuration Retrieval

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 a typical DHCP daemon configuration specifying Option 66:

 Example DHCP daemon configuration specifying Option 66
ddns-update-style none;
option domain-name "digiumphones.org";
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 "digiumphones.org";
 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 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.

  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

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:

 Example firmware service Avahi definition
<?xml version="1.0" standalone='no'?>
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
    <name>Digium 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:

Option

Values

Description

name

string

The name of the firmware service.

type

"_digiumproxy._udp"

A carryover from Digium's existing service configuration for communicating with DPMA and Switchvox configuration servers; must be "_digiumproxy._udp"

port

integer

The port number on which the Apache server is running to service firmware files

firmwareUrl

string

The base URL for the server (HTTP, HTTPs, FTP, FTPs) from which firmware files will be retrieved by the phone.

firmwareVersion

string

The version identifier of the provided firmware

D40File

string

The path and file that model D40 phones will retrieve

D50File

string

The path and file that model D50 phones will retrieve

D70File

string

The path and file that model D70 phones will retrieve

serviceType

"firmware"

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:

 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

Option

Values

Description

model

D40, D50, D70

Model number of the Digium phone

version

string

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

url

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.

Remote Restart

Digium phones, by default, are configured to remotely restart themselves upon receipt of the check-sync Event in a SIP NOTIFY. This behavior is controlled by the enable_check_sync XML configuration setting. By default, this setting is enabled, and phones will restart upon receipt of the Event. If the setting is disabled, the phones will not restart upon receipt of the Event.

When phones are configured with the DPMA, this setting is not available. Instead, the DPMA provides the capability to remotely reconfigure Digium phones from the Asterisk CLI and via AMI.

The SIPp test tool can be used with the following scenario file:

 SIPp Reconfigure checksync.xml
<?xml version="1.0" ?>
<scenario name="Reconfigure">
 <send>
  <![CDATA[
    NOTIFY sip:[service]@[remote_ip]:[remote_port];ob SIP/2.0
    Via: SIP/2.0/UDP [local_ip]:[local_port];branch=[branch];rport
    Max-Forwards: 70
    From: "asterisk" <sip:asterisk@[local_ip]>;tag=[call_number]
    To: <sip:[service]@[remote_ip]:[remote_port];ob>
    Contact: <sip:asterisk@[local_ip]:[local_port]>
    Call-ID: [call_id]@[local_ip]:[local_port]
    CSeq: 102 NOTIFY
    User-Agent: Asterisk PBX SVN-branch-11-r377355
    Date: Mon, 10 Dec 2012 16:23:50 GMT
    Allow: INVITE, ACK, CANCEL, OPTIONS, BYE, REFER, SUBSCRIBE, NOTIFY, INFO, PUBLISH
    Supported: replaces, timer
    Subscription-State: terminated
    Event: check-sync
    Content-Length: 0
  ]]>
</send>
</scenario>

to programmatically restart Digium phones like:

./sipp 10.24.19.95 -sf checksync.xml -m 1

where 10.24.19.95 represents the IP address of the Digium phone to be restarted.

Option 60

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

digium_[model]_[firmwareversion]

e.g.

digium_D40_1_1

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.

Icon

Note that this is not possible in firmwares prior to 1.1.3; for those firmwares, any provisioning via Option 66 will not cause the phone to contact DPMA or Switchvox servers.

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 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:

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

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.

Icon

If you use this format, leave the "sip:proxy" user:pass intact, and instead only modify the Hostname/IP address and port. The default port for Asterisk with the DPMA is 5060. The default port for Switchvox, when used with Digium phones is 5062

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.

Icon

The config_server_url setting tells the phone to contact, either via DPMA and Switchvox SIP MESSAGE communication or via cURL request for XML, the specified server for its final provisioning information.

Here is an example using the config_server_url setting for DPMA and Switchvox:

 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>

Option

Values

Description

config_server_url

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

and

Here is an example using the config_server_url setting for standard XML (non-DPMA, non-Switchvox) 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>

Option

Values

Description

config_server_url

[protocol://][user:password@]server[:port][/path]

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:

 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>
  • No labels