Phones - DPMA Configuration

Phones, Lines, Applications, Ringtones, Alerts, Firmware and Translations are configured in the res_digium_phone.conf configuration file – normally located at /etc/asterisk/res_digium_phone.conf. The file contains one reserved section:

[general]

The [general] section contains settings that are specific to the operation of the DPMA itself.

Ten other section types are available for user configuration, each contains a type definition. The type definition determines the function of the section. The ten types are:

network
phone
line
external_line
application
ringtone
alert
firmware
translation
multicastpage

network contains all settings for a network profile, to be applied to a phone
phone sections contain all settings for a phone profile.
line sections contain all settings for a line to be applied to a phone
external_line sections contain all settings for registration to an external SIP server, e.g. another Asterisk machine, to be applied to a phone
application sections contain all settings for a particular application that's running on a Sangoma phone, e.g. the Queues application, to be applied to a phone
ringtone sections contain all settings for a particular tone, to be applied to a phone
alert sections contain all settings for a ringtone to be combined with a particular info message and a ringing type, to be applied to a phone
firmware sections contains settings for a firmware file, to be applied to a phone
translation sections contain all settings for a translation set, to be used in an application that is then applied to a phone

multicastpage sections contain all settings for a multicast listener, to be applied to a phone

The network, phone, line, external_line, application, ringtone, alert, firmware, translation and multicastpage sections of res_digium_phone.conf are defined by a section identifier encapsulated in square brackets and are user-definable.

Example

This is an example, using invalid options and functions, of a res_digium_phone.conf configuration file, displaying the organizational layout. The various options and functions are described later in this page.

Example res_digium_phone.conf layout.

[general]
; comments are preceded by a semicolon
;
; the general section contains many options
generaloption=value
generaloption2=othervalue
;
[MyNetwork] ; A network
type=network
; Network options go here
networkoption=value
networkoption2=othervalue
;
[MyPhone] ; A phone
type=phone
; Phone options go here
phoneoption=value
phoneoption2=othervalue
;
[MyAccount] ; A SIP endpoint from pjsip.conf
type=line
; Line options go here
lineoption=value
lineoption2=othervalue
;
[MyExternalAccount] ; An external SIP registration
type=external_line
; External Line options go here
externallineoption=value
externallineoption2=othervalue
;
[MyApplication] ; An application
type=application
; Application options go here
applicationoption=value
applicationoption2=othervalue
;
[MyRingtone] ; A ringtone
type=ringtone
; Ringtone options go here
ringtoneoption=value
ringtoneoption2=othervalue
;
[MyAlert] ; An alert
type=alert
; Alert options go here
alertoption=value
alertoption2=othervalue
;
[MyFirmware] ; A firmware
type=firmware
; Firmware options go here
firmwareoption=value
firmwareoption2=othervalue
;
[MyTranslation] ; A translation
type=translation
; Translation options go here
translationoption=value
translationoption2=othervalue
;

[MyMulticastPage] ; A multicastpage
type=multicastpage
; Multicastpage options go here
multicastpageoption=value
multicastpageoption2=othervalue

Affecting Change

As with other Asterisk modules, If you make changes to the res_digium_phone.conf configuration file on a running system, those changes will not be reflected in Asterisk until you reload the DPMA module. To reload the DPMA module perform:

pbx*CLI> module reload res_digium_phone.so

In response, you should see:

Module 'res_digium_phone.so' reloaded successfully.
    -- Reloading module 'res_digium_phone.so' (Digium Phone Module for Asterisk)

Further, just because changes have been loaded into DPMA at the Asterisk level, those changes are not necessarily reflected on the phone itself. To affect those changes on the phone, you will need to issue a reconfigure command to the phone. To issue a reconfigure command to the phone, where the phone's identifier is 101, perform:

pbx*CLI> digium_phones reconfigure phone 101

In response, you'll see:

Phone 'Your phone name' will reconfigure shortly.

Other sections of this wiki outline the available CLI and AMI capabilities of DPMA.

Authentication Options

The General Section provides the following options related to authentication:

Option	Values	Description

