EPM-DPMA for Digium Phones

Introduction 

The "Digium Phone Module for Asterisk (DPMA)" is used with Sangoma D Series & Sangoma P Series IP phones to ensure a secure, easy installation process and to take advantage of the power of Asterisk.  Please refer to "Digium Phone Module for Asterisk (DPMA)" or "DPMA Datasheet" to for more details about DPMA. 

Endpoint Manager v  / v  and onward is capable of configuring D&P series phones using Asterisk's "Digium Phone Module for Asterisk (DPMA)" module. The PBX Endpoint Manager commercial module will be responsible for configuring the "DPMA" asterisk module which allows DPMA to push configurations to respective DPMA phones.

DPMA operates over SIP (PJSIP) which negates the need for additional provisioning ports to be open on the firewall.

All Digium phones which are supported can be found in EPM-Supported Devices.

License

We do not need Asterisk DPMA specific license while running on a validly licensed FreePBX/PBXact Distro.

Endpoint Manager module is also free to use for D&P series phones.

Enable DPMA + Configure DPMA

Please find below list of steps to configure the Sangoma D&P series phones.

Step-1: Disable Digium Phone Module 

Go to Admin → Module Admin and Disable the "Digium Phones Config" module if it's enabled. This is the legacy module which was previously used to configure Digium phones. 

Open

Endpoint Manager Configuration

Step-2: Enable DPMA 

DPMA is disabled by default in Endpoint Manager. We need to manually enable this option.

"Endpoint Manager → Global Settings → Use DPMA"  option needs to be set to YES.   Leaving this option to NO means that Endpoint Manager will only use the legacy provisioning method (i.e. tftp/http) to provision Sangoma D series phones.

By-default this is "NO". 

Open

As soon as DPMA is enabled here, the PBX will check the installation/licensing status of the "DPMA" module in the background, and inform the status to user.

After selecting "Use DPMA" to "YES" , Click the Save Global button to save your changes.

Step-3: DPMA Configuration

The next step is to perform the common settings config related to DPMA. 

To access the DPMA Management page, you can use the "Endpoint Manager → Global Settings→ DPMA Management" button, or "Endpoint Manager → Right Nav → DPMA Management" 

• DPMA Version - The version number of Asterisk DPMA module.

• Global Pin - A numeric identifier that, depending on the setting of Phone Authentication Method, can be used to assign the configuration of any phone.

• Phone Authentication Method - This is the authentication type required for a user to take ownership of a phone. By default, no authentication is required and any user can claim any phone configuration. Other available options are:

  • Global PIN - The user must enter the Global PIN in order to claim the phone.(Recommended)

  • Note: The "MAC" Phone Authentication Method has been removed.  Upon updating to the new EPM version, the option will be changed to None if MAC was previously selected.  The MAC authentication behavior is now based on the "Configured By" mode.  See the "Extension Mapping Features" section of this document for more details.  In other words, if your mappings are all set with Configured By: Server, and this Phone Authentication Method is set to None, the behavior should be the same as when MAC was the selected authentication method in past versions.  Having said that, it is still recommended to use a Global Pin for authentication.

• mDNS Service Name - Defines the registration server name for this server, provided to the phone during its mDNS server discovery.

• mDNS Discovery Address - Defines the Ip address or hostname of this server, provided to the phone during its mDNS server discovery.

• mDNS Discovery Port - Defines the SIP UDP signaling port for this server, provided to the phone during its mDNS server discovery. Defaults to 5060.

  • mDNS Discovery Transport - Defines the SIP UDP signaling transport for this server, provided to the phone during its mDNS server discovery. Defaults to UDP.

• Default User List Template - Selected template will be used to generate the phone config when user picks the extension from available user list from the phone. this is applicable for only those extensions who are not associated with any template in extension mapping page.

• PJSIP Max Contact Display Limit - Set the user list display limit for PJSIP maxcontact. this is applicable for only those extensions who are not configured in extension mapping page.
  Available options are:
  One:- Display only first extension in user list(i.e. ext-1)
  All:- Display all extension in user list (i.e. ext-1 to ext-n where n is max contact )

• DPMA Logging - Enable or Disable DPMA logging. If enable will generate logs in "/var/log/asterisk/dpma" file.

