XML Configuration
This section describes the formatting and options available when creating XML-based configuration files for provisioning Digium phones. Users choosing this method of configuration forgo use of the DPMA, and instead are provisioning phones for use with Asterisk versions that do not support the DPMA.
Setting Elements
Each <setting> element represents at least an id and value pair of attributes. Some <setting> tags may have additional attributes.
General (Login)
Option |
Values |
Description |
|---|---|---|
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 |
General (Time)
Option |
Values |
Description |
|---|---|---|
time_zone |
Timezone String, e.g. America/Chicago |
Sets the time zone for the phone |
time_source |
"ntp" |
Sets the time source for the phone. Currently, the only option is "ntp" |
ntp_server |
Hostname or IP address, e.g. 0.digium.pool.ntp.org |
Sets the NTP server to which the phone will synchronize itself, defaults to 0.digium.pool.ntp.org |
ntp_resync |
Seconds as integer, e.g. 86400 |
Sets the interval between NTP synchronization |
General (SIP)
Option |
Values |
Description |
|---|---|---|
accept_local_calls |
any / host |
Sets whether to accept calls from any source or only from hosts to which the phone is registered |
transport_udp_enabled |
boolean |
Sets whether to enable UDP transport, defaults to 1 |
transport_udp_port |
Valid integer for ports (1-65535) |
Sets the local UDP SIP port, defaults to 5060 |
transport_tcp_enabled |
boolean |
Sets whether to enable TCP transport, defaults to 1 |
transport_tcp_port |
Valid integer for ports (1-65535 ) |
Sets the local TCP SIP port, defaults to 5060 |
Preferences (Idle Screen)
Option |
Values |
Description |
|---|---|---|
logo_file |
value as factory / user; path as location on disk of file - /factory_asterisk.png for default and /user_image.png for custom ; url as optional location to fetch a logo; md5 as optional when url is used to determine if logo has changed to avoid re-fetching |
Sets the idle screen logo, defaults to factory-asterisk.png |
display_mc_notification |
boolean |
Disables / Enables display of missed calls on the phone, defaults to 1 |
Preferences (Display)
Option |
Values |
Description |
|---|---|---|
brightness |
integer (0-10) |
Sets the LCD screen brightness, defaults to 5 |
contrast |
integer (0-10) |
Sets the LCD screen contrast, defaults to 5 |
enable_check_sync |
boolean |
Controls whether the phone will perform a reconfigure when sent a check-sync SIP NOTIFY Event from the server to which it is registered. Defaults to 1. |
dim_backlight |
boolean |
enable backlight dimming where 1 dims the screen after backlight timeout has been reached and phone is otherwise idle, defaults to 1 |
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 1, defaults to 2 |
Preferences (Sounds)
Option |
Values |
Description |
|---|---|---|
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 |
reset_call_volume |
boolean |
If 1, volume changes made during a call do not persist to the next call, defaults to 0 |
default_ringtone |
Tone ID from <tones> provided to phone |
Sets the default phone ringtone, defaults to Digium |
active_ringtone |
Tone ID from <tones> provided to phone |
Sets the current user-selected ringtone, defaults to Digium |
Preferences (Answering Calls)
Option |
Values |
Description |
|---|---|---|
headset_answer |
boolean |
Sets whether to use the headset, rather than the speaker, for answering all calls, defaults to 0 |
ehs |
Plantronics |
Defines the Electronics Hookswitch type to support |
Contacts
Option |
Values |
Description |
|---|---|---|
desi_strip_enable |
boolean |
Applies to D50 and D70 models, enables / disables sidecar, defaults to 1 |
enable_blf_on_unused_line_keys |
boolean |
If 1, assigns BLFs beginning with first empty line key. If 0, assigns BLFs beginning with first sidecar key. Defaults to false. |
name_format |
first_last, last_first |
Formats the display of contact names, defaults to first_last |
blf_contact_group |
Any group_name from the loaded contacts |
The group_name of the contact list group to use for the rapid dial list |
Network (IP Settings)
Option |
Values |
Description |
|---|---|---|
network_enable_dhcp |
boolean |
Disable or Enable DHCP network configuration, defaults to 1 |
network_static_ip_address |
IPv4 address |
Defines the network address for the phone |
network_subnet_mask |
IPv4 netmask |
Defines the netmask for the phone |
network_default_gateway |
IPv4 address |
Defines the network gateway for the phone |
network_primary_dns_server |
IPv4 address |
Defines the primary DNS server for the phone |
network_secondary_dns_server |
IPv4 address |
Defines the secondary DNS server for the phone |
Network (Virtual LAN)
Option |
Values |
Description |
|---|---|---|
network_vlan_discovery_mode |
value of NONE, MANUAL, LLDP; network as IP mask |
Sets use of none, manual, or LLDP discovered VLAN and, if MANUAL, defines the network; defaults to LLDP |
network_vlan_qos |
integer (0-7) |
Sets the VLAN QOS level |
network_vlan_id |
integer (0-4095) |
Sets the VLAN ID |
Logging
Option |
Values |
Description |
|---|---|---|
log_level |
error, warning, debug, info |
Sets the logging level, defaults to error |
log_server |
IPv4 address of syslog server |
Specifies remote syslog server |
log_port |
port as integer |
Specifies port of remote syslog server |
enable_logging |
boolean |
Disables or Enables remote syslog, defaults to 0 |
Miscellaneous
Option |
Values |
Description |
|---|---|---|
web_ui_enabled |
boolean |
Disables, Enables the phone's web user interface, defaults to 1 (Enabled) |
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 |
Keymap Elements
Keymap Elements control the functionality of softkeys during various phone states.
Option |
Values |
Description |
|---|---|---|
key |
id as 0-3, action as "accept_call, reject_call, transfer_call, send_to_vmail" |
Maps a softkey represented by id of 0-3, left-to-right, to an action. |
Contacts Element
Any number of contacts elements may be present directly under the config element.
These <contacts> elements have attributes, most importantly url which allow contacts xml sheets to be downloaded via the DPMA.
Option |
Values |
Description |
|---|---|---|
contacts |
url as file link, id as unique identifier, md5 as the md5sum of the xml file |
Specifies the contacts XML file to be retrieved by the phone and identifies that file; more than one contacts parameter may be used |
Accounts Element
Option |
Values |
Description |
|---|---|---|
index |
integer (0-5) |
Defines the line key to which the account will be mapped |
status |
boolean |
Enables the line key; if false, will not display the line on the phone or register with the primary host |
register |
boolean |
If 1, then this account will attempt to register with the primary host |
account_id |
string |
SIP username |
username |
string |
SIP username |
authname |
string |
SIP authname |
password |
string |
SIP password |
passcode |
string |
SIP password |
line_label |
string |
The text that shows up next to the line key for this account |
caller_id |
Name <Number> |
Outgoing caller id displayed for this account |
dial_plan |
Digit mapping, see #dialplans |
The dial plan / digit mapping for this account |
visual_voicemail |
boolean |
Only valid on account with index of 0. Only valid for phones provisioned by Switchvox or the DPMA. If this is set to 1 then the Msgs button action will open the voicemail app. Otherwise it will dial the voicemail extension. |
voicemail |
digits or SIP URI |
A SIP URI or extension to be dialed for voicemail pertaining to this account. |
outbound_proxy |
IP address / Hostname |
Outbound proxy for this account |
outobund_port |
port |
Port for the outbound proxy |
conflict |
replace |
Host Primary: Child Element of <account>
Option |
Values |
Description |
|---|---|---|
server |
Hostname or IPv4 Address |
Sets the server to which calls for this account are directed |
port |
integer (1-65535) |
Sets the server's SIP port |
transport |
udp, tcp |
Sets the transport type, UDP or TCP |
reregister |
integer in seconds |
Sets the re-registration interval |
retry |
integer |
Specifies the number of time to attempt re-registration if registration fails |
num_retries |
integer |
Specifies the number of retries to attempt if registration fails |
Permission: Child Element of <account>
Defines line/account based permissions for various phone functions with an id and value pair.
Option |
Values |
Description |
|---|---|---|
record_own_calls |
boolean |
If 1, allows the user to record their own calls using a soft-key. Note that this feature can only enabled when using the DPMA. Users manually provisioning Digium phones should set this to 0 in order to ensure that a non-functional (because the DPMA is not being used) call recording softkey does not appear. |
Networks Element
The networks element contains definitions for networks, each described by an individual <network> element and its attributes.
Each <network> element is described by the following attributes:
Option |
Values |
Description |
|---|---|---|
id |
integer |
Unique, numbered identifier for the network |
display_name |
string |
A named identifier for the network |
cidr |
CIDR formatted address |
A CIDR formatted network address, e.g. 10.0.0.0/8 |
Codecs Element
The codecs element contains all available codecs, each described by an individual <codec> element and its attributes.
Each <codec> element is described by the following attributes:
Option |
Values |
Description |
|---|---|---|
id |
PCMU, PCMA, G722, G726-32, G729, L16, L16-256 |
A codec supported by the phone |
priority |
integer (1-255) |
Priority of the codec where higher numbers mean the codec is more favored |
packetization |
integer in 10ms increments per RFC codec guidelines |
Packetization (ptime) rate for the specified codec, defaults to 20 |
jitter_min |
integer in ms |
Sets the minimum size of the codec jitter buffer |
jitter_max |
integer in ms |
Sets the maximum size of the codec jitter buffer |
jitter_target |
integer in ms |
Sets the target size of the codec jitter buffer |
enabled |
boolean |
Disables / Enables a codec |
Ringtones Element
This section has two primary child elements:
- tones, which are the actual sounds heard when a call is made
- alerts, which map to a tone and represent a certain call condition
Tones: Child element of <ringtones>
Element lists the <tone> elements, each described by the following attributes:
Option |
Values |
Description |
|---|---|---|
id |
string |
Internal Tone identifier |
display |
string |
External Tone Description |
url |
URL string |
Location from which to retrieve a 16-bit, 16kHz, mono raw signed linear sound file, less than 1MB in size |
md5 |
md5sum |
MD5 sum of the file to be retrieved |
type |
phone, user |
Indicates the tone's origin; tones that are type phone are embedded into the phone's firmware, tones that are type user are retrieved by URL |
Alerts: Child element of <ringtones>
- Element lists the <alert> elements, each described by the following attributes.
- Alert tones are played when the event designated by 'alert_info' occurs.
Option |
Values |
Description |
|---|---|---|
alert_info |
string |
The alert_info header that, as received, applies to this alert |
ringtone_id |
string |
The id of the ring tone for this alert |
ring_type |
normal, answer, ring-answer, visual |
The type of call-answer to affect for this alert. |
Firmwares Element
- 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 |
Public Firmwares Element
- Element lists the <public_firmwares> elements, each described by the following attributes.
- Specifies a fallback firmare location - more than one public_firmware element may be specified for each model and the public_firmware servers will be tried in the order they are listed, in the event that an internal firmware server cannot be reached
- A <public_firmwares> element does not take the place of a <firmwares> element; if a <firmwares> element is not present in the config, the phone will not apply any settings from any <public_firmwares> elements.
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 |
Appconfig Element
- Element lists the <appconfig> elements
The can_transfer_vm attribute controls the display of the "Transfer VM" softkey from within the Contacts application.
The name_format attribute controls the display order of names from within the Contacts application.
network_id attribute
The network_id attribute, in conjunction with the Networks element is used to provision multiple different options for a particular element, e.g. account address, so that when the Digium phone is located on different networks, the proper element for that network can be loaded by the phone. When the phone boots and discovers its IP address, it compares that against matching elements with network_id attributes and loads only those elements, rather than elements with non-matching network_ids.
Currently, the network_id attribute can be applied to the following elements:
- ntp_server setting
- network_vlan_discovery_mode setting
- host_primary element
- contacts element
- firmwares element
Example