Setup Phone Provisioning

Menu: (Apps-Phones)

This section of SkyPBX is used for automatic phone provisioning.

Provision Settings

Add these settings in the Advanced Menu under Default Settings, Domain

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: text
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

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 SkyPBX official training classes or contact professional support.

Vendor Specific

Polycom

dhcp Option 66

The DHCP Option 66 allows mass provisioning of IP Phones which can not leverage the use of PnP provisioning. Option 66 automates the administrative task of manually inserting the provisioning link in each IP Phone. This way the roll out is faster and mistakes are eliminated. Commonly, Option 66 stands for TFTP boot up server and will be recognized by any IP Phone after they retrieve an IP address from this DHCP server.

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 <GENERAL/> 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.

• add this line to the <GENERAL/> section of {$mac}-phone.cfg

voIpProt.SIP.local.port="{$polycom_local_port}"

• 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

VVX Template

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:

<APPLICATION APP_FILE_PATH="sip.ld" CONFIG_FILES="[PHONE_MAC_ADDRESS]-features.cfg,[PHONE_MAC_ADDRESS]-site.cfg,[PHONE_MAC_ADDRESS]-registration.cfg" MISC_FILES="" LOG_FILE_DIRECTORY="" OVERRIDES_DIRECTORY="" CONTACTS_DIRECTORY="" LICENSE_DIRECTORY="" USER_PROFILES_DIRECTORY="" CALL_LISTS_DIRECTORY="">

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

SkyPBX 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 SkyPBX under Advanced > Default Settings > Provision > http_auth_username
 Password: Found in SkyPBX 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).

Cisco

SPA 5xx Series

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

• Extension: Disabled
• Share Call Appearance: private
• Extended Function:

fnc=blf+sd+cp;sub=1000@voip.example.com;ext=1000@voip.example.com

• Short Name: 1000 [or person's name/whatever]

Hunt Group

• Extension: Disabled
• Share Call Appearance: private
• Extended Function:

fnc=sd+cp;sub=HUNT_GROUP_EXT_NUM@voip.example.com;ext=HUNT_GROUP_EXT_NUM@voip.example.com

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

• Extension: Disabled
• Share Call Appearance: private
• Extended Function:

fnc=blf+sd+cp;sub=PARKINGLOT_EXT_SLOT@$PROXY;ext=PARKINGLOT_EXT_SLOT@$PROXY

• Short Name: Whatever you want on screen.
• SkyPBXhowto: Parking_howto

dhcp Option 66

DHCP (ISC)

/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, SkyPBX 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/SkyPBX

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/sip_330(\.(ld))$" /includes/firmware/sip_330.$2;
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;

From syadnom, for Polycom, with functioning features.cfg and background images

#Polycom
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;

Benefits of Provisioning

• It allows you to automatically configure phone functionality and set up the phone as a specific extension on your SkyPBX 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 SkyPBX

• At any time in the future, you can edit the configuration template on the SkyPBX 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 SkyPBX 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://SkyPBX/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#Provisioning, All

Provisioning, HTTP

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: http://{Linksys-IP}/admin/resync?http://{PBX-Box}/app/provision/?mac=$MA (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 SkyPBX's database.

Edit Hardware Phone in SkyPBX

NOTE: THIS IS NOT IN THE DEFAULT APP->MENU. YOU MIGHT WANT TO ADD IT THERE

• https://voip.example.com/app/hardware_phones/v_hardware_phones.php

Edit the phone you need to do...

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:

• http://voip.example.com/app/provision/?mac=PUT:YOUR:MAC:HERE

If you don't get an XML file back, try above.

1. In SkyPBX 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.
   1. Select a line number to assign.
4. save the extension.
5. reboot the phone.
   1. You may actually have to tell the phone to do the re-provision dance again:
   2. load: http://{Linksys-IP}/admin/resync?http://{PBX-Box}/app/provision/?mac=$MA

Continue with Phones#Provisioning, All

Provisioning, All

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

In SkyPBX 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 SkyPBXknows 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 SkyPBX server and allows the setting of the settings specific to each phone eg. the extension to connect to.

2. SkyPBX requires a rewrite rule in the web server so that http://SkyPBX/provisioning/yealink/001565aabbcc.cfg gets rewritten to the SkyPBX provisioning URL e.g. The rewrite rule should forward the request to http://SkyPBX/app/provision/index.php?mac=001565aabbcc. SkyPBX 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 SkyPBX .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, SkyPBX will add the MAC address of the phone to the database and it will show up in the phones screen in SkyPBX. For the linksys-2102 and 3102, the user_agent enables SkyPBX to automatically assign a template, which includes setting a permanent provisioning.

If SkyPBX 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 SkyPBX for provisioning you can try this URL (changing SkyPBX to the IP address of your server): http://SkyPBX/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:

# /etc/dnsmasq.d/pbx

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

log-dhcp

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

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

<!-- /etc/dnsmasq.d/pbx.tftp/spa3102.cfg -->

<!--
  Assumes SkyPBX is at http://pbx.local/ and there is a syslog server
  accepting remote UDP packets listening at 10.1.2.1:514.
-->
<flat-profile>
  <!-- Device being provisioned automatically replaces $MA with its own MAC address. -->
  <Profile_Rule>http://pbx.local/app/provision/?mac=$MA</Profile_Rule>
  <Resync_Periodic ua="na">10</Resync_Periodic>
  <Syslog_Server>10.1.2.1</Syslog_Server>
  <Debug_Server>10.1.2.1</Debug_Server>
  <Debug_Level>2</Debug_Level>
</flat-profile>

Or, using the SPA3102 web interface without TFTP, visit http://10.1.2.50/admin/resync?http://pbx.local/app/provision/?mac=$MA in your browser, assuming 10.1.2.50 is the address of the device you want to provision and pbx.local is the hostname of your SkyPBX 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:

<?xml version="1.0" encoding="utf-8" standalone="yes"?> <sip> <efk>

  <version efk.version="2" />
  <efklist>
       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$"

</efklist> <efkprompt>

       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"

</efkprompt> </efk> <softkey>

    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"
   </softkey>

</sip>

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 [1]

Grandstream

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 >=< with a >

Screen Capture

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