Skip to end of metadata
Go to start of metadata

DPMA Configuration

Phones and Lines 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.

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

  • phone
  • line
  • external_line

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

The phone and lines section 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 comma
;
; the general section contains many options
generaloption=value
generaloption2=othervalue
;
[MyPhone] ; A phone
type=phone
; Phone options go here
phoneoption=value
phoneoption2=othervalue
;
[MyAccount] ; A SIP peer from sip.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
;

Authentication Options

The General Section provides the following options related to authentication:

Option

Values

Description

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.

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 is required in order to retrieve the list of phone profiles.

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; 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.

Registration Server Options

The General Section provides the following options related to the registration server:

Option

Values

Description

registration_address

IP address or Hostname

Allows for explicit definition of the address to which phones should register. If the option is not set, then the address given to the phones to register is the same address that the phone uses in the To: header when requesting a configuration

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.

mDNS Discovery Options

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

Option

Values

Description

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, registration_address and registration_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.

Firmware Update Options

The General Section provides the following options related to Firmware Update:

Option

Values

Description

firmware_url_prefix

URL, e.g. http://10.10.10.10/firmware_package_directory

Specifies the URL prefix the phone module should use to tell the phones where to retrieve firmware files.

firmware_package_directory

file path, e.g. /var/www/firmware_package_directory

Specifies the actual disk location of the firmware package provided by the webserver. RPM-based distributions, e.g. Red Hat, CentOS, etc. typically locate web content in the /var/www/html directory; so, for those distributions, the firmware_package_directory should be a subdirectory inside of /var/www/html. Debian-based distributions typically locate web content in the /var/www directory; so, for those distributions, the firmware_package_directory should be a subdirectory inside of /var/www.

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 txt and binary files. This directory is primarily used for storing contacts.xml and user-generated phone configuration. Defaults to /var/lib/asterisk/digium_phones

Other General Options

The General Section provides the following other options:

Option

Values

Description

message_context

string, e.g. dpma_message_context

The context matching the sip.conf [general] section definition for outofcall_message_context, defaults to dpma_message_context.

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 Registration Server is set to 10.10.10.10 on port 5060
  • The Avahi service name has been set to “Go 4 Phones” with discovery enabled
  • Firmware will be retrieved from http://10.10.10.10/digium_phones_firmware
    • which is actually located at /var/www/digium_phones_firmware
  • Files are stored in /var/lib/asterisk/digium_phones
  • and the dialplan context used for message handing is dpma_message_context
Example General Section configuration.
[general]
globalpin=344486
userlist_auth=disabled
config_auth=pin
registration_address=10.10.10.10
registration_port=5060
service_name=Go 4 Phones
service_discovery_enabled=yes
firmware_url_prefix=http://10.10.10.10/digium_phones_firmware
firmware_package_directory=/var/www/digium_phones_firmware
file_directory=/var/lib/asterisk/digium_phones
message_context=dpma_message_context

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

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

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

line

entity defined as line in res_digium_phone.conf

Maps directly to a sip.conf peer/friend 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

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. For information about custom configuration files, see XML Configuration 1.1. 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 in the file_directory containing a list of contacts to serve to the phone. Multiple contact options can exist in a single phone configuration.

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.

timezone

Timezone String, e.g. America/Chicago

Sets the timezone used for the clock on this phone.

ntp_server

hostname, IP address, e.g. ntp.mycompany.com

Defines the NTP server to which phones will synchronize themselves

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.

ringtone

Alarm, Chimes, Digium, GuitarStrum, Jingle, Office2, Office, RotaryPhone, SteelDrum, Techno, Theme, Tweedle, Twinkle, Vibe

Sets the default ringtone for the phone, defaults to Digium.

web_ui_enabled

no / yes

By default, when using the Digium 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.

blf_unused_linekeys

no / yes

Digium 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.

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. Loaded from the directory specified by the file_directory\ option. The D40 and D50 screen size is the same; therefore it is permissible to re-use the same logo file for both.

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. Loaded from the directory specified by the file_directory\ option. The D40 and D50 screen size is the same; therefore it is permissible to re-use the same logo file for both.

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. Loaded from the directory specified by the file_directory\ option.

Example

In this example:

  • 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's primary line is a SIP peer named bob101
  • the phone's secondary line is a SIP peer named bob102
  • the phone has an external line called bobexternal
  • 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 uses a contact group, from bobscontacts.xml, named "RapidDial" for its BLF keys
  • the phone is set for the "America/Los_Angeles" timezone
  • the phone's NTP server is set to 0.digium.pool.ntp.org
  • the phone's NTP resynchronization time is 86400
  • the phone will blind transfer parked calls to extension 700
  • the phone's ringtone is a Guitar Strum
  • the phone's Web UI is disabled
  • the phone's Rapid Dial keys will begin from the side car
  • 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
Example Phone Configuration.
[bobsphone]
type=phone
mac=0123456789ab
pin=10101019
line=bob101
line=bob102
external_line=bobexternal
;config_file
full_name=Bob's Phone
contact=bobstonctacts.xml
blf_contact_group=RapidDial
timezone=America/Los_Angeles
ntp_server=0.digium.pool.ntp.org
ntp_resync=86400
parking_exten=700
parking_transfer_type=blind
ringtone=GuitarStrum
web_ui_enabled=no
blf_unused_linekeys=no
d40_logo_file=d40_logo.png
d50_logo_file=d50_logo.png
d70_logo_file=d70_logo.png

Line Configuration Options

Internal lines are SIP peers (friends), but there is Digium Phone-specific data associated with lines that does not otherwise exist in the sip.conf entry. Because of this, advanced line features must be defined separately from sip.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 sip.conf entry.

Option

Values

Description

exten

string, e.g. 1000

When the sip peer 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 sip peer name is actual 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 Dial Plans 1.2

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.

language

string, e.g. en_US

The preferred language to use for this line. Currently, only US English is supported.

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 sip peer 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 SIP peers are stored in ARA, then the mailbox to which the SIP peer is assigned must be specified here, as it cannot be retrieved by the DPMA from ARA.

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

SIP transport method this line should use. Defaults to udp

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 SIP peers are stored in ARA, then the secret for the SIP peer mapped to this line must be specified so that the Digium phone can be passed the correct SIP peer credentials. If the SIP peer for this line is specified in sip.conf, this option is not required.

context

Asterisk dialplan context

If SIP peers are stored in ARA, then the dialplan context to which the SIP peer is assigned must be specified so that dialplan hints can be properly created by the DPMA. If the SIP peer for this line is specified in sip.conf, this option is not required.

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 Voicemail URI (number to be dialed) is 8000 at the 10.10.10.10 PBX.
  • The Outbound Proxy is 10.10.10.1 and its port is 5060.
  • The Transport type for the signaling is TCP
  • The Re-registration timeout is 300 seconds
  • The Registration Retry Interval is 25 seconds
  • The Maximum Registration Retries is 5 times
Example Line Configuration.
[bob101]
type=line
digit_map=[0-8]xx
line_label=BobbyJ
mailbox=bob101
voicemail_uri=sip:8000@10.10.10.10
outboundproxy_address=10.10.10.1
outboundproxy_port=5060
transport=tcp
reregistration_timeout=300
registration_retry_interval=25
registration_max_retries=5
Icon

If SIP peers are configured using Asterisk Realtime, 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.

Icon

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.

Icon

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

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

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
  • 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.
[bob1234]
type=external_line
server_address=otherpbx.mycompany.com
server_port=5061
transport=tcp
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>
  • No labels