Database driven Polycom provisioning with Asterisk RealTime

Getting Started

This page will make setting up Polycom phone extensions a breeze within your network. This was done with Polycom's new 4.0.3 software for the current SoundPoint IP Series (450, 550, 650, etc), using Asterisk 11 on an Ubuntu 12.04 server. However, you should be able to adapt it to any Polycom SIP version, Asterisk version, or Linux version you choose.

The basic function of this setup is that you never have to hand edit another Polycom config file as long as you live. DHCP tells the phone to get its config from FTP, which tells the phone to pull an HTTP request that has its own mac address in it, Apache rewrites it and passes it as a variable to a PHP script, which then queries the database and returns with a generated config file specific for that phone. It's a lot simpler than it sounds!

FTP Provisioning

The first step is to get your server set up to update the firmware on the handsets. We want to use FTP so that the phone can report back its logs as well as store config overrides and custom phone books back on the server. You can't do that with HTTP or TFTP.

  • Add a user called "polycom" and pick a password. 456 is appropriate, or make it more complex if you'd like, but there's no way to hide it from the rest of the network because it will be included in the DHCP answers.
  • In /etc/passwd, change the shell to /usr/sbin/nologin so the polycom user can't get shell access.
  • In your dhcp server scope, include this line. It will point your phones to your server for provisioning.
    option tftp-server-name "ftp://polycom:456@192.168.1.55";
  • Use the ftp server of your choice. I just used ftpd. Be sure to add polycom to /etc/ftpchroot for added security.

Polycom Software

  • Download the latest, or appropriate software package from http://support.polycom.com/PolycomService/support/us/support/voice/soundpoint_ip/
  • This example uses Polycom 4.0.3.
  • If you're like me and going to 4.0, you'll need to update your bootrom. This guide can still apply if you want to stick on 3.x or even 2.x, but why would you? Read about upgrading and downgrading the bootrom here: http://support.polycom.com/PolycomService/support/us/support/eula/ucs/UCagreement_combined_4_4_0_upgrader.html
  • I think what I did was unpack the combined, then the split, then the bootrom upgrader to /home/polycom.
  • make three directories under /home/polycom: log, overrides, and contacts. It's just cleaner that way.
  • Important: if you did the above as root you'll need to chown all the stuff in /home/polycom back to the polycom user. example: chown -R polycom.polycom /home/polycom
  • Finally, edit 000000000000.cfg with the following changes:
    • change CONFIG_FILES to read: "http://192.168.1.55/polycoms/[PHONE_MAC_ADDRESS]" — replace the IP with your server IP but you're not replacing the brackets with any of your phone's mac addresses. What this url does is tell the Polycom phone to go to that URL and put its own mac address in there to get its configuration information.
    • for the LOG_FILE_DIRECTORY, OVERRIDES, and CONTACTS.. put "log" "overrides" and "contacts" respectively (you created these folders in a previous step).
    • Leave everything else as default.

Apache Setup

  • Ensure mod php and cgi are enabled. Doing that is beyond the scope of this document.
  • Install and enable mod rewrite.
  • in your /var/www/polycoms/.htaccess file, put this:
    RewriteEngine on
    RewriteRule (0004[0-9a-f]+) config.php?mac=$1 [PT]
    This matches any polycom product (or at least the ones I was using)

Database Setup

You'll need to have set up Asterisk RealTime Sip, which is beyond the scope of these directions. It's quite simple, folks! You'll need a valid sip_peers table for this to work properly.

Create a table called polycoms. with three columns, id (auto increment), mac (varchar length 12), and name (varchar, this is their extension/phone number so make it long enough). Add all your physical handsets here. The mac address should be in lower case. The "name" column needs to match the "name" entry in the sip_peers table that you have already set up for that user.

PHP Provisioning Script

See below for explanation.
/var/www/polycoms/config.php:
<?php

function returnQuery($mac) {
  return mysql_query("SELECT * FROM polycoms LEFT JOIN (sip_peers) on (sip_peers.name=polycoms.name) WHERE polycoms.mac = '" . $mac . "'");
} // returnQuery

$mac = $_GET["mac"] or die ("\nno mac supplied!\n");

include ("dbinfo.php");
mysql_connect($hostname,$username,$password);
@mysql_select_db($database) or die ("Unable to select database");

$query = returnQuery($mac);
if (mysql_num_rows($query) < 1) die ("Extension not found in database...\n");

$authpass = mysql_result($query,0,'secret');
$name = mysql_result($query,0,'name');

