sipura mass deployment

Sipura Mass Deployment


If you need only backup/restore config for linksys/sipura devices - see spaconf utility.

Introduction


Reading various mailing lists and forums about Sipura phones, it is apparently difficult as an end user to get adequate information from Sipura or Sipura resellers regarding mass phone provisioning of the SPA-841 phone. I have no direct experience with this, as I've never contacted those sources for help on the issue. The following guide is a compilation of information I've found online which has helped me with the process of preparing for mass deployment of SPA-841 phones.

NOTE: The Linksys SPA-941, while externally a very different phone, is almost exactly the same as the SPA-841 in the way that it is configured and provisioned (down to the "Sipura" logo on the configuration web page in the firmware currently shipping). Older firmwares from the SPA-841 do not seem to be accepted by the 941. The only thing I've had to change to keep our SPA-941's running with the same provisioning as our SPA-841's is to add an spa941.cfg file in the tftp directory, and turn off firmware upgrades until we have a firmware to upgrade to.



Basic flow


As described in the SPA-841 Administrator's Guide, available on Sipura's website, provisioning happens in two steps. The first "pre-provisioning" step uses the phone's default settings to retrieve a default configuration from a TFTP server. This step should only be required once per phone, unless the phone is reset to its factory defaults. The primary purpose of pre-provisioning is to tell the phone where to find its per-phone specific configuration.

The provisioning step provides phone-specific configuration settings to the phone, when the phone retrieves its configuration from the source specified during pre-provisioning. The phone can be configured to automatically resync with the provisioning server periodically (every hour, by default), to prevent end users from breaking the phone too badly. The phone generally automatically resyncs on restart and reboot, as well.

SPA-841 Configuration File Formats


The SPA-841 accepts configuration files in one of two formats: a proprietary binary format which is produced by the Sipura configuration tool, and a plaintext XML configuration format. My experience is only with the XML configuration format, so that is all I will describe here.

A Sample XML Configuration for the SPA-841 is available on Sipura's website, in the SPA-841 FAQ. This file contains all configuration parameters availavle for the SPA-841, with occasional comments describing allowed values of the parameters. More complete information on the meaning and format of the configuration parameters is available in the SPA-841 Administrator's Guide.

NOTE: Recent versions of the SPA-2000 and SPA-3000 firmware ( > 2.0.11), and the Linksys PAP2, also support the plaintext XML configuration format.
The configuration tags used in the XMP file are identical to the parameters described in the Administrators Guide, except that the bracketed parameters are modified to use underscores.
IE: Line_Enable[2] becomes Line_Enable_2_

See here for a blank PAP2T XML configuration file.


Pre-Provisioning using DHCP and TFTP


The pre-provisioning step sets up a Profile_Rule for your phone, which allows the "real" configuration file to be loaded by the phone in the future. Use DHCP to set the phone's TFTP server at phone boot time, to a locally available TFTP server. The phone will download file "spa841.cfg" from the TFTP server, and use that for its initial configuration.

A sample dhcpd.conf entry for isc-dhcpd:


option tftp-server-name "10.1.123.1"


A sample spa841.cfg file which sets only Profile_Rule:


<flat-profile> <!-- Sipura SPA-841 Configuration Parameters -->
<Profile_Rule ua="na">
http://10.1.123.1/spa841-$MA.cfg
</Profile_Rule>
</flat-profile>


In this example, after the pre-provisioning step, the spa-841 will load its phone-specific configuration from http://10.1.123.1/spa841-$MA.cfg, where "$MA" is the phone's mac address (without colons). In our specific setup, we have installed a cgi-bin script which we use for phone configuration by MAC address. The script finds the phone in our phone database, and builds the correct configuration parameters based on that. Our Profile_Rule looks something like this:


http://10.1.123.1/spaconfig.cgi?mac=$MA


(See here for a blank PAP2T XML configuration file.)

Provisioning per-phone configuration


Now that you have your phone configured to retrieve its per-phone config file from a new location, the rest of the process is pretty straightforward: put your configuration file into place, and reboot your phone. However, we did run into a few stumbling blocks worth mentioning.

