Phones

Menu: (Apps-Phones)

This section of FusionPBX is used for automatic phone provisioning.

=Provision Settings=

Advanced, Default Settings, Category, Provision (or in advanced, domains)

How to enable web based on demand provisioning. Category: provision Sub Category: enabled Type: text Value: true Enabled: true

Protect the server with a CIDR range. Category: provision Sub Category: cidr Type: array Value: value: could be a single ip address or a range. Example: 10.8.0.1/32 (single ip) 10.8.0.0/24 (allow all the IP addresses from 10.8.0.0-255 in the 10.8.0 subnet. 0.0.0.0/0 (allow all ip addresses) Enabled To add multiple CIDR blocks add another cidr array to the provision section under "Advanced" > "Default Settings". Be sure to increment the "Order".

Used to protect the device configuration with HTTP authentication Category: provision Sub Category: http_auth_username and http_auth_password Type: text Value: username or password goes here

A password that is required to login to the phone Category: provision Sub Category: admin_name and admin_password Type: text Value: username or password goes here

Some advanced options are: template_directory, device_time_zone, and many others, their usage is reviewed at the FusionPBX official training classes or contact professional support.

=Vendor Specific=

DHCP (ISC)
/etc/dhcp/dhcpd.conf option provision-tftp code 66 = string; subnet ############## { option provision-tftp          "http://{yourserver}/provision"; }

dnsmasq
/etc/dnsmasq.conf dhcp-option=tag:eth0,66,"http://{yourserver}/provision"

4.0 and 5.0 Templates
The 4.0 and 5.0 templates are the most recent additions to the Polycom provisioning templates. They use only one file for all required items, and leave the rest up to the phone for defaults and overrides.

Hold Music Issues
Polycom's default hold music behavior is to use multiple methods, including deprecated RFC 2543 where calls on hold get c=0.0.0.0, which results in silence. This can be fixed in the 4.0 and 5.0 templates by adding the following to the  section of {$mac}-phone.cfg voIpProt.SIP.useRFC3264HoldOnly="1" voIpProt.SIP.useSendonlyHold="1"

overlapping local ports behind NAT
Occasionally, remote phones behind a NAT firewall will negotiate the same local port, which the NAT handler will not likely be able to handle. If you get some phones the work and others that don't, check your SIP Profiles, Internal, Registrations for any extensions registered from the same IP listing the same port. If this is happening, you may need to statically define the local port for the phones behind that firewall. voIpProt.SIP.local.port="{$polycom_local_port}"
 * add this line to the  section of {$mac}-phone.cfg
 * in the Settings section of each device, define Name 'polycom_local_port', with a unique Value for that site (somewhere around 5060), set Enabled = True.
 * Re-provision the phone and you should see that it registers with the defined port under SIP Profiles, Internal, Registrations

features.cfg
optional, to use features.cfg, you must modify the {$mac}.cfg in Files/polycom/vvx under the provisioning editor to include [PHONE_MAC_ADDRESS]-features.cfg, see example excerpt: 

note, if you add this configuration you MUST use rewrite rules (see in document) that include features.cfg, else the phones will complain about missing files.

Updating line key display
the default line key display is set to be the extension. This may not be ideal and is easy to change. In the provisioner, modify {mac}-registration.cfg and change the following lines label="{$row.display_name}" thirdPartyName=""

the label="" can be a variety, but is limited to 15 characters else the display. the variable display_name is set in Devices in the same field name.

NOTE on updating line key display
in response to 'Updating line key display' above, it should be noted that the default line key display can be edited in the Keys section. I.E. To define a label for line 1, follow these steps:
 * 1) select 'Line' in Category
 * 2) select a key number that corresponds with the line (i.e. Key 1 for Line 1)
 * 3) select 'Line' under Type
 * 4) enter the number of line appearances you want for the selected line (i.e. 2 to get 2 buttons, or 1 to get 1 button).
 * 5) leave 'Extension' blank
 * 6) enter desired label under 'Label' i.e. "x221 - Bob"

NTP client on phones
one method of configuring the ntp client on polycom phones is to set variables in default settings Navigate to Advanges, Default Settings. Under the Provision section, add the following, taking care to convert your GMT offset to seconds (hours * 3600), example is for GMT -0700. Subcategory=ntp_server_primary type=text Value=pool.ntp.org Enabled=True Subcategory=polycom_gmt_offset type=text Value=-25200