print "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n";
?>
<polycomConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="polycomConfig.xsd">
  <call call.callsPerLineKey="24">
  </call>
  <reg reg.1.address="<? print $name; ?>" reg.1.auth.password="<? print $authpass; ?>" reg.1.auth.userId="<? print $name; ?>" reg.1.label="<? print $name; ?>" reg.1.outboundProxy.address="" reg.2.address="" reg.2.auth.password="" reg.2.auth.userId="" reg.2.label="" reg.2.outboundProxy.address="">
  </reg>
  <msg>
    <msg.mwi msg.mwi.1.callBackMode="registration" msg.mwi.2.callBackMode="registration">
    </msg.mwi>
  </msg>
  <voIpProt>
    <voIpProt.server voIpProt.server.1.address="192.168.1.55" voIpProt.server.1.port="5060" voIpProt.server.2.address="" voIpProt.server.2.port="0">
    </voIpProt.server>
    <voIpProt.SIP voIpProt.SIP.enable="1">
      <voIpProt.SIP.outboundProxy voIpProt.SIP.outboundProxy.address="">
      </voIpProt.SIP.outboundProxy>
      <voIpProt.SIP.alertInfo voIpProt.SIP.alertInfo.1.value="Ring Answer" voIpProt.SIP.alertInfo.1.>
      </voIpProt.SIP.alertInfo>
    </voIpProt.SIP>
  </voIpProt>
  <dialplan>
    <digitmap dialplan.digitmap="911|5000|[2-9]xxxxxxxxx|1[2-9]xxxxxxxxx|*xx.T" dialplan.digitmap.timeOut="3|3|3|3|3" />
  </dialplan>
  <up up.headsetMode="1" up.oneTouchVoicemail="1" />
  <feature feature.enhancedFeatureKeys.enabled="1" />
  <softkey softkey.feature.forward="0" softkey.1.enable="1" softkey.1.label="Cell Fwd" softkey.1.use.idle="1" softkey.1.insert="3" softkey.1.action="**78383" />
  <microbrowser mb.proxy="">
    <idleDisplay mb.idleDIsplay.home="http://192.168.1.55/polycoms/stats.php" mb.idleDisplay.refresh="7" />
    <main mb.main.home="" />
    <limits mb.limits.nodes="" mb.limits.cache="" />
  </microbrowser>
</polycomConfig>

  • dbinfo.php contains your mysql login, database info, etc
  • Change the IP of your SIP server obviously.
  • Modify your digit map as necessary.
  • The softkey referenced here was to a custom action that I wrote to enable queue joining and auto forwarding to cell phones
  • The microbrowser page was a simple PHP which gave them live call statistics. Feel free to take both of these out.
  • If you are provisioning an older Polycom SIP version, you'll need to incorporate a whole bunch more stuff due to the massive config files of 3.x. Good luck with that. I think it's just easier to upgrade to 4.x and throw your old 501's out the window.

Wrapping up

Go upgrade some handsets and kick some major ass.

Getting Started

This page will make setting up Polycom phone extensions a breeze within your network. This was done with Polycom's new 4.0.3 software for the current SoundPoint IP Series (450, 550, 650, etc), using Asterisk 11 on an Ubuntu 12.04 server. However, you should be able to adapt it to any Polycom SIP version, Asterisk version, or Linux version you choose.

The basic function of this setup is that you never have to hand edit another Polycom config file as long as you live. DHCP tells the phone to get its config from FTP, which tells the phone to pull an HTTP request that has its own mac address in it, Apache rewrites it and passes it as a variable to a PHP script, which then queries the database and returns with a generated config file specific for that phone. It's a lot simpler than it sounds!

FTP Provisioning

The first step is to get your server set up to update the firmware on the handsets. We want to use FTP so that the phone can report back its logs as well as store config overrides and custom phone books back on the server. You can't do that with HTTP or TFTP.

  • Add a user called "polycom" and pick a password. 456 is appropriate, or make it more complex if you'd like, but there's no way to hide it from the rest of the network because it will be included in the DHCP answers.
  • In /etc/passwd, change the shell to /usr/sbin/nologin so the polycom user can't get shell access.
  • In your dhcp server scope, include this line. It will point your phones to your server for provisioning.
    option tftp-server-name "ftp://polycom:456@192.168.1.55";
  • Use the ftp server of your choice. I just used ftpd. Be sure to add polycom to /etc/ftpchroot for added security.

Polycom Software

  • Download the latest, or appropriate software package from http://support.polycom.com/PolycomService/support/us/support/voice/soundpoint_ip/
  • This example uses Polycom 4.0.3.
  • If you're like me and going to 4.0, you'll need to update your bootrom. This guide can still apply if you want to stick on 3.x or even 2.x, but why would you? Read about upgrading and downgrading the bootrom here: http://support.polycom.com/PolycomService/support/us/support/eula/ucs/UCagreement_combined_4_4_0_upgrader.html
  • I think what I did was unpack the combined, then the split, then the bootrom upgrader to /home/polycom.
  • make three directories under /home/polycom: log, overrides, and contacts. It's just cleaner that way.
  • Important: if you did the above as root you'll need to chown all the stuff in /home/polycom back to the polycom user. example: chown -R polycom.polycom /home/polycom
  • Finally, edit 000000000000.cfg with the following changes:
    • change CONFIG_FILES to read: "http://192.168.1.55/polycoms/[PHONE_MAC_ADDRESS]" — replace the IP with your server IP but you're not replacing the brackets with any of your phone's mac addresses. What this url does is tell the Polycom phone to go to that URL and put its own mac address in there to get its configuration information.
    • for the LOG_FILE_DIRECTORY, OVERRIDES, and CONTACTS.. put "log" "overrides" and "contacts" respectively (you created these folders in a previous step).
    • Leave everything else as default.

