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:
In response, you'll see:
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 |
---|---|---|
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 |
---|---|---|
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 |
---|---|---|
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 |
---|---|---|
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.
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 |
---|---|---|
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 | 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.
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 |
---|---|---|
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 | Defines Multicastpage listeners to be applied to this phone profile. More than one Multicastpage listener may be applied by specifying additional multicastpage lines. |
blf_unused_linekeys | no / yes | Sangoma phones, by default, place BLF keys on the sidecar, not on unused line keys. To disable this behavior and allow BLF keys to start mapping from the next available unused line key, enable this option. |
send_to_vm | yes / no | Disabling this option hides the "Send VM" softkey during incoming calls and the "Transfer VM" softkey inside the Contacts application during call transfers. Enabled by default. |
d40_logo_file | string | The idle screen image for a D40 model phone in PNG format, 150x45 pixels, 8-bit depth, a color type without alpha transparency and less than 10k in size. Retrieved from the file_url_prefix. The D40, D45 and D50 screen size is the same; therefore it is permissible to re-use the same logo file for each. |
d45_logo_file | string | The idle screen image for a D45 model phone in PNG format, 150x45 pixels, 8-bit depth, a color type without alpha transparency and less than 10k in size. Retrieved from the file_url_prefix. The D40, D45 and D50 screen size is the same; therefore, it is permissible to re-use the same logo file for each. |
d50_logo_file | string | The idle screen image for a D50 model phone in PNG format, 150x45 pixels, 8-bit depth, a color type without alpha transparency and less than 10k in size. Retrieved from the file_url_prefix. The D40, D45 and D50 screen size is the same; therefore it is permissible to re-use the same logo file for each. |
d60_logo_file | string | The idle screen image for a D60 model phone in PNG format, 296x128 pixels, 8-bit depth, a color type without alpha transparency and less than 10k in size. Retrieved from the file_url_prefix. |
d62_logo_file | string | The idle screen image for a D62 model phone in PNG format, 296x128 pixels, 8-bit depth, a color type without alpha transparency and less than 10k in size. Retrieved from the file_url_prefix. |
d65_logo_file | string | The idle screen image for a D65 model phone in PNG format, 296x128 pixels, 8-bit depth, a color type without alpha transparency and less than 10k in size. Retrieved from the file_url_prefix. |
d70_logo_file | string | The idle screen image for a D70 model phone in PNG format, 205x85 pixels, 8-bit depth, a color type without alpha transparency and less than 10k in size. Retrieved from the file_url_prefix. |
d80_logo_file | string | The idle screen image for a D80 model phone in PNG format, 800x1280 pixels. Retrieved from the file_url_prefix. |
wallpaper_file | string | The wallpaper image for a D6x model phone in PNG format, 480x272 pixels, 8-bit depth, a color type without alpha transparency and less than 50k in size. Retrieved from the file_url_prefix. |
ehs | auto, plantronics, jabra_iq | Sets the electronic hookswitch device type. |
lock_preferences | yes / no | Enabling this option locks phone preference settings to the DPMA supplied settings. Enabling this option also hides phone preference menus for menu items that are set in the Phone profile. Disabled by default |
login_password | Integer, e.g. 789 | Sets the Admin Password for logging into Web UI or Admin Settings Section on Phone Menu, defaults to 789 |
accept_local_calls | any, host | Sets whether to accept calls from any source or only from hosts to which the phone is registered |
display_mc_notification | yes / no | Enables / Disables display of missed calls on the phone, defaults to Enabled |
idle_company_text | String | When set, allows control over the text string seen on idle screens in the status bar. D6x phones only, beginning with firmware 2.2.1.4. Defaults to null. |
small_clock | yes / no | Enables / Disables display of the small-format clock on a D6x phone's idle screen. Defaults to disabled (show large clock). |
default_fontsize | integer, e.g. 10 | Sets the default font size for the phone. Caution should be exercised when using this option as larger sizes will cause labels to overrun their allowed space. D40, D45 and D50 default to 10. D70 defaults to 11. |
brightness | Integer, 0-10 | Sets the LCD screen brightness, defaults to 5 |
contrast | Integer, 0-10 | Sets the LCD screen contrast, defaults to 5 |
dim_backlight | yes, no | Enable backlight dimming. When enabled, dims the screen after backlight timeout has been reached and phone is otherwise idle. Defaults to enabled |
backlight_timeout | Integer (0-3200) | Time, in seconds, before backlight is set to backlight_dim_level while phone is idle; setting to 0 disables backlight timeout, defaults to 0 |
backlight_dim_level | Integer (0-10) | Brightness level dims to when when dim_backlight is enabled, defaults to 2. |
active_locale | de_DE, en_AU, en_CA, en_GB, en_NZ, en_US, es_ES, es_MX, fr_BE, fr_CA, fr_FR, it_IT, nl_BE, nl_NL, pt_BR, pt_PT, ru_RU | Specifies the locale used by the phone, defaults to en_US. ru_RU applies only to D6x models of phones. |
ringer_volume | Integer (0-10) | Sets the ringer volume, defaults to 5 |
speaker_volume | Integer (0-10) | Sets the speaker volume, defaults to 5 |
handset_volume | Integer (0-10) | Sets the handset volume, defaults to 5 |
headset_volume | Integer (0-10) | Sets the headset volume, defaults to 5 |
call_waiting_tone | yes / no | If disabled, the phone will not play a call waiting tone when it receives a new call while already on a call. |
handset_sidetone_db | Integer, e.g. -25 | Sets the gain, in negative dBs, for sidetone presented on the phone's handset. Defaults to -25. Sangoma cautions against changing this value. |
headset_sidetone_db | Integer, e.g. -15 | Sets the gain, in negative dBs, for sidetone presented on the phone's headset. Defaults to -15. Sangoma cautions against changing this value. |
reset_call_volume | yes / no | If enabled, volume changes made during a call do not persist to the next call, defaults to disabled |
headset_answer | yes / no | Sets whether to use the headset, rather than the speaker, for answering all calls, defaults to disabled |
ring_headset_only | yes / no | Sets whether or not to play ringing tone out the headset, instead of the loudspeaker. Note that adjusting the ringing volume while ringing is playing out the headset port will cause ringing tone to play out the loudspeaker. |
name_format | first_last, last_first | Formats the display of contact names, defaults to first_last |
lan_port_mode | auto, 10hd, 10fd, 100hd, 100fd, 1000fd | Sets the port speed of the phones' LAN port. Available options depend on phone model. Defaults to auto |
pc_port_mode | auto, 10hd, 10fd, 100hd, 100fd, 1000fd, off | Sets the port speed of the phones' PC port. Available options depend on phone model. When set to off, the PC port will be disabled. Defaults to auto |
enable_check_sync | yes / no | Defaults to yes. If disabled, phones will not respond to check-sync SIP Events. |
8021x_passthrough | 1 / 0 | Defaults to 0. If set to 1, phone will allow EAPOL packets to cross from PC port to LAN port. |
8021x_eapol_on_disconnect | 1 / 0 | Defaults to 0. If set to 1, phone will keep track of EAPOL logins from PC-port attached devices and send a logoff on behalf of the attached MAC address when the PC-port device disconnects |
8021x_method | null, eap-md5, peap-mschap, eap-tls, peap-gtc, ttls-mschap, ttls-gtc | Sets the method of 802.1X authentication for the phone, defaults to null (none). |
8021x_identity | null, string | Sets the 802.1X authentication identifier (username), defaults to null (none). |
8021x_anonymous_identity | null, string, PHONE_MAC | Â Sets the 802.1X anonymous authentication identifier (username), defaults to null (none), can be set to "PHONE_MAC" to pass phone's MAC address |
8021x_password | null, string | Sets the 802.1X authentication password, defaults to null (none) |
8021x_client_cert_url | null, http(s) or ftp(s) URL | Sets the URL the phone will cURL its 802.1X client certificate from |
8021x_client_cert_value | string | Sets the local name the phone should use when storing the certificate. Phone will retrieve a new certificate when factory defaulted or when value changes. |
8021x_root_cert_url | null, http(s) or ftp(s) URL | Sets the URL the phone will cURL its 802.1X root (CA) certificate from |
8021x_root_cert_value | string | Sets the local name the phone should use when storing the certificate. Phone will retrieve a new certificate when factory defaulted or when value changes. |
8021x_debug | null, -d, -dd | Sets the debug level to be used when troubleshooting 802.1X authentication errors. Phone will generate error report that can be utilized by Sangoma Support. Phone should not be configured to operate in this mode on an ongoing basis as it will generate excessive messages. Defaults to null (none) |
codecs | null, PCMU, PCMA, G722, G7221, G726-32, opus, G729, iLBC, L16, L16-256 | Enables or disables codecs and sets the codec priority. To disable, prefix a codec name with an "!". Earlier entries have higher priority. Not all codecs apply to all models of phones. |
openvpn_enable | 0, 1 | When enabled, and when necessary config files are present, the phone will run the OpenVPN client on boot. Applies to D6x models of phones. |
openvpn_config_file_url | null, http(s) or ftp(s) URL | Sets the URL the phone will cURL its OpenVPN client configuration file from |
openvpn_config_file_value | string | Sets the local name the phone should use when storing the openvpn configuration file. Phone will retrieve a new config file when factory defaulted or when value changes. |
openvpn_root_cert_url | null, http(s) or ftp(s) URL | Sets the URL the phone will cURL the OpenVPN CA cert from |
openvpn_root_cert_value | string | Sets the local name the phone should use when storing the openvpn root certificate. Phone will retrieve a new certificate file when factory defaulted or when value changes. |
openvpn_client_cert_url | null, http(s) or ftp(s) URL | Sets the URL the phone will cURL the OpenVPN client certificate from |
openvpn_client_cert_value | string | Sets the local name the phone should use when storing the openvpn client certificate. Phone will retrieve a new certificate file when factory defaulted or when value changes. |
openvpn_client_key_url | null, http(s) or ftp(s) URL | Sets the URL the phone will cURL the OpenVPN client key from |
openvpn_client_key_value | string | Sets the local name the phone should use when storing the openvpn client key. Phone will retrieve a new key file when factory defaulted or when value changes. |
transport_tls_allowed | Boolean, defaults to null | Allows TLS signaling to be disabled or explicitly enabled. Defaults to null (use phone default). |
expansion_enabled | yes / no | If enabled, causes a D65 to enable its EXP150M sidecar control daemon. Defaults to no. |
expansion_page_indicators_enabled | yes / no | If enabled, causes the EXP150M to display page indicators when items on the non-visible page are active. Defaults to no. |
Example
In this example:
the phone is assigned to a network called MyNetwork
the phone is configured to use a firmware called 1.1Firmware
the phone configuration is set for a phone whose MAC address matches 01:23:45:67:89:ab
the phone configuration has a PIN of 10101019
the phone has a group PIN of 1234
the phone's primary line is a line named bob101, mapped to PJSIP endpoint bob101
the phone's secondary line is a line named bob102, mapped to PJSIP endpoint bob102
the phone has an external line called bobexternal
the phone will load the application called queue-bob-1234
the phone will load the application called available-working
the phone will load the application called available-nopants
the phone will load the application called parking-sales
the phone will load the application called voicemail_for_de_DE
the phone does not load an external configuration file
the full name of the phone is Bob's Phone
the phone loads a contacts XML file named bobscontacts.xml
the phone loads a contacts display rules file called bobsdisplayrules.xml
the phone uses a contact group, from bobscontacts.xml, named "RapidDial" for its BLF keys
the phone loads a BLF Items file called bobsblfitems.xml
the phone will return to the first page of BLF results, if it's a D65, after 30 seconds
the phone is configured to allow 50 Contacts BLF subscriptions
the phone is set for the "America/Los_Angeles" timezone
the phone's NTP resynchronization time is 86400
the phone will blind transfer parked calls to extension 700
the phone's parking lot application will be visible
the phone loads a ringtone called FancyTone
the phone's active ringtone is a Guitar Strum
the phone's Web UI is disabled
one touch call recording is enabled
the call forward application is enabled
the call log application is enabled
the phone has been configured with an Alert called fancyringer
the phone's Rapid Dial keys will begin from the side car
the phone's Send VM and Transfer VM keys are enabled
the phone stores contacts on the server
if the phone claiming the profile is a D40, it will use the logo file d40_logo.png
if the phone claiming the profile is a D50, it will use the logo file d50_logo.png
if the phone claiming the profile is a D70, it will use the logo file d70_logo.png
if the phone claiming the profile is a D80, it will use the logo file d80_logo.png
if the phone is a D6x model, the phone will display a wallpaper my_wallpaper.png
the phone's EHS is set to auto, to operate with any of the supported EHS types
the phone's preferences are locked to the server's settings
the phone's login password id 1234
the phone will only accept local calls
the phone will display missed call notifications
the phone will display an idle company text of Office Phone
if the phone is a D6x model, the phone will display a small clock
the phone's brightness is 5
the phone's contrast is 5
the phone's backlight will dim
the phone's backlight will dim after 30 seconds
the phone's backlight will dim to 2
the phone's active_locale is de_DE
the phone's ringer is at level 5
the phone's speaker volume is 5
the phone's handset volume is 5
the phone's headset volume is 5
the phone's volume does not reset after calls
the phone will play a call waiting tone
the phone does not answer to the headset by default
the phone sends ringing tone to the loudspeaker
the phone's contacts will show up lastname, firstname
the phone's lan port is set to auto-negotiate
the phone's pc port is set to 100 megabit, full-duplex operation
the phone will respond to check-sync Events
Example Phone Configuration.
Line Configuration Options
Internal lines are PJSIP endpoints, but there is Sangoma Phone-specific data associated with lines that does not otherwise exist in PJSIP. Because of this, advanced line features must be defined separately from pjsip.conf, here, in res_digium_phone.conf. Advanced line configuration is not a requirement to get a line to work, it only acts as a method of setting advanced phone features to an already-defined pjsip.conf entry.
Option | Values | Description |
---|---|---|
exten | string, e.g. 1000 | When the PJSIP endpoint name is different than the actual extension used to contact this line, this option should be set to the line's dialable extension. By default it is assumed that the PJSIP endpoint is actual dialable extension, which is true for most Asterisk distributions such as FreePBX and AsteriskNOW, but is not considered a best practice for use of generic Asterisk. |
digit_map | Digit mapping, see #dialplans | The digit mapping to use for this line. |
line_label | string, e.g. MD 123 | The line label to display on the phone for this line's line key. |
mailbox | mailbox from voicemail.conf | The voicemail box associated with the line. When not set, this will default first to the mailbox defined for the PJSIP endpoint associated with the line, and second to a mailbox entry in voicemail.conf matching the name of the line. If neither of these are found and this option is not set, the line does not have a mailbox and visual voicemail will not be enabled. If PJSIP endpoints are stored using Sorcery rather than the flat pjsip.conf file, then the mailbox to which the PJSIP endpoint is assigned must be specified here, as it cannot be retrieved by the DPMA from Sorcery . |
voicemail_uri | string, sip:user@host | If the phone's Msgs button should dial a SIP URI rather than opening the visual voicemail application, this option specifies what URI the Msgs button should dial. Setting this option on a phone's primary lie will disable visual voicemail. |
outboundproxy_address | Host / IP address | The Outbound SIP proxy address this line should use |
outboundproxy_port | Port as integer | The port of the Outbound SIP proxy; defaults to 5060 when outboundproxy_address is set |
transport | udp, tcp, tls | SIP transport method this line should use. If not specified, the network transport is preferred. Using tls or tcp as a transport for phones attached to DPMA requires Asterisk 13.11.0 or greater. |
media_encryption | null, sdes | Specifies media encryption protocol. Can be set to sdes, defaults to not set (none). |
reregistration_timeout | integer, e.g. 300 | The number of seconds before re-registering |
registration_retry_interval | integer, e.g. 25 | The number of seconds to wait before retrying to register after registration fails. |
registration_max_retries | integer, e.g. 5 | The number of times the phone will attempt to retry registering after registration fails |
secret | string, e.g. mymagicpassword | If PJSIP endpoints are stored using Sorcery rather than the flat pjsip.conf file, then the secret for the PJSIP endpoint mapped to this line must be specified so that the Sangoma phone can be passed the correct PJSIP endpoint credentials. |
context | Asterisk dialplan context | If PJSIP endpoints are stored using Sorcery rather than the flat pjsip.conf file, then the dialplan context to which the PJSIP endpoint is assigned must be specified so that dialplan hints can be properly created by DPMA. |
callerid | caller id string, e.g. "Bob Jones" <1234> | If PJSIP endpoints are stored using Sorcery rather than the flat pjsip.conf file, then the caller ID for the PJSIP endpoint mapped to this line should be specified so that the Sangoma phone can be provided with a proper Caller ID. |
subscribecontext | Asterisk dialplan context | Allows for overriding of the line's subscription context. If defined here will override the setting from Asterisk's PJSIP configuration |
plar_number | Dialable Number | When set, specifies a number that will be automatically dialed when this line is taken off hook on the phone. Defaults to null (do not automatically go off-hook and dial a number). D6x models beginning with firmware 2.2.1.4. |
Example
In this example:
the Digit Mapping for the phone is set to [0-8]xxx
The Label for the line, as it appears on the phone is BobbyJ
The Mailbox for the line is bob101
the Outbound Proxy is 10.10.10.1 and its port is 5060.
The Transport type for the signaling is TCP
Media Encryption is enabled
The Re-registration timeout is 300 seconds
The Registration Retry Interval is 25 seconds
The Maximum Registration Retries is 5 times
Example Line Configuration.
Â
If PJSIP endpoints are configured using the Sorcery data storage mechanism, then the secret, context, and mailbox parameters must be populated.
External Line Configuration Options
External lines are external to this Asterisk instance; they are lines that are not entries in sip.conf. The external line concept exists to work around the forcing of lines as sip.conf peers. Since external lines are not SIP peers, they require more information than normal line configurations. Here are the external line-specific configuration options.
Note that all internal line options are also available for external lines; but, any internal line options specific to applications on the phone, such as mailbox to enable visual voicemail, will not work unless the server-side component resides on this Asterisk instance.
Â
Configuring an external line as the primary line for a phone will result in the advanced PBX features being disabled for the phone
Â
Option | Values | Description |
---|---|---|
server_address | string, e.g. otherpbx.othercompany.com | The address this line should contact for registration and outbound calls |
server_port | integer, e.g. 5060 | The port this line should contact for registration and outbound calls. Defaults to 5060 |
transport | udp, tcp, tls | The transport type used for registration and calling to/from the server. Defaults to udp |
secondary_server_address | string, e.g. backuppbx.othercompany.com | The address this line should contact for registration and outbound calls if the primary server is not available |
secondary_server_port | integer, e.g. 5060 | The port this line should contact for registration and outbound calls if the primary server is not available |
secondary_server_transport | tcp or udp | The transport type used for registration and calling to/from the secondary server |
media_encryption | null, sdes | Specifies media encryption protocol. Can be set to sdes, defaults to not set (none). |
userid | string, e.g. bob1234 | This line's SIP username. Defaults to the line's name |
authname | string, e.g. bob1234 | SIP authorization name if different than userid. If blank, defaults to userid. |
secret | string, e.g. mymagicpassword | The SIP secret this line should used |
register | yes / no | Indicates whether or not this line should register |
callerid | string | Caller ID field to use for this line |
Example
In this example:
The address of the external registration server is otherpbx.mycompany.com
The contact port of the external registration server is 5061
The transport method of the external registration server is TCP
The address of the secondary external registration server is otherpbx2.company.com
The contact port of the secondary registration server is 5061
The transport method of the secondary external registration server is UDP
Media Encryption is enabled
The SIP username is bob1234
The SIP authname is bob4321
The SIP password (secret) is mymagicalpassword
Registration is enabled
Caller ID is set to "Bob Jones" <555-1234>
Example External Line Configuration.
Application Configuration Options
Applications represent phone applications, separately applied to phone configurations, requiring parameters that cannot otherwise be inferred by DPMA. Applying an application to a phone configuration enables that application for that phone.
Option | Values | Description |
---|---|---|
application | queue, status, parking, voicemail | The application type name |
Queues Application
The Queues application provides phone users with permission-controlled views into Asterisk's app_queue.
Option | Values | Description |
---|---|---|
queue | string | Asterisk's queue identifier, as configured in queues.conf |
membername | string | Defaults to 'fullname' from the phone type configuration. Allows customization of the queue membername as viewed in the Queues application |
location | Asterisk queue member location, e.g. Local/6002@ext-queue/n | Defines the location of the member, from app_queue.so's perspective. For setups not involving local channels, this may not be required. |
member | yes / no | Defines whether or not the user of this application is also a member of the queue that will receive calls. Defaults to yes. |
permission | status, overview, details | Sets the permission level for this user. Status provides only login/out/pause capabilities. Overview also provides statistical information about a queue. Details also provides information about waiting callers and on-call members. |
login_exten | Asterisk extension@context, e.g. *451234@ext-queue | If defined, sets the extension to be dialed when a user of the application executes a log in command. If not set, the DPMA will use the QueueAdd functionality directly. |
logout_exten | Asterisk extension@context, e.g. *451234@ext-queue | If defined, sets the extension to be dialed when a user of the application eecuted a log out command. If not set, the DPMA will use the QueueRemove functionality directly. |
Example
In this example:
The Queue is sales-queue
The named identifier of the member is Bob Jones
The dial / channel location of the member if Local/6002@ext-queue/n
The user of this application is a full member of the queue and will be receiving calls
The user has details permission level
The login extension to be executed by Asterisk is *451234@ext-queue
THe logout extension to be executed by Asterisk is *451234@ext-queue
Example Queue Application Configuration.
Status Application
The status application on Sangoma phones provides users the ability to set their presence. That presence then can be read from the Asterisk dialplan for the purposes of call routing. The status application supports five main statuses, each of which can support a substatus message. Multiple Statuses can be applied to a Phone definition. If no Statuses are applied to a Phone definition, the default statuses (Available, Do Not Disturb, Away, Extended Away, Prefer Chat and Unavailable) will be used. Statuses can also be provided with an option that , when the phone is in a particular state, returns a 486 from the phone to Asterisk. By default, this behavior is off for a Status, when defined, but when a phone maintains no Status definitions 486 is returned, by default, for the Do Not Disturb and Extended Away statuses.
Option | Values | Description |
---|---|---|
status | available, dnd, away, xa, chat, unavailable | Sets the base presence type from one of the available six types |
substatus | string | Optional. Sets a substatus for a particular status, e.g. "At the movies" for the away status would result in "Away - At the Movies" |
send486 | yes / no | Defaults to no. If set, when this Status is set on a phone, the phone will return a 486 reject to Asterisk when called. |
Example
In this example:
An available status with a subtype of "Working" is defined.
An away status with a subtype of "Without pants" and that returns 486 to Asterisk is defined.
Status Application Example Configuration.
Parking Application
The Parking application on Sangoma phones allows users to see calls parked into parking lots. If there are no parking applications set for a phone, and the parking_exten option has been set for the phone, then the phone will see calls parked into all parking lots that Asterisk is aware of. If there are any parking applications set for a phone, and the parking_exten option has been set for the phone, then the phone will only see the parking lots defined for the phone.
Option | Values | Description |
---|---|---|
parkinglot | string | Sets the name of a parking lot context as defined by Asterisk in features.conf |
Example
In this example:
A parking lot application for the sales-parking and support-parking lots is defined
Voicemail Applications
The Voicemail application on Sangoma phones represents the folder names in a folder list and controls the password access.  The application is in turn applied to a phone. Then, when the phone loads the voicemail application, the folder names will appear translated as per the translation set. So, in order to have localized voicemail folders, one must create a translation, apply it to a voicemail application, and apply that application to a phone.
Option | Values | Description |
---|---|---|
translation | identifier of a type=voicemail section | Sets the translation set for the application |
require_password | no, yes | If enabled, requires a user to input their phone PIN before they can access the voicemail application. Supported beginning with phone firmware 1.4.1. |
Example
In this example:
A voicemail translation called voicemail_de_DE is used for this application
The voicemail application will require entry of the user's phone PIN before loading
Custom Applications
Sangoma phones support loading and running user-created custom JavaScript applications. Fore more information about creating these applications, and the endless possibilities therein, please see the Sangoma Phones SDK Wiki at Phone API Reference - Core - digium. Custom applications are always defined with an application name of "custom."
Option | Values | Description |
---|---|---|
name | string | The name of the custom application, e.g. JasonParkerApp; also used for the idlescreen_softkey label |
filename | string | A named .zip file containing the user's application, as reachable from the file_url_prefix. |
autostart | yes / no | Sets whether or not the custom application should load when the phone boots, or the first time a user opens the application |
key | value | Optional key=value parameters may be passed to the application |
Example
In this example:
An application named Jason-Fancy-App is declared, it's of the Custom application type
The internal name of the application is jasonapp
The filename of the application, as retrieved from the file_url_prefix is jasonsillyapp.zip
The application will start when the phone boots
Custom keypairs for user=1234 and permission=lots are passed in
Example Custom Application.
Ringtone Configuration Options
A Ringtone defines an actual ringing tone to by used by a phone. When the phone rings, it's what's played over the phone's speaker.
Option | Values | Description |
---|---|---|
alias | string | An identifier for the ringtone, e.g. FancyRinger. This identifier will be present in the phone's preferences menu and in its web menu |
filename | string | A named 16-bit 16kHz mono raw audio file, not a .wav file, as reachable from the file_url_prefix. |
Example
In this example:
The ringtone is identified as FancyRinger
Example Ringtone Configuration.
Alert Configuration Options
Alerts define an Alert-Info header, a ringing type and a ringtone to be used by the phone. Alerts allow complete customization of the phone's ringing behavior.
Option | Values | Description |
---|---|---|
alert_info | string | The Alert-Info header that the phone should expect when this Alert is to be used. |
ring_type | normal, answer, ring-answer, visual | The type of ringing behavior that the phone should present when this Alert is called. |
ringtone | Alarm, Chimes, Digium, GuitarStrum, Jingle, Office2, Office, RotaryPhone, SteelDrum, Techno, Theme, Tweedle, Twinkle, Vibe, or one of the context names where type=ringtone | Defines the ringtone to be used for this Alert. If blank, then the phone will not play back a ringing tone, instead present silence. |
Example
In this example:
The Alert Info string is "ai-Guitar"
The ringing type is ring-answer
The ringtone is fancyringer
Example Alert Configuration.
Firmware Configuration Options
Firmwares define the actual firmware file, for a specified phone model, that is in turn applied to a Phone type. This allows configuration of different firmwares for different groupings of phones.
Option | Values | Description |
---|---|---|
model | D40, D50, D70 | Defines the phone model for this firmware. A firmware applies to only one model; thus, to handle all 3 (currently) models of phones, 3 different firmware definitions must be created and used |
version | version string identifier of firmware | Sets the version string identifier for a particular firmware. The string is the version of the firmware, not counting the final underscore, model, underscore, "firmware," and ".eff" suffix. |
file | string | Sets the file location of the firmware, to be retrieved by the phone and respecting the file_url_prefix network option |
public_firmware | yes, no | Whether or not we will include a fallback address (based on the network's public_firmware_url_prefix) to retrieve this firmware if the phone can not reach the file specified here. Default is no. |
Example
In this example:
There are firmwares for each of the three models
The firmware version is 1_0_5_46476
The filenames are specific to the phone and are retrieved in the "firmware" subdirectory of the file_url_prefix
Firmware retrieval will fallback to the public location if the local location fails
Firmware Example Configuration.
Translation Configuration Options
Translations maintain a mapping of values from internal names to externally represented names. The current use of translations is for the voicemail application, to be applied to phones to localize the folder names within the messaging application on the phone.
Option | Values | Description |
---|---|---|
key | value as a string | Sets the value to be substituted for the key |
Example
In this example:
INBOX will be set to INBOX
Work will be set to Arbeit
Family will be set to Familie
Friends will be set to Fruende
Recordings will be set to Aufnahmen
Multicastpage Configuration Options
Multicastpages define address and port combinations to which the phone will listen for multicasted RTP in G.711 u-law, G.711 a-law and G.722 formats as well as call hold behavior. Â Multiple listeners may be attached to a phone.
Option | Values | Description |
---|---|---|
alias | string | A named identifier for this listener, which will show in the phone's status bar during audio playback |
address | IPv4 address string | The address at which to expect multicast RTP |
port | port (1-65536) as integer | The port at which, combined with the address, to expect multicast RTP |
priority | integer, 1-10 | The priority for this listener. Lower (1) priorities take precedence over higher (10) priorities. |
interrupt | 0, 1 | When enabled, places any in-progress calls on hold before playing back audio, and ignore the phone's local volume setting, playing back the audio at full volume. When disabled, in-progress calls will have their audio played over. Defaults to 0. |
Example
In this example:
Audio from the listener will identify with "Emergency" on the phone's status bar
Multicast audio will come across address 237.0.0.101
Multicast audio will come across port 32000
The listener is given top priority
In-progress calls will not be placed on hold
Firmware Example Configuration.