Home

Cisco SPA2102-R3 Specifications

1. Linksys SPA Provisioning Guide pa Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter4 Provisioning Field Reference Macro Expansion Variables Table 4 4 Macro Expansion Variables continued Macro Name Macro Expansion PSN Product Series Number for example 2102 SN Serial Number string for example 88012BA01234 SSL Client Certificate status Installed or Not Installed IP address of the SPA within its local subnet for example 192 168 1 100 External IP of the SPA as seen on the Internet for example 66 43 16 52 Software version string for example 2 0 6 b Hardware version string for example 1 88 1 Provisioning State a numeric string e explicit resync request 0 power up resync periodic resync e 2 resync failed retry attempt Upgrade State a numeric string first upgrade attempt 2 upgrade failed retry attempt UPGERR Result message ERR of previous upgrade attempt for example http_get failed PRVTMR Seconds since last resync attempt UPGTMR Seconds since last upgrade attempt REGTMRI Seconds since Line 1 lost registration with SIP server REGTMR2 Seconds since Line 2 lost registration with SIP server UPGCOND Legacy macro name always expands to true in firmware rev 2 0 6 and above SCHEME File access scheme one of TFTP HTTP or HTTPS as obtained after parsing resync or upgrade URL D
2. lt flat profile gt lt End user manages these parameters values are not changed by this profile gt m Linksys SPA Provisioning Guide 2 4 Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter2 Creating Provisioning Scripts Open Format Configuration File lt Speed_Dial_2 2 ua rw gt lt Speed_Dial_3 2 ua rw gt lt Speed_Dial_4 2 ua rw gt lt Speed_Dial_5 2 ua rw gt lt Speed_Dial_6 2 ua rw gt lt Speed_Dial_7_ 2 ua rw gt lt Speed_Dial_8 2 ua rw gt lt Speed_Dial_9 2 ua rw gt lt flat profile gt Configuration File Compression Optionally the XML configuration profile can be compressed to reduce the network load on the provisioning server The supported compression method is the gzip deflate algorithm RFC1951 The gzip utility and a compression library that implements the same algorithm zlib are readily available from Internet sites To identify when compression is applied the SPA expects the compressed file to contain a gzip compatible header as generated by invoking the gzip utility on the original XML file For example if profile xml is a valid profile the file profile xml gz is also accepted This example be generated with either of the following commands Example 2 7 Compressing the Configuration Profile first invocation replaces original file with compressed file gzip profile xml second invocation leaves original file in place produces new c
3. A Linksys VoIP device is generically referred to in this document as a SPA Unless otherwise noted the instructions in this document apply equally to the SPA9000 Linksys Analog Telephone Adapters ATAs and SPA900 Series IP phones Residential Deployment Provisioning Requirements Linksys ATAs such as the PAP2T are primarily intended for high volume deployments by VoIP service providers to residential and small business customers In this scenario units are likely to be widely distributed across the Internet connected through routers and firewalls at the customer premises Further ATAs can also serve as terminal nodes in business or enterprise environments where the units may be operated within a self contained LAN environment The ATA can be seen as a remote extension of the service provider back end equipment In essence it replaces the traditional physical analog telephone line connection from a customer premise to a central office with a virtual connection which relies on broadband Internet service to extend the central office phone line termination into the customer premises The ATA can assume responsibility for many of the functions that were traditionally handled at the central office At a minimum the ATA serves as a media conversion endpoint offering the consumer a telephone port analogous to a traditional phone line terminal Remote management and configuration is required to efficiently ensure proper operation of the
4. In addition the key can be specified either explicitly as a hexadecimal digit sequence hex Key or by hashing a secret phrase ascii key With the hex key option the key can be up to 256 bits in length With the ascii key option the generated key is 128 bits The following examples illustrate explicit key based encryption spc rc4 ascii key apple4sale spa2102 txt spa2102 cfg spc aes ascii key lucky777 spa2102 txt spa2102 cfg spc aes ascii key my secret phrase spa2102 txt spa2102 cfg spc aes hex key 8d23fe7 a5c29 spa2102 txt spa2102 cfg Any combination of scrambling targeting and explicit key encrypting can be applied to a CFG file as shown by the following example spc target 000e08aaa010 aes ascii key VerySecret a txt a cfg After each compilation SPC prints a final status message Syntax error messages are also printed if a compilation is not successful The status and error messages printed by SPC are suppressed with the quiet command line option Messages can be redirected to a file with the log file_name option In the latter case the SPC command itself is also printed in the log file preceded by a timestamp spc quiet spc log prov log SPC can also be used to generate sample configuration source files for both plain text and XML formats corresponding to the accompanying firmware release The commands for producing sample files are as follows sample plain txt to
5. Parameter Name Aliases Step 1 When generating an XML profile for the SPA it may be convenient to assign names to certain configuration parameters that are different from the canonical names recognized by the SPA For example a customer account database may generate XML element tags for a customer telephone number and SIP registration password with names such as SIP number and SIP password These names can be mapped to the SPA canonical names User_ID_1_ and Password_1_ before being applied to SPA Line 1 In many instances the back end provisioning solution used by the service provider can perform this mapping However the SPA itself can remap the parameter names internally To do this an alias map is defined and stored in one of the general purpose provisioning parameters Then the profile rule which invokes the resync is directed to remap the non canonical XML elements as specified by the alias map Exercise Generate a profile named customer XML containing the proprietary customer account XML form indicated in the following example lt customer account gt Linksys SPA Provisioning Guide 3 12 Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter3 Provisioning Tutorial Profile Formats lt SIP number gt 17775551234 lt SIP number gt lt SIP password gt 512835907884 lt SIP password gt lt customer account gt Step2 Store the file in the TFTP server virtual root directory Step 3 Open th
6. Profile_Rule This parameter is a profile script that evaluates to the provisioning resync command The command is a TCP IP operation and an associated URL The TCP IP operation can be TFTP HTTP or HTTPS If the command is not specified TFTP is assumed and the address of the TFTP server is obtained through DHCP option 66 In the URL either the IP address or the FQDN of the server can be specified The file name can have macros such as MA which expands to the device MAC address The default is spa PSN cfg Linksys SPA Provisioning Guide pa Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter4 Provisioning Field Reference Configuration Profile Parameters Table 4 1 Configuration Profile Parameters continued Parameter Name Description and Default Value Profile_Rule_B Defines second third and fourth resync Profile Rule C commands and associated profile URLs These p 7 profile scripts are executed sequentially after the Profile_Rule_D primary Profile Rule resync operation has completed If a resync is triggered and Profile Rule is blank Profile Rule B C and D are still evaluated and executed The default is empty Log_Resync_Request_Msg This parameter contains the message that is sent to the Syslog server at the start of a resync attempt The default is PN MAC Requesting resync SCHEME SERVIP PORT PATH Log_Resync_Success_Msg Syslog message issued upon successful
7. options Parallel Sequential Syslog_Server MN Debug_Server M g Debug_Level 0 options 0 1 2 3 Primary_NTP_Server a Secondary_NTP_Server iia Configuration Profile Provision_Enable Yes Resync_On_Reset Yes Resync_Random_Delay a s Resync_Periodic 3600 Resync_Error_Retry_Delay 3600 Forced_Resync_Delay 14400 Linksys SPA Provisioning Guide Version 3 01 C 1 LINKSYS A Division of Cisco Systems Inc Appendix C Example SPA Configuration Profile E Resync_From_SIP Yes Resync_After_ Upgrade_Attempt yea 4 Resync_Trigger_1 ee Resync_Trigger_2 ey te Profile Rule spa PSN cfg Profile Rule B ney Profile Rule C ae Profile Rule D AR Log_Resync_Request_Msg SPN SMAC Requesting resync SSCHEME SSERVIP SPORTSPATH Log _Resync_Success_ Msg SPN SMAC Successful resync SSCHEME SSERVIP SPORTSPATH Log _Resync_Failure_Msg SPN SMAC Resync failed SERR Firmware Upgrade Upgrade_Enable Yes Upgrade_Error_Retry_Delay 3600 Downgrade_Rev_Limit n Upgrade_Rule re Log_Upgrade_Request_Msg SPN SMAC Requesting upgrade SSCHEME SSERVIP SPORTSPATH Log _Upgrade_Success_ Msg SPN SMAC Successful upgrade SSCHEME SSERVIP SPORTSPATH SERR Log _Upgrade_Failure_Msg SPN SMAC Upgrade failed SERR General Purpose Parameters GPP_A it 3 GPP_B ar GPP_C ct GPP_D R g GPP_E oe 4 GPP_F a g GPP_G LE GPP_H ae GPP_I ony GPP_J rm 3 GPP
8. A Division of Cisco Systems Inc l Preface How This Documentis Organized e WAG310G Wireless G ADSL2 gateway with VoIP and PSTN connectivity RTP300 IP router with two FXS ports e WRP400 Wireless G ADSL gateway with two FXS ports e WRTP54G Wireless G IP router with two FXS ports e WRT54GP2 Wireless G IP router with two FXS ports e WAG54GP2 Wireless G ADSL gateway with two FXS ports SPA900 Series IP phones SPA901 One line small affordable no display SPA921 One line business phone SPA922 One line business phone with Power over Ethernet PoE support and an extra Ethernet port for connecting another device to the LAN SPA941 Default is two lines upgradeable to four lines SPA942 Default is two lines upgradeable to four lines Power over Ethernet PoE support and an extra Ethernet port for connecting another device to the LAN SPA962 Six lines hi res color display Power over Ethernet PoE support and an extra Ethernet port for connecting another device to the LAN S Note A Linksys VoIP device that supports the remote provisioning options described in this document is referred to generically as a SPA How This Document is Organized This document is divided into the following chapters and appendices Chapter Contents Chapter 1 Provisioning This chapter introduces Linksys VoIP products Linksys VoIP Devices Chapter 2 Creating This chapter descri
9. Cfwd_Sel3_Dest 2 Cfwd_Sel4 Caller 2 Cfwd_Sel4 Dest 2 Cfwd_Sel5 Caller 2 Cfwd_Sel5_ Dest 2 Cfwd_Sel6 Caller 2 Cfwd_Sel6_Dest 2 Cfwd_Sel7 Caller 2 Cfwd_Sel7_Dest 2 Cfwd_Sel8 Caller 2 Cfwd_Last_Caller 2 Cfwd_Last_Dest 2 Block_Last_Caller 2 Accept_Last_Caller 2 Speed Dial Settings Speed_Dial_2 2 Speed_Dial_3 2 Speed_Dial_4 2 Speed_Dial_5 2 Speed_Dial_6 2 Speed_Dial_7 2 Speed_Dial_8 2 Speed_Dial_9 2 uw 7Ciwd_Sels Dest 2 De are wou wou 1 wou n Supplementary Service Settings CW_Setting 2 Block_CID_ Setting 2 Block_ANC_Setting 2 DND_Setting 2 CID_Setting 2 CWCID_ Setting 2 Dist_Ring_ Setting 2 Secure_Call_Setting 2 Distinctive Ring Settings Ringl Caller 2 Ring2_Caller 2 Ring3_Caller 2 Ring4_Caller 2 Ring5_Caller 2 Ring6_Caller 2 Yeo 3 No No No Yes 4 Yeo 3 Yes 3 No 3 Linksys SPA Provisioning Guide Version 3 01 C9 LINKSYS A Division of Cisco Systems Inc Appendix C Example SPA Configuration Profile E Ring7_Caller 2 onw Ring8_Caller 2 onn Ring Settings Default_Ring 2 1 gt options 1 2 3 4 5 6 7 8 Default_CWT 2 1 options 1 2 3 4 5 6 7 8 Hold_Reminder_Ring 2 8 options 1 2 3 4 5 6 7 8 none Call_Back_Ring 2 7 options 1 2 3 4 5 6 7 8 Cfwd_Ring_Splash_Len 2 1 o 3 Cblk_Ring_Splash_Len 2 1 wE 4 VMWI_Ring_Spl
10. Example 2 Stutter tone 350 19 440 19 2 1 1 1 4 2 10 0 1 2 Number of Frequencies 2 Frequency 1 350 Hz at 19 dBm Frequency 2 440 Hz at 19 dBm Number of Cadence Sections 2 Cadence Section 1 Section Length 2s Number of Segments 1 Segment 1 On 0 1s Off 0 1s with Frequencies 1 and 2 Linksys SPA Provisioning Guide pa Version 3 01 2 2 LINKSYS A Division of Cisco Systems Inc Data Types Chapter2 Creating Provisioning Scripts Cadence Section 2 Section Length 10s Number of Segments 1 Segment 1 On forever with Frequencies 1 and 2 Total Tone Length 12s Example 3 SIT tone 985 16 1428 16 1777 16 20 380 0 1 380 0 2 380 0 3 0 47 0 Number of Frequencies 3 Frequency 1 985 Hz at 16 dBm Frequency 2 1428 Hz at 16 dBm Frequency 3 1777 Hz at 16 dBm Number of Cadence Sections 1 Cadence Section 1 Section Length 20s Number of Segments 4 Segment 1 On 0 38s Off 0s with Frequency 1 Segment 2 On 0 38s Off 0s with Frequency 2 Segment 3 On 0 38s Off 0s with Frequency 3 4 Segment On 0s Off 4s with no frequency components Total Tone Length 20s ProvisioningRuleSyntax Scripting syntax used to define configuration resync and firmware upgrade rules DialPlanScript Scripting syntax used to specify Line 1 and Line 2 dial plans Notes lt Par Name gt represents a configuration parameter name In a profile the corresponding
11. No n n Supplementary Service Subscription 1 1 1 1 options options options options 1 2 3 4 5 6 7 8 1 2 3 4 5 6 7 8 1 2 3 4 5 6 7 8 none 1 2 3 4 5 6 7 8 options New VM Available New VM options none 1 line 1 line excl OPT 1 line excl NTFY 1 line excl REG 1 line excl OPT NTFY REG full full excl OPT full excl NTFY full excl REG full excl OPT NTFY REG options low medium high very high Linksys SPA Provisioning Guide Version 3 01 C7 LINKSYS A Division of Cisco Systems Inc Appendix C Example SPA Configuration Profile E Call_Waiting_Serv 2 Yes Block CID Serv 2 Yes Block_ANC_Serv 2 Yes Dist_Ring_Serv 2 Yes Cfwd_All_Serv 2 Yes Cfwd_Busy_Serv 2 Yes Cfwd_No_Ans_Serv 2 eS Cfwd_Sel_Serv 2 Yes Cfwd_Last_Serv 2 ees j Block_Last_Serv 2 ee j Accept_Last_Serv 2 Yes DND_Serv 2 Yes 7 CID_Serv 2 Yes CWCID_Serv 2 Xes Call_Return_Serv 2 Yes Call_Back_Serv 2 es 7 Three_Way_Call_Serv 2 Yes Three_Way_Conf_Serv 2 Yes Attn_Transfer_Serv 2 Yes Unattn_Transfer Serv 2 Yes MWI_Serv 2 Les 3 VMWI_Serv 2 Les 3 Speed_Dial_Serv 2 Yes Secure_Call_Serv 2 Yes Referral Serv 2 Yes Feature_Dial_Serv 2 Yes Audio Configuration Preferred_Codec 2 G711u 4 options G711u G711a G726 16 G726 24 G726 32 G726 40 G729a G723 Silence_Supp_Enable 2 No
12. where F F are frequency in Hz unsigned integers only and L L are corresponding levels in dBm with up to 1 decimal places White spaces before and after the comma are allowed but not recommended Example 1 Call Waiting Tone 440 10 Number of Frequencies 1 Frequency 2 440 Hz at 10 dBm Example 2 Dial Tone 350 19 440 19 Number of Frequencies 2 Frequency 1 350 Hz at 19 dBm Frequency 2 440 Hz at 19 dBm ToneScript A mini script that specifies the frequency level and cadence parameters of a call progress tone May contain up to 127 characters Syntax FreqScript Z Z The section Z is similar to the S section in a CadScript except that each on off segment is followed by a frequency components parameter Z D on off f on off 2 fi 2 Lon 3 0ff 3 fi 3 Lon off 4 f 4 on 5 off lt f s Lon 6 off 6 fis where fi j n n n n n5 n and 1 lt n lt 6 indicates which of the frequency components given in the FreqScript are used in that segment if more than one frequency component is used in a segment the components are summed together Example 1 Dial tone 350 19 440 19 10 0 1 2 Number of Frequencies 2 Frequency 1 350 Hz at 19 dBm Frequency 2 440 Hz at 19 dBm Number of Cadence Sections 1 Cadence Section 1 Section Length 10 s Number of Segments 1 Segment 1 On forever with Frequencies 1 and 2 Total Tone Length 10s
13. For example http p tel com firmware spa021025 bin In this example the Upgrade_Rule upgrades the firmware to the image stored at the indicated URL The following is another example SF ne beta customer http p tel com firmware spa021025 bin http p tel com firmware spa test 0527s bin This example directs the unit to load one of two images based on the contents of a general purpose parameter GPP_F The SPA can enforce a downgrade limit with respect to firmware revision number This can be useful as a customization option If a valid firmware revision number is configured in the parameter Downgrade_Rev_Limit the SPA rejects upgrade attempts for firmware versions earlier than the specified limit Data Types The data types used with configuration profile parameters are as follows Linksys SPA Provisioning Guide pa Version 3 01 2 19 LINKSYS A Division of Cisco Systems Inc Data Types Chapter 2 Creating Provisioning Scripts Uns lt n gt Unsigned n bit value where n 8 16 or 32 It can be specified in decimal or hex format such as 12 or 0x18 as long as the value can fit into n bits Sig lt n gt Signed n bit value It can be specified in decimal or hex format Negative values must be preceded by a sign A sign before positive value is optional Str lt n gt A generic string with up to n non reserved characters Float lt n gt A floating point value with up to n decimal p
14. LINKSYS A Division of Cisco Systems Inc Chapter2 Creating Provisioning Scripts Using Provisioning Parameters General Purpose Parameters The general purpose parameters GPP_ are used as free string registers when configuring the SPA to interact with a particular provisioning server solution The GPP_ parameters are empty by default They can be configured to contain diverse values including the following Encryption keys e URLs Multistage provisioning status information Post request templates Parameter name alias maps Partial string values eventually combined into complete parameter values The GPP_ parameters are available for macro expansion within other provisioning parameters For this purpose single letter upper case macro names A through P are sufficient to identify the contents of GPP_A through GPP_P Also the two letter upper case macro names SA through SD identify GPP_SA through GPP_SD as a special case when used as arguments of the key URL option For example if GPP_A contains the string ABC and GPP_B contains 123 the expression A B macro expands into ABC123 Enables All profile resync and firmware upgrade operations are controlled by the Provision_Enable and Upgrade_Enable parameters These parameters control resyncs and upgrades independently of each other These parameters also control resync and upgrade URL commands issued through the SPA administration web server Both of these param
15. The example above defines one parameter value the first general purpose parameter GPP_A with a value of 12345678 Exercise Within a LAN environment connect a PC and an SPA to a hub switch or small router Connect an analog phone to the Phone 1 port of the SPA On the PC install and activate a TFTP server Using a text editor create the configuration profile and save it with the name basic txt in the virtual root directory of the installed TFTP server If possible verify that the TFTP server is properly configured by requesting the basic txt file using a TFTP client other than the SPA itself Preferably the TFTP client should be running on a separate host from the server Using the analog phone obtain the local IP address of the SPA IVR menu 110 If the SPA configuration has been modified since it was manufactured perform manufacturing reset on it using the IVR RESET option 73738 Open the PC web browser on the SPA admin advanced configuration page For example if the SPA IP address is 192 168 1 100 Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter3 Provisioning Tutorial Basic Resync http 192 168 1 100 admin advanced Step8 The Provisioning tab in the admin advanced page contains a number of configurable parameters specific to provisioning Select the Provisioning tab and inspect the values of the general purpose parameters GPP_A through GP
16. and NAME p q where p and q are non negative integers available in revision 2 0 11 and above The resulting macro expansion is the substring starting at character offset p with length q or else till end of string if q is not specified For example if GPP_A contains ABCDEF then A 2 expands to CDEF and A 2 3 expands to CDE An unrecognized name is not translated and the NAME or NAME form remains unchanged in the parameter value after expansion Table 4 4 summarizes the macro expansion variables Table 4 4 Macro Expansion Variables Macro Name Macro Expansion The form expands to a single character A through P Replaced by the contents of the general purpose parameters GPP_A through GPP_P SA through SD Replaced by the contents of the special purpose parameters GPP_SA through GPP_SD These parameters are meant to hold keys or passwords used in provisioning Note that SA through SD are only recognized as arguments to the optional resync URL qualifier key as in the following example key SA http ps callme com profiles abcdefg cfg These variables are not expanded outside of this limited context MAC address using lower case hex digits for example 000e08aabbcce MAC address using upper case hex digits for example QOOEO8AABBCC MAC address using lower case hex digits and colons to separate hex digit pairs for example 00 0e 08 aa bb cc Product Name for example SPA2102
17. Admin account provides full access to all IVR functions and to all administration web server parameterse The User and Admin accounts can be independently password protected The configuration parameters available to the User account are completely configurable in the SPA on a parameter by parameter basis Optionally user access to the SPA administration web server can be totally disabled The manufacturing reset control using the IVR can also be disabled via provisioning The Internet domains accessed by the SPA for resync upgrades and SIP registration for Line 1 can be restricted These and other features are described in detail in administration guides for each product SPA Configuration Profiles The SPA configuration profile defines the parameter values for a specific SPA device The configuration profile can be used in two formats Open XML style format Proprietary plain text format The XML style format lets you use standard tools to compile the parameters and values To protect confidential information contained in the configuration profile this type of file is generally delivered from the provisioning server to the SPA over a secure channel provided by HTTPS The plain text configuration file uses a proprietary format which can be encrypted to prevent unauthorized use of confidential information By convention the profile is named with the extension cfg for example spa2102 cfg The Linksys Profile Compiler SPC too
18. Client Certificates CERT PKEY Authenticates Server in HTTPS Connection Authenticates Client in HTTPS Connection PKEY CERT Signs Provisioning Server Certificates Provisioning Server CERT PKEY VolP Service Provider Provisioning Server Entity HTTPS Server Configuration Files Root CA Certificate List Stored on Service Provider s Provisioning Server Sipura Technology Inc Client Certificate Root Authority 1 As indicated in the lower half of the diagram a Linksys Client Certificate Root Authority signs each unique certificate The corresponding root certificate is made available to service providers for client authentication purposes Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter1 Provisioning Linksys VoIP Devices Provisioning Setup Provisioning Setup This section describes setup requirements for provisioning a SPA and includes the following topics License Keys page 1 11 Software Tools page 1 11 Server Configuration page 1 11 e TFTP page 1 12 HTTP page 1 12 Enabling HTTPS page 1 13 Syslog Server page 1 15 License Keys Certain products within the SPA product family provide for premium features Enabling these features requires a license key This key is unique per feature and device To enable a premium feature in any
19. Repeat the TFTP Resync operation described in the previous exercise The SPA generates two syslog messages during the resync The first indicates that a request is in progress The second marks success or failure of the resync Step4 Verify that your syslog server received messages such as the following SPA 2102 00 0e 08 ab cd ef Requesting resync tftp 192 168 1 200 basic txt SPA 2102 00 0e 08 ab cd ef Successful resync tftp 192 168 1 200 basic txt More detailed messages are available by programming the Debug_Server parameter instead of the Syslog Server parameter with the IP address of the syslog server and setting the Debug_Level to a value between 0 and 3 3 being the most verbose The contents of these messages can be configured using the following parameters e Log Resync_Request_Msg Log _Resync_Success_Msg l Linksys SPA Provisioning Guide pa Version 3 01 3 3 LINKSYS A Division of Cisco Systems Inc Chapter3 Provisioning Tutorial Basic Resync Log _Resync_Failure_Msg If any of these parameters are cleared the corresponding syslog message is not generated Occasionally it may also be informative to capture an Ethernet packet trace of the interaction between the SPA and the provisioning server You can run the Ethernet packet analyzer such as Ethereal Wireshark on a PC connected through a hub to the same subnet as the SPA Automatic Resync Step 1 Step 2 Step 3 Step 4 Step
20. This expression is evaluated and processed as follows 1 Conditions are evaluated from left to right until one is found that evaluates as true or until one alternative is found with no conditional expression 2 Any accompanying assignment expression is evaluated if present 3 Ifa URL is specified as part of that alternative an attempt is made to download the profile located at the specified URL and update the internal parameters accordingly Linksys SPA Provisioning Guide LINKSYS A Division of Cisco Systems Inc Chapter 2 Creating Provisioning Scripts Using Provisioning Parameters Report Rule If all alternatives have conditional expressions and none evaluates to true or if the whole profile rule is empty then the entire Profile_Rule parameter is skipped and the next profile rule parameter in the sequence is evaluated The following are some examples of valid programming for a single Profile_Rule parameter The following example resyncs unconditionally to the profile at the specified URL performing an http GET request to the remote provisioning server http remote server com Linksys SMA cfg In the following example the SPA resyncs to two different URLs depending on the registration state of Line 1 In case of lost registration the SPA performs an HTTP POST to a CGI script transmitting the contents of the macro expanded GPP_A which may provide additional information on the state of the SPA SR
21. Use_Pref_Codec_Only 2 No Echo_Canc_Enable 2 Yes G729a_Enable 2 Yes Echo_Canc_Adapt_Enable 2 Yes G723_Enable 2 Yes Echo_Supp_Enable 2 Yes 3 G726 16_Enable 2 Yes FAX CED Detect_Enable 2 Yes gt G726 24 Enable 2 Yes 4 FAX CNG Detect_Enable 2 Yes G726 32_ Enable 2 Yes FAX Passthru_Codec 2 G711lu options G711u G71la G726 40_Enable 2 Yes FAX Codec_Symmetric 2 Yes DTMF_Tx Method 2 Auto options InBand AVT INFO Auto FAX Passthru_Method 2 NSE options None NSE ReINVITE Hook _Flash_Tx Method 2 None options None AVT INFO FAX Process _ NSE 2 Yes Release_Unused_Codec 2 Yes Dial Plan Dial _Plan 2 xx 34569 11 0 00 12 9 seme Ian 2 9 xxx 0 xxxxxrxxx x j Enable_IP_Dialing 2 No FXS Port Polarity Configuration Idle_Polarity 2 Forward options Forward Reverse Linksys SPA Provisioning Guide C8 Version 3 01 Appendix C Example SPA Configuration Profile LINKSYS A Division of Cisco Systems Inc Caller Conn Polarity 2 Callee_Conn_Polarity 2 Call Forward Settings Cfwd_All Dest 2 Cfwd_Busy_ Dest 2 Cfwd_No_Ans_Dest 2 Cfwd_No_Ans_ Delay 2 Forward options Forward Reverse Forward options Forward Reverse 20 Selective Call Forward Settings Cfwd_ Sell Caller 2 Cfwd_Sell_ Dest 2 Cfwd_Sel2 Caller 2 Cfwd_Sel2_Dest 2 Cfwd_Sel3 Caller 2
22. Yes Audio Configuration Preferred_Codec 1 G711u options G711u G711a G726 16 G726 24 G726 32 G726 40 G729a G723 Silence_Supp_Enable 1 No Use_Pref_Codec_Only 1 No Echo_Canc_Enable 1 Yes G729a_Enable 1 Yes Echo_Canc_Adapt_Enable 1 Yes G723_Enable 1 Yes Echo_Supp_Enable 1 Yes 4 G726 16_Enable 1 Yes FAX CED Detect_Enable 1 Yes 3 G726 24 Enable 1 Yes FAX CNG Detect_Enable 1 Yes G726 32_Enable 1 Yes FAX_Passthru_Codec 1 G711u options G711u G711la G726 40_Enable 1 Yes FAX Codec_Symmetric 1 Yes 4 DTMF_Tx Method 1 Auto options InBand AVT INFO Auto FAX Passthru_Method 1 NSE options None NSE ReINVITE Hook _ Flash_Tx_ Method 1 None options None AVT INFO FAX Process _ NSE 1 Yes Release_Unused_Codec 1 Yes Dial Plan Dial _Plan 1 xx 3469 11 0 00 2 9 xxxxxx look 2 9 xxxxxxS0 XXXXXXXXXXXX Enable_IP_Dialing 1 No FXS Port Polarity Configuration Idle_Polarity 1 Forward options Forward Reverse Caller _Conn_Polarity 1 Forward options Forward Reverse Callee_Conn_Polarity 1 Forward options Forward Reverse Call Forward Settings Linksys SPA Provisioning Guide Version 3 01 C5 LINKSYS A Division of Cisco Systems Inc Appendix C Example SPA Configuration Profile E Cfwd_All_Dest 1 ne Cfwd_Busy_Dest 1 pe 3 Cfwd_No_Ans_ Dest 1 Lo Cfwd
23. g Blind Transfer Code 9g gt Call_Back_Act_Code coo 3s Call Back _Deact_Code On Cfwd_All Act Code ETAN Cfwd_All_Deact_Code VETS Y F Cfwd_Busy_Act_Code PEON z Cfwd_Busy_Deact_Code me Ls Cfwd_No_Ans_Act_Code x902 os Cfwd_No_Ans_ Deact_Code was 3 Cfwd_Last_Act_Code x63 Cfwd_Last_Deact_Code EGG a Block_Last_Act_Code x60 Block_Last_Deact_Code x80 Accept_Last_Act_Code x64 Accept_Last_Deact_Code x84 CW_Act_Code EDON 3 CW_Deact_Code ARS CW_Per_Call_Act_Code wE 4 CW_Per_Call_Deact_Code 70 3 Block_CID Act Code eas ow ae Block _CID_ Deact_Code x68 Block_CID_ Per Call _Act_Code 1x81 Block_CID Per Call Deact_Code x82 Block_ANC_Act_Code ME ae Block_ANC_Deact_Code ERBE 3 Linksys SPA Provisioning Guide Version 3 01 C 11 LINKSYS A Division of Cisco Systems Inc Appendix C Example SPA Configuration Profile E DND_Act_Code Eo g DND_Deact_Code eae 3 CID_Act_Code 65 CID Deact_Code 85 3 CWCID_Act_Code R23 j CWCID_Deact_Code EASY 3 Dist Ring Act Code 2OY 2 Dist_Ring Deact_Code weEG g Speed_Dial_Act_Code 74 3 Secure_All_ Call _Act_Code ELON 3 Secure_No_Call_Act_Code eee 3 Secure_One_Call_Act_Code reo 3 Secure_One_Call_Deact_Code Pew 3 Referral Services Codes on Feature_Dial_Services_Codes u Outbound Call Codec Selection Codes Prefer _ G7 711u_Code x017110 Force_G711u_Code x027110 Prefer_G711a_Code x017111 Force_G711a_Code 02 7111 Prefe
24. in double quotes Other minor syntax and parameter naming differences also apply The following example specifies values for two Line 1 parameters Exercise Step1 Obtain the SPC utility from Linksys Executables are available for the Windows Win32 environment Linux ELF and OpenBSD Step2 Generate the text profile account txt containing the two line profile shown in the following example User _ID 1 17775551234 Password 1 512835907884 Step 3 Compile the text profile into a binary file account cfg using the following command spc account txt account cfg Step4 Store account cfg in the TFTP server virtual root directory Linksys SPA Provisioning Guide 5 Version 3 01 i LINKSYS A Division of Cisco Systems Inc Chapter3 Provisioning Tutorial Profile Formats Step5 Modify the test SPA profile rule to point to the new profile tf tp 192 168 1 200 account cfg Step6 Click Submit All Changes Upon resync the SPA retrieves the new file recognizes its binary format and updates the two specified parameters Step 7 Observe the syslog messages sent by the SPA during resync Linksys SPA Provisioning Guide 3 14 Version 3 01 LINKSYS A Division of Cisco Systems Inc Provisioning Field Reference This chapter provides a listing of the parameters provided on the administration web server Provisioning tab which can be used in configuration profile scripts It includes
25. lets you determine the value for each parameter used by the SPA and also to determine the user access to each parameter hidden read only or read write Any parameters not specified by a profile are left at the factory default values The SPA accepts a configuration profile in two formats Open XML style format Proprietary plain text format The XML style format lets you use standard tools to compile the parameters and values To protect confidential information contained in the configuration profile this file is generally delivered from the provisioning server to the SPA over a secure channel provided by HTTPS A complete example XML profile can be generated using the Linksys profile compiler tool see the SPA Configuration Profile Compiler section on page 2 6 using the following command spc sample xml sample txt The plain text configuration file uses a proprietary format which can be encrypted to prevent unauthorized use of confidential information By convention the profile is named with the extension cfg for example spa2102 cfg The Linksys Profile Compiler SPC tool is used to compile the plain text file containing parameter value pairs into an encrypted CFG file The SPC tool is available from Linksys for the Win32 environment spc exe and Linux 1386 elf environment spc linux i386 static Availability of the SPC tool for the OpenBSD environment is available on a case by case basis Linksys SPA Provisioning
26. obtaining the profile from the HTTP server Also the server should be logging each request if connection logging is enabled in the server configuration Step6 Inthe HTTP server logs observe how information identifying the test SPA appears in the log of user agents This should include the SPA manufacturer product name current firmware version and serial number Secure Resync This section demonstrates the preferred mechanisms available on the SPA for securing the provisioning process It includes the following topics Basic HTTPS Resync page 3 7 HTTPS With Client Certificate Authentication page 3 9 HTTPS Client Filtering and Dynamic Content page 3 9 Basic HTTPS Resync HTTPS adds SSL to HTTP for remote provisioning so that The SPA can authenticate the provisioning server The provisioning server can authenticate the SPA The confidentiality of information exchanged between the SPA and the provisioning server is ensured through encryption SSL generates and exchanges secret Symmetric keys for each connection between the SPA and the server using public private key pairs preinstalled in the SPA and the provisioning server On the client side using HTTPS with the GET method simply requires changing the definition of the URL in the Profile_Rule parameter from http to https On the server side the service provider must install and set up the HTTPS server In addition an SSL server certificate signed by L
27. profiles with XML style syntax To use the proprietary plain text format you need to convert the files using SPC before they can be used This procedure is described in the Proprietary Profile Format section on page 3 13 Linksys SPA Provisioning Guide Version 3 01 3 1 LINKSYS A Division of Cisco Systems Inc Basic Resync Chapter3 Provisioning Tutorial Basic Resync TFTP Resync Step 1 Step 2 Step 3 Step 4 Step 5 Step 6 Step 7 This section demonstrates the basic resync functionality of Linksys VoIP devices It includes the following topics TFTP Resync page 3 2 Syslog page 3 3 Automatic Resync page 3 4 Unique Profiles and Macro Expansion page 3 5 URL Resolution page 3 5 HTTP GET Resync page 3 6 The SPA supports multiple network protocols for retrieving configuration profiles The most basic profile transfer protocol is TFTP RFC1350 TFTP is widely used for the provisioning of network devices within private LAN networks Although not recommended for deployments of endpoints across the Internet it can be convenient for deployment within small organizations for in house preprovisioning and for development and testing The following configuration profile format uses the XML style syntax lt flat profile gt lt GPP A gt 12345678 lt GPP_A gt lt flat profile gt The lt flat profile gt element tag encloses all parameter elements to be recognized by the SPA
28. release 2 0 6 the SPA implements SSL which lets the SPA client to connect to servers using HTTPS HTTPS encrypts the communication between the client and the server protecting the message contents from other intervening network devices The encryption method for the body of the communication between client and server is based on symmetric key cryptography With symmetric key cryptography a single secret key is shared by the client and the server over a secure channel protected by Public Private key encryption Messages encrypted by the secret key can only be decrypted using the same key HTTPS supports a wide range of symmetric encryption algorithms The SPA implements up to 256 bit symmetric encryption using the American Encryption Standard AES in addition to 128 bit RC4 HTTPS also provides for the authentication of the server and the client engaged in a secure transaction This feature ensures that the provisioning server and an individual client cannot be spoofed by other devices on the network This is an essential capability in the context of remote endpoint provisioning Linksys SPA Provisioning Guide Version 3 01 Chapter 1 LINKSYS A Division of Cisco Systems Inc Provisioning Linksys VoIP Devices Using HTTPS Server and client authentication is performed using public private key encryption using certificates containing the public key Text encrypted with a public key can be decrypted only by its correspondin
29. submits provserver csr to Linksys for signing Upon receiving the provserver csr file Linksys generates provserver crt the signed server certificate In addition Linksys also provides a Linksys CA Client Root Certificate to the service provider This root certificate certifies the authenticity of the client certificate carried by each SPA The unique client certificate offered by each SPA during an HTTPS session carries identifying information embedded in its subject field This information can be made available by the HTTPS server to a CGI script invoked to handle secure requests In particular the certificate subject indicates the unit product name OU element MAC address S element and serial number L element The following is an example of these elements from a SPA2102 client certificate subject field OU SPA 2102 L 88012BA01234 S 000e08abcdef Early SPA units manufactured before firmware 2 0 x do not contain individual SSL client certificates When these units are upgraded to a firmware release in the 2 0 x tree they become capable of connecting to a secure server using HTTPS but are only able to supply a generic client certificate if requested to do so by the server This generic certificate contains the following information in the SPA identifying fields OU Linksys com L Linksysgeneric S Linksysgeneric f Linksys SPA Provisioning Guide Ja Version 3 01 1 13 LINKSYS A Division of Cisco Systems Inc Chapter1 Prov
30. the new file is downloaded by the SPA and used to update its parameters The file size of such a small profile is not reduced by gzip Compression is only useful with larger profiles For integration into customized back end provisioning server solutions the open source zlib compression library can be used in place of the standalone gzip utility to perform the profile compression However the SPA expects the file to contain a valid gzip header Profile Encryption A compressed or uncompressed profile can be encrypted This is useful when the confidentiality of the profile information is of particular concern such as when using TFTP or HTTP for communication between SPA clients and the provisioning server The SPA supports symmetric key encryption using the 256 bit AES algorithm This encryption can be performed using the open source OpenSSL package Exercise Step1 Install OpenSSL on a local PC This may require recompilation to enable the AES code Step2 Starting from the XML profile in basic txt generate an encrypted file with the following command openssl enc aes 256 cbc k MyOwnSecret in basic txt out basic cfg The compressed basic txt gz file could be used instead because the XML profile can be both compressed and encrypted Step3 Store the encrypted file basic cfg in the TFTP server virtual root directory Step4 Modify the Profile_Rule on the test SPA to resync to the encrypted file in place of the original XML file The enc
31. the server now performs symmetric authentication so that both server and client certificates are verified before the profile is transferred Using ssldump capture a resync connection between the SPA and the HTTPS server If client certificate verification is properly enabled on the server the ssldump trace shows the symmetric exchange of certificates first server to client then client to server before the encrypted packets containing the profile With client authentication enabled only a SPA with a MAC address matching a valid client certificate can request the profile from the provisioning server A request from an ordinary browser or other unauthorized device is rejected by the server HTTPS Client Filtering and Dynamic Content Version 3 01 Step 1 Step 2 If the HTTPS server is configured to require client certificates the information in each certificate identifies the resyncing SPA and supplies it with the correct configuration information The HTTPS server makes the certificate information available to CGI scripts or compiled CGI programs invoked as part of the resync request For the purpose of illustration this exercise uses the open source Perl scripting language and assumes that Apache v 2 is used as the HTTPS server Exercise Install Perl on the host running the HTTPS server Generate the following Perl reflector script usr bin perl wT use strict print Content Type text plain n n prin
32. to be generated for each provisioning server to which the SPA resyncs using HTTPS The server certificate must be signed by the Linksys Server CA Root Key whose certificate is carried by all deployed units To obtain a signed server certificate the service provider must forward a certificate signing request to Linksys which signs and returns the server certificate for installation on the provisioning server The provisioning server certificate must contain in the subject Common Name CN field the FQDN of the host running the server It may optionally contain additional information following the host FQDN separated by a character The following are examples of CN entries that would be accepted as valid by the SPA CN sprov callme com CN pv telco net mailto admin telco net CN prof voice com info voice com In addition to verifying the certificate chain of the provisioning server certificate the SPA tests the server IP address against a DNS lookup of the server name specified in the server certificate A certificate signing request can be generated using the OpenSSL utility The following shows an example of the openssl command that produces a 1024 bit RSA public private key pair and a certificate signing request openssl req new out provserver csr This command generates the server private key in privkey pem and a corresponding certificate signing request in provserver csr In this example the service provider keeps privkey pem secret and
33. ua attribute Example 2 4 Using Numbers and Spaces in an XML Profile lt flat profile gt lt This sets the SIP TOS DiffServ Value 1 parameter to be user not accessible gt lt SIP_TOS_DiffServ_Value_1_ ua na gt lt This sets the Dial Plan 1 parameter to be user read only gt lt Dial_ Plan_1_ ua ro gt lt This sets Dial Plan 2 parameter to be user read write gt lt Dial_Plan_2_ ua rw gt lt flat profile gt The SPA processes empty elements and elements with empty values differently If an element tag is specified within an empty element form than the current value of the corresponding parameter is left unchanged On the other hand if the element tag is used within an opening and a closing element with no value between them then the corresponding parameter is set to an empty string This is illustrated in Example 2 5 Example 2 5 Empty Elements vs Empty Strings lt flat profile gt lt GPP_A will be set to an empty string gt lt GPP_A gt lt GPP_A gt lt GPP_B will remain unchanged gt lt GPP_B gt lt flat profile gt Using the empty element form is useful when specifying a read write parameter ua rw This allows the end user to set and maintain specific values such as User 1 and User 2 settings while preventing the profile from overwriting the user supplied values during a resync operation Example 2 6 Empty Elements Preserve User Configured Values
34. xml out profile cfg analogous invocation for a compressed xml file openssl enc e aes 256 cbc k SecretPhrase1234 in profile xml gz out profile cfg A lower case k precedes the secret key which can be any plain text phrase and is used to generate a random 64 bit salt Then in combination with the secret specified with the k argument it derives a random 128 bit initial vector and the actual 256 bit encryption key When this form of encryption is used to encrypt a configuration profile the SPA needs to be informed of the secret key value to decrypt the file This value is specified as a qualifier in the pertinent profile URL The syntax is as follows using an explicit URL key SecretPhrase1234 http prov telco com path profile cfg This is programmed using one of the Profile_Rule parameters The key must be preprovisioned into the unit at an earlier time This bootstrap of the secret key can be accomplished securely using HTTPS Preencrypting configuration profiles offline with symmetric key encryption allows the use of HTTP for resyncing profiles The provisioning server only needs to use HTTPS to handle initial provisioning of SPAs after deployment This reduces the load on the HTTPS server in large scale deployments The final file name does not need to follow a specific format but it is conventional to end the name with the cfg extension to indicate that it is a configuration profile SPA Configuration Profile Co
35. 5 Step 6 Step 7 Step 8 Step 9 When a SPA is deployed remotely or as part of an internal company deployment it may need to resync periodically to the service provider provisioning server to ensure that any customer profile configuration changes made on the server are propagated to the endpoint without requiring an explicit resync request to the endpoint To cause the SPA to automatically and periodically resync to a server a configuration profile URL is defined using the Profile_Rule parameter and a resync period is defined using the Resync_Periodic parameter Exercise Using the PC web browser open the SPA admin advanced page Provisioning tab Define the Profile_Rule parameter The following value assumes a TFTP server IP address of 192 168 1 200 tftp 192 168 1 200 basic txt In the Resync_Periodic parameter enter a small value for testing such as 30 meaning 30 seconds Click Submit all Changes With the new parameter settings the SPA now resyncs to the configuration file specified by the URL twice a minute Observe the resulting messages in the SPA syslog trace Ensure that the Resync_On_Reset parameter is set to yes Power cycle the SPA The SPA also automatically resyncs to the provisioning server whenever it is power cycled If the resync operation fails for any reason such as if the server is not responding the unit waits the number of seconds defined in Resync_Error_Retry_Delay before attempting to resyn
36. ATA at the customer premises ATA configuration varies according to the individual customer and with the same customer over a period of time Linksys SPA Provisioning Guide Version 3 01 1 1 LINKSYS A Division of Cisco Systems Inc Chapter1 Provisioning Linksys VoIP Devices Provisioning Overview The ATA must be configured to match the account service parameters for the individual customer Also configuration may need to be modified because of newly introduced service provider features modifications in the service provider network or firmware upgrades in the endpoint This customized ongoing configuration is supported by the following features of Linksys ATAs Reliable remote control of the endpoint Encryption of the communication controlling the endpoint Streamlined endpoint account binding Remote Endpoint Control The service provider must be able to modify configuration parameters in the ATA after the unit has been deployed to the customer premises The service provider must also be able to upgrade the endpoint firmware remotely and both of these operations must be reliable In a residential deployment the endpoint itself is typically connected in a local network and accesses the Internet through a router using network address translation NAT For enhanced security the router may attempt to block unauthorized incoming packets by implementing symmetric NAT a packet filtering strategy which severely res
37. EGTMR1 eq 0 http p tel com has reg cfg post a http p tel com lost reg In the following example the SPA resyncs to the same server but provides additional information if a certificate is not installed in the unit for legacy pre 2 0 units SCCERT eq Installed https p tel com config https p tel com config Linksys MAU In the following example Line 1 is disabled until GPP_A is set equal to Provisioned through the first URL Afterwards it resyncs to the second URL SA ne Provisioned Line _Enable_1_ No https p tel com init prov https p tel com configs In the following example the profile returned by the server is assumed to contain XML element tags that need to be remapped to proper SPA parameter names by the aliases map stored in GPP_B alias b https p tel com account spaSMA xml A resync is typically considered unsuccessful if a requested profile is not received from the server This default behavior can be overridden by the parameter Resync_Fails_On_FNF If Resync_Fails_On_FNF is set to No then the SPA accepts a file not found response from the server as a successful resync The default value for Resync_Fails_On_FNF is Yes The SPA provides a mechanism for reporting its current internal configuration to the provisioning server This is useful for development and debugging The report syntax is similar to the XML profile All provisionable parameters are included ex
38. Guide Version 3 01 2 1 LINKSYS A Division of Cisco Systems Inc Chapter2 Creating Provisioning Scripts Open Format Configuration File Open Format Configuration File A configuration file in open XML style format can be sent from the provisioning server to the SPA during a resync operation without compiling them into a binary object The SPA can accept configuration formats generated by standard tools This eases development of back end provisioning server software to generate SPA configuration profiles from existing databases The SPA configuration profile open format consists of a text file with XML like syntax optionally compressed using the gzip deflate algorithm RFC1951 and further optionally encrypted using 256 bit AES symmetric key encryption The XML profile syntax consists of an XML style hierarchy of elements with element attributes and values Opening element tags need to be properly matched by corresponding closing element tags Empty element tags are allowed Element tags are case sensitive Comments are allowed using standard XML syntax Leading and trailing white space is removed from the parameter value New lines within a value are converted to spaces The SPA recognizes elements with proper SPA parameter names when encapsulated in the special lt flat profile gt element In addition the SPA also recognizes arbitrary configurable aliases for a limited number of parameter names The lt flat profi
39. L post http ps one com cpe resyncs The alias option provides a flexible means of recognizing alternative parameter names in XML based configuration profiles This is useful in cases where part of the configuration profile is obtained from a customer database form that uses different terminology than expected by the SPA For example a customer XML profile specifies the SIP registration parameters name number auth secret enclosed in an XML element hierarchy as follows lt CPE gt lt SIP Credentials gt lt name gt J Smith lt name gt lt number gt 14085551234 lt number gt lt auth secret gt 732091751563sfd lt auth secret gt lt SIP Credentials gt lt CPE gt Linksys SPA Provisioning Guide LINKSYS A Division of Cisco Systems Inc Chapter2 Creating Provisioning Scripts Using Provisioning Parameters To map these three parameters directly to the SPA Display_Name_1_ User_ID_1_ and Password_1_ parameters Line 1 enter this mapping in a general purpose parameter for example GPP_M CPE SIP Credentials name flat profile Display_Name_1_ CPE SIP Credentials number flat profile User_ID_1_ CPE SIP Credentials auth secret flat profile Password_1_ Then request the customer credentials profile with the following URL option showing an example URL for completeness alias m http acct voipservice net credentials spaSMA xml Upon receiving the profile the SPA would apply the i
40. L character escapes including escapes for those shown in Table 2 1 Table 2 1 Special Character XML Escape Sequence amp ampersand amp amp lt less than amp lt gt greater than amp gt apostrophe amp apos double quote amp quot Numeric character escapes using decimal and hexadecimal values s a 40 and s x2e are also translated The SPA firmware does not support the full Unicode character set but only the ASCII subset The profile in Example 2 3illustrates character escapes This example defines an information hotline dial plan which sets the Dial_Plan 1 parameter equal to SO lt 18005551212 gt Example 2 3 Dial Plan Example lt flat profile gt lt Dial_Plan_1 gt SO amp lt 18005551212 amp gt lt Dial Plan 1 gt Linksys SPA Provisioning Guide LINKSYS A Division of Cisco Systems Inc Chapter2 Creating Provisioning Scripts Open Format Configuration File lt flat profile gt The element names that are recognized by the SPA can be derived from the SPA administration web server field names as follows Append n to each of the numbered parameters where n is the line user or extension number for example Dial_Plan 1 and Dial_Plan 2 Replace spaces plus any of the following special characters with underscores This is illustrated by Example 2 4 which also illustrates setting user access privileges using the
41. LINKSYS A Division of Cisco Systems Inc Linksys SPA Provisioning Guide Version 3 01 Corporate Headquarters Linksys 121 Theory Drive Irvine CA 92617 USA http www linksys com Tel 949 823 1200 800 546 5797 Fax 949 823 1100 Cisco SYSTEMS Linksys SPA Provisioning Guide Copyright 2007 Cisco Systems Inc All rights reserved Specifications are subject to change without notice Linksys is a registered trademark or trademark of Cisco Systems Inc and or its affiliates in the U S and certain other countries Other brands and product names are trademarks or registered trademarks of their respective holders Disclaimer Please Read This document contains implementation examples and techniques using Linksys a division of Cisco Systems Inc and in some instances other company s technology and products and is a recommendation only and does not constitute any legal arrangement between Linksys a division of Cisco Systems Inc and the reader either written or implied The conclusions reached and recommendations and statements made are based on generic network service and application requirements and should be regarded as a guide to assist you in forming your own opinions and decision regarding your particular situation As well Linksys reserves the right to change the features and functionalities for products described in this document at any time These changes may involve changes to the described solutions over time Use
42. Name G723_Codec_Name NAT Support Parameters Handle VIA received Handle VIA _rport Insert_VIA_received Insert_VIA_rport Substitute_VIA_ Addr send Resp To Src Port 16384 16482 0 030 wyn o A 100 101 rgo 97 3 96 3 go 3 NSE telephone event POMU 4 PCMA G726 16 G726 24 G726 32 G726 40 G729a G729ab G723 No No No No No No 1 Linksys SPA Provisioning Guide Version 3 01 E LINKSYS A Division of Cisco Systems Inc Appendix C Example SPA Configuration Profile E STUN_Enable No STUN_Test_Enable No 3 STUN_Server as EXT IP a a EXT RTP _Port_Min ne 3 NAT Keep Alive _Intvl al es KK Line Fnable 1 Yes 3 SAS_Enable 1 No 7 MOH_Server 1 nS SAS DLG Refresh _Intvl 1 30 3 NAT_Mapping_Enable 1 No SAS _ Inbound RTP_Sink 1 MS ae SIP_Port 1 5060 NAT_Keep_Alive_Enable 1 No EXT_SIP_Port 1 a NAT _Keep_ Alive _ Msg 1 SNOTIFY SIP _ TOS DiffServ_Value 1 0x68 NAT_Keep_Alive_Dest 1 SPROXY RTP_TOS DiffServ_Value 1 0xb8 SIP_Debug_Option 1 none options none 1 line 1 line excl OPT 1 line excl NTFY 1 line excl REG 1 line excl OPT NTFY REG full full excl OPT full excl NTFY full excl REG full excl OPT NTFY REG Network_Jitter_Level 1 high options low medium high very high SIP_100REL Enable 1 No Blind _ Attn Xfer_Enablel 1 No SIP_Proxy Req
43. P_P These should be empty Step9 To resync the test SPA to the basic txt configuration profile open the following URL from the PC browser Assuming the PC IP address is 192 168 1 200 http 192 168 1 100 admin resync tfitp 192 168 1 200 basic txt This resync URL method is designed for development and testing When it receives this command the SPA at address 192 168 1 100 requests the file basic txt from the TFTP server at IP address 192 168 1 200 It then parses the downloaded file and updates the GPP_A parameter with the value 12345678 Step 10 Verify that the parameter was correctly updated by refreshing the admin advanced page on the PC web browser and selecting the Provisioning tab on that page The GPP_A parameter should now contain the value 12345678 Syslog The SPA sends a syslog message to a syslog server when the SPA is about to resync to a provisioning server and after the resync has either completed or failed This server is identified in the web server administration admin advanced System tab Syslog_Server parameter It is instructive to configure the syslog server IP address into the SPA and observe the messages generated during each exercise Exercise Step1 Install and activate a syslog server on the local PC Step 2 Program the PC IP address into the Syslog Server parameter and submit the change Click the System tab and enter the value of your local syslog server into the Syslog_Server parameter Step3
44. Systems Inc Basic Resync Chapter3 Provisioning Tutorial Also the configuration profile can be stored in a subdirectory of the server virtual root directory Again this is specified using standard URL notation For example the following is a valid Profile_Rule that requests the file spa2102 cfg in the server subdirectory Linksys config for the TFTP server running on host prov telco com which listens for connection on port 6900 tftp prov telco com 6900 Linksys config spa2102 cfg Again macro expansion can be used anywhere in the URL This can be convenient in organizing a directory of profiles on the server for the deployed SPA devices For example a profile subdirectory name might be supplied for each SPA in a dedicated general purpose parameter with its value referred within a common profile rule via macro expansion For example GPP_B has the following definition Dj 6LMp230 The Profile Rule has this value tftp prov telco com Linksys SB SMA cfg Then when resyncing this SPA assuming a MAC address of 000e08012345 requests the profile at the following URL tftp prov telco com Linksys Dj6Lmp230 000e08012345 cfg HTTP GET Resync Step 1 Step 2 Step 3 Step 4 HTTP provides a more reliable resync mechanism than TFTP because it is better at establishing a TCP connection between a SPA client behind a firewall or NAT device and a remote provisioning server on the Internet In addition HTTP servers
45. _K 3 GPP_L ia GPP_M ae GPP_N re GPP_O i GPP_P 7 GPP_SA bie 3 GPP_SB vas g GPP_SC ae GPP_SD ca STP Parameters Max Forward 70 3 Max Redirection Vo g Max_Auth mag E SIP_User_Agent_Name SVERS LON SIP_Server_Name SVERSION SIP_Accept_Language a DTMF_Relay_MIME_ Type application dtmf relay Hook_Flash_MIME_ Type application hook flash Remove_Last_Reg No Use_Compact_Header No Linksys SPA Provisioning Guide C 2 Version 3 01 AppendixC Example SPA Configuration Profile LINKSYS A Division of Cisco Systems Inc STP Timer Values sec SIP_T1 SIP _ T2 SIP_T4 SIP_Timer_B SIP_Timer_F SIP_Timer_H SIP Timer_D SIP Timer _J INVITE _Expires ReINVITE_Expires Reg_Min_FExpires Reg _Max_Expires Reg_Retry_Intvl Reg_Retry_Long_Intvl io 3 nau m5 TAr g TOAT toe 4 ge ee oa 2 240 30 3 mq 7200 2 30 1200 Response Status Code Handling SIT RSC SIT RSC SIT3_RSC SIT4_RSC Try_Backup_RSC Retry_Reg_RSC RTP Parameters RTP_Port_Min RTP _Port_Max RTP Packet Size Max RTP ICMP Err RTCP_Tx Interval SDP Payload Types NSE_Dynamic_Payload AVT_Dynamic_Payload G726r16_Dynamic_Payload G726r24 Dynamic_Payload G726r40_Dynamic_Payload G729b Dynamic_Payload NSE_Codec_Name AVT_Codec_Name G711u_Codec_Name G711la_Codec_Name G726r16_Codec_Name G726r24 Codec_Name G726r32_Codec_Name G726r40_Codec_Name G729a_Codec_Name G729b_Codec_
46. _No_Ans_ Delay 1 L 20 Selective Call Forward Settings Cfwd_Sell Caller 1 Lee 4 Cfwd_Sell Dest 1 1O ANAN 4a Cfwd_Sel2_Caller 1 Les Cfwd_Sel2 Dest 1 Ee Cfwd_Sel3 Caller 1 EN 4 Cfwd_Sel3_Dest 1 L ww G Cfwd_Sel4 Caller 1 ae 3 Cfwd_Sel4 Dest 1 LE ei S Cfwd_Sel5 Caller 1 pe 3 Cfwd_Sel5_Dest 1 ee Cfwd_Sel6 Caller 1 ne Cfwd_Sel6_Dest 1 be Cfwd_Sel7 Caller 1 or a Cfwd_Sel7 Dest 1 Lm F Cfwd_Sel8 Caller 1 i ee 3 Cfwd_Sel8_Dest 1 homes Cfwd_Last_Caller 1 Coe Cfwd_Last_Dest 1 Pee 4 Block_Last_Caller 1 es Accept_Last_Caller 1 iL 3 Speed Dial Settings Speed_Dial_2 1 ee Speed_Dial_3 1 Ls Speed_Dial_4 1 E oe Speed_Dial_5 1 ee 3 Speed_Dial_6 1 Speed_Dial_7 1 eee Speed_Dial_8 1 bw F Speed_Dial_9 1 Le 4 Supplementary Service Settings CW_Setting 1 L Yes 3 Block_CID_Setting 1 No 3 Block_ANC_Setting 1 1 No 3 DND_Setting 1 PY No CID_Setting 1 L Yes CWCID Setting 1 I Yes Dist_Ring_Setting 1 Yes Secure_Call_ Setting 1 No 4 Distinctive Ring Settings Ringl Caller 1 be Gs Ring2 Caller 1 Do weg Ring3 Caller 1 Rt og Ring4_Caller 1 Lies Ring5 Caller 1 Lam 4 Ring6_Caller 1 Cee 4 Ring7 Caller 1 oe y Ring8 Caller 1 eee Ring Settings Linksys SPA Provisioning Guide C6 Version 3 01 Appendix C Example SPA Configuration Profile LINKSYS A Division of Cisco Systems Inc Default_Ring 1 Default_C
47. acro 4 8 PORT macro 4 9 premium features 1 11 preprovisioning 1 5 Profile_Rule_B parameter 4 4 Profile_Rule parameter 4 3 profile encryption explicit 1 12 profile resync syslog messages 1 15 profiles encrypted 1 12 proprietary format 1 5 Provision_Enable parameter 4 1 provisioning setup 1 10 states 1 7 provisioning flow 1 6 provisioning servers Version 3 01 LINKSYS A Division of Cisco Systems Inc Index redundant 1 4 PRVST macro 4 8 PRVTMR macro 4 8 PSN macro 4 8 public private key pairs 1 9 generating 1 13 R redundant provisioning servers 1 4 REGTMRI macro 4 8 REGTMR2 macro 4 8 remote control 1 2 remote provisioning 1 2 Report_Rule parameter 4 4 resynce 1 2 automatic 1 5 syslog messages 1 15 URL command 1 4 Resync_After_Upgrade_Attempt parameter 4 3 Resync_Error_Retry_Delay parameter 4 2 Resync_Fails_On_FNF parameter 4 3 Resync_From_SIP parameter 4 3 Resync_On_Reset parameter 4 1 Resync_Periodic parameter 4 2 Resync_Random_Delay parameter 4 2 Resync_Trigger_l parameter 4 3 retail distribution model 1 3 root authorities 1 9 root certificate 1 13 RSA 1 13 RTP300 5 vii S SA through SD macro 4 7 SCHEME macro 4 8 SEC PRV 1 flow step 1 8 secure remote provisioning 1 2 Linksys SPA Provisioning Guide p LINKSYS A Division of Cisco Systems Inc Index server authentication 1 9 certificate 1 9 server certificates generating 1 13 obtaining 1 13 server confi
48. ansmission between switches Switch switching Equipment that connects and routes calls and provides other interim functions such as least cost routing IVR and voicemail It performs the traffic cop function of telecommunications via automated management decisions Touchtone DTMF The tone recognized by a push button touchtone telephone Unified messaging Platform that lets users send receive and manage all e mail voice and fax messages from any telephone PC or information device Voicemail A system that allows storage and retrieval of voice messages through voice mail boxes Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Example SPA Configuration Profile What follows is a sample profile An up to date profile template can be obtained from the SPC tool with the command line invocation spc sample profile sample txt kKkK Linksys SPA Series Configuration Parameters kkk System Configuration Restricted_Access_Domains n Enable_Web_Server Yes 3 Web_Server_Port 80 Enable_Web_Admin_Access Yes Admin_Passwd nu User_Password foun Internet Connection Type DHCP Yes Static 1P Lee 3 NetMask Ler g Gateway Ls Optional Network Configuration HostName be g Domain Lo a Primary_DNS DOLE 2 Secondary_DNS fw DNS _Server_Order Manual options Manual Manual DHCP DHCP Manual DNS_Query_ Mode Parallel
49. apter 1 Provisioning Linksys VoIP Devices TFTP is convenient for managing small deployments of SPA units within an office LAN environment It is also useful for in house preprovisioning of SPAs in preparation for remote deployment However once deployed remotely HTTP offers greater provisioning reliability given NAT and router protection mechanisms The SPA is able to obtain a TFTP server IP address directly from the DHCP server through DHCP option 66 If this is done a Profile_Rule need be configured only with the profile filepath on that TFTP server The Profile_Rule provided with the factory default configuration is as follows spa PSN cfg For example on a SPA2102 this expands to spa2102 cfg which means that the unit resyncs to this file on the local TFTP server if that is specified via DHCP option 66 Note that the specified filepath is relative to the TFTP server virtual root directory The SPA behaves like a browser requesting web pages from any remote Internet site This provides a reliable means of reaching the provisioning server even when a customer router implements symmetric NAT or other protection mechanisms HTTP and HTTPS works more reliably than TFTP in remote deployments especially when the deployed units are connected behind residential firewalls or NAT enabled routers As an alternative to HTTPS the SPA can resync to a configuration profile using HTTP In this case a separate explicit profile encryption can be use
50. ash_Len 2 bo Soe 3 VMWI_Ring_Policy 2 New VM Available options New VM Available New VM Becomes Available New VM Arrives Ring _On_No_New_VM 2 No 4 Call Progress Tones Dial Tone 350 G 19 440 G 19 10 0 142 Second_Dial_Tone 420 19 520 19 10 0 1 2 Outside _Dial_ Tone 420 16 10 0 1 3 Prompt_Tone 520 19 620 19 10 0 1 2 Busy_Tone 480 19 620 19 10 5 5 14 2 Reorder_Tone 480 19 620 19 10 25 25 1 2 Off_Hook_Warning_Tone 480 10 62000 10 125 125 1 2 Ring_Back_Tone 4240 19 480 19 2 4 1 2 Confirm Tone 600 16 1 25 25 1 SIT Tone 985 16 1428 16 1777 16 20 380 0 1 380 0 2 380 0 3 0 4 0 SIT2 Tone 914 16 1371 16 1777 16 20 274 0 1 274 70 2 380 0 3 0 4 0 SIT3_Tone 914 16 1371 16 1777 16 20 380 0 1 380 0 2 380 0 3 0 4 0 SIT4 Tone 9385 16 13714 16 1777 16 20 380 0 1 274 0 2 380 0 3 0 4 0 MWI_Dial_Tone 350 19 440 19 2 1 1 1 2 10 0 1 2 Cfwd_Dial_Tone 350 19 440 19 2 2 2 1 2 10 0 1 2 Holding_Tone 600 19 1 1 1 1 1 1 1 9 5 1 Conference_Tone 350 19 20 1 1 1 1 9 7 1 Secure_Call_Indication_Tone 397 19 507 19 15 0 2 0 2 1 1 1 2 1 2 Distinctive Ring Patterns Ringl_ Cadence 60 2 4 Ring2 Cadence 60 3 2 1 2 3 4 3 Ring3 Cadence 60 0 lt 4 2 8 4 Ring4 Cadence 60 4 2 3 2 8 4 Ring5_Cadence GO se ooo ee wees eee l
51. associate the device with the new account In the following example a device at the DHCP assigned IP address 192 168 1 102 is instructed to provision itself to the SuperVoIP service http 192 168 1 102 admin resync https prov supervoip com linksys init 1234abcd In this example 1234abcd is the PIN number of the new account The remote provisioning server is configured to associate the SPA that is performing the resync request with the new account based on the URL and the supplied PIN Through this initial resync operation the SPA is configured in a single step and is automatically directed to resync thereafter to a permanent URL on the server For example https prov supervoip com linksys For both initial and permanent access the provisioning server relies on the SPA client certificate for authentication and supplies correct configuration parameter values based on the associated service account Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter1 Provisioning Linksys VoIP Devices Provisioning Overview Automatic In House Preprovisioning Using the administration web server and issuing a resync URL is convenient for a customer in the retail deployment model but it is not as convenient for preprovisioning a large number of units The SPA supports a more convenient mechanism for in house preprovisioning With the factory default configuration a SPA automatically tries to resync
52. be used as source file for eventual spc compilation Linksys SPA Provisioning Guide LINKSYS A Division of Cisco Systems Inc Chapter2 Creating Provisioning Scripts Proprietary Plain Text Configuration File spc sample profile plain txt sample config xml to be fed directly to an SPA running 2 0 6 or above spc sample xml config xml Proprietary Plain Text Configuration File The plain text format is an alternative to the open format and is the only format recognized by firmware releases prior to 2 0 6 Source Text Syntax The syntax of the plain text file accepted by SPC is a series of parameter value pairs with the value enclosed in double quotes Each parameter value pair is followed by a semicolon for example parameter_name parameter_value If no quoted value is specified for a parameter or if a parameter specification is missing entirely from the plain text file the value of the parameter remains unchanged in the SPA The syntax also controls the User account access to the parameter in the administration web server An optional exclamation point or question mark immediately following the parameter name indicates the parameter should be read write or user read only for the User account If neither mark is present the parameter is made inaccessible to the user from the web server pages Note that this syntax has no effect on the Admin account access to the parameter If the parameter specification is mis
53. bes how to work with Linksys provisioning Provisioning Scripts scripts and configuration profiles Chapter 3 Provisioning This chapter provides step by step procedures for using the Tutorial scripting language to create a configuration profile Chapter 4 Provisioning Field This chapter provides a systematic reference for each parameter on Reference the Provisioning tab of the administration web server Appendix A Acronyms This appendix provides the expansion of acronyms used in this document Appendix B Glossary This appendix defines the terms used in this document Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Preface Document Conventions The following are the typographic conventions used in this document Typographic Element Meaning Boldface Indicates an option on a menu or a literal value to be entered in a field lt parameter gt Angle brackets lt gt are used to identify parameters that appear on the configuration pages of the Linksys device administration web server The index at the end of this document contains an alphabetical listing of each parameter hyperlinked to the appropriate table in Chapter 4 Provisioning Field Reference Italic Indicates a variable that should be replaced with a literal value Monospaced Font Indicates code samples or system output Related Documentation The following documentation provides additio
54. c again If Resync_Error_Retry_Delay is zero the SPA does not try to resync following a failed resync attempt Optional Verify that the value of Resync_Error_Retry_Delay is set to a small number such as 30 disable the TFTP server and observe the results in the syslog trace Linksys SPA Provisioning Guide ey Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter3 Provisioning Tutorial Basic Resync Unique Profiles and Macro Expansion In a large deployment each SPA needs to be configured with distinct values for specific parameters such as User_ID or Display_Name This requires the service provider to generate distinct profiles one for each deployed SPA Each SPA in turn must be configured to resync to its own profile according to some predetermined profile naming convention The SPA profile URL syntax can include identifying information specific to each SPA such as MAC address and serial number via macro expansion of built in variables This eliminates the need to specify these values within each SPA profile The SPA profile rule undergoes macro expansion internally before being applied The macro expansion understands a number of values including the following MA expands to the unit MAC address using lower case hex digits for example O00eO08abcdef SN expands to the unit Serial Number for example 88012BA01234 Exercise Step1 Obtain the MAC address of the test SPA from its product label Th
55. cept for the values of passwords keys and the GPP_SA to GPP_SD parameters which are not shown The Report_Rule parameter is evaluated like a profile rule parameter In other words it accepts a URL optionally qualified with a bracketed expression The URL specifies the target destination for the report and an encryption key can be included as an option The URL scheme can be TFTP HTTP or HTTPS When using TFTP the operation performed is TFTP PUT In the case of HTTP and HTTPS the operation performed is HTTP POST If an encryption key is specified the report is encrypted using 256 bit AES in CBC mode The encrypted report can be decrypted with the following OpenSSL or equivalent command openssl enc d aes 256 cbc k secretphrase in rep xml enc out rep xml Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter2 Creating Provisioning Scripts Data Types The following is an example of the corresponding Report_Rule configuration key secretphrase http prov serv net spa SMA rep xml enc Once the report rule is configured an actual report can be generated and transmitted by sending the SPA a SIP NOTIFY message with the Event report type The SIP NOTIFY request is handled like other SIP notifies with the SPA requiring authentication from the requesting server before honoring the request to issue areport Each SIP NOTIFY report request generates one attempt to transmit the r
56. choice of most long distance providers that bill their customers directly Blocked calls Caused by an insufficient network facility that does not have enough lines to allow calls to reach a given destination May also pertain to a call from an originating number that is blocked by the receiving telephone number Bundled service Offering various services as a complete package Call completion The point at which a dialed number is answered Call termination The point at which a call is disconnected CDR Call Detail Records A software program attached to a VoIP telephone system that records information about the telephone number activity Carrier s carrier Companies that build fiber optic and microwave networks primarily selling to resellers and carriers Their main focus is on the wholesale and not the retail market Casual access When customers choose not to use their primary carriers to process the long distance call being made The customer dials the carrier 101XXXX number CO Central Office Switching center for the local exchange carrier Centrex This service is offered by the LEC to the end user The feature rich Centrex line offers the same features and benefits as a PBX to a customer without the capital investment or maintenance charges The LEC charges a monthly fee to the customer who must agree to sign a term agreement Circuits The communication path s that carry calls between two points on a network C
57. completion of a resync attempt The default is PN MAC Successful resync SCHEME SERVIP PORTS PATH ERR Log_Resync_Failure_Msg Syslog message issued after a failed resync attempt The default is PN MAC Resync failed SERR Report_Rule The target URL to which configuration reports are sent This parameter has the same syntax as the Profile_Rule parameter and resolves to a TCP IP command with an associated URL A configuration report is generated in response to an authenticated SIP NOTIFY message with Event report The report is an XML file containing the name and value of all the device parameters This parameter may optionally contain an encryption key For example key K tftp ps callhome net S MA rep xml enc The default is empty Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter4 Provisioning Field Reference Firmw are Upgrade Parameters Firmw are Upgrade Parameters The following table defines the function and usage of each parameter in the Firmware Upgrade section of the Provisioning tab Table 4 2 Firmware Upgrade Parameters Parameter Name Description and Default Value Upgrade_Enable Enables firmware upgrade operations independently of resync actions The default is Yes Upgrade_Error_Retry_Delay The upgrade retry interval in seconds applied in case of upgrade failure The device has a firmware upgrade er
58. d to protect confidential information The SPA supports 256 bit AES in CBC mode to pre encrypt individual profiles These encrypted profiles can be downloaded by the SPA using HTTP without danger of unauthorized use of confidential information in the configuration profile This resync mode may be useful to reduce the computational load on the provisioning server required when using HTTPS for every resync request In a small deployment within a single LAN environment it is common to rely on a simple TFTP server for provisioning of network devices Linksys voice devices support TFTP for both provisioning resync and firmware upgrade operations TFTP is especially useful for the in house preprovisioning of a large number of un provisioned devices Basic HTTP based SPA provisioning relies on the HTTP GET method for retrieving configuration profiles Typically this means that a configuration file is pre generated for each deployed SPA and these files are stored within an HTTP server directory When the server receives the GET request it simply returns the file specified in the GET request header Alternatively the requested URL can invoke a CGI script still using the GET method In this case the configuration profile might be generated dynamically perhaps by querying a customer database and producing the profile on the fly In the case of CGI handling resync requests the SPA also supports the HTTP POST method as a mechanism to request the resync c
59. device the corresponding key needs to be programmed into the lt License_Keys gt parameter Once programmed the feature remains enabled permanently License_Keys is a write only parameter that always appears empty when read Contact Linksys for further information or to obtain license keys Softw are Tools The following software tools are useful for provisioning Linksys ATAs Open source gzip compression utility used when generating configuration profiles Open source OpenSSL software package for profile encryption and HTTPS operations Scripting language with CGI scripting support such as the open source Perl language tools to test dynamic generation of profiles and one step remote provisioning using HTTPS Ethernet packet analyzer such as the freely downloadable Ethereal Wireshark to verify secure exchanges between provisioning servers and Linksys voice devices The ssldump utility for monitoring HTTPS transactions Server Configuration Provisioning requires the availability of servers which for testing purposes can be installed and run on a local PC TFTP UDP port 69 HTTP TCP port 80 HTTPS TCP port 443 Syslog UDP port 514 To troubleshoot server configuration it is helpful to install a separate client for each type of server ona different host Linksys SPA Provisioning Guide p Version 3 01 LINKSYS A Division of Cisco Systems Inc Provisioning Setup TFTP HTTP Ch
60. device unique CFG file should reconfigure the profile parameters to enable stronger encryption by programming a 256 bit encryption key and pointing to arandomly generated TFTP directory For example the CFG file might contain Profile Rule key SA tftp callme com profile SB spa2102 cfg GPP_A 8e4ca259 256 bit key GPP_B Gp3sqbn random CFG file path directory SEC PRV 2 Secure Provisioning Full Configuration The subsequent profile resync operations retrieve 256 bit encrypted CFG files which maintain the SPA in a state synchronized to the provisioning server All remaining SPA parameters are configured and maintained through this strongly encrypted profile The encryption key and random directory location can be changed periodically for extra security Using HTTPS The SPA provides a reliable and secure provisioning strategy based on HTTPS requests from the SPA to the provisioning server using both server and client certificates for authenticating the client to the server and the server to the client To use HTTPS with Linksys SPA units you must generate a Certificate Signing Request CSR and submit it to Linksys Linksys generates a certificate for installation on the provisioning server that is accepted by the SPA units when they seek to establish an HTTPS connection with the provisioning server This procedure is described in the Enabling HTTPS section on page 1 13 How HTTPS Works Starting with firmware
61. dom time interval that the device waits before making its initial contact with the provisioning server This delay is effective only on the initial configuration attempt following device power on or reset The delay is a pseudo random number between zero and this value This parameter is in units of 20 seconds the default value of 2 represents 40 seconds This feature is disabled when this parameter is set to Zero This feature can be used to prevent an overload of the provisioning server when a large number of devices power on simultaneously The default is 2 40 seconds Resync_Periodic The time interval between periodic resyncs with the provisioning server The associated resync timer is active only after the first successful sync with the server Set this parameter to zero to disable periodic resyncing The default is 3600 seconds Resync_Error_Retry_Delay Linksys SPA Provisioning Guide Resync retry interval in seconds applied in case of resync failure The device has an error retry timer that activates if the previous attempt to sync with the provisioning server fails The device waits to contact the server again until the timer counts down to zero This parameter is the value that is initially loaded into the error retry timer If this parameter is set to zero the device immediately retries to sync with the provisioning server following a failed attempt The default is 3600 seconds Ve
62. e test SPA web interface on the admin advanced page Provisioning tab and edit GPP_A to contain the alias map indicated above do not enter new lines through the web interface instead simply enter each alias consecutively customer account SIP number flat profile User_ID 1 customer account SIP password flat profile Password_1_ Step4 Edit the Profile_Rule to point to the new XML profile and also specify the alias map as a URL option as follows alias a tftp 192 168 1 200 customer xml Step5 Click Submit All Changes When the SPA resyncs it receives the XML profile remaps the elements as indicated by the alias map and populates the User_ID_1_ and Password_1_ parameters Step6 View the Line 1 tab to verify the new configuration S Note The SPA supports alias remapping of a limited number of parameters It is not meant to rename all parameters in its configuration Proprietary Profile Format Firmware releases prior to 2 0 6 do not recognize the XML based profiles described so far in this chapter Instead the Linksys Profile Compiler tool SPC converts a text based profile definition into a proprietary binary format understood by earlier versions of the firmware The tool provides its own options for encrypting the resulting binary profile The text based profile understood by SPC uses a different syntax from the XML profile presented earlier It consists of a list of parameter value pairs with the value
63. e to a remote profile periodically and on power up Starting with firmware release 2 0 256 bit symmetric key encryption of profiles is supported In addition an unprovisioned SPA can receive an encrypted profile specifically targeted for that device without requiring an explicit key Release 2 0 supports a secure first time provisioning mechanism using SSL functionality Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter1 Provisioning Linksys VoIP Devices Provisioning Overview s Note Remote customization RC units are introduced with Release 5 x RC units are customized by Linksys so when the unit is started it tries to contact the Linksys provisioning server to download its customized profile User intervention is not required to initiate or complete a profile update or firmware upgrade Remote firmware upgrade is achieved via TFTP or HTTP but not using HTTPS because the firmware does not contain sensitive information that can be read by a customer The SPA upgrade logic is capable of automating multi stage upgrades if intermediate upgrades are required to reach a future upgrade state from an older release A profile resync is only attempted when the SPA is idle because this may trigger a software reboot General purpose parameters are provided to help service providers manage the provisioning process Each SPA can be configured to periodically contact a normal provisioning serv
64. eneration of configuration profiles To explain the functionality in this section TFTP from a local PC is used as the resync method although HTTP or HTTPS can be used for testing as well if it is convenient This section includes the following topics Profile Compression page 3 10 Profile Encryption page 3 11 Partitioned Profiles page 3 12 Parameter Name Aliases page 3 12 Proprietary Profile Format page 3 13 Profile Compression Step 1 A configuration profile in XML format can become quite large if all parameters are individually specified by the profile To reduce the load on the provisioning server the SPA supports compression of the XML file using the deflate compression format used by the gzip utility RFC 1951 Exercise Install gzip on the local PC Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter3 Provisioning Tutorial Profile Formats Step 2 Compress the basic txt profile from earlier exercises by invoking gzip from the command line gzip basic txt This generates the deflated file basic txt gz Step3 Save the deflated file in the TFTP server virtual root directory Step4 Modify the Profile_Rule on the test SPA to resync to the deflated file in place of the original XML file as in the following example tftp 192 168 1 200 basic txt gz Step5 Click Submit All Changes Step6 Observe the syslog trace from the SPA Upon resync
65. eport Retries are not supported Upgrade Rule The SPA provides one configurable remote upgrade parameter Upgrade_Rule This parameter accepts a syntax similar to the profile rule parameters URL options not supported for upgrades but conditional expressions and assignment expressions can be used If conditional expressions are used the parameter can be populated with multiple alternatives separated by the character The syntax for each alternative is as follows conditional expr assignment expr URL As in the case of Profile_Rule parameters the Upgrade_Rule parameter evaluates each alternative until a conditional expression is satisfied or an alternative has no conditional expression The accompanying assignment expression is evaluated if specified Then an upgrade to the specified URL is attempted If the Upgrade_Rule contains a URL without a conditional expression the SPA upgrades to the firmware image specified by the URL Subsequently it does not attempt to upgrade again until either the rule itself is modified or the effective combination of scheme server port filepath is changed following macro expansion and evaluation of the rule In order to attempt a firmware upgrade the SPA disables audio at the start of the procedure and reboots at the end of the procedure For this reason an upgrade driven by the contents of Upgrade_Rule is only automatically initiated by the SPA if any voice line is currently inactive
66. eprecated alias for SCHEME do not use Request target server host name as obtained after parsing resync or upgrade URL SERVIP Request target server IP address as obtained after parsing resync or upgrade URL possibly following DNS lookup Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter4 Provisioning Field Reference Internal Error Codes Table 4 4 Macro Expansion Variables continued Macro Name Macro Expansion PORT Request target UDP TCP port as obtained after parsing resync or upgrade URL PATH Request target file path as obtained after parsing resync or upgrade URL ERR Result message of resync or upgrade attempt Only useful in generating result syslog messages The value is preserved in the UPGERR variable in the case of upgrade attempts UIDI The contents of the Line 1 User_ID configuration parameter Firmware 2 0 11 and above UID2 The contents of the Line 2 User_ID configuration parameter Firmware 2 0 11 and above ISCUST Value 1 if unit is customized 0 otherwise customization status viewable on WebUI Info page Internal Error Codes The SPA defines a number of internal error codes X00 X99 to facilitate configuration in providing finer control over the behavior of the unit under certain error conditions They can be viewed in Table 4 5 Table 4 5 Error Code Definitions Error Code Descript
67. er NPS Communication wit the NPS does not require the use of a secure protocol because the updated profile is encrypted by a shared secret key The NPS can be a standard TFTP HTTP or HTTPS server Initial Provisioning Linksys ATAs provide convenient mechanisms for initial provisioning based on two deployment models Retail distribution where the customer purchases the ATA separately from the VoIP service Bulk distribution where the service provider issues the ATA to the customer as part of the VoIP service contract In the first model the customer purchases the ATA from a retail outlet and subsequently requests VoIP service from the service provider for use with that adapter The service provider must then support secure remote configuration of the unit In the second model the service provider acquires adapters in bulk quantity and either preprovisions the adapters in house or purchases RC units from Linksys Deploying RC Units The in house preprovisioning step can be eliminated by using RC units Customization of RC units reduces the need to handle the units prior to shipping to end customers It also discourages the use of the SPA with a different service The MAC address of each RC unit is associated with a customized profile for the customer who purchased each unit on a provisioning server maintained by Linksys The RC unit is preprovisioned by Linksys with the connection information for the Linksys provisioning serv
68. er When the RC unit is started it tries to contact the Linksys provisioning server and download its customized profile The status of customization for an RC unit can be determined by viewing the Customization parameter in the Product Information section of the Info tab An RC unit that has not been provisioned displays Pending An RC unit that has been provisioned displays the name of the company that owns the unit If the unit is not an RC unit the web page displays Not Customized Linksys offers RC units to service providers for volume deployments of SPA endpoints Through customization the manufacturing default values of a select number of parameters can be customized to meet the needs of individual service providers l Linksys SPA Provisioning Guide a Version 3 01 1 3 LINKSYS A Division of Cisco Systems Inc Chapter1 Provisioning Linksys VoIP Devices Provisioning Overview The following is a sample template for an RC unit Restricted Access Domain domain com domainl com domain2 com Primary_DNS X Moy os Secondary_DNS We o a 4 Provision_Enable Yes Resync_Periodic x 130r Resync_Error_Retry_Delay 30 Profile Rule http rov domain com sipura profile id SMA The Restricted Access Domain parameter is configured with the actual domain names of up to a maximum of five domains The Primary_DNS and Secondary_DNS parameters are configured with the actual domain names or IP addresses of the DNS servers avai
69. ers Triggers The SPA is designed to resync with the provisioning server periodically The resync interval is configured in Resync_Periodic seconds If this value is left empty the SPA does not resync periodically The resync typically takes place when the voice lines are idle In case a SPA voice line is active when a resync is due the SPA delays the resync procedure until the line becomes idle again However it waits no longer than Forced_Resync_Delay seconds A resync may cause configuration parameter values to change This in turn causes a firmware reboot which terminates any voice connection active at the time of the resync If a resync operation fails because the SPA was unable to retrieve a profile from the server if the downloaded file is corrupt or an internal error occurs the SPA tries to resync again after a time specified in Resync_Error_Retry_Delay seconds If Resync_Error_Retry_Delay is set to 0 the SPA does not try to resync again following a failed resync attempt When upgrading if an upgrade fails a retry is performed after Upgrade_Error_Retry_Delay seconds Two configurable parameters are available to conditionally trigger a resync Resync_Trigger_1 and Resync_Trigger_2 Each of these parameters can be programmed with a conditional expression which undergoes macro expansion If the condition in any of these parameters evaluates to true a resync operation is triggered as though the periodic resync timer had e
70. es to the Profile_Rule Upgrade_Rule and Resync_Trigger_ parameters Macro Expansion Several provisioning parameters undergo macro expansion internally prior to being evaluated This preevaluation step provides greater flexibility controlling the resync and upgrade activities of the SPA The parameter groups which undergo macro expansion before evaluation are as follows e Resync_Trigger_ Profile_Rule Log _Resync_ Upgrade_Rule Log _Upgrade_ Under certain conditions some general purpose parameters GPP_ also undergo macro expansion as explicitly indicated in the Optional Resync Arguments section Linksys SPA Provisioning Guide pa Version 3 01 2 9 LINKSYS A Division of Cisco Systems Inc E Chapter2 Creating Provisioning Scripts Proprietary Plain Text Configuration File During macro expansion expressions of the form NAME and NAME are replaced by the contents of the named variables See the Macro Expansion Variables section on page 4 7 for the complete list of variables available for macro expansion These include general purpose parameters several product identifiers certain event timers and provisioning state values For example for a SPA with MAC address 000E08012345 the expression spas MAU config cfg macro expands into the following string spa000E08012345config cfg If a macro name is not recognized it remains unexpanded For example The name STRANGE is not recognized a
71. esync_On_Reset gt lt Resync_Periodic gt 7200 lt Resync_Periodic gt lt Profile Rule gt tftp prov telco com 6900 Linksys config spa2102 cfg m Linksys SPA Provisioning Guide 2 2 Version 3 01 Chapter 2 Version 3 01 LINKSYS A Division of Cisco Systems Inc Creating Provisioning Scripts Note Open Format Configuration File lt Profile Rule gt lt flat profile gt The profiles in Example 2 1 and Example 2 2 are functionally equivalent Example 2 2 contains additional information and comments which are ignored by the SPA Also in Example 2 2 the lt flat profile gt element is encapsulating within the lt top level gt element Such extra encapsulation is allowed and the parameters within it are still recognized Example 2 2 XML Profile with Comments lt xml Wersion 1 0 7 gt lt top level gt lt Unrecognized element generator is ignored by SPA gt lt generator gt Telco Profile Compiler v 1 2 lt generator gt lt Unrecognized flat profile attribute device is ignored by SPA gt lt flat profile device Linksys gt lt three parameters are specified by this profile gt lt Resync_On_Reset gt Yes lt Resync_On_Reset gt lt Resync_Periodic gt 7200 lt Resync_Periodic gt lt Profile Rule gt tftp prov telco com 6900 Linksys config spa2102 ctg lt Profile Rule gt lt flat profile gt lt top level gt The SPA recognizes and translates basic XM
72. eter names correspond to the names as for XML based profiles Linksys SPA Provisioning Guide LINKSYS A Division of Cisco Systems Inc Chapter2 Creating Provisioning Scripts Proprietary Plain Text Configuration File Any parameter can be assigned a new value in this way and macro expansion applies For example the following is a valid assignment expression User ID 1 uid B GPP_C W GPP_D SMA For conciseness the general purpose parameters GPP_A through GPP_P can also be referred to by the single lowercase letters a through p The example above is equivalent to the following User ID 1 uid B c W d SMA White space can optionally be used for readability URL Syntax Standard URL syntax is used to specify how to retrieve configuration files and firmware loads in Profile_Rule and Upgrade_Rule parameters respectively The syntax is as follows scheme server port filepath Where scheme is one of the following values e tftp http http If scheme is omitted tftp 1s assumed The server can be a DNS recognized host name or a numeric IP address The port is the destination UDP or TCP port number The filepath must begin with the root directory In other words it must be an absolute path If server is missing then the tftp server specified through DHCP option 66 is used instead If port is missing then the standard port for the specif
73. eters are set to yes by default In addition the Resync_From_SIP parameter controls requests for resync operations via a SIP NOTIFY event sent from the service provider proxy server to the SPA If enabled the proxy can request a resync by sending a SIP NOTIFY message containing the Event resync header to the SPA The SPA challenges the request with a 401 response and expects an authenticated subsequent request before honoring the resync request from the proxy The Event reboot_now and Event restart_now headers perform cold and warm restarts respectively are also challenged The two remaining enables are Resync_On_Reset and Resync_After_Upgrade_Attempt These determine if the SPA performs a resync operation after power up software reboots and after each upgrade attempt When enabling Resync_On_Reset the SPA introduces a random delay following the boot up sequence before actually performing the reset The delay is a random time up to the value specified in Resync_Random_Delay in seconds In a pool of SPA units all of which are simultaneously powered up this introduces a spread in the times at which each unit initiates a resync request to the provisioning server This feature can be useful in a large residential deployment in the case of a regional power failures Linksys SPA Provisioning Guide pa Version 3 01 2 15 LINKSYS A Division of Cisco Systems Inc Chapter2 Creating Provisioning Scripts Using Provisioning Paramet
74. g private key and vice versa The SPA supports the RSA algorithm for public private key cryptography Certificates are authenticated in the context of a certificate chain A certificate authority lies at the root of the chain with all other certificates depending on the root authority for authority Server Certificates Each secure provisioning server is issued an SSL server certificate directly signed by Linksys The firmware running on the SPA clients recognizes only these certificates as valid The clients try to authenticate the server certificate when connecting via HTTPS and reject any server certificate not signed by Linksys This mechanism protects the service provider from unauthorized access to the SPA endpoint or any attempt to spoof the provisioning server This might allow the attacker to reprovision the SPA to gain configuration information or to use a different VoIP service Without the private key corresponding to a valid server certificate the attacker is unable to establish communication with a Linksys SPA Client Certificates In addition to a direct attack on the SPA an attacker might attempt to contact a provisioning server using a standard web browser or other HTTPS client to obtain the SPA configuration profile from the provisioning server To prevent this kind of attack each SPA also carries a unique client certificate also signed by Linksys including identifying information about each individual endpoint A ce
75. ges 1 15 Firmware Upgrade section 4 4 Forced_Resync_Delay parameter 4 3 FQDN redundant provisioning servers 1 4 G General Purpose Parameters section 4 6 GPP_A parameter 4 6 GPP_SA parameter 4 6 H HTTP 1 12 HTTP GET method 1 12 HTTP POST method 1 12 HTTPS 1 13 clients 1 8 HTTPS monitoring 1 11 HWVER macro 4 8 in house preprovisioning 1 5 initial access 1 4 m Linksys SPA Provisioning Guide IN 2 iit IP macro 4 8 ISCUST macro 4 9 IVR functions 1 5 K key pairs location of 1 9 L License_Keys parameter 1 11 license keys 1 11 License Keys parameter 4 5 Linksys CA Client Root Certificate 1 13 Linksys Profile Compiler see SPC Linksys Provisioning Server Root Authority 1 9 Linux 1386 elf SPC for 1 6 Log_Resync_Failure_Msg parameter 4 4 Log_Resync_Request_Msg 1 15 Log_Resync_Request_Msg parameter 4 4 Log_Resync_Success_Msg parameter 4 4 Log_Upgrade_Failure_Msg parameter 4 5 Log_Upgrade_Request_Msg parameter 4 5 Log_Upgrade_Success_Msg parameter 4 5 M MAC macro 4 7 macro variables 4 7 MA macro 4 7 MAU macro 4 7 METH macro 4 8 MFG RESET flow step 1 7 monitoring HTTPS 1 11 Version 3 01 NAT devices ATAs with 1 2 O open XML style format 1 5 OpenBSD SPC for 1 6 OpenSSL software package 1 11 OpenSSL utility 1 13 P PAPT2T 5 vii password protection 1 5 PATH macro 4 9 Perl language tools 1 11 permanent access 1 4 plain text format 1 5 PN m
76. guration it is helpful to install clients for each type of server on a separate server machine That establishes proper server operation independent of the interaction with Linksys VoIP devices The pertinent servers include Syslog UDP port 514 TFTP UDP port 69 HTTP TCP port 80 HTTPS TCP port 443 For generating configuration profiles it is useful to install the open source gzip compression utility For profile encryption and HTTPS operations you can install the open source OpenSSL software package In addition to test dynamic generation of profiles and one step remote provisioning using HTTPS a scripting language with CGI scripting support such as the open source Perl language tools is recommended Finally to verify secure exchanges between provisioning servers and Linksys voice devices it is useful to install an Ethernet packet sniffer such as the freely downloadable Ethereal Wireshark For HTTPS transactions you can use the ssldump utility A Linksys VoIP device SPA can retrieve a configuration profile from a provisioning server and update its internal configuration accordingly SPAs accept two different profile formats one based on an open published syntax and one based on an unpublished binary definition The open configuration profile format uses a simple XML like syntax The binary format is generated by converting a plain text file using the SPA Profile Compiler SPC The examples in this tutorial use configuration
77. guration troubleshooting 1 11 SERVIP macro 4 8 SERV macro 4 8 setup provisioning 1 10 signing root authorities 1 9 SN macro 4 8 software tools 1 11 SPA1001 5 vii SPA2102 5 vii SPA3102 5 vii SPA9000 5 vii SPA900 Series IP phones 5 viii SPA provisioning flow 1 6 SPC 1 5 SP CUST flow step 1 7 SSL 1 2 1 8 ssldump utility 1 11 SWVER macro 48 symmetric key encryption 1 2 syslog servers 1 4 1 15 T technical support 5 ix TFTP 1 12 TLS_DHE_RSA_WITH_AES_256_CBC_SHA cipher suite 1 14 tools software 1 11 transport protocols supported 1 2 troubleshooting server configuration 1 11 Linksys SPA Provisioning Guide fee iN F U UIDI macro 4 9 UID2 macro 4 9 UPGCOND macro 4 8 UPGERR macro 4 8 Upgrade_Enable parameter 4 5 Upgrade_Error_Retry_Delay parameter 4 5 Upgrade_Rule parameter 4 5 UPGST macro 4 8 UPGTMR macro 4 8 User account 1 5 User Agent field 1 14 User Agent request field 1 13 W Win32 environment SPC for 1 6 WRTP54G 5 vii X X00 error code 4 9 X20 error code 4 9 X40 error code 4 9 X60 error code 4 9 XML style format 1 5 Version 3 01
78. ied scheme is used instead tftp uses UDP port 69 http uses TCP port 80 https uses TCP port 443 A filepath must be present It need not necessarily refer to a static file but can indicate dynamic content obtained through CGI Macro expansion applies within URLs The following are examples of valid URLs SMA cfg Linksys spa021025 bin 192 168 1 130 profiles init cfg tftp prov call com cpe LinksysSMA cfg http neptune speak net 8080 prov SD SE cfg https secure me com profile Linksys Optional Resync Arguments The URLs entered in Profile_Rule parameters may be preceded by optional arguments collectively enclosed by square brackets The recognized options are key post and alias key The Key option is used to specify an encryption key It is required to decrypt profiles which have been encrypted with an explicit key The key itself is specified as a possibly quoted string following the term key Linksys SPA Provisioning Guide f 2 12 Version 3 01 Chapter 2 post alias Version 3 01 LINKSYS A Division of Cisco Systems Inc Creating Provisioning Scripts Proprietary Plain Text Configuration File Some usage examples key VerySecretValue key my secret phrase key a37d2 b9055c1d04883a0745eb0917a4 The bracketed optional arguments are macro expanded In particular note that the special purpose parameters GPP_SA through GPP_SD are only macro expanded into their macro variable
79. inksys must be installed on the SPA provisioning server The SPA devices cannot resync to a server using HTTPS unless the server supplies a Linksys signed server certificate Exercise Step1 Install an HTTPS server on a host whose IP address is known to the network DNS server through normal hostname translation The open source Apache server can be configured to operate as an HTTPS server when installed with the open source mod_ssl package Step 2 Generate a server Certificate Signing Request for the server Linksys SPA Provisioning Guide jy Version 3 01 LINKSYS A Division of Cisco Systems Inc Secure Resync Step 3 Step 4 Step 5 Step 6 Step 7 Step 8 Step 9 Step 10 Step 11 Step 12 Step 13 Step 14 Chapter3 Provisioning Tutorial For this step you may need to install the open source OpenSSL package or equivalent software If using OpenSSL the command to generate the basic CSR file is as follows openssl req new out provserver csr This command generates a public private key pair which is saved in the privkey pem file Submit the CSR file provserver csr to Linksys for signing A signed server certificate is returned provserver cert along with a Linksys CA Client Root Certificate Sspacroot cert Store the signed server certificate the private key pair file and the client root certificate in the appropriate locations on the server In the case of an Apache installation on Linu
80. ion X00 Transport layer or ICMP error when sending a SIP request X20 SIP request times out while waiting for a response X40 General SIP protocol error for example unacceptable codec in SDP in 200 and ACK messages or times out while waiting for ACK X60 Dialed number invalid according to given dial plan Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter4 Provisioning Field Reference Internal Error Codes Linksys SPA Provisioning Guide 4 10 Version 3 01 LINKSYS A Division of Cisco Systems Inc Acronyms A D Analog To Digital Converter ANC Anonymous Call B2BUA Back to Back User Agent Bool Boolean Values Specified as yes and no or 1 and O in the profile CA Certificate Authority CAS CPE Alert Signal CDR Call Detail Record CID Caller ID CIDCW Call Waiting Caller ID CNG Comfort Noise Generation CPC Calling Party Control CPE Customer Premises Equipment CWCID Call Waiting Caller ID CWT Call Waiting Tone D A Digital to Analog Converter dB decibel dBm dB with respect to milliwatt DHCP Dynamic Host Configuration Protocol DNS Domain Name Server DRAM Dynamic Random Access Memory DSL Digital Subscriber Loop DSP Digital Signal Processor DTAS Data Terminal Alert Signal same as CAS DTMF Dual Tone Multiple Frequency FQDN Fully Qualified Domain Name FSK Freque
81. is is a 12 digit number using lower case hex digits beginning with 000308 such as OOOeO8aabbcc Step 2 Copy the basic txt configuration file to a new file named spa_mac_address cfg and place the new file in the virtual root directory of the TFTP server Replace mac_address with the actual MAC address of the SPA Step3 Open the SPA admin advanced page Provisioning tab Step4 Enter the following value in the Profile_Rule parameter tftp 192 168 1 200 spa MA cfg Step5 Click Submit All Changes This causes an immediate reboot and resync When the next resync occurs the SPA retrieves the new file by expanding the MA macro expression into its own MAC address Several other values can be macro expanded in this way including all the general purpose parameters GPP_A through GPP_P These can be referenced as A through P Macro expansion is not limited to the URL file name but can also be applied to any portion of the profile rule parameter For a complete list of variables available for macro expansion see the Macro Expansion Variables section on page 4 7 URL Resolution The profile URL can contain a provisioning server name instead of an explicit IP address In this case the SPA performs a DNS lookup to resolve the name A non standard server port can be specified in the URL using the standard syntax port following the server name Linksys SPA Provisioning Guide pa Version 3 01 LINKSYS A Division of Cisco
82. ision of Cisco Systems Inc Symbols CCERT macro 1 14 macro 4 7 Numerics 256 bit encryption 1 2 A access initial and permanent 1 4 access control 1 5 Admin account 1 5 administration web server 1 4 Analog Telephone Adapters 5 vii Apache 1 14 A through Pmacro 4 7 attackers protecting SPA from 1 9 authentication certificates 1 9 authorities certificate 1 9 automatic resync 1 5 bulk distribution model 1 3 C CA root certificate 1 13 CCERT macro 4 8 certificates chain 1 10 server 1 9 certificate signing request 1 13 certification authority 1 9 CGI scripting support 1 11 CGI scripts 1 12 chain certificate 1 10 cipher suites 1 14 client certificate 1 4 CN field 1 13 Configuration Profile Parameters section 4 1 configuration profiles 1 2 encrypted 1 12 protecting 1 9 two types 1 5 customization manufacturing 1 3 D deployment models 1 3 DHCP 1 5 disabling User account access 1 5 DNS lookups 1 13 Downgrade_Rev_Limit parameter 4 5 dynamic generation of profiles 1 11 encrypted profiles 1 12 encryption Linksys SPA Provisioning Guide Version 3 01 IN 1 LINKSYS A Division of Cisco Systems Inc Index explict profile 1 12 need for 1 2 ERR macro 4 9 error codes 4 9 Ethernet packet analyzer 1 11 explicit profile encryption 1 12 EXTIP macro 4 8 F factory default configuration 1 5 firmware release 2 0 1 2 firmware upgrades 1 2 log messa
83. isioning Linksys VoIP Devices Provisioning Setup To determine if a SPA carries an individualized certificate use the CCERT provisioning macro variable whose value expands to either Installed or Not Installed according to the presence or absence of a unique client certificate In the case of a generic certificate it is possible to obtain the serial number of the unit from the HTTP request header in the User Agent field HTTPS servers can be configured to request SSL certificates from connecting clients If enabled the server can verify the client certificate chain using the Linksys CA Client Root Certificate supplied by Linksys It can then provide the certificate information to a CGI for further processing The location for storing certificates may vary For example on a Apache installation the file paths for storing the provisioning server signed certificate its associated private key and the Linksys CA client root certificate are likely to be as follows Server Certificate SSLCertificateFile etc httpd conf provserver crt Server Private Key SSLCertificateKeyFile etc httpd conf provserver key Certificate Authority CA SSLCACertificateFile etc httpd conf spacroot crt Refer to the documentation provided for an HTTPS server for specific information Firmware release 2 0 6 supports the following cipher suites for SSL connection to a server using HTTPS Future release updates may implement additional cipher suites Tab
84. l is provided for compiling the Linksys SPA Provisioning Guide pa Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter1 Provisioning Linksys VoIP Devices SPA Provisioning Flow plain text file containing parameter value pairs into an encrypted CFG file The SPC tool is available from Linksys for the Win32 environment spc exe and Linux i386 elf environment spc linux 1386 static Availability of the SPC tool for the OpenBSD environment is available on a case by case basis SPA Provisioning Flow Firmware release 1 0 provides basic features in support of secure provisioning This section describes the high level provisioning flow supported by release 1 0 in the context of a service provider application The SPA provisioning flow is illustrated in Figure 1 1 Figure 1 1 SPA Provisioning Flow SPA 2000 IP 192 168 0 4 DHCP Server MAC 000e08000001 Manufacturing Reset State Unencrypted spa2000 cfg LAN TFTP Server OIH Profile _Rule tftp phoneme com MA spa2000 cfg vsk aaar naaca http 192 168 0 4 admin resync tftp phoneme corv000e0800000 1 spa2000 cfg we on local PC SSS i t i t e OR i i t r t 4 x Remote TFTP Server Targeted encrypted 00060800000 1 spa2000 cfg N C tftp phoneme com SSS Profile_Rule key A tftp phoneme com B spa2000 cfg GPP_A 8d34a9 c721d8d049a3b5fe287329a0b GPP_B Gs7LPr25a1 Re
85. lable to the RC unit Redundant Provisioning Servers The provisioning server may be specified as an IP address or as a fully qualified domain name FQDN The use of a FQDN facilitates the deployment of redundant provisioning servers When the provisioning server is identified through a FQDN the SPA attempts to resolve the FQDN to an IP address through DNS Only DNS A records are supported for provisioning DNS SRV address resolution is not available for provisioning The SPA continues to process A records until the first server responds If no server associated with the A records responds the SPA logs an error to the syslog server Retail Provisioning The SPA firmware includes an administration web server that displays SPA internal configuration and accepts new configuration parameter values The server also accepts a special URL command syntax for performing remote profile resync and firmware upgrade operations In a retail distribution model a customer purchases a Linksys voice endpoint device and subsequently subscribes to a particular service The customer first signs on to the service and establishes a VoIP account possibly through an online portal Subsequently the customer binds the particular device to the assigned service account To do so the unprovisioned SPA is instructed to resync with a specific provisioning server through a resync URL command The URL command typically includes an account PIN number or alphanumeric code to
86. laces Time lt n gt Time duration in seconds with up to n decimal places Extra decimal places specified are ignored PwrLevel Power level expressed in dBm with 1 decimal place such as 13 5 or 1 5 dBm Bool Boolean value of either yes or no a b c A choice among a b c IP IP Address in the form of x x x x where x between 0 and 255 For example 10 1 2 100 Port TCP UDP Port number 0 65535 It can be specified in decimal of hex format UserID User ID as appeared in a URL up to 63 characters FQDN Fully Qualified Domain Name such as sip Linksys com 5060 or 109 12 14 12 12345 It can contain up to 63 characters Phone A phone number string such as 14081234567 69 72 345678 or a generic URL such as 1234 10 10 10 100 5068 or jsmith Linksys com It can contain up to 39 characters ActCode Activation code for a supplementary service such as 69 It can contain up to 7 characters PhTmplt A phone number template Each template may contain one or more patterns separated by a White space at the beginning of each pattern is ignored and represent wildcard characters To represent literally use xx For example 2a represents It can contain up to 39 characters Examples 1408 1510 1408123 555 1 RscTmplt A template of SIP Response Status Code such as 404 5 61 407 408 487 481 It can contain up t
87. le 1 2 Cipher Suites Supported for Connecting to an HTTPS Server Numeric Code Cipher Suite 0x0039 TLS_DHE_RSA_WITH_AES_256_CBC_SHA 0x0035 TLS_RSA_WITH_AES_256_CBC_SHA 0x0033 TLS_DHE_RSA_WITH_AES_ 128 CBC _SHA Ox002f TLS_RSA_WITH_AES_ 128 CBC SHA 0x0005 TLS_RSA_WITH_RC4_128_SHA 0x0004 TLS_RSA_WITH_RC4_128 MD5 0x0062 TLS_RSA_EXPORT1024_ WITH_RC4 56_SHA 0x0060 TLS_RSA_EXPORT1024 WITH_RC4_56_MD5 0x0003 TLS_RSA_EXPORT_WITH_RC4_ 40 MD5 Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter1 Provisioning Linksys VoIP Devices Where to Go From Here Syslog Server If a syslog server is configured on the SPA using the lt Syslog_Server gt or lt Debug_Server gt parameters the resync and upgrade operations log messages to the syslog server A message can be generated at the start of a remote file request configuration profile or firmware load and at the conclusion of the operation with either success or failure The logged messages themselves are configured in the following parameters For profile resync Log Resync_Request_Msg Log _Resync_Success_Msg Log _Resync_Failure_Msg For firmware upgrades Log Upgrade_Request_Msg Log Upgrade_Success_Msg Log _Upgrade_Failure_Msg These parameters are macro expanded into the actual syslog messages W here to Go From Here The following table summarizes the location of specific information in this doc
88. le Compiler A generic non targeted CFG file is accepted as valid by any SPA that resyncs to it The following command generates a basic CFG file spc spa2102 txt spa2102 cfg This example compiles the plain text spa2102 txt file into the binary spa2102 cfg file understood by the SPA2102 The scramble option performs encryption that does not require the explicit transmission of a key to the target SPA It requires one randomizing argument For example spc scramble SomeSecretPhrase spa2102 txt spa2102 cfg The resulting encrypted spa2102 cfg is accepted as valid by any SPA that resyncs to it The target option also encrypts the CFG file without the need to explicitly transmit a key but does so in such a way that only the target SPA can decode it Targeted CFG files provide a basic level of security This command uses the MAC address of the target SPA as an argument For example spc target 000e08aabbcc spa2102 txt spa2102 cfg This command uses the MAC address 000e08aabbcc and only the SPA with that MAC address is able to decrypt and process the generated spa2102 cfg profile Any other SPA attempting to resync to this file rejects it as unreadable The third option performs an explicit key based encryption of the CFG file This option requires that the key used to encrypt the file be preprovisioned in the target SPA so that it can be decoded Two algorithms are available for this type of encryption RC4 rc4 AES aes
89. le gt element itself can in turn be encapsulated within other arbitrary elements Unrecognized element names are ignored by the SPA Any parameters not specified by a profile are left unchanged in the SPA If the XML file contains multiple occurrences of the same parameter tag the last such occurrence overrides any earlier ones To avoid inadvertently overriding configuration values for a parameter it is recommended that at most one instance of a parameter be specified in any one profile Element attributes are allowed Their value must be enclosed by double quotes All such attributes are ignored by the SPA except for the user access attribute ua The user access attribute defines access to the administration web server for a specific parameter by the User account Access by the Admin account is unaffected by this attribute The ua attribute if present must have one of the following values e na no access ro read only e rw read write If the user access attribute ua is not specified in an element tag the factory default user access is applied for the corresponding parameter An XML header of the form lt gt is allowed but is ignored by the SPA As an example the following profile would be accepted by the SPA It supplies the values of three provisioning parameters Basic XML Profile FormatBasic XML Profile Format Example 2 1 Basic XML Profile Format lt flat profile gt lt Resync_On_Reset gt Yes lt R
90. mote TFTP Server Targeled key encrypted ASGs7LPr25a1 spa2000 cfg i __ ______ tftp phoneme com SES Profile_Rule key A tftp phoneme com B spa2000 cfg GPP_A 8d34a9 c721d8d049a3b5fe287329a0b changed periodically GPP_B Gs7LPr25a1 changed periodically SPA 2000 MAC 000608000001 Fully Provisioned Linksys SPA Provisioning Guide 1 6 Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter1 Provisioning Linksys VoIP Devices SPA Provisioning Flow At a high level the provisioning process involves four provisioning states described in Table 1 1 Table 1 1 Provisioning States Flow Step Step Description MFG RESET Manufacturing reset Performing manufacturing reset on the SPA returns the device to a fully unprovisioned state All configurable parameters regain their manufacturing default values Manufacturing reset can be performed from any state through the IVR sequence KEE RESET HIF Allowing the end user to perform manufacturing reset guarantees that the device can always be returned to an accessible state SP CUST Service provider customization The provisioning parameters are customized for a particular service provider network The Profile_Rule parameter must be configured in this step to point to a device specific configuration profile using a service provider specific provisioning server This can be accomplished in one of three ways e Auto configuration via local DHCP
91. mpiler The SPA also accepts configuration profiles in binary format The SPA configuration profile compiler is a translation tool spc exe that translates a plain text format into the required binary format Appendix C Example SPA Configuration Profile provides an example of a typical SPA2102 configuration text file Other ATAs are similar However the SPA3102 has a number of unique parameters 99 The SPC tool expects a semicolon to separate each parameter definition If a parameter is not defined in the configuration profile the current value for that parameter is retained by the SPA The SPC tool is available from Linksys upon request in binary executable format in the following versions spc exe Windows 32 bit PC environment spc linux 1386 static Linux ELF environment Versions of the SPC tool for other platforms may be available by special request The profile compiler can generate different types of configuration files using different types of encryption Generic non targeted CFG file without an explicit key Targeted target option also encrypts the CFG file without an explicit key but uses the MAC address of the target SPA and only that SPA can decode it Explicit key based encryption of the CFG file Linksys SPA Provisioning Guide Version 3 01 Chapter 2 Version 3 01 LINKSYS A Division of Cisco Systems Inc Creating Provisioning Scripts SPA Configuration Profi
92. n place of the two character string Conditional expressions typically involve macro expanded variables For example SREGTMR1 gt 300 and SPRVTMR gt 1200 and SEXTIP ne SSWVER ge 2 0 6 and SCCERT eq Installed It is important to enclose macro variables in double quotes where a string literal is expected Do not do so doing so where a number or version number is expected For legacy support of firmware versions prior to 2 0 6 a relational expression with no left hand side operand assumes SWVER as the implicit left hand side For example 1 0 33 is equivalent to SSWVER 1 0 33 When used in the context of the Profile_Rule and Upgrade_Rule parameters conditional expressions must be enclosed within the syntax expr as in the following upgrade rule example SSWVER ne 2 0 6 http ps tell com sw spa021024 bin On the other hand the syntax above using parentheses should not be used when configuring the Resync_Trigger_ parameters Assignment Expressions Version 3 01 Arbitrary parameters can be pre assigned values within the context of Profile_Rule and Upgrade_Rule parameter This causes the assignment to be performed before the profile if retrieved The syntax for performing these assignments is a list of individual parameter assignments enclosed within parentheses assignments with each assignment taking the form ParameterXMLName Value Note that the recognized param
93. nal information about features and functionality of Linksys ATAs AA Quick Guide IVR Quick Guide SPA Provisioning Guide The following documentation describes how to use other Linksys Voice System products SPA9000 Administrator Guide LVS CTI Integration Guide LVS Integration with ITSP Hosted Voicemail Guide SPA900 Series IP Phones Administrator Guide SPA 2 0 ATA Administrator Guide Linksys Voice over IP Product Guide SIP CPE for Massive Scale Deployment Technical Support Technical support contact information for authorized Linksys Voice System partners is as follows LVS Phone Support requires an authorized partner PIN 888 333 0244 Hours 4am 6pm PST 7 days a week E mail support voipsupport linksys com Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Preface Technical Support Linksys SPA Provisioning Guide Bey Version 3 01 LINKSYS A Division of Cisco Systems Inc S Note Provisioning Linksys VolP Devices This chapter describes the features and functionality available when provisioning Linksys VoIP devices and explains the setup required It includes the following sections Residential Deployment Provisioning Requirements page 1 1 Provisioning Overview page 1 2 Configuration Access Control page 1 5 Using HTTPS page 1 8 Provisioning Setup page 1 11 Where to Go From Here page 1 15
94. ncy Shift Keying FXS Foreign eXchange Station Linksys SPA Provisioning Guide Version 3 01 A 1 LINKSYS A Division of Cisco Systems Inc Linksys SPA Provisioning Guide Appendix A Acronyms GW Gateway ITU International Telecommunication Union HTML Hypertext Markup Language HTTP Hypertext Transfer Protocol HTTPS HTTP over SSL ICMP Internet Control Message Protocol IGMP Internet Group Management Protocol ILEC Incumbent Local Exchange Carrier IP Internet Protocol ISP Internet Service Provider ITSP IP Telephony Service Provider IVR Interactive Voice Response LAN Local Area Network LBR Low Bit Rate LBRC Low Bit Rate Codec MC Mini Certificate MGCP Media Gateway Control Protocol MOH Music On Hold MOS Mean Opinion Score 1 5 the higher the better ms Millisecond MSA Music Source Adaptor MWI Message Waiting Indication OSI Open Switching Interval PCB Printed Circuit Board PR Polarity Reversal PS Provisioning Server PSQM Perceptual Speech Quality Measurement 1 5 the lower the better PSTN Public Switched Telephone Network NAT Network Address Translation OOB Out of band REQT SIP Request Message RESP SIP Response Message RSC SIP Response Status Code such as 404 302 600 RTP Real Time Protocol RTT Round Trip Time SAS Streaming Audio Server SDP Session Description Protocol Version 3 01 Appendix A Ac
95. ndicated translations assigning J Smith to Display_Name_1_ 14085551234 to User_ID_1_ and 732091751563sfd to Password_1_ The alias option matches only the left hand side of an alias as much as specified by the configured alias map The element itself can be nested further In the example above GPP_M could have contained the following instead SIP Credentials name flat profile Display_Name_1_ SIP Credentials number flat profile User_ID_1_ auth secret flat profile Password_1_ In general it is best to specify enough enclosing elements to ensure an unambiguous translation The alias option is designed to recognize a limited number of critical parameters Up to 30 parameters can be remapped this way Combining Options Multiple URL options can be combined by enclosing them within the same set of square brackets The following are examples of valid URL option strings post j alias k key SymmetricSecret alias a key SSB post g alias a key abracadabra321 post c Using Provisioning Parameters This section describes the provisioning parameters broadly organized according to function It includes the following topics General Purpose Parameters page 2 15 Enables page 2 15 Triggers page 2 16 Configurable Schedules page 2 16 Profile Rules page 2 17 Report Rule page 2 18 Upgrade Rule page 2 19 Linksys SPA Provisioning Guide 2 14 Version 3 01
96. ning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Contents Linksys SPA Provisioning Guide a Version 3 01 LINKSYS A Division of Cisco Systems Inc Preface This guide describes the provisioning of Linksys Voice over IP VoIP products It contains the following sections Document Audience page vii Linksys VoIP Products page vii How This Document is Organized page vill Document Conventions page 1x Related Documentation page ix Technical Support page ix Document Audience This document is written for service providers who offer services using Linksys VoIP products and specifically for administrative staff responsible for remote provisioning and preprovisioning Linksys devices Linksys VoIP Products The following summarizes the Linksys VoIP products that can be remotely provisioned or preprovisioned using the information provided in this document SPA9000 IP PBX with Auto Attendant can be used with the SPA400 which provides a SIP PSTN gateway Linksys Analog Telephone Adapters ATAs PAP2T Voice adapter with two FXS ports SPA1001 Small VoIP adapter SPA2102 Voice adapter with router SPA3102 Voice adapter with router and PSTN connectivity e SPA8000 Voice adapter supporting up to eight FXS connections AG310 ADSL2 gateway with VoIP and PSTN connectivity Linksys SPA Provisioning Guide Version 3 01 vii LINKSYS
97. o 39 characters CadScript A mini script that specifies the cadence parameters of a signal Up to 127 characters Syntax S S where S D on off on off on off on off L on off on off 5 and is known as a section on j and off are the on off duration in seconds of a segment and i 1 or 2 and j 1 to 6 D is the total duration of the section in seconds All durations can have up to three decimal places to provide ms resolution The wildcard character stands for infinite duration The segments within a section are played in order and repeated until the total duration is played Example 1 60 2 4 Number of Cadence Sections 1 Cadence Section 1 Section Length 60 s Number of Segments 1 Segment 1 On 2s Off 4s Total Ring Length 60s Example 2 Distinctive ring short short short long 60 2 2 2 2 2 2 1 4 Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter2 Creating Provisioning Scripts Data Types Number of Cadence Sections 1 Cadence Section 1 Section Length 60s Number of Segments 4 Segment 1 On 0 2s Off 0 2s Segment 2 On 0 2s Off 0 2s Segment 3 On 0 2s Off 0 2s 4 Segment On 1 0s Off 4 0s Total Ring Length 60s FreqScript A mini script that specifics the frequency and level parameters of a tone Up to 127 characters Syntax F L F F L3 F L LF L F L
98. of Proprietary Information and Copyright Notice This document contains proprietary information that is to be used only by Linksys customers Any unauthorized disclosure copying distribution or use of this information is prohibited LINKSYS A Division of Cisco Systems Inc Preface vii Document Audience vii Linksys VoIP Products vii How This Document is Organized viii Document Conventions viii Related Documentation ix Technical Support ix cuapter 1 Provisioning Linksys VoIP Devices 1 1 Residential Deployment Provisioning Requirements 1 1 Remote Endpoint Control 1 2 Communication Encryption 1 2 Provisioning Overview 1 2 Initial Provisioning 1 3 Deploying RC Units 1 3 Redundant Provisioning Servers 1 4 Retail Provisioning 1 4 Automatic In House Preprovisioning 1 5 Configuration Access Control 1 5 SPA Configuration Profiles 1 5 SPA Provisioning Flow 1 6 Using HTTPS 1 8 How HTTPS Works 1 8 Server Certificates 1 9 Client Certificates 1 9 Linksys Certificate Chain Structure 1 9 Provisioning Setup 1 10 License Keys 1 11 Software Tools 1 11 Server Configuration 1 11 TFTP 1 12 HTTP 1 12 Linksys SPA Provisioning Guide Version 3 01 OH LINKSYS A Division of Cisco Systems Inc Contents Enabling HTTPS 1 13 Syslog Server 1 15 Where to Go From Here 1 15 CHAPTER 2 Creating Provisioning Scripts 2 1 SPA Configuration File 2 1 Open Format Configuration File 2 2 Configuration File Compression 2 5 File Enc
99. offer improved filtering and logging features compared to TFTP servers which helps to regulate and track connections On the SPA client side using HTTP with the GET method simply means changing TFTP to HTTP in the URL defined in the Profile_Rule parameter On the server side the service provider must install and configure the HTTP server The SPA does not require any special configuration setting on the server to be able to resync using HTTP If a standard web browser can retrieve a profile from a particular server using HTTP the SPA should be able to do so as well Exercise Install an HTTP server on the local PC or other accessible host The open source Apache server can be downloaded from the Internet Copy the basic txt configuration profile from the earlier exercises onto the virtual root directory of the installed server Verify proper server installation and file access of basic txt by accessing the profile using a standard web browser Modify the Profile_Rule of the test SPA to point to the HTTP server in place of the TFTP server so as to download its profile periodically For example assuming the HTTP server is at 192 168 1 300 enter the following value Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter3 Provisioning Tutorial Secure Resync http 192 168 1 200 basic txt Step5 Observe the syslog messages sent by the SPA The periodic resyncs should now be
100. ompressed file cat profile xml gzip gt profile xml gz The SPA inspects the downloaded file header to determine the format of the file The choice of file name is not significant and any convention that is convenient for the service provider can be used File Encryption An XML configuration profile can be encrypted using symmetric key encryption whether or not it is already compressed The supported encryption algorithm is the American Encryption Standard AES using 256 bit keys applied in cipher block chaining mode Note Compression must precede encryption for the SPA to recognize a compressed and encrypted XML profile First generate the XML then compress with gzip and finally encrypt The OpenSSL encryption tool available for download from various Internet sites can be used to perform the encryption Note that support for 256 bit AES encryption may require recompilation of the tool so as to enable the AES code The SPA firmware has been tested against version openssl1 0 9 7c If encrypted the profile expects the file to have the same format as generated by the following command l Linksys SPA Provisioning Guide jm Version 3 01 2 5 LINKSYS A Division of Cisco Systems Inc Chapter2 Creating Provisioning Scripts SPA Configuration Profile Compiler Example 2 8 Encrypting the Configuration Profile example encryption key SecretPhrasel1234 openssl enc e aes 256 cbc k SecretPhrase1234 in profile
101. onfiguration data The SPA can be configured to convey certain status and identification information to the server within the body of the HTTP POST request The server can use this information to help generate a desired response configuration file or store the status information for later analysis and tracking As part of both GET and POST requests the SPA automatically includes basic identifying information in the request header in the User Agent field The supplied information conveys manufacturer product name current firmware version and product serial number Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter1 Provisioning Linksys VoIP Devices Provisioning Setup For example the following is the User Agent request field from a SPA2102 User Agent Linksys SPA 2102 2 0 5 88012BA01234 Enabling HTTPS For increased security managing remotely deployed units the SPA supports HTTPS for provisioning To this end each newly manufactured SPA carries a unique SLL Client Certificate and associated private key in addition to a Linksys CA server root certificate The latter allow the SPA to recognize authorized provisioning servers and reject non authorized servers On the other hand the client certificate allows the provisioning server to identify the individual SPA issuing the request In order for a service provider to manage SPA deployment using HTTPS a server certificate needs
102. r_G723_Code x01723 Force_G723_Code x02723 Prefer_G726r16_Code x0172616 Force_G726r16_Code x0272616 Prefer_G726r24_Code x0172624 Force_G726r24_Code x0272624 Prefer_G726r32_Code x0172632 Force_G726r32_Code x0272632 Prefer_G726r40_Code x0172640 Force_G726r40_Code x0272640 Prefer_G729a_Code x01729 Force_G729a_Code x02729 Miscellaneous Set_Local_Date_ mm dd a Set_Local_Time_ HH mm mG Time_Zone GMT 07 00 options GMT 12 00 GMT 11 00 GMT 10 00 GMT 09 00 GMT 08 00 GMT 07 00 GMT 06 00 GMT 05 00 GMT 04 00 GMT 03 30 GMT 03 00 GMT 02 00 GMT 01 00 GMT GMT 01 00 GMT 02 00 GMT 03 00 GMT 03 30 GMT 04 gt 00 GMT 05 00 GMT 05 30 GMT 05 45 GMT 06 00 GMT 06 30 GMT 07 00 GMT 08 00 GMT 09 00 GMT 09 gt 30 GMT 10 00 GMT 11 00 GMT 12 00 GMT 13 00 FXS_Port_Impedance 600 2 options 600 900 600 2 16uF 900 2 16uF 270 750 150nF 220 820 120nF 220 820 115nF 370 620 310nF FXS_Port_Input_Gain vag 3 FXS_Port_Output_Gain 23 3 DTMF_Playback_Level 16 DTMF_Playback_Length Bed 34 Detect_ABCD Yes Playback_ABCD Yes Caller _ID Method Bellcore N Amer China options Bellcore N Amer China DTMF Finland Sweden DTMF Denmark ETSI DTMF ETSI DTMF With PR ETSI DTMF After Ring ETSI FSK ETSI FSK With PR UK FXS_Port_Power_Limit 3 options 1 2 3 4 5 6 7 8 Protect_IVR_FactoryReset No Linksys SPA Provisioning Guide C 12 Version 3 01 LINKSYS A Div
103. ronyms Version 3 01 LINKSYS A Division of Cisco Systems Inc SDRAM Synchronous DRAM sec seconds SIP Session Initiation Protocol SLA Shared line appearance SLIC Subscriber Line Interface Circuit SP Service Provider SPA Linksys Phone Adaptor SSL Secure Socket Layer TFTP Trivial File Transfer Protocol TCP Transmission Control Protocol UA User Agent uC Micro controller UDP User Datagram Protocol URL Uniform Resource Locator VM Voicemail VMWI Visual Message Waiting Indication Indicator VQ Voice Quality WAN Wide Area Network XML Extensible Markup Language Linksys SPA Provisioning Guide LINKSYS A Division of Cisco Systems Inc Appendix A Acronyms El Linksys SPA Provisioning Guide AA Version 3 01 LINKSYS A Division of Cisco Systems Inc Glossary ACD Automatic Call Distribution A switching system designed to allocate incoming calls to certain positions or agents in the order received and to hold calls not ready to be handled often with a recorded announcement Area code A 3 digit code used in North America to identify a specific geographic telephone location The first digit can be any number between 2 and 9 The second and third digits can be any number Billing increment The division by which the call is rounded In the field it is common to see full minute billing on the local invoice while 6 second rounding is the
104. ror timer that activates after a failed firmware upgrade attempt The timer is initialized with the value in this parameter The next firmware upgrade attempt occurs when this timer counts down to zero The default is 3600 seconds Downgrade_Rev_Limit Enforces a lower limit on the acceptable version number during a firmware upgrade or downgrade The device does not complete a firmware upgrade operation unless the firmware version is greater than or equal to this parameter The default is empty Upgrade_Rule This parameter is a firmware upgrade script with the same syntax as Profile_Rule Defines upgrade conditions and associated firmware URLs The default is empty Log _Upgrade_Request_Msg Syslog message issued at the start of a firmware upgrade attempt The default is SPN MAC Requesting upgrade SCHEME SERVIP PORT PATH Log _Upgrade_Success_Msg Syslog message issued after a firmware upgrade attempt completes successfully The default is PN MAC Successful upgrade SCHEME SERVIP PORTS PATH ERR Log_Upgrade_Failure_Msg Syslog message issued after a failed firmware upgrade attempt The default is PN MAC Upgrade failed SERR License Keys This field is empty Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter4 Provisioning Field Reference General Purpose Parameters General Purpose Parameters The following
105. rsion 3 01 LINKSYS A Division of Cisco Systems Inc Chapter4 Provisioning Field Reference Configuration Profile Parameters Table 4 1 Configuration Profile Parameters continued Parameter Name Description and Default Value Forced_Resync_Delay Maximum delay in seconds the SPA waits before performing a resync The device does not resync while one of its phone lines is active Because a resync can take several seconds it is desirable to wait until the device has been idle for an extended period before resyncing This allows a user to make calls in succession without interruption The device has a timer that begins counting down when all of its lines become idle This parameter is the initial value of the counter Resync events are delayed until this counter decrements to zero The default is 14 400 seconds Resync_From_SIP Enables a resync to be triggered via a SIP NOTIFY message The default is Yes Resync_After_Upgrade_Attempt Triggers a resync after every firmware upgrade attempt The default is Yes Resync_Trigger_1 Configurable resync trigger conditions A resync is triggered when the logic equation in these Resync_Trigger_2 parameters evaluates to TRUE The default is empty Resync_Fails_On_FNF Determines whether a file not found response from the provisioning server constitutes a successful or a failed resync A failed resync activates the error resync timer The default is Yes
106. rtificate authority root certificate capable of authenticating the device client certificate is given to each service provider This authentication path allows the provisioning server to reject unauthorized requests for configuration profiles Linksys Certificate Chain Structure Version 3 01 The combination of server certificates and client certificates ensures the secure communication between a remote SPA and its provisioning server Figure 1 2 illustrates the relationship and placement of certificates public private key pairs and signing root authorities among the Linksys client the provisioning server and the Linksys certification authority The upper half of the diagram shows the Linksys Provisioning Server Root Authority used to sign individual provisioning server certificates The corresponding root certificate is compiled into all firmware releases at or above 2 0 6 allowing the SPA endpoints to authenticate authorized provisioning servers Linksys SPA Provisioning Guide LINKSYS A Division of Cisco Systems Inc Using HTTPS Chapter1 Provisioning Linksys VoIP Devices Figure 1 2 SPA Configuration and Provisioning Certificate Chain SPA Configuration Provisioning Certificate Chain Sipura Technology Inc Provisioning Server Root Authority 1 Compiled into SPA Firmware SPA y Root CA Certificate List SPA Firmware Load SPA PKEY CERT Signs SPA
107. ryption 2 5 SPA Configuration Profile Compiler 2 6 Proprietary Plain Text Configuration File 2 8 Source Text Syntax 2 8 Comments 2 9 Macro Expansion 2 9 Conditional Expressions 2 10 Assignment Expressions 2 11 URL Syntax 2 12 Optional Resync Arguments 2 12 key 2 13 post 2 13 alias 2 13 Combining Options 2 14 Using Provisioning Parameters 2 15 General Purpose Parameters 2 15 Enables 2 15 Triggers 2 16 Configurable Schedules 2 16 Profile Rules 2 17 Report Rule 2 19 Upgrade Rule 2 19 Data Types 2 20 CHAPTER 3 Provisioning Tutorial 3 1 Preparation 3 1 Basic Resync 3 2 TFTP Resync 3 2 Syslog 3 3 Automatic Resync 3 4 Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Contents Unique Profiles and Macro Expansion 3 5 URL Resolution 3 5 HTTP GET Resync 3 6 Secure Resync 3 7 Basic HTTPS Resync 3 7 HTTPS With Client Certificate Authentication 3 9 HTTPS Client Filtering and Dynamic Content 3 9 Profile Formats 3 10 Profile Compression 3 10 Profile Encryption 3 11 Partitioned Profiles 3 12 Parameter Name Aliases 3 12 Proprietary Profile Format 3 13 cuapter 4 Provisioning Field Reference 41 Configuration Profile Parameters 4 1 Firmware Upgrade Parameters 4 4 General Purpose Parameters 4 6 M acro Expansion Variables 4 7 Internal Error Codes 4 9 APPENDIX Acronyms APPENDIX B Glossary APPENDIX C Example SPA Configuration Profile INDEX Linksys SPA Provisio
108. ryption key is made known to the SPA with the following URL option key MyOwnSecret tftp 192 168 1 200 basic cfg Step5 Click Submit All Changes Step6 Observe the syslog trace from the SPA Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter3 Provisioning Tutorial Profile Formats On resync the new file is downloaded by the SPA and used to update its parameters Partitioned Profiles Step 1 Step 2 Step 3 Step 4 Step 5 The SPA download multiple separate profiles during each resync This allows managing different kinds of profile information on separate servers and maintaining common configuration parameter values separate from account specific values Exercise Create anew XML profile basic2 txt that specifies a value for a distinct parameter from the earlier exercises For instance the file can contain the following lt flat profile gt lt GPP_ B gt ABCD lt GPP_B gt lt flat profile gt Store the basic2 txt profile in the TFTP server virtual root directory Leave the first profile rule as in any the earlier exercises but configure the second profile rule Profile_Rule_B to point to the new file tftp 192 168 1 200 basic2 txt Click Submit All Changes The SPA now resyncs to both the first and second profiles in that order whenever a resync operation 1s due Observe the SPA syslog trace to confirm the expected behavior
109. s SA through SD when used as arguments of the key option as in the following examples key SC key SSD In the case of XML style profiles the argument to key must be the same as the argument to the k option given to openssl In the case of SPC compiled profiles the argument to key must be the same as the argument to either the ascii key or the hex key options as given to SPC The post option provides an alternative access method for the http and https schemes If left unspecified the SPA performs an HTTP GET operation when contacting the provisioning server If specified on the other hand the SPA performs an HTTP POST operation The body of the POST is generated from the contents of one of the general purpose parameters GPP_A through GPP_P with macro expansion applied The GPP_ parameter to use is indicated by a single lowercase letter a through p given as argument to the term post Using POST provides a convenient alternative to the GET method when arbitrary state or identifying information needs to be supplied from the SPA to the server as part of periodic resyncs For example GPP_F could contain the following POST body template Product SPN MAC Addr SMA Ser_Num SSN SW_Ver SSWVER Then a URL option such as the following would use the POST method to convey the information to the server in the body of the profile request message shown here with an accompanying UR
110. s a valid macro name while MAU is recognized as a valid macro name so the expression spaSSTRANGESMAU cfg macro expands into the string spaSSTRANGEO00E08012345 cfg Macro expansion is not applied recursively For example MAU expands into MAU the is expanded and not OOEO8ABCDEP for a SPA with the indicated MAC address The special purpose parameters GPP_SA through GPP_SD whose contents are mapped to the macro expressions SA through SD are only macro expanded as the argument of the key option in a resync URL Also the macro expression can qualify the expansion so that only a substring of the macro variable is used instead of its full value such as a portion of the MAC address The syntax for substring macro expansion is NAME p and NAME p q where p and q are non negative integers The resulting expansion results in the macro variable substring starting at character offset p and of length q or till end of string if q is not specified For example for an SPA with MAC address 000E08012345 the expression MAU 4 macro expands into the string 08012345 while the expression MAU 8 2 macro expands into the string 23 Conditional Expressions Conditional expressions can trigger resync events and select from alternative URLs for resync and upgrade operations Conditional expressions consist of a list of comparisons separated by the and operator All comparisons must be satisfied for the condition to be
111. server A TFTP server name or IPv4 address is specified by DHCP on he local network The indicated TFTP server carries the desired Profile_Rule entry in the CFG file spa2102 cfg Enter aresync URL An end user opens a browser onto the SPA web server explicitly requesting a resync to a specific TFTP server using this URL syntax http x x x x admin resync prvserv spa2102 cfg where x x x x 1S the IP address of the specific SPA and prvserv is the target TFTP server followed by a profile path Edit Profile_Rule parameter Open the provisioning pane on the SPA web interface and enter the TFTP URL in the Profile_Rule parameter for example prserv spa2102 cfg The spa2102 cfg file modifies the Profile_Rule to contact a specific TFTP server and request a MAC address specific CFG file For example the following entry contacts a specific provisioning server requesting a new profile unique to this unit Profile_Rule tftp callme com profile MA spa2102 cfg Linksys SPA Provisioning Guide Eo Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter1 Provisioning Linksys VoIP Devices Using HTTPS Table 1 1 Provisioning States continued SEC PRV 1 Secure Provisioning Initial Configuration The initial device unique CFG file should be targeted to each SPA by compiling the CFG file with the spc target option This provides an initial level of encryption that does not require the exchange of keys The initial
112. sing entirely from the plain text file the User account access to the parameter remains unchanged in the SPA If the plain text file contains multiple occurrences of the same parameter value specification the last occurrence overrides any earlier ones To avoid accidentally overwriting configuration values it is recommended that no more than one specification for each parameter be included in one profile Parameter names in the plain text file must match the corresponding names appearing in the SPA web interface with the following modifications Spaces between words are replaced by underscores for example Multi_Word_Parameter Parameters with a numeric identifier use a bracketed index syntax to identify the line extension or user for example Line_Enable 1 and Line_Enable 2 Comments are delimited by a character up to the end of line Blank lines can be used for readability The following illustrates the format for each parameter value pair Parameter_name quoted_parameter_value_string Boolean parameter values are asserted by any one of the values Yes yes Enable enable 1 They are deasserted by any one of the values No no Disable disable 0 The following are examples of plain text file entries These parameter names are for illustration only Feature Enable l Enable user read write but force the value to Enable Another_Parameter 3600
113. successfully resyncs The following is another example Resync_Periodic 3600 600 Resync_Error_Retry_Delay 1800 300 3600 600 7200 900 Linksys SPA Provisioning Guide 2 16 Version 3 01 Profile Rules Chapter 2 Version 3 01 LINKSYS A Division of Cisco Systems Inc Creating Provisioning Scripts Using Provisioning Parameters In this example the SPA periodically resyncs every hour plus an additional random delay of up to 10 minutes In case of resync failure the SPA retries in 30 minutes plus up to five minutes more If it fails again it waits an additional hour plus up to 10 minutes If again unsuccessful it waits two more hours plus up to 15 minutes and so also thereafter until it successfully resyncs The following is another example Upgrade_Error_Retry_ Delay 1800 3600 7200 14400 3600 In this example if a remote upgrade attempt fails the SPA retries the upgrade in 30 minutes then again after one more hour then in two hours If it still fails it subsequently retries every four to five hours until it succeeds The SPA provides multiple remote configuration profile parameters Profile_Rule This means that each resync operation can retrieve multiple files potentially managed by different servers In the simplest scenario the SPA resyncs periodically to a single profile on a central server which updates all pertinent internal parameters Alternatively the profile can be split bet
114. t lt flat profile gt lt GPP D gt Linksys SPA Provisioning Guide pa LINKSYS A Division of Cisco Systems Inc Profile Formats Step 3 Step 4 Step 5 Step 6 Step 7 Step 8 Step 9 Chapter3 Provisioning Tutorial print OU SENV SSL CLIENT I DN _ OU n print L SENV SSL CLIENT I DN L n print S SENV SSL CLIENT I DN S n print lt GPP D gt lt flat profile gt Save this file with the file name reflect pl with executable permission chmod 755 on Linux in the CGI scripts directory of the HTTPS server Verify accessibility of CGI scripts on the server as in cgi bin Modify the Profile_Rule on the test SPA to resync to the reflector script as in the following example https prov server com cgi bin reflect pl Click Submit All Changes Observe the SPA syslog trace to ensure a successful resync Open the SPA admin advanced page Provisioning tab Verify that the GPP_D parameter contains the information captured by the script This information contains the SPA product name MAC address and serial number if the test SPA carries a unique certificate from the manufacturer or else generic strings if it is a unit manufactured before firmware release 2 0 A similar script could be used to determine information about the resyncing SPA and then provide it with appropriate configuration parameter values Profile Formats This section demonstrates the g
115. table defines the function and usage of each parameter in the General Purpose Parameters section of the Provisioning tab Table 4 3 General Purpose Parameters Parameter Name Description and Default Value GPP_SA Special purpose provisioning parameters GPP SB designed to hold encryption keys and passwords To ensure the integrity of the encryption GPP_SC mechanism these parameters must be kept GPP SD secret Therefore these parameters are not displayed on the device configuration web page and they are not included in the configuration report sent in response to a SIP NOTIFY command The default is empty General purpose provisioning parameters These parameter can be used as variables in provisioning and upgrade rules They are referenced by prepending the variable name with a character such as GPP_A The default is empty Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter4 Provisioning Field Reference Macro Expansion Variables Macro Expansion Variables The following macro variables are recognized within the following provisioning parameters Profile_Rule Profile_Rule_ e Resync_Trigger_ Log _Resync_ Upgrade_Rule Log Upgrade_ GPP_ under specific conditions Within these parameters syntax types such as NAME or NAME are recognized and expanded Macro variable substrings can be specified with the notation NAME p
116. tag is formed by replacing the space with an underscore _ such as Par_Name An empty default value field implies an empty string lt gt The SPA continues to use the last configured values for tags that are not present in a given profile Templates are compared in the order given The first not the closest match is selected The parameter name must match exactly If more than one definition for a parameter is given in a configuration file the last such definition in the file is the one that takes effect in the SPA A parameter specification with an empty parameter value forces the parameter back to its default value To specify an empty string instead use the empty string as the parameter value Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Provisioning Tutorial This chapter describes the procedures for transferring configuration profiles between the SPA and the provisioning server and includes the following sections Preparation page 3 1 Basic Resync page 3 2 Secure Resync page 3 7 Profile Formats page 3 10 For information about creating configuration profiles refer to Chapter 2 Creating Provisioning Scripts Preparation The examples presented in this chapter require the availability of one or more servers For the purposes of this tutorial these can be installed and run on a local PC To troubleshoot server confi
117. the following sections Configuration Profile Parameters page 4 1 Firmware Upgrade Parameters page 4 5 General Purpose Parameters page 4 6 Macro Expansion Variables page 4 7 Internal Error Codes page 4 9 The Provisioning parameters described in this chapter are recognized by the SPA beginning with firmware release 2 0 6 For a complete list of all the parameters available through the administration web server and which can be used in configuration profiles refer to the administration guide for each product Configuration Profile Parameters The following table defines the function and usage of each parameter in the Configuration Profile Parameters section under the Provisioning tab Table 4 1 Configuration Profile Parameters Parameter Name Description and Default Value Provision_Enable Controls all resync actions independently of firmware upgrade actions Set to yes to enable remote provisioning The default is Yes Resync_On_Reset Triggers a resync after every reboot except for reboots caused by parameter updates and firmware upgrades The default is Yes Linksys SPA Provisioning Guide Version 3 01 Al LINKSYS A Division of Cisco Systems Inc Configuration Profile Parameters Chapter4 Provisioning Field Reference Table 4 1 Configuration Profile Parameters continued Parameter Name Description and Default Value Resync_Random_Delay The maximum value for a ran
118. to a specific file on a TFTP server whose IP address is offered as one of the DHCP provided parameters This lets a service provider connect each new SPA to a LAN environment configured to preprovision SPAs Any new SPA connected to this LAN automatically resyncs to the local TFTP server initializing its internal state in preparation for deployment Among other parameters this preprovisioning step configures the URL of the SPA provisioning server Subsequently when a new customer signs up for service the preprovisioned SPA can be simply bar code scanned to record its MAC address or serial number before being shipped to the customer Upon receiving the unit the customer connects the unit to the broadband link possibly through a router On power up the SPA already knows the server to contact for its periodic resync update Configuration Access Control Besides configuration parameters that control resync and upgrade behavior the SPA provides mechanisms for restricting end user access to various parameters The SPA firmware provides specific privileges for login to a User account and an Admin account The Admin account is designed to give the service provider configuration access to the SPA while the User account is designed to give limited and configurable control to the end user of the device The User account provides access to basic interactive voice response IVR functions and to a subset of the administration web server parameters The
119. tricts the packets that are allowed to enter the protected network from the Internet Communication Encryption The configuration parameters communicated to the endpoint may contain authorization codes or other information should not be revealed to the customer This may be required to protect the service provider from unauthorized activity by the customer It is also necessary to protect the customer from unauthorized use of the account by other customers For this reason the service provider may wish to encrypt the configuration profile communication between the provisioning server and the endpoint in addition to restricting access to the ATA administration web server Provisioning Overview Linksys VoIP products support secure remote provisioning and firmware upgrades Configuration profiles can be generated using common open source tools facilitating integration into service provider provisioning systems Supported transport protocols include TFTP HTTP and HTTPS with client certificates Linksys provisioning solutions are designed for high volume residential deployment where each SPA typically resides in a separate LAN environment connected to the Internet with a NAT device Note This Provisioning Guide is intended to supplement the product administration guides which provide definitions and usage guidelines for each parameter available for a specific device The SPA can be configured to resync its internal configuration stat
120. true Each comparison can relate one of three types of literals integer values software or hardware version numbers and doubled quoted strings Note that version numbers take the form of three non negative integers separated by periods major minor and build numbers plus an optional alphanumeric string in parentheses No intervening spaces are allowed The following are examples of valid version numbers Linksys SPA Provisioning Guide 2 10 Version 3 01 Chapter 2 LINKSYS A Division of Cisco Systems Inc Creating Provisioning Scripts Proprietary Plain Text Configuration File 2 0 6 Quoted strings can be compared for equality or inequality Integers and version numbers can also be compared arithmetically The comparison operators can be expressed as symbols or as acronyms as indicated in the table below Acronyms are particularly convenient when expressing the condition in an XML style profile Table 2 2 Comparison Operators for Conditional Expressions Alternate Applicable to Integer Applicable to Quoted Operator Syntax Description and Version Operands String Operands eq equal to Yes Yes ne not equal to Yes Yes lt lt less than Yes No lt le less than or Yes No equal to gt gt greater than Yes No gt ge greater than or Yes No equal to For legacy support to firmware versions prior to 2 0 6 the not equal to operator can also be expressed as a single character i
121. uire 1 ee Auth_Resync Reboot 1 Yes 3 SIP_Remote Party ID 1 No Proxy and Registration Proxy 1 mn Use_Outbound_Proxy 1 No Outbound_Proxy 1 ww Use_OB_ Proxy _In_Dialog 1 Yes Register 1 Yes 4 Make Call Without_Reg 1 No Register_Expires 1 3600 Ans Call Without_Reg 1 No 4 Use_DNS_SRV 1 No DNS_SRV_Auto_Prefix 1 No Proxy _Fallback_Intvl 1 3600 Subscriber Information Display_Name 1 wn User_ID 1 wn Password 1 nm Use_Auth_ID 1 No Auth_ID 1 i Mini_Certificate 1 wn SRTP_Private_Key 1 nu Supplementary Service Subscription Call Waiting _Serv 1 Yes 3 Block _CID_ Serv 1 Yes Block_ANC_Serv 1 Yes 7 Dist_Ring_Serv 1 Yes Linksys SPA Provisioning Guide C4 Version 3 01 LINKSYS A Division of Cisco Systems Inc AppendixC Example SPA Configuration Profile H Cfwd_All_Serv 1 Yes Cfwd_Busy_Serv 1 Veer j Cfwd_No_Ans_Serv 1 Yes Cfwd_Sel_Serv 1 Yes 7 Cfwd_Last_Serv 1 Yes Block _Last_Serv 1 Yes Accept_Last_Serv 1 Yes DND_Serv 1 Les Gy CID Sery 1 Yes CWCID_Serv 1 Yes Call_Return_Serv 1 Yes Call_Back_Serv 1 Yes Three_Way_Call_Serv 1 Yes Three_Way_Conf_Serv 1 Yes Attn_Transfer_Serv 1 Yes Unattn_Transfer Serv 1 Yes MWI_Serv 1 YOS a VMWI_Serv 1 Yes Speed_Dial_Serv 1 Yes Secure_Call_Serv 1 yes 2 Referral Serv 1 Yes Feature_Dial_Serv 1
122. ument for completing different provisioning tasks To Do This Refer to Learn to work with Linksys provisioning scripts Chapter 2 Creating Provisioning Scripts and configuration profiles Review step by step procedures for using the Chapter 3 Provisioning Tutorial scripting language to create a configuration profile Refer to the function and usage of each parameter Chapter 4 Provisioning Field Reference on the Provisioning tab of the administration web server Look up the expansion for an acronyms use inthis Appendix A Acronyms document Define a term used in this document Appendix B Glossary Linksys SPA Provisioning Guide a oe Version 3 01 one LINKSYS A Division of Cisco Systems Inc Chapter1 Provisioning Linksys VoIP Devices Where to Go From Here Linksys SPA Provisioning Guide 1 16 Version 3 01 LINKSYS A Division of Cisco Systems Inc Creating Provisioning Scripts This chapter describes the Linksys provisioning script and includes the following sections SPA Configuration File page 2 1 Open Format Configuration File page 2 2 SPA Configuration Profile Compiler page 2 6 Proprietary Plain Text Configuration File page 2 8 Using Provisioning Parameters page 2 14 Data Types page 2 19 SPA Configuration File The SPA configuration profile defines the parameter values for a specific SPA device The profile
123. user read only Hidden Parameter abc123 user not accessible Linksys SPA Provisioning Guide Version 3 01 LINKSYS A Division of Cisco Systems Inc Chapter2 Creating Provisioning Scripts E Proprietary Plain Text Configuration File Some_Entry user read write leaves value unchanged Multiple plain text files can be spliced together to generate the source for the final binary CFG file This is accomplished using the import directive at the start of a new line followed by one or more spaces and the file name to splice into the stream of parameter value pairs File splicing can be nested several files deep For example the file base txt contains the following Paraml base value 1 Param2 base value 2 The file spa1234 txt contains the following lines import base txt Paraml new value overrides base Param7 particular value 7 When compiled spal234 txt becomes Paraml base value 1 Param2 base value 2 Paraml new value overrides base Param7 particular value 7 Comments During development and scripting it is often convenient to temporarily disable a provisioning parameter by entering a character at the start of the parameter value This effectively comments out the remaining text in that parameter For example a Profile_Rule with the value http 192 168 1 200 sample cfg is equivalent to an empty Profile_Rule The character comment mechanism appli
124. ustomer Premise Equipment The only part of the telecommunications system that the customer comes into direct contact with Example of such pieces of equipment are telephones key systems PBXs voice mail systems and call accounting systems as well as wiring telephone jacks The standard for this equipment is set by the FCC and the equipment is supplied by an interconnect company Dedicated access Customers have direct access to the long distance provider via a special circuit T1 or private lines The circuit is hardwired from the customer site to the POP and does not pass through the LEC switch The dial tone is provided from the long distance carrier Linksys SPA Provisioning Guide Version 3 01 Bl LINKSYS A Division of Cisco Systems Inc a Appendix B Glossary Dedicated Access Line DAL Provided by the local exchange carrier An access line from the customer telephone equipment directly to the long distance company switch or POP Demarcation point This is where the LEC ownership and responsibility wiring equipment ends and the customer responsibilities begin Direct Inward Dialing DID Allows an incoming call to bypass the attendant and ring directly to an extension Available on most PBX systems and a feature of Centrex service Dual Tone Multifrequency DTMF Better known as the push button keypad DTMF replaces dial pulses with electronically produced tones for network signaling Enhanced service Ser
125. ver is encrypted However the transfer is not secure because any client can connect to the server and request the file given knowledge of the file name and directory location For secure resync the server must also authenticate the client as demonstrated in the next exercise Linksys SPA Provisioning Guide Version 3 01 Chapter 3 LINKSYS A Division of Cisco Systems Inc Provisioning Tutorial Secure Resync HTTPS With Client Certificate Authentication Step 1 Step 2 Step 3 Step 4 In the factory default configuration the server does not request SSL client certificates from clients After changing the configuration to enable client authentication the server requires a client certificate to authenticate the SPA before accepting a connection request Because of this the resync operation in this exercise cannot be independently tested using a browser lacking the proper credentials Nevertheless the SSL key exchange within the HTTPS connection between the test SPA and the server can be observed using the ssldump utility The utility trace shows the interaction between client and server Exercise Enable client certificate authentication on the HTTPS server In Apache v 2 set the following in the server configuration file SSLVerifyClient require Also ensure that the spacroot cert has been stored as shown in the previous exercise Restart the HTTPS server and observe the syslog trace from the SPA Each resync to
126. vices that are provided in addition to basic long distance and accessed by way of a touchtone phone through a series of menus Exchange code NX X The first three digits of a phone number Flat rate pricing The customer is charged one rate sometimes two rates one for peak and one for off peak rather than a mileage sensitive program rate IXC Interexchange Carrier A long distance provider that maintains its own switching equipment IVR Interactive Voice Response Provides a mechanism for information to be stored and retrieved using voice and a touchtone telephone Local loop The local telephone company provides the transmission facility from the customer to the telephone company office which is engineered to carry voice and or data North American Numbering Plan NANP How telephone numbers are identified in North America The telephone number can be identified based on their three separate components NPA NXX and XXXX PIN Personal Identification Code A customer calling billing code for prepaid and pay as you go calling cards Private Branch Exchange Advanced phone system commonly used by the medium to larger customer It allows the customer to perform a variety of in house routing inside calling The dial tone that is heard when the customer picks up the phone is an internal dial tone SS7 Linksys device Signaling Number 7 Technology used by large carriers to increase the reliability and speed of tr
127. wT 1 Hold Reminder _Ring 1 Call Back _Ring 1 Cfwd_Ring_Splash_Len 1 Cblk_Ring_Splash_Len 1 VMWI_Ring_Splash_Len 1 VMWI_Ring_Policy 1 Becomes Available New VM Arrives Ring _On_No_New_VM 1 kkk Line Fnable 2 SAS Enable 2 MOH Server 2 SAS DLG Refresh Intvl 2 NAT _ Mapping _Enable 2 SAS Inbound RTP Sink 2 SIP Port 2 NAT Keep Alive _Enable 2 BAT SIP Port 24 NAT _Keep_ Alive _ Msg 2 SIP_TOS DiffServ_Value 2 NAT Keep Alive Dest 2 RTP_TOS DiffServ_Value 2 SIP_Debug_Option 2 Network_Jitter_Level 2 SIP_100REL Enable 2 Blind Attn Xfer_ Enable 2 SIP_Proxy Require 2 Auth_Resync Reboot 2 SIP_Remote Party ID 2 Proxy and Registration Proxy 2 Use_Outbound_Proxy 2 Outbound_Proxy 2 Use_OB_ Proxy _In_Dialog 2 Register 2 Make Call Without_Reg 2 Register_Expires 2 Ans Call Without_Reg 2 Use_DNS_SRV 2 DNS_SRV_Auto_ Prefix 2 Proxy _Fallback_Intvl 2 Subscriber Information Display _Name 2 User_ID 2 Password 2 Use_Auth_ID 2 Auth_ID 2 Mini Certificate 2 SRTP_Private_Key 2 TER TER ng TIE Oo Oo ie New VM Available W No W W Yes W No W Wor 1 30 No n 1 5061 W No W n 1 NOTIFY 0x68 PROXY 0xb8 none high No No n 1 W Yes W No W 4 Wo 1 W No W Wor 1 Yes Yeg No 3600 No No No 3600 n n n
128. ween different files One file is common for all the SPAs in a deployment while a separate file is provided that is unique for each account Encryption keys and certificate information could be supplied by still another profile stored on a separate server Whenever a resync operation is due the SPA evaluates the four Profile_Rule parameters in sequence 1 Profile_Rule 2 Profile_Rule_B 3 Profile_Rule_C 4 Profile_Rule_D Each evaluation may result in a profile being retrieved from a remote provisioning server possibly updating some number of internal parameters If any of these evaluations fails the resync sequence is interrupted and is retried again from the beginning specified by the Resync_Error_Retry_Delay parameter seconds If all evaluations succeed the SPA waits for the second specified by the Resync_Periodic parameter and then resync once more The contents of each Profile_Rule parameter consist of a set of alternatives The alternatives are separated by the character Each alternative consists of a conditional expression an assignment expression a profile URL and any associated URL options All these components are optional within each alternative The following are the valid combinations and the order in which they must appear if present conditional expr assignment expr options URL Within each Profile_Rule parameter all of the alternatives except the last one must provide a conditional expression
129. x these locations are typically as follows Server Certificate SSLCertificateFile etc httpd conf provserver cert Server Private Key SSLCertificateKeyFile etc httpd conf pivkey pem Certificate Authority SSLCACertificateFile etc httpd conf spacroot cert Restart the server Copy the basic txt configuration profile from the earlier exercises onto the virtual root directory of the HTTPS server Verify proper server operation by downloading basic txt from the HTTPS server using a standard browser from the local PC Inspect the server certificate supplied by the server The browser probably does not recognize it as valid unless the browser has been preconfigured to accept Linksys as a root CA However SPA devices expect the certificate to be signed this way Modify the Profile_Rule of the test SPA to contain a reference to the HTTPS server in place of the HTTP server for example https my server com basic txt This example assumes the name of the HTTPS server is my server com Click Submit All Changes Observe the syslog trace sent by the SPA The syslog message should indicate that the resync obtained the profile from the HTTPS server Optional Use an Ethernet protocol analyzer on the SPA subnet to verify that the packets are encrypted In this exercise client certificate verification is not yet enabled use a browser to request the profile stored in basic txt At this point the connection between SPA and ser
130. xpired The following example condition triggers a resync if Line 1 failed to register for more than 5 minutes 300 seconds and at least 10 minutes 600 seconds have elapsed since the last resync attempt SREGTMR1 gt 300 and SPRVTMR ge 600 Configurable Schedules Profile resyncs and upgrades provide for automatic retries in case of failure in addition to periodic configuration updates Time intervals are specified via three parameters which are usually specified as a specific interval duration in seconds Starting with firmware version 3 these parameters allow the application level macro time scale retry schedule to be configured These provisioning parameters are e Resync_Periodic Resync_Error_Retry_Delay Upgrade_Error_Retry_Delay These parameters accept a single delay value seconds The new extended syntax allows for a comma separated list of consecutive delay elements Each delay element consists of a deterministic delay value optionally followed by a plus sign and an additional numeric value which bounds a random extra delay The last element in the sequence is implicitly repeated forever For example Resync_Periodic 7200 Resync_Error_Retry_Delay 1800 3600 7200 14400 In this example the SPA periodically resyncs every two hours In case of resync failure the SPA retries in 30 minutes then again in more hour then after two more hours and then after four more hours continuing at four hour intervals until it
131. ye GF Ring6_Cadence 60 2 4 2 4 2 4 Ring7_Cadence 60 4 2 4 2 4 4 Ring8_Cadence 60 0 25 9 75 Distinctive Call Waiting Tone Patterns CWT1_Cadence 30 3 9 7 CWT2_Cadence 30 1 1 1 9 7 CWT3_Cadence 30 l l 3 1 179 3 3 CWT4_Cadence POO aly slp edd yk pede 95 3 CWT5_ Cadence 30 3 1 1 1 3 9 1 CWT6_Cadence PSO g L l f pepe oy eek CWT7_Cadence BO Ce Sf alge l elyet eed 3 CWT8_Cadence 2 3 3 2 Linksys SPA Provisioning Guide C 10 Version 3 01 LINKSYS A Division of Cisco Systems Inc AppendixC Example SPA Configuration Profile E Distinctive Ring CWT Pattern Names Ringl_Name Bellcore ri Ring2_ Name Bellcore r2 Ring3_Name Bellcore r3 3 Ring4_Name Bellcore r4 Ring5_Name Bellcore r5 Ring6_Name Bellcore r6 Ring7_ Name Bellcore r7 Ring8_Name Bellcore r8 Ring and Call Waiting Tone Spec Ring Waveform Sinusoid options Sinusoid Trapezoid Ring _ Frequency 25 3 Ring Voltage 70 CWT_Frequency A2A40 10 Control Timer Values sec Hook_Flash_ Timer _Min L gt Hook_Flash_Timer_Max ot Callee_On_Hook_Delay KOM I Reorder_Delay io CS Call _Back_Expires 1800 Call_Back_Retry_Intvl 30 Call_Back_Delay AS ee VMWI_Refresh_Intvl 30 Interdigit_Long_Timer 10 Interdigit_Short_Timer no 3 CPC_Delay Maa e CPC_Duration O Vertical Service Activation Codes Call_Return_Code EOIS

Cisco SPA2102-R3 Specifications

Contents

Download Pdf Manuals

Related Search

Related Contents