Click the Save button to save your changes when done. Also click on Apply Config button to write the config files.

Step-4: Adding Digium Templates

The next step is to go to  Settings → Endpoint Manager → Brands → Sangoma →  D & P series phones and modify the template you will be using. At this point, enable all phones that you will be using as shown below. 

Step-5: Adding Extensions in Extension Mapping 

We need to add extensions in "Endpoint Manager → Extension Mapping" to configure the D&P series phones.  

Adding Extension(s) manually in Extension Mapping 

We can add extensions manually by following the How to add extensions in Endpoint Manager wiki.

Please note - 

1. If you are adding extensions without a MAC address, then you will be able to choose one of these extensions from a list that is displayed on the phone during configuration.

2. If you are adding extensions with a MAC address, then that particular extension is locked with that phone mac address. This extension's configuration will not be available to other phones when selected from the extension list during configuration.

Please note that when multiple accounts are mapped to device, the Account 1 mapping must include a MAC address.  In DPMA we consider Account 1 as a main account, and all other accounts (Account 2, Account 3 etc) are treated as additional accounts which are linked to Account 1 by MAC address.

Extension Mapping Features

As highlighted in above snapshot, if we are using DPMA option to configure D&P series phones, we can see few extra options which are defined as follows - 

1. Configured By:  This value indicates whether the assignment was Server-based or Phone-based. Meaning, the assignment was Configured By the Server(the device MAC was set in the Extension Mapping by the Admin in Endpoint Manager), or the Phone(the extension was specified at the phone during configuration).

   1. Server-based assignments are locked, meaning they cannot be changed from the phone itself. They will always be given the configuration for the extension that the device's MAC address is mapped to, and when requested, the extension's configuration will only be available to the device with the specified MAC address

   2. Phone-based assignments are not locked. When configuring, devices will choose the desired extension at the phone. They will be not be able to get configurations for extensions that are Configured By Server(locked). When assignments will be chosen from the Phone, it is strongly advised to enable a Phone Authentication Method from DPMA Settings.

      1. Force Phone to Check Config -  This option will trigger phones to pull their configuration from the server.

      2. Force Reboot of phone  - This option will forcefully reboot the phone. 

      3. Toggle "Configured By" mode - This will toggle the configuration mode in case you'd like to change the way a MAC address is locked to an extension mapping.

         1. For example, if an extension is initially configured by manually being selected at the phone during configuration, the "Configured By" value will be set to "Phone".  If we later decide that we want this extension to be permanently locked with this phone, then we can click this action to switch the "Configured By" setting to "Server" mode.

Adding Extension(s) using bulk handler to Extension Mapping 

We can also use "Bulk handler" to import bulk extensions to do the bulk provisioning of Sangoma D series phones.

We can either use "Endpoint Manager → Extension Mapping → Import List", or "FreePBX GUI → Admin → Bulk Handler → Import → Endpoint".

Please see the snapshot below, which shows an example of a spreadsheet entry for the bulk configuration of extensions.

How to Configure Additional Accounts

When configuring additional accounts, we can follow the same steps which were described in the "Adding Extensions in Extension Mapping" section of this guide.  The main thing to note is that including a MAC address is mandatory when adding the mapping for the extension's primary device.  

Phone Configuration Methods

Manual Method

When the D&P series phone boots,  please follow steps below in order to manually select the configuration server.

Pointing your Sangoma D&P series phone to the DPMA Configuration Server

Once the above settings are in place, boot your D&P series phone. If it has not previously been provisioned, it will attempt to discover the DPMA server or it will prompt you to enter your Asterisk Configuration Server details. Enter the details as shown in the DPMA Settings for IP and port.

mDNS Service Name is shown on the left, and can be customized from "DPMA Management" in Endpoint Manager.

Select the Extension

Once we select the DPMA server, the phone will display the User List.  The User List is the list of extensions(Account 1) that we've added in Extension Mappings page of Endpoint Manager. Select an extension to load its configuration.

Phone Reconfiguration

Sometimes, reconfiguring the phone to a different extension is required.  Follow the steps below to reconfigure a device.

• Phone->Menu->Advanced→Reconfigure

• Select the Digium Configuration server

• Select the Extension