Option	Values	Description
server_uuid	String	Sets a unique identifier for this server. Used, notably, inside the voicemail application for forwarding to contacts associated with this server. Optional, no default. If server_uuid is set in the general section, it must also be set for individual contacts. If it is only set in one location (general or contact) instead of both, forwarding of voicemails to contacts is not permitted.
globalpin	integer; e.g. 10101019	If userlist_auth is set to globalpin, sets the PIN that must be entered on a phone, at boot, in order to retrieve the list of available phone configurations. If config_auth is set to globalpin, sets the PIN that must be entered on a phone, at the userlist screen, in order to request a particular phone configuration - note that if the globalpin has already been entered to authenticate to retrieve the list of available phone configurations, that it will not required a second time in order to request a particular phone configuration. If group_pin is used for phones, and userlist_auth and config_auth are set to globalpin, then entry of the globalpin will show all phones for all groups
userlist_auth	disabled, globalpin	Specifies the kind of authentication required to retrieve the list of available phone profiles from the provisioning server. Options are "disabled," where no authentication is required to retrieve the list of phone profiles; and "globalpin," where entry of the Global PIN or a group_pin is required in order to retrieve a list of phone profiles. If the globalpin is entered by a phone user to retrieve the user list, all phones configured in the DPMA will be shown. If, instead, a group_pin is entered, only the phones with matching group_pins will be shown.
config_auth	mac, pin, globalpin, disabled	Specifies the kind of authentication required to retrieve a phone's configuration from the provisioning server. Options are "mac," where the MAC address of the device requesting the configuration must match the phone profile, and if it does, the phone will be automatically provisioned with the matching phone profile; "pin" where the entered PIN must match the phone profile; "globalpin," where the entered PIN must match the Global PIN or a group_pin; and disabled, where profiles are served without authentication - with this setting, any phone can pull any phone profile defined in this configuration file with no authentication challenges.

mDNS Discovery Options

The General Section provides the following options related to mDNS / Avahi Service Discovery:

Option	Values	Description

Option	Values	Description
mdns_address	IP address or Hostname	The registration address provided by DPMA to Avahi. This is the address to which phones discovering DPMA by using mDNS will contact for SIP communications
mdns_port	Port, as an Integer; e.g. 5060	The registration port provided by DPMA to Avahi. This is the port to which phones discovering DPMA by using mDNS will connect for SIP communications
mdns_transport	udp, tcp, tls	Sets the transport type provided by DPMA to Avahi. This is the transport type to which phones discovering DPMA by using mDNS will connect for SIP communications. Defaults to udp. Using tls or tcp as a transport for phones attached to DPMA requires Asterisk 13.11.0 or greater.
service_name	string, e.g. Sangoma Phones Config Server	The name of the service to be used in Avahi service discovery. Defaults to "Digium Phones Config Server" when service_discovery_enabled, mdns_address and mdns_port are set.
service_discovery_enabled	yes / no	If set to yes, will advertise the config server using Avahi. Defaults to yes. The Discovery Service will only be enabled when registration_address and registration_port are explicitly configured.

Files Options

The General Section provides the following options related to Files:

Option	Values	Description

Option	Values	Description
file_directory	path, e.g. /var/lib/asterisk/digium_phones	Specifies a folder from which phones can retrieve Display Rules XML files. Defaults to /var/lib/asterisk/digium_phones

Other Options

The General Section provides the following other options:

Option	Values	Description

Option	Values	Description
pjsip_message_context	A dialplan context addressable by PJSIP	The dial plan context used for routing PJSIP messages so that conflicts found in pjsip.conf can be avoided. Defaults to dpma_pjsip_message_context
transaction_initial_threads	Integer	Initial number of threads to handle transactions with. Defaults to 1
transaction_max_threads	Integer	Maximum number of threads to handle transactions with. Threads are created as needed by a threadpool. Defaults to 4.

Example

In this example:

The general section has been configured with a Global PIN of 344486 (DIGIUM)
Userlist authentication has been disabled
Config Authorization has been set to PIN
The Avahi service name has been set to "Go 4 Phones" with discovery enabled and is pointing to 10.1.2.3 on port 5060
Files are stored in /var/lib/asterisk/digium_phones

Example General Section configuration.