These variables are already being used in site.cfg, so there are no other changes needed.

Yealink
FusionPBX supports many of the Yealink phones out of the box. To provision you can use either DHCP option 60 (not tested) or HTTP provision.

HTTP Provisioning
HTTP provisioning is configured under Phone > Auto Provision menu. I have tested this on a Yealink T32G.

Provisioning Server: https://PBX_IP_OR_HOST/app/provision User Name: Found in FusionPBX under Advanced > Default Settings > Provision > http_auth_username Password: Found in FusionPBX under Advanced > Default Settings > Provision > http_auth_password

Note that if you enable `cidr` verification then you must also configure it at Advanced > Default Settings > Provision > cidr.

Useful Note
If you are provisioning using HTTPS then either ensure that you have a trusted server certificate or disable trusted certificates (Security > Trusted Certificates > Only Accept Trusted Certificates).

Dialplan
(*xxxxxxx|*xxxxxx|*xxxxx|*xxxx|*xxx|*xx*|*x|**xxxxx|**xxxx|**xxx|**xx|10xx|5xxx|[3469]11|0|00|1[2-9]xx[2-9]xxxxxx|[2-9]xx[2-9]xxxxxx|[2-9]xxxxxx|011[2-9]x.|1900xxxxxxx!)

Line Key
Admin->Advanced->Voice->Phone