In our cgi-bin configuration builder, we needed to return a proper Content-Type header and XML specification, in order for the spa-841 to correctly use the configuration file. I'm not sure which of these are necessary when using a static configuration file instead of cgi-bin, but the TFTP server does not need to specify the XML specification in any case.


Content-Type: text/xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<flat-profile> <!-- Sipura SPA-841 Configuration Parameters -->
...
</flat-profile>


Debugging the provisioning process can be a bit hairy, at least until you get syslog logging and debugging up and running correctly. During the debugging stages, I used a simple trick to determine whether the SPA-841 was loading the per-phone configuration file correctly or not. Using the web interface, I set <Resync_Periodic> to 10 seconds, and the <Resync_Error_Retry_Delay> to 5 seconds. I then did a "tail -f" on my web server log, and checked the time stamps. If I saw a resync every 10 seconds, I knew the cgi-bin was sending out a configuration it liked. If I saw a resync every 5 seconds, I knew I broke something.


Other possibilities


This document describes one solution to Sipura mass phone deployment, but it is likely not the only way to do it. Maybe someone else can fill in details on these other possibilities?

As seen in snom mass deployment, some phones support the DHCP "boot_file_name" option, and this name can be configured with a mac address at DHCP configuration time. Does the SPA-841 support this option, and if so, could all phone configuration be done with DHCP configuration followed by a single http: based provisioning step, instead of a two-step bootstrap process? iT COULD BE DONE ALL WITH THE DHCP. DHCP SERVER TIVE THE PHONE TFTP SERVER FOR INITIAL CONFIG THEM THE PHONE DL IT AND POINT TO YOUR HTTP OR HTTPS CONFIGFILES.

Does anyone have any information on the binary compiled configuration format? Are tools available for compiling configurations in a non-Windows environment? The binary format is more friendly to service providers who don't want a human-readable format, but XML is a better choice for easy debugging.

Yes! Linksys provide the "SPC.exe" util which will generate configfiles (SAMPLE) and then encode your configfiles see http://spc.pifiu.com for the detail and download

See Also:


Sipura Mass Deployment


If you need only backup/restore config for linksys/sipura devices - see spaconf utility.

Introduction


Reading various mailing lists and forums about Sipura phones, it is apparently difficult as an end user to get adequate information from Sipura or Sipura resellers regarding mass phone provisioning of the SPA-841 phone. I have no direct experience with this, as I've never contacted those sources for help on the issue. The following guide is a compilation of information I've found online which has helped me with the process of preparing for mass deployment of SPA-841 phones.

NOTE: The Linksys SPA-941, while externally a very different phone, is almost exactly the same as the SPA-841 in the way that it is configured and provisioned (down to the "Sipura" logo on the configuration web page in the firmware currently shipping). Older firmwares from the SPA-841 do not seem to be accepted by the 941. The only thing I've had to change to keep our SPA-941's running with the same provisioning as our SPA-841's is to add an spa941.cfg file in the tftp directory, and turn off firmware upgrades until we have a firmware to upgrade to.



Basic flow


As described in the SPA-841 Administrator's Guide, available on Sipura's website, provisioning happens in two steps. The first "pre-provisioning" step uses the phone's default settings to retrieve a default configuration from a TFTP server. This step should only be required once per phone, unless the phone is reset to its factory defaults. The primary purpose of pre-provisioning is to tell the phone where to find its per-phone specific configuration.

The provisioning step provides phone-specific configuration settings to the phone, when the phone retrieves its configuration from the source specified during pre-provisioning. The phone can be configured to automatically resync with the provisioning server periodically (every hour, by default), to prevent end users from breaking the phone too badly. The phone generally automatically resyncs on restart and reboot, as well.

SPA-841 Configuration File Formats


The SPA-841 accepts configuration files in one of two formats: a proprietary binary format which is produced by the Sipura configuration tool, and a plaintext XML configuration format. My experience is only with the XML configuration format, so that is all I will describe here.

A Sample XML Configuration for the SPA-841 is available on Sipura's website, in the SPA-841 FAQ. This file contains all configuration parameters availavle for the SPA-841, with occasional comments describing allowed values of the parameters. More complete information on the meaning and format of the configuration parameters is available in the SPA-841 Administrator's Guide.