[general]
server_uuid=abcdefg123
globalpin=344486
userlist_auth=disabled
config_auth=pin
mdns_address=10.1.2.3
mdns_port=5060
mdns_transport=udp
service_name=Go 4 Phones
service_discovery_enabled=yes
file_directory=/var/lib/asterisk/digium_phones

Network Configuration Options

Network profiles are configured by defining a context with type option equal to "network." A Network profile contains provisioning information specific to a CIDR-numbered network. When the Sangoma phone boots, it compares its network address to the CIDR addresses defined for each of its network profiles, and the phone choses to use the provisioning information specific to the network on which it is located. Network profiles allow administrators to gracefully handle situations where the movement of a Sangoma phone causes the registration address (and/or other information) of the Asterisk server to change.

A Network Is Required

Definition of a network is mandatory. Older versions of the DPMA, prior to DPMA 1.2, did not require a network section. DPMA beginning with 1.2 requires a network section.

It is good practice to create a network with a CIDR of "0.0.0.0/0" When thus set, the phone is configured with a network that it will use when no other networks are matched - a wildcard network.

More than one Network profile may be assigned to a Sangoma phone.

Option	Values	Description

Option	Values	Description
alias	String, e.g. MyNetwork	The name for the network, viewable in the phone's preferences menu
cidr	CIDR noted network, e.g. 198.51.100.1/24	A CIDR-formatted network address
registration_address	IP address or Hostname	Allows for explicit definition of the address to which phones should register.
registration_port	Port, as an Integer; e.g 5060	The port on which the registration server is running – the same port on which SIP is running on the Asterisk instance.
transport	udp, tcp, tls	Sets the transport type for communications using this network. Defaults to udp. Using tls or tcp as a transport for phones attached to DPMA requires Asterisk 13.11.0 or greater.
alternate_registration_address	IP address or Hostname	Optional. If defined, the address to which phones will maintain a backup registration. If the primary server becomes unavailable, calls will be directed to this alternate host.
alternate_registration_port	Port, as an Integer; e.g. 5060	Optional. If defined along with alternate_registration_address, the port to be used for the backup registration.
alternate_transport	udp, tcp, tls	Sets the transport type for communications using the alternate host. Defaults to udp.
file_url_prefix	URL, e.g. http://10.10.10.10/file_package_directory	Specifies the URL prefix the phone module should use to tell the phones where to retrieve firmware, logo, ringtone, contacts and blf items files. Sangoma phones support basic authentication, so a username and password may be passed in the URL line, e.g. http://user:pass@server.example.com
public_firmware_url_prefix	URL	Specifies the URL prefix the phone should use, if public_firmware for a firmware profile is set to yes, to download firmware if the phone fails to retrieve a given firmware from the location specified in its firmware profile. This will default to a publicly accessible site hosted by Sangoma (address: http://dphone.dl.digium.com/firmware/asterisk/ ) if it isn't specified manually. When using firmwares from a public firmware repository, the path will always use the following pattern: public_firmware_url_prefix/VERSION/VERSION_MODEL_firmware.eff
ntp_server	hostname, IP address, e.g. ntp.mycompany.com	Defines the NTP server to which phones will synchronize themselves
syslog_server	hostname, IP address, e.g. syslog.mycompay.com	Defines a remote server to which syslog message are sent. Defaults to none.
syslog_port	port, as an integer, e.g. 514	Port to which syslog messages are sent. Defaults to 514.
syslog_level	debug, error, warning, information	Logging level for syslog messages
network_vlan_discovery_mode	NONE, MANUAL, LLDP	Sets use of none, manual, or LLDP discovered VLAN and, if MANUAL, defines the network; defaults to LLDP
sip_qos	Integer (0-7)	Sets the SIP QoS level. Defaults to 3
rtp_qos	Integer (0-7)	Sets the RTP QoS level. Defaults to 6
network_vlan_id	Integer (0-4095)	Sets the VLAN identifier of the network port
pc_vlan_id	(Integer (0-4095)	Sets the VLAN identifier of the PC port
pc_qos	Integer (0-7)	Sets the QoS level for PC port traffic. Defaults to 0.
sip_dscp	Integer (0-63)	Specifies the DSCP field of the DiffServ byte for SIP Signaling QoS, defaults to 24
rtp_dscp	Integer (0-63)	Specifies the DSCP field of the DiffServ byte for RTP Media QoS, defaults to 46
udp_ka_interval	Integer in seconds	Defines the interval at which, for the UDP transport, phones using this network will send a lightweight keep-alive to the registered server. Defaults to 0, never.

Example

In this example:

a network, "MyNetwork" is defined
the CIDR for the network is 192.168.50.0/24
the Registration server is set to 10.10.10.10 on port 5060 using udp
the Alternate / Backup Registration server is set to 192.168.50.1 on port 5080 using udp
files will be retrieved from http://10.10.10.10/digium_phones_files
the backup location for firmware retrieval is http://dphone.dl.digium.com/firmware/asterisk/
the phone's NTP server is set to 0.digium.pool.ntp.org
the phone does not configure syslog messages
the phone is set to manually assign itself to a VLAN
the phone's SIP QoS is set to 3
the phone's RTP QoS is set to 6
the phone's network port VLAN is set to 4
the phone's pc port VLAN is set to 10
QoS for the phone's pc port is set to 2
the DSCP field for SIP signaling is set to 24
the DSCP field for RTP media is set to 46
the phone will send a keep-alive to the server every 60 seconds

Example Network Configuration.

[network1]
type=network
alias=My Default Network
cidr=192.168.50.0/24
registration_address=10.10.10.10
registration_port=5060
transport=udp
alternate_registration_address=192.168.50.1
alternate_registration_port=5080
alternate_transport=udp
file_url_prefix=http://10.10.10.10/digium_phones_files
public_firmware_url_prefix=http://dphone.dl.digium.com/firmware/asterisk/
ntp_server=0.digium.pool.ntp.org
network_vlan_discovery_mode=MANUAL
sip_qos=3
rtp_qos=6
network_vlan_id=4
pc_vlan_id=10
pc_qos=2
sip_dscp=24
rtp_dscp=46
udp_ka_interval=60

Phone Configuration Options

Phones profiles are configured by defining a context with type option equal to "phone." A Phone profile can have any number of lines associated with it. Each line defined in the configuration is reflected as a separate line key on the phone; and, when provisioned, is ordered on the phone itself as it is in the profile configuration.

The first line key associated with a Phone profile is set internally as the phone's primary line. The primary line is the only one listed in the User list on boot up. The primary line is also used to automatically match the phone to voicemail boxes.

The following options are provided for Phone configuration:

Option	Values	Description

Option	Values	Description
network	entity defined as "network" type in res_digium_phone.conf.	Assigns a network profile to a phone. More than one network can be assigned to a phone by using multiple network lines
firmware	entity defined as "firmware" type in res_digium_phone.conf	Assigns a firmware to a phone. More than one firmware can be assigned to a phone, provided that each firmware is for a different model, by using multiple firmware lines
mac	A MAC address, e.g. 0123456789ab	Optional. When set, and when the general config_auth option requires MAC, locks a phone configuration to a device matching this MAC address.
pin	integer, e.g. 10101019; or "voicemail"	Optional. When set, and when the general config_auth option requires PIN, one must enter this PIN on the phone before being able to pull the phone's configuration. If set to "voicemail" will tie the phone's pin to the voicemail account password, from voicemail.conf, as defined for the SIP peer, for flat-file configurations without externally maintained passwords only, used for the phone's primary internal line.
group_pin	integer; e.g. 101010109	Optional. When set, and when the general config_auth and userlist_auth options are set to globalpin, assigns this phone a group pin. When the group pin is input by the user, all phones with a matching group_pin will appear in the list of available phone profiles
line	entity defined as line in res_digium_phone.conf	Maps directly to a PJSIP endpoint entry. More than one line may be defined for a phone configuration. The first line entry defined is adopted as the phone's primary line.
external_line	entity defined as external_line in res_digium_phone.conf	Maps directly to an external_line defined in this configuration file. External line are lines not defined by SIP peers in sip.conf and generally do not register to this instance of Asterisk. If an external line is defined as the primary extension for a phone, many of the advanced phone application features will be disabled
application	Application section name identifier	Applies application-specific settings to a phone configuration. Multiple application options can exist in a single phone configuration
config_file	file, e.g. mycustomconfig.xml	The phone module automatically generates a configuration file for each phone based on the lines assigned to it; but, it is possible to supply a custom configuration file instead. Using this option will direct the DPMA to serve up the specified file, as found in the file_directory defined directory, to the phone. Note that using a custom configuration file, as opposed to the provisioning generated by the DPMA, precludes the phone's use of DPMA-specific applications, e.g. voicemail, parking, user status, etc. This option allows users to make use of the DPMA's mDNS provisioning capabilities, providing a simpler alternative to HTTP and Option 66 provisioning, but sacrifices the DPMA-specific features.
full_name	string, e.g. Bob Johnson	The full name of the person who will be using this phone, and what will appear in the user list that the phone pulls
contact	file, e.g. contacts.xml	An XML file, retrievable from the file_url_prefix, containing a list of contacts to serve to the phone. Multiple contact options can exist in a single phone configuration.
contacts_display_rules	file, e.g. mydisplayrules.xml	An XML file in the file_directory containing rules that control the display of actions when viewing a contact.
blf_contact_group	string, a group from contacts	Every contacts xml file will have at least one group defined in it. This setting controls which loaded group the phone should subscribe to for its Rapid Dial (BLF) keys. If this setting is blank, the phone will not subscribe for any device state or presence updates and LED indicators will not light.
blf_items	file e.g. blfitems.xml	An XML file, retrievable from the file_url_prefix, containing a list of items to be displayed on the phone's BLF keys. Only one blf_items option can exist in a single phone configuration. This option should note be used with phones possessing firmware older than 1.4, otherwise phones will end up in a boot loop.
blf_page_return_timeout	integer, time in seconds	An integer value representing the number of seconds until BLF page retrieval times out. Upon reaching the specified timeout the first page of BLF pages is shown. Defaults to 0 (never).
contacts_max_subscriptions	integer, e.g. 40	Sets the maximum number of SUBSCRIBEs a phone can perform; defaults to 40
timezone	Timezone String, e.g. America/Chicago	Sets the timezone used for the clock on this phone.
ntp_resync	seconds as integer, e.g. 86400	Defines the interval between NTP synchronization
parking_exten	extension, e.g. 700	Sets the extension used for parking calls. When this option is set, and the phone has an in-progress call, it will display a "Park" softkey, allowing for one touch parking.
parking_transfer_type	blind / attended	The type of transfer to perform when parking a call using the "Park" softkey.
show_call_parking	yes / no	Enables the built-in call parking application. When disabled, the one touch call parking softly is shown, if parking_exten is set, but the Parking Lot notice screen nor the Parking Lot applications are available from the phone's application menu.
ringtone	context name of a type=ringtone identifier	Loads ringtones onto a phone. More than one ringtone may be loaded onto a phone.
active_ringtone	Alarm, Chimes, Digium, GuitarStrum, Jingle, Office2, Office, RotaryPhone, SteelDrum, Techno, Theme, Tweedle, Twinkle, Vibe or the context name of a type=ringtone identifier that has been loaded onto the phone using the ringtone option	Sets the active ringtone for the phone, defaults to Digium.
web_ui_enabled	no / yes	By default, when using the Desk Phone Module for Asterisk, the phone's built-in Web UI is disabled. To override this and enable the Web UI anyway, which may result in unpredictable behavior if user settings conflict with the settings provided by the DPMA, enable this option.
record_own_calls	no / yes	When this option is enabled, and the phone has an in-progress call, it will display a "Record" softkey, allowing for one touch call recording. Disabled by default.
can_forward_calls	yes / no	When this option is disabled, the phone will not display the Call Forward application in the applications menu. Supported beginning with phone firmware 1.4.1
show_call_log	yes / no	When this option is disabled, the phone will not display the Call Log application in the applications menu or the associated soft key on the idle screen. Supported beginning with phone firmware 1.4.1.
logout_enabled	yes / no	When this option is enabled, the phone will load its LogOut application into the applications menu. Supported on D6x models beginning with firmware 2.5.0.
alert	Alert section name identifier	Defines Alerts to be applied to this phone profile. More than one Alert may be applied by specifying additional alert lines.
multicastpage	Mutlicastpage section name identifier