THIS WIKI IS APPLICABLE ONLY FOR THE ENDPOINT MANAGER V15.0.38+ AND V14.0.67+ RELEASES
The "Digium Phone Module for Asterisk (DPMA)" is used with Sangoma D 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 Digium 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.
The Endpoint Manager module will entirely take care of asterisk's DPMA related configuration, so this deprecates the FreePBX "Digium phone module" module going forward.
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 series phones.
Please find below list of steps to configure the Sangoma D 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.
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 → Use DPMA" option needs to 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".
The older "Digium Phones module" and DPMA through Endpoint Manager can not be enabled at the same time.
If you are using the PBX "Digium Phones Config" module to configure Sangoma D series phones then the EPM global setting must be set to 'NO'.
If you are using Endpoint Manager exclusively to provision Sangoma D series phones, set this global setting to 'YES'. For this situation it is recommended that you uninstall/remove the PBX Digium Phones module, otherwise conflict may occur where 2 PBX modules might try to modify phone configurations.
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"
The DPMA Management page will only be visible if "Use DPMA" option in EPM Global Settings is "YES".
- 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 → Digium and modify the Digium 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 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 -
- 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.
- 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.
After performing a "Save and Rebuild Config(s)", be sure to click the "Apply Config" button to ensure that the changes are applied to DPMA.
Extension Mapping Features
As highlighted in above snapshot, if we are using DPMA option to configure D phones, we can see few extra options which are defined as follows -
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).
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
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.
- Force Phone to Check Config - This option will trigger phones to pull their configuration from the server.
- Force Reboot of phone - This option will forcefully reboot the phone.
- 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.
- 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 - Manual Method
When the D series phone boots, please follow steps below in order to manually select the configuration server.
Pointing your Sangoma D series phone to the DPMA Configuration Server.
Once the above settings are in place, boot your D 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.
Phones will search the local network and display a list of all the systems that are running DPMA. Unless you have multiple DPMA-enabled PBX's on your network, most lists will only include one item.
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.
Only 'Account 1' extensions will display in the user list because DPMA considered Account 1 as a main account. All other accounts (Account 2, Account 3) considered as additional accounts.
If we set Phone Authentication Method to Global PIN, the global password will be requested at this time.
Sometimes, reconfiguring the phone to a different extension is required. Follow the steps below to reconfigure a device.
- 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.
Phone Configuration - Option 66
Please find below list of steps to configure the Sangoma D 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 series phones Only
if you have only Sangoma D 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.
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.
For Sangoma D 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 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 https://wiki.freepbx.org/display/PHON/Setup+Phone+with+DHCP+Option+66#SetupPhonewithDHCPOption66-ConfigureYourCompany'sDHCPServerforOption66 to know more about DHCP Option 66 configuration.
Migrating from previous 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 (v22.214.171.124+/ v126.96.36.199+). 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.
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.
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.
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 -
D Phone VPN
Endpoint Manager has been enhanced to add support for VPN for D series phones as well.
D Phone VPN Supported model
VPN connectivity is only supported by models D60, D62, D65, and D80.
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 series phones.
D Phone Template Improvements
We have improved the layout of the D phone template and also added multiple new options.
The D series phones support 'Smart BLF' which allows control over LED color/blink for normal BLF behavior.
Here you can set display related settings.
Volume Control Settings
This section will allow you to set volume control settings.
- Backup Destination- Enable and Disable the use of backup PBX servers IP Address or FQDN and port.
- Backup Destination Address- If Backup destination Enable, you can define the backup PBX servers IP Address or FQDN (Secondary host).
- Backup Destination Port- If Backup destination Enable, you can define the backup PBX servers IP Address or FQDN port.
- Outbound Proxy- You can define the outbound PBX servers IP Address or FQDN.
- Outbound Proxy Port- You can define the outbound PBX servers IP Address or FQDN port.
- Sip Keep Alive Mode- You can enable and disable the sip keep alive mode.
- Sip Keep Alive Interval (Seconds)- You can define the sip keep alive interval in seconds.
D Phones Ringtones
With our latest update for D Phones, now you can set D phones ringtones with custom ringtones.
Adding the Custom RingTones -
- Endpoint Manager → Right Navigator → Ringtone Management
- Ringtone Management page will show the option to add Ringtones for Sangoma S series phones or Digium D series phones.
- Click on Add Ringtone Button to add custom ringtone.
- Now give Description for custom ringtones and to upload the .wav or .mp3 ringtones file you can click on Browse button or drag the ringtone to Drop Ringtone Here. Important size of custom ringtone file should be less than 1MB and 15 or less seconds in length. Once the ringtone uploaded click on play button.
- The three options are available at the bottom of the Add New Ringtone page are:
- Save- This button will save the custom ringtones in PBX database and convert the .wav or .mp3 ringtone file to sln16. The custom ringtones file will be save to path /tftpboot/ringtones/formatted.
- Reset- This option will reset the Add new ringtone for unsaved custom ringtones file.
- Delete- This option will delete the custom ringtones.
- These two option are use to edit and delete the custom ringtones.
We have added the Ring Tone feature in Digium template. Here you can either choose default ringtones or custom uploaded ringtones.
D Phone TLS Support
Endpoint Manager has been enhanced to add support for TLS for D series phones using DPMA as well.
TLS is only supported by D60, D62, D65, and D80 models.
Currently D series phone only support the publicly-signed certificate.
Setting up proper Hostname
Accessing your system from hosts that are not associated with your SSL certificate will result in an SSL error and on Digium phones, the phone applications will not function properly.
Please define the same SSL certificate host name to your system as well.
- Sysadmin → Right Navigator → Hostname
- Endpoint Manager -> Global Setting : Internal or External address, depends on your template configuration.
Setting up TLS , SRTP Configuration
Please refer to TLS and SRTP wiki guide in order to configure TLS for D series phones.
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 ?
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.
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.