Apache Setup

  • Ensure mod php and cgi are enabled. Doing that is beyond the scope of this document.
  • Install and enable mod rewrite.
  • in your /var/www/polycoms/.htaccess file, put this:
    RewriteEngine on
    RewriteRule (0004[0-9a-f]+) config.php?mac=$1 [PT]
    This matches any polycom product (or at least the ones I was using)

Database Setup

You'll need to have set up Asterisk RealTime Sip, which is beyond the scope of these directions. It's quite simple, folks! You'll need a valid sip_peers table for this to work properly.

Create a table called polycoms. with three columns, id (auto increment), mac (varchar length 12), and name (varchar, this is their extension/phone number so make it long enough). Add all your physical handsets here. The mac address should be in lower case. The "name" column needs to match the "name" entry in the sip_peers table that you have already set up for that user.

PHP Provisioning Script

See below for explanation.
/var/www/polycoms/config.php:
<?php

function returnQuery($mac) {
  return mysql_query("SELECT * FROM polycoms LEFT JOIN (sip_peers) on (sip_peers.name=polycoms.name) WHERE polycoms.mac = '" . $mac . "'");
} // returnQuery

$mac = $_GET["mac"] or die ("\nno mac supplied!\n");

include ("dbinfo.php");
mysql_connect($hostname,$username,$password);
@mysql_select_db($database) or die ("Unable to select database");

$query = returnQuery($mac);
if (mysql_num_rows($query) < 1) die ("Extension not found in database...\n");

$authpass = mysql_result($query,0,'secret');
$name = mysql_result($query,0,'name');

print "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>\n";
?>
<polycomConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="polycomConfig.xsd">
  <call call.callsPerLineKey="24">
  </call>
  <reg reg.1.address="<? print $name; ?>" reg.1.auth.password="<? print $authpass; ?>" reg.1.auth.userId="<? print $name; ?>" reg.1.label="<? print $name; ?>" reg.1.outboundProxy.address="" reg.2.address="" reg.2.auth.password="" reg.2.auth.userId="" reg.2.label="" reg.2.outboundProxy.address="">
  </reg>
  <msg>
    <msg.mwi msg.mwi.1.callBackMode="registration" msg.mwi.2.callBackMode="registration">
    </msg.mwi>
  </msg>
  <voIpProt>
    <voIpProt.server voIpProt.server.1.address="192.168.1.55" voIpProt.server.1.port="5060" voIpProt.server.2.address="" voIpProt.server.2.port="0">
    </voIpProt.server>
    <voIpProt.SIP voIpProt.SIP.enable="1">
      <voIpProt.SIP.outboundProxy voIpProt.SIP.outboundProxy.address="">
      </voIpProt.SIP.outboundProxy>
      <voIpProt.SIP.alertInfo voIpProt.SIP.alertInfo.1.value="Ring Answer" voIpProt.SIP.alertInfo.1.>
      </voIpProt.SIP.alertInfo>
    </voIpProt.SIP>
  </voIpProt>
  <dialplan>
    <digitmap dialplan.digitmap="911|5000|[2-9]xxxxxxxxx|1[2-9]xxxxxxxxx|*xx.T" dialplan.digitmap.timeOut="3|3|3|3|3" />
  </dialplan>
  <up up.headsetMode="1" up.oneTouchVoicemail="1" />
  <feature feature.enhancedFeatureKeys.enabled="1" />
  <softkey softkey.feature.forward="0" softkey.1.enable="1" softkey.1.label="Cell Fwd" softkey.1.use.idle="1" softkey.1.insert="3" softkey.1.action="**78383" />
  <microbrowser mb.proxy="">
    <idleDisplay mb.idleDIsplay.home="http://192.168.1.55/polycoms/stats.php" mb.idleDisplay.refresh="7" />
    <main mb.main.home="" />
    <limits mb.limits.nodes="" mb.limits.cache="" />
  </microbrowser>
</polycomConfig>

  • dbinfo.php contains your mysql login, database info, etc
  • Change the IP of your SIP server obviously.
  • Modify your digit map as necessary.
  • The softkey referenced here was to a custom action that I wrote to enable queue joining and auto forwarding to cell phones
  • The microbrowser page was a simple PHP which gave them live call statistics. Feel free to take both of these out.
  • If you are provisioning an older Polycom SIP version, you'll need to incorporate a whole bunch more stuff due to the massive config files of 3.x. Good luck with that. I think it's just easier to upgrade to 4.x and throw your old 501's out the window.

Wrapping up

Go upgrade some handsets and kick some major ass.
Created by: doctorray, Last modification: Tue 08 of Jan, 2013 (23:41 UTC)
Please update this page with new information, just login and click on the "Edit" or "Discussion" tab. Get a free login here: Register Thanks! - Find us on Google+