BLF
fnc=blf+sd+cp;sub=1000@voip.example.com;ext=1000@voip.example.com
 * Extension: Disabled
 * Share Call Appearance: private
 * Extended Function:
 * Short Name: 1000 [or person's name/whatever]

Hunt Group
fnc=sd+cp;sub=HUNT_GROUP_EXT_NUM@voip.example.com;ext=HUNT_GROUP_EXT_NUM@voip.example.com
 * Extension: Disabled
 * Share Call Appearance: private
 * Extended Function:
 * Short Name: Whatever you want on screen.

Call Park with BLF
The following is for Call Park to a specific slot, this is the method that works best with Cisco SPA phones.

fnc=blf+sd+cp;sub=PARKINGLOT_EXT_SLOT@$PROXY;ext=PARKINGLOT_EXT_SLOT@$PROXY
 * Extension: Disabled
 * Share Call Appearance: private
 * Extended Function:
 * Short Name: Whatever you want on screen.
 * Fusion howto: Parking_howto

Certificate Request for Signing
default_ca = CA_default [ CA_default ] default_days = 1095 default_crl_days = 15 default_md = sha1 crl_extensions = crl_ext [ req ] default_bits      = 4096 distinguished_name = req_distinguished_name req_extensions    = req_ext [ req_distinguished_name ] countryName                = Country Name (2 letter code) stateOrProvinceName        = State or Province Name (full name) localityName              = Locality Name (eg, city) organizationName          = Organization Name (eg, company) commonName                = Common Name (e.g. server FQDN or YOUR name) [ req_ext ] subjectAltName = @alt_names [alt_names] DNS.1  = myhostname1.domain.com DNS.2  = myhostname2.domain.com DNS.3  = myhostname3.domain.com
 * Create empty file with favorite editor san.cfg

openssl req -out cisco-provision.csr -newkey rsa:4096 -nodes -keyout private-key.pem -config san.cnf openssl req -noout -text -in cisco-provision.csr | grep DNS
 * Replace DNS.x with external hostnames.
 * Generate Signing Request with openssl
 * Verify generated certificate request

Sign generated certificate request with cisco CA cert
https://webapps.cisco.com/software/edos/home
 * Log in to cisco portal or create new account


 * Fill required information and send signed cert to you email

Apply signed cert on web server

 * HAproxy or NGINX

frontend prov-ssl bind :::my_port v4v6 ssl crt /my_cert_path/prod-prov.pem option httplog option dontlognull no option logasap

server { listen my_local_ip:my_local_port; server_name external_hostname; autoindex off; ssl on; ssl_protocols TLSv1 TLSv1.1 TLSv1.2; ssl_ciphers HIGH:!aNULL:!MD5; ssl_prefer_server_ciphers  on; ssl_certificate    /etc/nginx/cert/cert_bundle.pem; ssl_certificate_key /etc/nginx/cert/cert-key_nopasswd.key;

Certificate order

-BEGIN RSA PRIVATE KEY- generated key -END RSA PRIVATE KEY- -BEGIN CERTIFICATE- signed cert -END CERTIFICATE- -BEGIN CERTIFICATE- Cisco CA and Intermediate Certs -END CERTIFICATE-


 * Enjoy

dhcp Option 66
/etc/dhcp/dhcpd.conf option provision-tftp code 66 = string; subnet ############## { option provision-tftp          "http://{yourserver}/app/provision?mac=$MA"; }

dnsmasq
/etc/dnsmasq.conf dhcp-option=tag:eth0,66,"http://{yourserver}/app/provision?mac=$MA'"

SLA on Polycom
SLA is configurable and functional on both Polycom and Cisco/Linksys SPA models and works perfectly with the provisioner

Polycom
in the provisioning editor/Files/polycom/model(650 or vvx)/{$mac}-registration update the following line from private to shared, this is line 10 reg.{$row.line_number}.type="shared"

additionally, thirdPartyName must be set to "", typically line 12 reg.{$row.line_number}.thirdPartyName=""

in each sip profile that phones will register to, verify that both manage_presence and manage-shared-appearance is set to true. This is the default at time of writing so you may not have to make any changes.

=Requirements=
 * The phone/ata must support automatic provisioning.
 * If your DHCP server supports supplying options 66 or 43 to DHCP clients, then you can start provisioning more easily.
 * Your phone will require either a TFTP server or an FTP server or an HTTP or HTTPS server to provide the provisioning files. If you are using http, FusionPBX is set up to handle that automatically.

Rewrite Rules
You may need some of the following rewrite rules (for nginx) to support provisioning. Add to /etc/nginx/sites-enabled/fusionpbx

from mcrane:

aastra rewrite "^.*/provision/aastra.cfg$" /app/provision/?mac=$1&file=aastra.cfg; rewrite "^.*/provision/([A-Fa-f0-9]{12})(\.(xml|cfg))?$" /app/provision/index.php?mac=$1 last; grandstream rewrite "^.*/provision/cfg([A-Fa-f0-9]{12})(\.(xml|cfg))?$" /app/provision/?mac=$1; yealink rewrite "^.*/(y[0-9]{12})(\.cfg)?$" /app/provision/index.php?file=\$1\$2; rewrite "^.*/provision/([A-Fa-f0-9]{12})(\.(xml|cfg))?$" /app/provision/index.php?mac=$1 last; combined (untested) rewrite "^.*/provision/(cfg)?([A-Fa-f0-9]{12})(\.(xml|cfg))?$" /app/provision/index.php?mac=$2;

note, this does not handle features.cfg rewrite properly: From mputnam, for Polycom rewrite "^.*/provision/000000000000.cfg$" "/app/provison/?mac=$1&file=%7b%24mac%7d.cfg"; rewrite "^.*/provision/features.cfg$" /app/provision/?mac=$1&file=features.cfg; rewrite "^.*/provision/([A-Fa-f0-9]{12})-sip.cfg$" /app/provision/?mac=$1&file=sip.cfg; rewrite "^.*/provision/([A-Fa-f0-9]{12})-phone.cfg$" /app/provision/?mac=$1; rewrite "^.*/provision/([A-Fa-f0-9]{12})-registration.cfg$" "/app/provision/?mac=$1&file=%7b%24mac%7d-registration.cfg"; rewrite "^.*/provision/([A-Fa-f0-9]{12})-site.cfg$" /app/provision/?mac=$1&file=site.cfg; rewrite "^.*/provision/([A-Fa-f0-9]{12})-web.cfg$" /app/provision/?mac=$1&file=web.cfg;
 * 1) rewrite "^.*/provision/sip_330(\.(ld))$" /includes/firmware/sip_330.$2;

From syadnom, for Polycom, with functioning features.cfg and background images rewrite "^.*/provision/000000000000.cfg$" "/app/provison/?mac=$1&file=%7b%24mac%7d.cfg"; rewrite "^.*/provision/(.*).(png|jpg|gif)" "/app/provision/$1.$2"; #this catches image requests, put images in the provision folder. rewrite "^.*/provision/([A-Fa-f0-9]{12})-features.cfg$" /app/provision/?mac=$1&file=features.cfg; rewrite "^.*/provision/([A-Fa-f0-9]{12})-sip.cfg$" /app/provision/?mac=$1&file=sip.cfg; rewrite "^.*/provision/([A-Fa-f0-9]{12})-phone.cfg$" /app/provision/?mac=$1; rewrite "^.*/provision/([A-Fa-f0-9]{12})-registration.cfg$" "/app/provision/?mac=$1&file=%7b%24mac%7d-registration.cfg"; rewrite "^.*/provision/([A-Fa-f0-9]{12})-site.cfg$" /app/provision/?mac=$1&file=site.cfg; rewrite "^.*/provision/([A-Fa-f0-9]{12})-web.cfg$" /app/provision/?mac=$1&file=web.cfg;
 * 1) Polycom