• Phone will reboot and new selected extension will get configured in phone.

After Reconfiguration, the previously assigned extension will be released, and the new extension's configuration will be loaded on the phone.  When selecting the new extension, it can't be one that has its Configured By mode set to Server if it is mapped to a different mac address, as that mapping is considered to be locked.

Option 66

Please find below list of steps to configure the Sangoma D&P series phones with Option 66.

If we have both Option 66 and DPMA mDNS enabled then phone will display both the options to choose one manually. To avoid this manual selection, we can hide mDNS server from the phone so phone will automatically pick DHCP Option 66 specified server to pull the configuration.

Step-1: Hide mDNS Server

Go to "Endpoint Manager → Right Nav → DPMA Management → mDNS Service Discovery Enable" option needs to set to NO.   

Leaving this option to NO means that mDNS server will not display during provision process and phone will automatically pick the Option 66.

Step-2: Configure DHCP Server

You can configure your DHCP server with option 66 to automatically point new phones to the PBX. Once this is setup, any phone that gets this option 66 string from the DHCP server will go to the FQDN/IP specified and look for its configuration.

For Sangoma D&P series phones Only

if you have only Sangoma D&P series phones in your network, then you can directly specify the PBX server IP : Port to fetch the configuration as DPMA uses asterisk to provision the phones.

1) This is done using the following string below. 

sip:proxy@<PBXIP>:<PJSIP PORT>

2) For an example, if your PBX IP is pbx.sangoma.com then the string will be the following, and this can be an IP or FQDN. 

sip:proxy@pbx.sangoma.com:5060

For Sangoma D&P series phones + S phone or any other DHCP Option 66 supported brands phones

This is a common configuration method, If you want to configure Sangoma's D&P series and S series phones or any other DHCP Option 66 supported brands phones present in your network with the same DHCP Option 66 configuration option.

Refer to Setup Phone with DHCP Option 66 to know more about DHCP Option 66 configuration.

Zero Touch Provisioning

• Go to the Sangoma Portal at https://portal.sangoma.com and Login.

• On the left menu select Sangoma Phones → Change redirection settings

• Search your Sangoma D&P-Series phone 
  
  
  

• Click on the View/Edit button.

• Here you need to put all the information's in sync with DPMA configuration!
  
  
  

• Reboot your phone and you are done.

Migrating from Old EPM+DPMA to New DPMA

FreePBX has included DPMA in Endpoint Manager for some time now.  However, this new DPMA implementation is a major update which improves the existing functionalities and user experience by changing the way DPMA is setup within FreePBX.

The DPMA asterisk RPM itself is getting updated, and will be required  after Endpoint manager has been updated to (v14.0.68.20+/ v15.0.39.20+).  If you are already using Endpoint Manager with DPMA then your endpoint manager module will get disabled and you have to follow below steps to migrate to the updated DPMA.

1) Create a file in temp directory by using the below command.

touch /var/spool/asterisk/tmp/forceinstallepm

2) fwconsole ma install endpoint

3) "Endpoint Manager  → Right Nav → DPMA Management"  will show the option to migrate to the new DPMA.  This will upgrade the DPMA RPM.  Asterisk will need to be restarted, so please do this step during off-hours to avoid service interruptions.

D&P Series Phone VPN

Endpoint Manager has been enhanced to add support for VPN for D&P series phones as well. Please follow the standard EPM process for configuring VPN as defined in EPM-Admin User Guide#AdminUserGuide-VPN in order to configure VPN for D&P series phones.

D&P Phone Template Improvements

We have improved the layout of the D phone template and also added multiple new options. For more details, please refer :- D & P Phone Template

TLS support for D&P phone

Endpoint Manager has been enhanced to add support for TLS for D&P series phones using DPMA as well.

Step 1:- Setting up Hostname

Accessing your system from hosts that are not associated with your SSL certificate will result in an SSL error and on the phones, the phone applications will not function properly.

Please define the same SSL certificate host name to your system as well. 

1. Sysadmin → Right Navigator → Hostname 
   
   
   

2. Endpoint Manager -> Global Setting :  Internal or External address, depends on your template configuration.
   
   
   
   

Step 2:- Setting up TLS , SRTP Configuration

Please refer to TLS and SRTP wiki guide in order to configure TLS for D&P series phones.

