Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


Table of Contents
maxLevel3

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:

...

No Format
titleExample 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:

...

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_uuidStringSets 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_transportudp, tcp, tlsSets 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. Digium 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

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

...

No Format
titleExample 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 Digium 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 Digium phone causes the registration address (and/or other information) of the Asterisk server to change.

...

No Format
titleExample 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.

...

No Format
titleExample Phone Configuration.
[bobsphone]
type=phone
network=MyNetwork
firmware=1.1Firmware
mac=0123456789ab
pin=10101019
group_pin=1234
line=bob101
line=bob102
external_line=bobexternal
application=queue-bob-1234
application=available-working
application=available-nopants
application=parking-sales
application=voicemail_for_de_DE
;config_file
full_name=Bob's Phone
contact=bobstonctacts.xml
contacts_display_rules=bobsdisplayrules.xml
blf_contact_group=RapidDial
blf_items=bobsblfitems.xml
blf_page_return_timeout=30
contacts_max_subscriptions=50
timezone=America/Los_Angeles
ntp_resync=86400
parking_exten=700
parking_transfer_type=blind
show_call_parking=yes
ringtone=FancyTone
active_ringtone=GuitarStrum
web_ui_enabled=no
record_own_calls=yes
can_forward_calls=yes
show_call_log=yes
alert=fancyringer
blf_unused_linekeys=no
send_to_vm=yes
d40_logo_file=d40_logo.png
d45_logo_file=d45_logo.png
d50_logo_file=d50_logo.png
d70_logo_file=d70_logo.png
d80_logo_file=d80_logo.png
wallpaper_file=my_wallpaper.png
ehs=auto
lock_preferences=yes
login_password=1234
accept_local_calls=host
display_mc_notification=no
idle_company_text=Office Phone
small_clock=yes
brightness=5
contrast=5
dim_backlight=yes
backlight_timeout=30
backlight_dim_level=2
active_locale = de_DE
ringer_volume=5
speaker_volume=5
handset_volume=5
headset_volume=5
reset_call_volume=no
call_waiting_tone=yes
headset_answer=no
ring_headset_only=no
name_format=last_first
lan_port_mode=auto
pc_port_mode=100fd
enable_check_sync=yes
codecs=PCMU,PCMA,G722,G7221,G726-32,opus,G729,iLBC

Line Configuration Options

Internal lines are PJSIP endpoints, but there is Digium 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_encryptionnull, sdesSpecifies 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 Digium 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 Digium 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_numberDialable NumberWhen 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.

...

Tip

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.

...

No Format
titleExample External Line Configuration.
[bob1234]
type=external_line
server_address=otherpbx.mycompany.com
server_port=5061
transport=tcp
media_encryption=sdes
secondary_server_Address=otherpb2.mycompany.com
secondary_server_port=5061
secondary_server_transport=udp
userid=bob1234
authname=bob4321
secret=mymagicalpassword
register=yes
callerid="Bob Jones" <555-1234>

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.

...

No Format
titleExample Queue Application Configuration.
[bob-queue-1234]
type=application
application=queue
queue=sales-queue
membername=Bob Jones
location=Local/6002@ext-queue/n
member=yes
permission=details
login_exten=*451234@ext-queue
logout_exten=*451234@ext-queue

Status Application

The status application on Digium 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 five 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.

...

No Format
titleStatus Application Example Configuration.
[available-working]
type=application
application=status
status=available
substatus=Working

[away-nopants]
type=application
application=status
status=away
substatus=Without pants
send486=yes

Parking Application

The Parking application on Digium 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.

...

No Format
title:Parking Application Example Configuration
title:Parking Application Example Configuration
[allparking]
type=application
application=parking
parkinglot=sales-parking
parkinglot=support-parking

Voicemail Applications

The Voicemail application on Digium 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.

...

No Format
title:Voicemail Application Example
title:Voicemail Application Example
[voicemail_for_de_DE]
type=application
application=voicemail
translation=voicemail_de_DE
require_password=yes

Custom Applications

Digium 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 Digium Phones SDK Wiki at http://phones.digium.com/phone-api/reference/content/digium-phone-api-reference-guide. Custom applications are always defined with an application name of "custom."

...

No Format
titleExample Custom Application.
[Jason-Fancy-App]
type=application
application=custom
name=jasonapp
filename=jasonsillyapp.zip
autostart=yes
user=1234
permission=lots

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.

...

No Format
titleExample Ringtone Configuration.
[fancyringer]
type=ringtone
alias=FancyRinger
filename=FancyRinger.sln

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.

...

No Format
titleExample Alert Configuration.
[alert-fancyringer]
type=alert
alert_info=ai-Guitar
ring_type=ring-answer
ringtone=fancyringer

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.

...

No Format
titleFirmware Example Configuration.
[d40-1.0.5]
type=firmware
model=D40
version=1_0_5_46476
file=1_0_5_46476_D40_firmware.eff
public_firmware=yes

[d50-1.0.5]
type=firmware
model=D50
version=1_0_5_46476
file=1_0_5_46476_D50_firmware.eff
public_firmware=yes

[d70-1.0.5]
type=firmware
model=D70
version=1_0_5_46476
file=1_0_5_46476_D70_firmware.eff
public_firmware=yes

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.

...

No Format
[voicemail_de_DE]
type=translation
INBOX=INBOX
Work=Arbeit
Family=Familie
Friends=Freunde
Recordings=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.

...