|Table of Contents|
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] ; 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
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.
The General Section provides the following options related to authentication:
|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.|
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
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.
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:
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
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.|
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.
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.
The General Section provides the following options related to Files:
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
The General Section provides the following other options:
[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.
[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.
[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.
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 mapping, see #dialplans
The digit mapping to use for this line.
string, e.g. MD 123
The line label to display on the phone for this line's line key.
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 .
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.
Host / IP address
The Outbound SIP proxy address this line should use
Port as integer
The port of the Outbound SIP proxy; defaults to 5060 when outboundproxy_address is set
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).|
integer, e.g. 300
The number of seconds before re-registering
integer, e.g. 25
The number of seconds to wait before retrying to register after registration fails.
integer, e.g. 5
The number of times the phone will attempt to retry registering after registration fails
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.
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.
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.
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 126.96.36.199.|
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.
[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.
queue, status, parking, voicemail
The application type name
The Queues application provides phone users with permission-controlled views into Asterisk's app_queue.
[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
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.
[available-working] type=application application=status status=available substatus=Working [away-nopants] type=application application=status status=away substatus=Without pants send486=yes
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.
[allparking] type=application application=parking parkinglot=sales-parking parkinglot=support-parking
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.
[voicemail_for_de_DE] type=application application=voicemail translation=voicemail_de_DE require_password=yes
[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.
[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.
[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.
[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.
[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.