Troubleshooting

DPMA RPM : If you face any issue then first thing is to confirm that you have below minimum DPMA RPM version installed in your system.

[root@freepbx ~]# rpm -qa|grep res_digium

asterisk17-res_digium_phone-3.6.0-5.sng7.x86_64

Logging - In the DPMA Management page, we have an option to "Disable DPMA Logging".  By Default logs will be disabled.  It is recommended to leave this disabled unless requested by Tech Support.

The DPMA log file name is "dpma" and is stored in the "/var/log/asterisk" directory.  

Sample Logs -

Frequently Asked Questions

 I am using tftp or http provisioning to configure my D phones, why do i have to switch to DPMA ?
 A:- DPMA is the most secure way of configuring the D phones and this will not require you to open any other port like tftp or https to get configurations from the PBX server.  With DPMA, devices communicate over the SIP(PJSIP) port with asterisk to fetch their configuration.  While it is recommended to switch to DPMA provisioning however for the security benefits alone, it is still optional.  You can continue to use other methods such as tftp/http if desired. 

 I am using "Digium phone module" to configure D phones using DPMA.  Why should I switch to EPM to use DPMA instead?
 A:- "Digium Phone Module" is not a fully supported module, and Endpoint Manager is free to use for Sangoma's D series phones.  Going forward, we will keep enhancing EPM to improve the user experience to provision D series phones.  

 I am using "Digium phone module" to configure D phones using DPMA.  How can i migrate to to EPM to use DPMA instead?
 A:  As of now there is no migration step, we have to re-configure the same extension freshly in EPM.
 

 Where are we storing the DPMA and phone config files ?

 A:- We are storing DPMA and phone config related files in "/etc/asterisk/dpma" directory but all the contacts and firmware related files will continue to be stored in the "/tftpboot/digium" directory.

 Why does the User List only show Account 1 ?

 A:- The reason is, in DPMA we consider Account 1 as a main account and all other accounts (Account 2, Account 3) are considered to be an additional account.  So all the additional accounts will be linked with Account 1 by MAC address.

 Can we steal the configuration of an extension that is already configured on another phone ?

 A:- Yes, as long as the Configured By mode of the already-configured device is "Phone".  After selecting extension's configuration is loaded on the new phone, the previous phone will be updated to remove its configuration.

 How can we see all extension mappings on the phone's User List during configuration?

 A:- Press the Filter softkey at the User list to see the different sections.

 Will my rest apps will continue to work as normally ?

A:- Yes, As of now they will continue to work using XML API. 

 Why endpoint manager module is showing disabled after update to latest release?
A:- You are using the endpoint manager module with DPMA that's why it happened. Please follow the Migration Steps to resolve this.

 How do I fix a "Error fetching config from proxy" error ?

A:- Just click on retry button, phone will fetch the config again.

 What we need to do if we are restoring the backup in new server, is there any additional steps which we need to follow for configure the phones with new sever ?

A:- In case of backup & restore you have to update the Global settings and DPMA Management page and reconfigure the phones with new server.

 I'm using Advance Recovery module and primary server went down, now phone is showing error "Communication Error". How to fix it ?

A:- Just click on "Keep old" button. It will resolve your issue.

 I'm facing "Whoops\\Exception\\ErrorException","message":"DOMDocument::loadXML()" error. How to fix it ?

A:-  The latest Endpoint Manager with DPMA mandates "alert-info" configuration element in basefile to be in proper XML format.

      Due to migration, if you have any "alert-info" custom entry present in basefile then that needs to be change manually using Endpoint Manager → Basefile editor.

      Wrong format:-

        <alert alert_info=<http://127.0.0.1>;info=ring-answer/>

      Right format:-

       <alert alert_info="&lt;http://127.0.0.1&gt;;info=ring-answer"/>

     If we add new "alert-info" configuration parameter entry then Endpoint Manager will take care of converting that to proper format.

  Phone stuck into "Searching" Configuration server . How to fix it ?

A:-   D-phone will stuck at "Searching" page for Diguim Configuration Server if there is no server available to contact. This could happen due to mDNS Service name wrong configuration or  "mDNS Service Discovery Enable" set to NO and DHCP option 66 not present.