NOTE: Recent versions of the SPA-2000 and SPA-3000 firmware ( > 2.0.11), and the Linksys PAP2, also support the plaintext XML configuration format.
The configuration tags used in the XMP file are identical to the parameters described in the Administrators Guide, except that the bracketed parameters are modified to use underscores.
IE: Line_Enable[2] becomes Line_Enable_2_

See here for a blank PAP2T XML configuration file.


Pre-Provisioning using DHCP and TFTP


The pre-provisioning step sets up a Profile_Rule for your phone, which allows the "real" configuration file to be loaded by the phone in the future. Use DHCP to set the phone's TFTP server at phone boot time, to a locally available TFTP server. The phone will download file "spa841.cfg" from the TFTP server, and use that for its initial configuration.

A sample dhcpd.conf entry for isc-dhcpd:


option tftp-server-name "10.1.123.1"


A sample spa841.cfg file which sets only Profile_Rule:


<flat-profile> <!-- Sipura SPA-841 Configuration Parameters -->
<Profile_Rule ua="na">
http://10.1.123.1/spa841-$MA.cfg
</Profile_Rule>
</flat-profile>


In this example, after the pre-provisioning step, the spa-841 will load its phone-specific configuration from http://10.1.123.1/spa841-$MA.cfg, where "$MA" is the phone's mac address (without colons). In our specific setup, we have installed a cgi-bin script which we use for phone configuration by MAC address. The script finds the phone in our phone database, and builds the correct configuration parameters based on that. Our Profile_Rule looks something like this:


http://10.1.123.1/spaconfig.cgi?mac=$MA


(See here for a blank PAP2T XML configuration file.)

Provisioning per-phone configuration


Now that you have your phone configured to retrieve its per-phone config file from a new location, the rest of the process is pretty straightforward: put your configuration file into place, and reboot your phone. However, we did run into a few stumbling blocks worth mentioning.

In our cgi-bin configuration builder, we needed to return a proper Content-Type header and XML specification, in order for the spa-841 to correctly use the configuration file. I'm not sure which of these are necessary when using a static configuration file instead of cgi-bin, but the TFTP server does not need to specify the XML specification in any case.


Content-Type: text/xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<flat-profile> <!-- Sipura SPA-841 Configuration Parameters -->
...
</flat-profile>


Debugging the provisioning process can be a bit hairy, at least until you get syslog logging and debugging up and running correctly. During the debugging stages, I used a simple trick to determine whether the SPA-841 was loading the per-phone configuration file correctly or not. Using the web interface, I set <Resync_Periodic> to 10 seconds, and the <Resync_Error_Retry_Delay> to 5 seconds. I then did a "tail -f" on my web server log, and checked the time stamps. If I saw a resync every 10 seconds, I knew the cgi-bin was sending out a configuration it liked. If I saw a resync every 5 seconds, I knew I broke something.


Other possibilities


This document describes one solution to Sipura mass phone deployment, but it is likely not the only way to do it. Maybe someone else can fill in details on these other possibilities?

As seen in snom mass deployment, some phones support the DHCP "boot_file_name" option, and this name can be configured with a mac address at DHCP configuration time. Does the SPA-841 support this option, and if so, could all phone configuration be done with DHCP configuration followed by a single http: based provisioning step, instead of a two-step bootstrap process? iT COULD BE DONE ALL WITH THE DHCP. DHCP SERVER TIVE THE PHONE TFTP SERVER FOR INITIAL CONFIG THEM THE PHONE DL IT AND POINT TO YOUR HTTP OR HTTPS CONFIGFILES.

Does anyone have any information on the binary compiled configuration format? Are tools available for compiling configurations in a non-Windows environment? The binary format is more friendly to service providers who don't want a human-readable format, but XML is a better choice for easy debugging.

Yes! Linksys provide the "SPC.exe" util which will generate configfiles (SAMPLE) and then encode your configfiles see http://spc.pifiu.com for the detail and download

See Also:


Created by: ferrency, Last modification: Sun 30 of Nov, 2008 (21:50 UTC) by mbsat
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+