=Benefits of Provisioning=
 * It allows you to automatically configure phone functionality and set up the phone as a specific extension on your FusionPBX phone system.
 * It is useful when you have a large number of phones to configure with common settings and the only difference between them being the mac address and the extension details (rather than making the edits manually via the phones' own web administration pages)
 * If the phones are "out in the field" you can still make changes to the configuration files.

=Benefits of Provisioning with FusionPBX=
 * At any time in the future, you can edit the configuration template on the FusionPBX server in order to make a change to all the phones next time they provision/reboot, rather than having to manually change each one.
 * From the extensions page, you can select which device, and which line on that device, that phone should register to.
 * You can create a provisioning password. In the Variable page, add the variable "password" in a new category called "Provision"

=Provisioning Step By Step= There are two ways to start - Option 66 or manually adding the provisioning URL.

Provisioning, Option 66 (untested)
1. Setup a DHCP server where you can set options 66 and 43 to point to an HTTP or TFTP server (most phones capable of auto-provisioning support TFTP, but some also support HTTP) - dnsmasq is an example of a DHCP server that can do this

2. Point the URL in option 66 and 43 to a directory on your FusionPBX server. An example using dnsmasq syntax and assuming Yealink phone would be: log-dhcp dhcp-range=192.168.1.100,192.168.1.149,12h dhcp-host=00:15:65:aa:bb:cc,net:YEA,192.168.1.101,yealink_ext101 dhcp-option=YEA,66,"http://fusionpbx/provisioning/yealink" Note that normally option 66 will only be a hostname or IP address, but it is possible that some phones might be smart enough to have a URL there and work out the server type from it.

Continue with Phones

Add Phone URL to Provision
If your phone can use http for provisioning, e.g. Yealink and all Linksys, then you can manually add the provision URL to the device. This way, you only have to make one change to your phones manually - to make it look for the provisioning server. (Note for Yealink: you have to enable "check new config")

For example, in the Linksys, to provision via the web ONCE simply load: (To find out the IP of the device, pick up a phone and press ****. Then, 1 1 0 #. If the page is unreachable, the web config may be disabled. In that same menu, press 7 9 3 2 # followed by 1 # then 1 to save.) You might need to set "Provision Enable=Yes" in the Voice->Provisioning tab before doing the resync. If it doesn't work, check this.

Doing this will add the MAC address of the phone into FusionPBX's database.

Edit Hardware Phone in FusionPBX
'''NOTE: THIS IS NOT IN THE DEFAULT APP->MENU. YOU MIGHT WANT TO ADD IT THERE''' Edit the phone you need to do...
 * https://voip.example.com/app/hardware_phones/v_hardware_phones.php
 * 1) give the phone a label
 * 2) select a template
 * 3) vendor name should hopefully auto-fill
 * 4) set a time zone (eg America/Chicago)
 * 5) save it.

Add phone to extension
Note: You can test the configuration for this by going to: If you don't get an XML file back, try above.
 * http://voip.example.com/app/provision/?mac=PUT:YOUR:MAC:HERE
 * 1) In FusionPBX select Accounts->Extensions
 * 2) Pick an extension you want to assign a phone to and edit it.
 * 3) Under Phone Provisioning's dropdown, select the phone that should be assigned.
 * 4) Select a line number to assign.
 * 5) save the extension.
 * 6) reboot the phone.
 * 7) You may actually have to tell the phone to do the re-provision dance again:
 * 8) load:

Continue with Phones

Provisioning, All
After either Option 66 or manual entry, we continue here:

In FusionPBX you have to first setup a tftp, ftp server (or use html if your phones support it). Go to advanced -> system settings and set the path to that directory so that Fusion knows where to write the config.

1. The phone will then request the relevant files from the server. Yealink will request two - a config file, e.g. Yealink T-20->y000000000007.cfg and a file specific to the mac address of your phone. The linksys boxes only request one file. (but it seems you can set up multiple files to provision) A general config file should be provided on your webserver at the URL you specify, and will set all the standard parameters of your phones. The specific file is provided in the next few steps below by the FusionPBX server and allows the setting of the settings specific to each phone eg. the extension to connect to.

2. FusionPBX requires a rewrite rule in the web server so that http://fusionpbx/provisioning/yealink/001565aabbcc.cfg gets rewritten to the fusionpbx provisioning URL e.g. The rewrite rule should forward the request to http://fusionpbx/app/provision/index.php?mac=001565aabbcc. FusionPBX uses apache as a web server by default in the iso, but you might be using a different web server so you'll need to work this out for the server you are using. There are some Apache rewrite rule examples in the FusionPBX .htaccess file. An example for Nginx is: location / { rewrite "^/provisioning/[a-z]+/([A-Fa-f0-9]{12})(\.(xml|cfg))$" /app/provision/index.php?mac=$1 last; }

3. When the phone requests that URL, FusionPBX will add the MAC address of the phone to the database and it will show up in the phones screen in FusionPBX. For the linksys-2102 and 3102, the user_agent enables FusionPBX to automatically assign a template, which includes setting a permanent provisioning.

If FusionPBX does not automatically assign a template, you will need to edit the new entry (which has the info "auto") and set a template. You will now need to wait for option66 again, or set your device to provision once more.

4. The phone will re-configure itself from that config file and then register with freeswitch.

There are many things that can go wrong in automated provisioning. When you are first setting it up you might want to set your DHCP server to provide you with verbose logging so you can diagnose it. You also might want to set your phone to use verbose logging too.

As an example of what will happen when your phone makes a request to FusionPBX for provisioning you can try this URL (changing fusionpbx to the IP address of your server): http://fusionpbx/app/provision/index.php?mac=00085daabbcc. You can then go to the phones page and you'll see a new phone with this mac address added. Press the X to delete it since it was just an experiment anyway!

Linksys/Cisco SPA3102-specific notes
TODO: This information probably belongs on its own wiki page. Putting it here temporarily under the assumption that it's better to publish it in rough form somewhere rather than not at all. This information may also benefit SPA2102 and PAP2T users.

Using dnsmasq and TFTP option 66 to bootstrap provisioning:
 * 1) /etc/dnsmasq.d/pbx


 * 1) Assumes 00:0e:08:aa:bb:cc is the mac address of the SPA3102 you are provisioning
 * 2) and you want to assign the SPA3102 address 10.1.2.50 and hostname "my3102".

log-dhcp

enable-tftp=eth1 tftp-root=/etc/dnsmasq.d/pbx.tftp
 * 1) "=eth1" below is optional.  Leave it off if you don't mind dnsmasq's
 * 2) mini-TFTP server listening on all interfaces.

dhcp-option=SPA,66,0.0.0.0 dhcp-host=00:0e:08:aa:bb:cc,net:SPA,10.1.2.50,my3102
 * 1) dnsmasq replaces 0.0.0.0 with its IP
 * 1) add additional dhcp-host lines here as needed for other 3102s

 http://pbx.local/app/provision/?mac=$MA 10 10.1.2.1 10.1.2.1 2 

Or, using the SPA3102 web interface without TFTP, visit in your browser, assuming  is the address of the device you want to provision and  is the hostname of your FusionPBX server.

Polycom SoundPoint Phone-specific notes
Enhanced Feature Key Setup

In provisioning folder create a custom.cfg file (This file can be called whatever you want it to be. You might want different EFK config files for different users or groups of users, so name them appropriately.) and paste the contents of the XML file below:



<version efk.version="2" /> efk.efklist.1.mname="intercom1" efk.efklist.1.status="1" efk.efklist.1.label="Intercom" efk.efklist.1.action.string="*8$P1N4$$Tinvite$" efk.efklist.2.mname="xfervm1" efk.efklist.2.label="Transfer To Voicemail" efk.efklist.2.status="1" efk.efklist.2.action.string="*99$P2N4$$Trefer$" efk.efklist.3.mname="grppage1" efk.efklist.3.label="Group Page" efk.efklist.3.status="1" efk.efklist.3.action.string="$P3N4$$Tinvite$" efk.efkprompt.1.status="1" efk.efkprompt.1.label="Extension: " efk.efkprompt.1.userfeedback="visible" efk.efkprompt.1.type="numeric" efk.efkprompt.2.status="1" efk.efkprompt.2.label="Mail Box: " efk.efkprompt.2.userfeedback="visible" efk.efkprompt.2.type="numeric" efk.efkprompt.3.status="1" efk.efkprompt.3.label="Page Group: " efk.efkprompt.3.userfeedback="visible" efk.efkprompt.3.type="numeric" softkey.1.label="Xfer2VM" softkey.1.action="!xfervm1" softkey.1.enable="1" softkey.1.precede="0" softkey.1.use.idle="0" softkey.1.use.active="1" softkey.1.use.alerting="" softkey.1.use.dialtone="" softkey.1.use.proceeding="" softkey.1.use.setup="" softkey.1.use.hold="" softkey.3.label="Intercom" softkey.3.action="!intercom1" softkey.3.enable="1" softkey.3.precede="0" softkey.3.use.idle="1" softkey.3.use.active="1" softkey.3.use.alerting="1" softkey.3.use.dialtone="1" softkey.3.use.proceeding="" softkey.3.use.setup="" softkey.3.use.hold="1" softkey.4.label="Grp Page" softkey.4.action="!grppage1" softkey.4.enable="1" softkey.4.precede="0" softkey.4.use.idle="1" softkey.4.use.active="1" softkey.4.use.alerting="1" softkey.4.use.dialtone="1" softkey.4.use.proceeding="" softkey.4.use.setup="" softkey.4.use.hold="1" softkey.feature.newcall="1" softkey.feature.endcall="1" softkey.feature.split="1" softkey.feature.join="1" softkey.feature.forward="1" softkey.feature.directories="" softkey.feature.callers="" softkey.feature.mystatus="0" softkey.feature.buddies="0" softkey.feature.basicCallManagement.redundant="0"

This EFK file will: setup an intercom soft button on the phone that will dial *8 and then ask for user input and allow for a 4 digit extension to be entered setup a group page button that will allow for the entry of a page group. You can program this button to automatically dial particular page group by editing efk.efklist.3.action.string="$P3N4$$Tinvite$" and replacing "$P3N4$$Tinvite$" with "*468$P3N4$$Tinvite$" where *468 is some group page extension setup in the dial plan. setup transfer to voicemail button that will automatically throw a caller in a user's voicemail box.

For more information on Polycom Enhanced Feature Keys go to

Templates
Grandstream provides you with a text template. This template is similar to normal unix config style files. They give you a converter which then converts that into a binary file with a url encoded string of all of the P values. To get this into xml, here's some nasty sed fu: cat dp715.txt |sed 's/^#.*/& -->/' | sed -e s/^#/\<\!--/g | sed 's/^\(P[0-9]*\)\(=.*\)/<\1>\2<\/\1>/' | sed 's/>=/>/'

What it does
converts a unix style config file to an xml file. This won't work in all cases but it should work for grandstream config files...
 * make sure there are no spaces between the P2 = blah FIRST

cat dp715.txt | sed 's/^#.*/& -->/' put an xml end comment on all lines that start with #

sed -e s/^#/\<\!--/g replace the hash on all lines that start with # with <!--

sed 's/^\(P[0-9]*\)\(=.*\)/<\1>\2<\/\1>/' Find P followed by a number (pattern 1). Then find an equal followed by anything else (pattern 2). Print out <(pattern1)(pattern2)(pattern1)>

sed 's/>=/>/' replace >=

Screen Capture
Capture screenshot of phone http://wiki.fusionpbx.com/index.php?title=Screen_Capture