Cisco SPA1112, SPA232D, SPA122 Provisioning Manual

Cisco SPA1112, SPA122, SPA232D Analog Telephone Adapters

PROVISIONING

GUIDE

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL:

www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship

between Cisco and any other company. (1110R)

Contents

Chapter 1: Deployment and Provisioning 6

Deployment 7

Provisioning Overview 9

Chapter 2: Creating XML Provisioning Scripts 15

File Structure 15

Compression and Encryption 20

Applying a Profile to the ATA 22

Using Provisioning Parameters 23

Data Types 32

Chapter 3: In-House Preprovisioning and Provisioning Servers 38

Server Preparation and Software Tools 38

In-House Device Preprovisioning 39

Provisioning Server Setup 40

Chapter 4: Provisioning Examples 46

Basic Resync 46

Secure HTTPS Resync 53

Profile Management 61

Chapter 5: Provisioning Parameters 66

Delta Configuration Report 66

Configuration Profile Parameters 69

Firmware Upgrade Parameters 75

General Purpose Parameters 76

Macro Expansion Variables 77

Internal Error Codes 80

Chapter 6: Voice Parameters 81

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 3

Contents

Chapter 7: Router Configuration Parameters 146

Nested Structure 147

<WAN_Interface> WAN Interface Parameters 149

<PHY_Port_Setting> Parameters 155

<MAC_Address_Clone> Parameters 157

<Internet_Option> Parameters 158

<DHCP_Server_Pool> Parameters 160

<WAN_VLAN_Setting> Parameters 167

<CLDP_Setting> Parameters 168

<SNMP> Parameters 170

<Time_Setup> Parameters 176

<QoS_Bandwidth_Control> Parameters 179

<Software_DMZ> Parameters 180

<Bonjour_Enable> 182

<Reset_Button_Enable> 183

<Router_Mode> 184

<VPN_Passthrough> 185

<Web_Management> 187

<TR_069> Parameters 191

<Log_Configuration> Parameters 195

<Web_Login_Admin_Name> 203

<Web_Login_Admin_Password> 203

<Web_Login_Guest_Name> 204

<Web_Login_Guest_Password> 204

Additional Information in the <router-configuration> section 205

Appendix A: Acronyms 206

Appendix B: Time Zone Settings 210

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 4

Contents

Appendix C: Where to Go From Here 212

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 5

Deployment and Provisioning

Cisco IP Telephony devicesSPA100 and SPA200 Series ATAs are intended for high-volume deployments by VoIP service providers to residential and small business customers. In business or enterprise environments, these ATAs can serve as terminal nodes. These devices are widely distributed across the Internet, connected through routers and firewalls at the customer premises.

The IP Telephony device can be used as a remote extension of the service provider back-end equipment. Remote management and configuration ensures the proper operation of the IP Telephony device at the customer premises.

This customized, ongoing configuration is supported by the following features:

• Reliable remote control of the endpoint

• Encryption of the communication controlling the endpoint

• Streamlined endpoint account binding

This chapter describes the features and functionality available when provisioning these ATAs and explains the setup required:

• Deployment, page 7

• Provisioning Overview, page 9

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters

Deployment and Provisioning

Deployment

These ATAs provide convenient mechanisms for provisioning, based on two deployment models:

• Bulk distribution—The service provider acquires these ATAs in bulk quantity

• Retail distribution—The customer purchases the ATA from a retail outlet and

Bulk Distribution

and either preprovisions them in-house or purchases RC units from Cisco. The devices are then issued to the customers as part of a VoIP service contract.

requests VoIP service from the service provider. The service provider must then support the secure remote configuration of the device.

In this model, the service provider issues these ATAs to its customers as part of a VoIP service contract. The devices are either RC units or preprovisioned in-house.

RC units are preprovisioned by Cisco to resynchronize with a Cisco server that downloads the device profile and firmware updates.

A service provider can preprovision these ATAs with the desired parameters, including the parameters that control resynchronization, through various methods: in-house by using DHCP and TFTP; remotely by using TFTP, HTTP, or HTTPS; or a combination of in-house and remote provisioning.

RC Unit Deployment

RC units eliminate in-house preprovisioning of and reduce the need for the service provider to physically handle the devices prior to shipping them to end customers. This approach also discourages the use of these ATAs with an inappropriate service provider.

A RC unit is preprovisioned by Cisco with the connection information for the provisioning servers. These servers are maintained by Cisco Systems, Inc. for the service provider that purchased the units. The MAC address of each RC unit is associated with a customizable profile on the Cisco provisioning servers. When the RC unit is connected to the broadband link, it contacts the Cisco provisioning server and downloads its customized profile.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 7

Deployment and Provisioning

Deployment

The service provider works with a Cisco sales engineer to develop a simple provisioning profile. The profile contains minimal information that redirects the device to the service provider provisioning server. This profile is placed on the Cisco RC server by the Cisco Voice Team.

RC Unit Status

The status of an RC unit can be determined by viewing the Info > Product Information page, Customization section, on the administration web server. 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 page displays Open.

Below is a sample template for an RC unit to be preprovisioned by Cisco with the connection information:

Restricted Access Domains "domain.com, domain1.com, domain2.com"; Primary_DNS * "x.y.w.z"; Secondary_DNS * "a.b.c.d"; Provision_Enable * "Yes"; Resync_Periodic * "30"; Resync_Error_Retry_Delay * "30"; Profile_Rule * "http://prov.domain.com/sipura/profile?id=$MA";

The Restricted Access Domains 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 available to the RC unit.

Retail Distribution

In a retail distribution model, a customer purchases a Cisco IP Telephony deviceATA and subscribes to a particular service. The Internet Telephony Service Provider (ITSP) sets up and maintains a provisioning server, and preprovisions the phone to resynchronize with the service provider server. See In-House Device

Preprovisioning, page 39 for more information.

The customer signs on to the service and establishes a VoIP account, possibly through an online portal, and binds the device to the assigned service account. When the device is powered up or a specified time elapses, the IP Telephony device resynchronizes, downloading the latest parameters. These parameters can address goals such as setting up a hunt group, setting speed dial numbers, and limiting the features that a user can modify.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 8

Deployment and Provisioning

Provisioning Overview

Resynchronization Process

The firmware for each ATA includes an administration web server that accepts new configuration parameter values. The ATA is instructed to resync with a specified provisioning server through a resync URL command in the device profile. The URL command typically includes an account PIN number or alphanumeric code to associate the device with the new account. For example:

http://192.168.1.102/admin/resync?https://prov.supervoip.com/cisco-init/ 1234abcd

In this example, a device at the DHCP-assigned IP address 192.168.1.102 is instructed to provision itself to the SuperVoIP service at prov.supervoip.com. The PIN number for the new account is 1234abcd. The remote provisioning server is configured to associate the ATA that is performing the resync request with the new account, based on the URL and PIN.

Through this initial resync operation, the ATA is configured in a single step, and is automatically directed to resync thereafter to a permanent URL on the server.

For both initial and permanent access, the provisioning server relies on the client certificate for authentication and supplies configuration parameter values based on the associated service account.

Provisioning Overview

An IP Telephony device can be configured to resynchronize its internal configuration state to match a remote profile periodically and on power up by contacting a normal provisioning server (NPS) or an access control server (ACS).

By default, a profile resync is only attempted when the IP Telephony device is idle, because the upgrade might trigger a software reboot interrupting a call. If intermediate upgrades are required to reach a current upgrade state from an older release, the upgrade logic is capable of automating multi-stage upgrades.

NPS

The NPS can be a TFTP, HTTP, or HTTPS server. A remote firmware upgrade is achieved by using TFTP or HTTP, but not by using HTTPS because the firmware does not contain sensitive information.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 9

Deployment and Provisioning

Provisioning Overview

Communication with the NPS does not require the use of a secure protocol because the updated profile can be encrypted by a shared secret key. Secure first-time provisioning is provided through a mechanism that uses SSL functionality. An unprovisioned ATA can receive a 256-bit symmetric key encrypted profile specifically targeted for that device.

TR-069

The digital subscriber line (DSL) Forum TR-069, CPE WAN Management Protocol (CWMP), is used for communications between a customer premise equipment (CPE) device and an auto-configuration server (ACS). The TR-069 Agent manages a collection of CPE devices, with the primary capability for auto-configuration and dynamic service provisioning, software image management, status and performance monitoring and diagnostics.

It supports multiple scenarios, including:

• Device administration: Authenticates administrators, authorizes commands,

and provides an audit trail

• Remote Access: Works with VPN and other remote network access

devices to enforce access policies

• Network admission control: Communicates with posture and audit servers

to enforce admission control policies

The TR-069 Agent CPE devices must be set up and enabled for TR-069. An ACS used to communicate with the CPE must be TR-069 compliant in order to enable the TR-069 Agent.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 10

Deployment and Provisioning

Provisioning Overview

Provisioning States

The provisioning process involves these provisioning states.

State Description

MFG-RESET Manufacturing Reset

The device returns to a fully unprovisioned state; all configurable parameters regain their default values.

Manufacturing reset can be performed through the IVR sequence ****RESET#1#.

On phones that do not support IVR, power cycle the phone to reset it to the default values.

Allowing the end user to perform a manufacturing reset guarantees that the device can always be returned to an accessible state.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 11

Deployment and Provisioning

Provisioning Overview

State Description

SP-CUST Service Provider Customization

The Profile_Rule parameter points to a device-specific configuration profile by using a provisioning server that is specific to the service provider. The methods for initiating resynchronization are:

• Auto-configuration by using a local DHCP server. A

TFTP server name or IPv4 address is specified by DHCP. The TFTP server includes the Profile_Rule parameter in the configuration file.

• Entering a resync URL. The URL starts a web

browser and requests a resync to a specific TFTP server by entering the URL syntax: http://

x.x.x.x/admin/resync?prvserv/ device.cfg, where:

x.x.x.x is the IP address of the IP Telephony

device, prvserv is the target TFTP server, and device.cfg is the name of the configuration file on the server.

• Editing the Profile_Rule parameter by opening the

provisioning pane on the web interface and entering the TFTP URL in the Profile_Rule parameter. For example, prserv/spa962.cfg.

• Modifying the configuration file Profile_Rule and to

contact a specific TFTP server and request a configuration file identified by the MAC-address. For example, this entry contacts a provisioning server, requesting a profile unique to the device with a MAC address identified by the $MA parameter:

Profile_Rule tftp.callme.com/profile/ $MA/spa962.cfg;

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 12

Deployment and Provisioning

Provisioning Overview

State Description

SEC-PRV-1 Secure Provisioning— Initial Configuration

SEC-PRV-2 Secure Provisioning—Full Configuration

An initial, device-unique CFG file is targeted to a IP Telephony device by compiling the CFG file with the SPC -

-target option. This provides an encryption that does not require the exchange of keys.

The initial, device-unique CFG file reconfigures the device profile to enable stronger encryption by programming a 256-bit encryption key and pointing to a randomlygenerated TFTP directory. For example, the CFG file might contain:

Profile_Rule [--key $A] tftp.callme.com/profile/$B/ spa962.cfg; GPP_A 8e4ca259…; # 256 bit key GPP_B Gp3sqLn…; # random CFG file path directory

Profile resync operations subsequent to the initial SECPRV-1 provisioning retrieve the 256-bit encrypted CFG files that maintain the IP Telephony device in a state synchronized to the provisioning server.

The profile parameters are reconfigured and maintained through this strongly encrypted profile. The encryption key and random directory location in the SEC-PRV-2 configuration can be changed periodically for extra security.

Configuration Access Control

The IP Telephony device firmware provides mechanisms for restricting end-user access to some parameters. The firmware provides specific privileges for login to an Admin account or a User account. Each can be independently password protected.:

• Admin Account—Allows the service provider full access to all interactive

voice response (IVR) functions and to all administration web server parameters.

• User Account—Allows the user to access basic IVR functions and to

configure a subset of the administration web server parameters.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 13

Deployment and Provisioning

Provisioning Overview

The service provider can restrict the user account in the provisioning profile in the following ways:

• Indicate which configuration parameters are available to the User account

• Disable user access to the administration web server.

• Disable the factory reset control by using the IVR.

• Restrict the Internet domains accessed by the device for resync, upgrades,

Communication Encryption

The configuration parameters communicated to the device can contain authorization codes or other information that protect the system from unauthorized access. It is in the service provider’s interest to prevent unauthorized activity by the customer, and it is in the customer’s interest to prevent the unauthorized use of the account. The service provider can encrypt the configuration profile communication between the provisioning server and the device, in addition to restricting access to the administration web server.

when creating the configuration. (Described in “Element Tags” on page 16.)

or SIP registration for Line 1.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 14

Creating XML Provisioning Scripts

The configuration profile defines the parameter values for the ATA.

Standard XML authoring tools are used to compile the parameters and values. To protect confidential information in the configuration profile, this type of file is typically delivered from the provisioning server to the ATA over a secure channel provided by HTTPS. See Compression and Encryption, page 20.

NOTE Only UTF-8 charset is supported. If you modify the profile in an editor, do not

change the encoding format; otherwise, the ATA cannot recognize the file.

File Structure

The profile is a text file with XML-like syntax in a hierarchy of elements, with element attributes and values. This format lets you use standard tools to create the configuration file. A configuration file in this format can be sent from the provisioning server to the ATA during a resync operation without compiling the file as a binary object.

You can obtain the profile for your ATA by logging on to your ATA and then entering the path to the file: http://<LAN_IP_address>/admin/config.xml For example, using the default IP address of the ATA, you would enter: http://192.168.15.1/admin/config.xml

To protect confidential information contained in the configuration profile, this file is generally delivered from the provisioning server to the ATA over a secure channel provided by HTTPS. Optionally, the file can be compressed by using the gzip deflate algorithm (RFC1951). In addition, the file can be encrypted by using 256-bit AES symmetric key encryption.

Example: Open Profile Format

<flat-profile>

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters

Creating XML Provisioning Scripts

File Structure

<Resync_On_Reset> Yes

</Resync_On_Reset>

<Resync_Periodic> 7200

</Resync_Periodic>

<Profile_Rule>

tftp://prov.telco.com:6900/cisco/config/spa504.cfg

</Profile_Rule>

</flat-profile>

The <flat-profile> element tag encloses all parameter elements to be recognized by the ATA.

Element Tags, Attributes, Parameters, and Formatting

A file can include element tags, attributes, parameters, and formatting features.

Element Tags

The properties of element tags are:

• The ATA recognizes elements with proper parameter names, when

encapsulated in the special <flat-profile> element.

• The <flat-profile> element can be encapsulated within other arbitrary

elements.

• Element names are enclosed in angle brackets.

• Most of the element names are similar to the field names in the

administration web pages for the device, with the following modifications:

- Element names may not include spaces or special characters. To derive

the element name from the administration web field name, substitute an underscore for every space or the special characters [, ], (, ), or /.

For example, the Resync On Reset field is represented by the element <Resync_On_Reset>.

- Each element name must be unique. In the administration web pages,

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 16

the same fields might appear on multiple web pages, such as the Line,

Creating XML Provisioning Scripts

File Structure

• Each opening element tag must be matched by a corresponding closing

element tag. For example:

<flat-profile>

<Resync_On_Reset> Yes

<Resync_Periodic> 7200

<Profile_Rule>tftp://prov.telco.com: 6900/cisco/config/ spa962.cfg

User, and Extension pages. Append [n] to the element name to indicate the number that is shown in the page tab.

For example, the Dial Plan for Line 1 is represented by the element <Dial_Plan[1]>

</Resync_On_Reset>

</Resync_Periodic>

</Profile_Rule>

</flat-profile>

• Element tags are case sensitive.

• Empty element tags are allowed. Enter the opening element tag without a

corresponding element tag, and insert a space and a forward slash before the less-than symbol. In this example, Profile Rule B is empty:

<Profile_Rule_B />

• Unrecognized element names are ignored.

• An empty element tag can be used to prevent the overwriting of any user-

supplied values during a resync operation. In the following example, the user speed dial settings are unchanged:

<Speed_Dial_2_2_ ua=”rw”/>

<Speed_Dial_3_2_ ua=”rw”/>

<Speed_Dial_4_2_ ua=”rw”/>

<Speed_Dial_5_2_ ua=”rw”/>

<Speed_Dial_6_2_ ua=”rw”/>

</flat-profile>

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 17

<Speed_Dial_7_2_ ua=”rw”/>

<Speed_Dial_8_2_ ua=”rw”/>

<Speed_Dial_9_2_ ua=”rw”/>

Creating XML Provisioning Scripts

File Structure

• An empty value can be used to set the corresponding parameter to an

empty string. Enter an opening and closing element without any value between them. In the following example, the GPP_A parameter is set to an empty string.

<flat-profile>

<GPP_A>

</GPP_A>

</flat-profile>

User Access

The ua attribute controls access by the User account for specific parameters. If the ua attribute is not specified in an element tag, the factory default user access is applied for the corresponding parameter is applied. Access by the Admin account is unaffected by this attribute.

The ua attribute, if present, must have one of the following values:

• na—no access

• ro—read-only

• rw—read/write

The ua attribute is illustrated by the following example:

<flat-profile>

<SIP_TOS_DiffServ_Value_1_ ua=”na”/> <Dial_Plan_1_ ua=”ro”/> <Dial_Plan_2_ ua=”rw”/>

</flat-profile>

The value of the ua option must be enclosed by double quotes.

Parameter Properties

These properties apply to the parameters:

• Any parameters that are not specified by a profile are left unchanged in the

ATA .

• Unrecognized parameters are ignored.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 18

Creating XML Provisioning Scripts

File Structure

• The ATA recognizes arbitrary, configurable aliases for a limited number of

parameter names.

• If the Open format profile 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.

Formatting

These properties apply to the formatting of the strings:

• Comments are allowed by using standard XML syntax.

• Leading and trailing white space is allowed for readability and will be

removed from the parameter value.

• New lines within a value are converted to spaces.

• An XML header of the form <? . . . ?> is allowed, but is ignored by the ATA.

• To enter special characters, use basic XML character escapes, as shown in

the following table.

Special Character XML Escape Sequence

& (ampersand) &

< (less than) <

> (greater than) >

’ (apostrophe) '

” (double quote) "

In the following example, character escapes are entered to represent the greater than and less than symbols that are required in a dial plan rule. This example defines an information hotline dial plan that sets the Dial_Plan[1] parameter equal to (S0 <:18005551212>).

<flat-profile>

<Dial_Plan_1_>

(S0 <:18005551212>)

</Dial_Plan_1_>

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 19

Creating XML Provisioning Scripts

Compression and Encryption

</flat-profile>

• Numeric character escapes, using decimal and hexadecimal values (s.a. &

#40; and .), are translated.

• The firmware does not support the full Unicode character set, but only the

ASCII subset.

Compression and Encryption

The configuration profile can be compressed to reduce the network load on the provisioning server. It also can be encrypted to protect confidential information. Compression is not required, but it must precede encryption.

The supported compression method is the gzip deflate algorithm (RFC1951). The gzip utility and the compression library that implements the same algorithm (zlib) are available from Internet sites.

To identify when compression is applied, the ATA expects the compressed file to contain a gzip compatible header, as generated by invoking the gzip utility on the original Open profile. The ATA inspects the downloaded file header to determine the format of the file.

For example, if profile.xml is a valid profile, the file profile.xml.gz is also accepted. This profile type can be generated with either of the following commands:

>gzip profile.xml

replaces original file with compressed file.

>cat profile.xml | gzip > profile.xml.gz

leaves original file in place, produces new compressed file.

A tutorial on compression is provided in Open Profile gzip Compression,

page 61.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 20

Creating XML Provisioning Scripts

Compression and Encryption

Encryption by using AES

A configuration profile can be encrypted by using symmetric key encryption, whether or not the file is 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 ATA to recognize a compressed and

encrypted profile. A tutorial on encryption is provided in Profile Encryption by

using OpenSSL, page 62.

The OpenSSL encryption tool, available for download from various Internet sites, can be used to perform the encryption. Support for 256-bit AES encryption might require recompilation of the tool (to enable the AES code). The firmware has been tested against version openssl-0.9.7c.

If the file is encrypted, the profile expects the file to have the same format as generated by the following command:

# example encryption key = SecretPhrase1234

openssl enc –e –aes-256-cbc –k SecretPhrase1234 –in profile.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, the encryption tool 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 ATA must be informed of the secret key value to decrypt the file. This value is specified as a qualifier in the profile URL. The syntax is as follows, using an explicit URL:

[--key “SecretPhrase1234”] http://prov.telco.com/path/profile.cfg

This value is programmed by 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 by using HTTPS.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 21

Creating XML Provisioning Scripts

Applying a Profile to the ATA

Preencrypting configuration profiles offline with symmetric key encryption allows the use of HTTP for resyncing profiles. The provisioning server uses HTTPS to handle initial provisioning of the ATA after deployment. This feature 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.

Applying a Profile to the ATA

After you create an XML configuration script, it must be passed to the ATA for application. To apply the configuration, choose one of the following methods:

TFTP and the Resync URL

Complete the following steps to post the configuration file to a TFTP server application on your PC.

STEP 1 Connect your PC to the ATA LAN.

STEP 2 Run a TFTP server application on the PC and make sure that the configuration file

is available in the TFTP root directory.

STEP 3 In a web browser, and enter the LAN IP address of the ATA, the IP address of the

computer, the filename, and the login credentials, in this format:

http://<WAN_IP_Address>/admin/resync?tftp://<PC_IP_Address>/<file_name>& xuser=admin&xpassword=<password>

Example:

http://192.168.15.1/admin/resync?tftp://192.168.15.100/my_config.xml&xuser= admin&xpassword=admin

Direct HTTP Post using cURL

Complete the following steps to post the configuration to the ATA by using cURL. This command line tool is used to transfer data with a URL syntax. To download cURL, see:

http://curl.haxx.se/download.html

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 22

Creating XML Provisioning Scripts

Using Provisioning Parameters

STEP 1 Connect your PC to the LAN port of the ATA.

STEP 2 Post the configuration file to the ATA by entering the following cURL command:

curl –d @my_config.xml “http://192.168.15.1/admin/config.xml& xuser=admin&xpassword=admin”

Using Provisioning Parameters

This section describes the provisioning parameters broadly organized according to function:

• General Purpose Parameters

• Enables

• Triggers

• Configurable Schedules

• Profile Rules

• Report Rule

• Upgrade Rule

NOTE Additional parameters are described in Chapter 6, “Voice Parameters” and

Chapter 7, “Router Configuration Parameters.”

General Purpose Parameters

The general purpose parameters GPP_* are used as free string registers when configuring the ATA 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

• URLs

• Multi-stage provisioning status information

• Post request templates

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 23

Creating XML Provisioning Scripts

Using Provisioning Parameters

• 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 administration web server. Both of these parameters 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 ATA. If enabled, the proxy can request a resync by sending a SIP NOTIFY message containing the Event: resync header to the device.

The device challenges the request with a 401 response (authorization refused for used credentials), 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 device performs a resync operation after powerup software reboots and after each upgrade attempt.

When enabling Resync_On_Reset, the device 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 these ATAs, 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.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 24

Creating XML Provisioning Scripts

Using Provisioning Parameters

Triggers

The ATA allows you to resync at specific intervals or at a specific time.

Resyncing at Specific Intervals

The ATA 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 device does not resync periodically.

The resync typically takes place when the voice lines are idle. In case a voice line is active when a resync is due, the ATA delays the resync procedure until the line becomes idle again. However, it waits no longer than Forced_Resync_Delay (seconds). A resync might cause configuration parameter values to change. This, in turn, causes a firmware reboot and terminates any voice connection active at the time of the resync.

If a resync operation fails because the ATA was unable to retrieve a profile from the server, if the downloaded file is corrupt, or an internal error occurs, the device tries to resync again after a time specified in Resync_Error_Retry_Delay (seconds). If Resync_Error_Retry_Delay is set to 0, the device 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 expired.

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.

$REGTMR1 gt 300 and $PRVTMR ge 600

Resyncing at a Specific Time

The Resync_At parameter allows you to resync at a specific time. This parameter uses the 24-hour format (hhmm) to specify the time.

To avoid simultaneously flooding the server with resync requests from multiple phones set to resync at the same time, the phone triggers the resync up to 10 minutes after the specified time.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 25

Creating XML Provisioning Scripts

Using Provisioning Parameters

For example, if you set the resync time to 1000 (10 a.m.), the phone triggers the resync anytime between 10:00 a.m. and 10:10 a.m.

By default, this feature is disabled. If the Resync_At parameter is provisioned, the Resync_Periodic parameter is ignored.

Configurable Schedules

You can configure schedules for periodic resyncs, and you can specify the retry intervals for resync and upgrade failures by using these provisioning parameters:

• Resync_Periodic

• Resync_Error_Retry_Delay

• Upgrade_Error_Retry_Delay

Each parameter accepts a single delay value (seconds). The new extended syntax allows for a comma-separated list of consecutive delay elements. The last element in the sequence is implicitly repeated forever. Below is an example:

Resync_Periodic=7200 Resync_Error_Retry_Delay=1800,3600,7200,14400

In the above example, the ATA periodically resyncs every two hours. In case of a resync failure, the device retries at these intervals: 30 minutes, 1 hour, 2 hours, 4 hours. It continues trying at 4-hour intervals until it successfully resyncs.

Optionally, you can use a plus sign to specify an additional numeric value that appends a random extra delay, as shown in this example:

Resync_Periodic=3600+600 Resync_Error_Retry_Delay=1800+300,3600+600,7200+900

In the above example, the device periodically resyncs every hour (plus an additional random delay of up to 10 minutes). In case of a resync failure, the device retries at these intervals: 30 minutes (plus up to 5 minutes). 1 hour (plus up to 10 minutes), 2 hours (plus up to 15 minutes). It continues trying at 2-hour intervals (plus up to 15 minutes) until it successfully resyncs.

Below is another example:

Upgrade_Error_Retry_Delay = 1800,3600,7200,14400+3600

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 26

Creating XML Provisioning Scripts

Using Provisioning Parameters

In this example, if a remote upgrade attempt fails, the device 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.

Profile Rules

The ATA 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 device resyncs periodically to a single profile on a central server, which updates all pertinent internal parameters. Alternatively, the profile can be split between different files. One file is common for all of these ATAs 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 ATA 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 can result in a profile being retrieved from a remote provisioning server, possibly updating some number of internal parameters. If an evaluation 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 device waits for the second specified by the Resync_Periodic parameter, and then performs a resync again.

The contents of each Profile_Rule* parameter consist of a set of alternatives. The alternatives are separated by the | (pipe) 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 ]

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 27

Creating XML Provisioning Scripts

Using Provisioning Parameters

Within each Profile_Rule* parameter, all of the alternatives except the last one must provide a conditional expression. 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. If a 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.

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/cisco/$MA.cfg

In the following example, the device resyncs to two different URLs, depending on the registration state of Line 1. In case of lost registration, the device 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 device).

($REGTMR1 eq 0)? http://p.tel.com/has-reg.cfg | [--post a] http://p.tel.com/lost-reg?

In the following example, the device resyncs to the same server, but provides additional information if a certificate is not installed in the unit (for legacy pre-2.0 units).

(“$CCERT” eq “Installed”)? https://p.tel.com/config? | https://p.tel.com/config?cisco$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.

(“$A” ne “Provisioned”)? (Line_Enable_1_ = “No”;)! https://p.tel.com/initprov | https://p.tel.com/configs

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 28

Creating XML Provisioning Scripts

Using Provisioning Parameters

In the following example, the profile returned by the server is assumed to contain XML element tags that need to be remapped to proper parameter names by the aliases map stored in GPP_B.

[--alias b] https://p.tel.com/account/spa$MA.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 device accepts a file-not-found response from the server as a successful resync. The default value for Resync_Fails_On_FNF is Yes.

Report Rule

The ATA 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 Open format profile. All provisionable parameters are included, except 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 or HTTP PUT.

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

The following is an example of the corresponding Report_Rule configuration:

[ --key secretphrase ] http://prov.serv.net/spa/$MA/rep.xml.enc

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 29

Creating XML Provisioning Scripts

Using Provisioning Parameters

Once the report rule is configured, an actual report can be generated and transmitted by sending the device a SIP NOTIFY message, with the Event: report type. The SIP NOTIFY request is handled like other SIP notifies, with the device requiring authentication from the requesting server before honoring the request to issue a report. Each SIP NOTIFY report request generates one attempt to transmit the report. Retries are not supported.

Deltas Report

In addition to reporting the current internal configuration to the provisioning server, the Report Rule has an option for triggering the reporting of configuration changes (deltas) to the server since the last resync, reboot, or upgrade.

The syntax of this option is:

Report Rule: [--delta] URL

Where URL is the path to where the report is stored on the server.

For example, to store delta configuration changes in a file with a name like SPA504G_<MAC>_<serial#>.xml, do one of the following:

• On the phone Web GUI, set the Report Rule field on the Configuration

Profile page (Voice tab > Provisioning tab > Configuration Profile) to:

[--delta] http://reportTargetServer/reportPath/$PN_$MA_ $SN.xml

• Add the following to your provisioning file:

<Report_Rule ua="na">[ --delta ] http://reportTargetServer/reportPath/$PN_$MA_$SN.xml </Report_Rule>

Status.xml Report

The Report Rule has an option to report the status.xml data if [--status] is specified in the report rule. The status report file path should be defined after the [--status] keyword, separated with a comma. If the [--status] keyword or the status report file path is missing, the phone will not report the status.xml data.

For example, if the following is configured:

[--status]http://my_http_server/config-525.xml

The phone will report the status file to http://my_http_server/config-525.xml.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 30

Creating XML Provisioning Scripts

Using Provisioning Parameters

If the following is configured:

[--delta]http://my_http_server/config-525.xml; [--status]http://my_http_server/ status-525.xml

The phone will report the delta report to http://my_http_server/config-525.xml and the status report to http://my_http_server/status-525.xml.

Upgrade Rule

The ATA 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 device 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 device 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 device if any voice line is currently inactive.

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:

(“$F” ne “beta-customer”)? http://p.tel.com/firmware/ spa021025.bin

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 31

Creating XML Provisioning Scripts

Data Types

| 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 device 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 device rejects upgrade attempts for firmware versions earlier than the specified limit.

Data Types

The data types used with configuration profile parameters are as follows:

• Uns<n>—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<n>—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<n>—A generic string with up to n non-reserved characters.

• Float<n>—A floating point value with up to n decimal places.

• Time<n>—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.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 32

Creating XML Provisioning Scripts

Data Types

• FQDN—Fully Qualified Domain Name, such as “sip.Cisco.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@Cisco.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 to 39 characters.

• CadScript—A mini-script that specifies the cadence parameters of a signal.

Up to 127 characters. Syntax: S

[,on

/of f

[,on

/of f

off

i,2

i,3

i,4

section

, on

and off

i,j

1 or 2, and j = 1 to 6. D

[,on

i,4

are the on/off duration in seconds of a

is the total duration of the section in seconds. All

[;S2], where: Si=Di(on

/of f

[,on

i,5

i,6

/of f

i,6

/off

[,on

i,1

i,2

]]]]]) and is known as a

segment

and i =

durations can have up to three decimal places to provide 1 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)

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 33

Creating XML 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

Segment 4: 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

1@L1

Hz (unsigned integers only) and L up to 1 decimal places). White spaces before and after the comma are allowed (but not recommended).

[,F2@L2[,F3@L3[,F4@L4[,F5@L5[,F6@L6]]]]], where F1–F6 are frequency in

are corresponding levels in dBm (with

1–L6

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 CadScript except that each on/off segment is followed by a frequency

[;Z2]. The section Z1 is similar to the S1 section in a

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 34

Creating XML Provisioning Scripts

Data Types

components parameter: Z1 = D1(on [,on

/of f

i,4

[+n2]+n3[+n4[+n5[+n6]]]]] and 1 < nk < 6 indicates which of the frequency

i,4/fi,4

[,on

i,5

/of f

i,5/fi,5

[,on

i,6

i,1

/of f

i,6/fi,6

[,on

i,1/fi,1

i,2

/of f

]]]]]), where fi,j =

i,2/fi,2

[,on

i,3

/of f

i,3/fi,3

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

Example 2—Stutter tone:

350@-19,440@-19;2(.1/.1/1+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

Cadence Section 2: Section Length = 10s

Number of Segments = 1

Segment 1: On=forever, with Frequencies 1 and 2

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 35

Creating XML Provisioning Scripts

Data Types

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/4/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

NOTE

Segment 2: On=0.38s, Off=0s, with Frequency 2

Segment 3: On=0.38s, Off=0s, with Frequency 3

Segment 4: 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.

• <Par Name> represents a configuration parameter name. In a profile, the

corresponding tag is formed by replacing the space with an underscore “_”, such as Par_Name.

• An empty default value field implies an empty string < “” >.

• The ATA 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,

is selected. The parameter name must match exactly.

not the closest

, match

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 36

Creating XML Provisioning Scripts

Data Types

• If more than one definition for a parameter is given in a profile, the last such

definition in the file is the one that takes effect in the ATA.

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

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 37

In-House Preprovisioning and Provisioning Servers

Cisco IP Telephony devicesSPA100 and SPA200 Series ATAs, other than RC units, are preprovisioned by the service provider with a profile. That pre-provision profile can range from a a limited set of parameters that resynchronizes the ATA to another profile with a complete set of parameters delivered by remote server. Or, it can be a complete set of parameters. By default, the ATA resynchronizes on power up and at intervals configured in the profile. When the user connects the ATA at the customer premises, the device downloads the updated profile and any firmware updates.

This process of preprovisioning, deployment, and remote provisioning can be accomplished many ways. This chapter describes the features and functionality available when preprovisioning these ATAs in-house and provisioning them remotely:

• Server Preparation and Software Tools, page 38

• In-House Device Preprovisioning, page 39

• Provisioning Server Setup, page 40

Server Preparation and Software Tools

The examples presented in this chapter require the availability of one or more servers. These servers can be installed and run on a local PC:

• TFTP (UDP port 69)

• syslog (UDP port 514)

• HTTP (TCP port 80)

• HTTPS (TCP port 443).

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters

In-House Preprovisioning and Provisioning Servers

In-House Device Preprovisioning

To troubleshoot server configuration, it is helpful to install clients for each type of server on a separate server machine. This establishes proper server operation, independent of the interaction with these ATAs.

Cisco also recommends the installation of the following software tools:

• To generate configuration profiles, it is useful to install the open source gzip

compression utility.

• For profile encryption and HTTPS operations, install the open source

OpenSSL software package.

• To test the dynamic generation of profiles and one-step remote provisioning

using HTTPS, a scripting language with CGI scripting support, such as open source Perl language tools, is recommended.

• To verify secure exchanges between provisioning servers and these ATAs,

install an Ethernet packet sniffer (such as the freely downloadable Ethereal/ Wireshark). Capture an Ethernet packet trace of the interaction between the ATA and the provisioning server by running the packet sniffer on a PC that is connected to a switch with port mirroring enabled. For HTTPS transactions, you can use the ssldump utility.

In-House Device Preprovisioning

With the Cisco factory default configuration, an ATA automatically tries to resync to a profile on a TFTP server. The information regarding the profile and TFTP server configured for preprovisioning is delivered to the device by a managed DHCP server on a LAN. The service provider connects each new ATA that LAN and the ATA automatically resyncs to the local TFTP server, initializing its internal state in preparation for deployment. This preprovisioning profile typically includes the URL of a remote provisioning server that will keep the device updated after it is deployed and connected to the customer network.

The preprovisioned device barcode can be scanned to record its MAC address or serial number before the ATA is shipped to the customer. This information can be used to create the profile to which the ATA will resynchronize.

Upon receiving the ATA, the customer connects it to the broadband link. On power-up the ATA contacts the provisioning server through the URL configured through preprovisioning to for its resync and updates the profile and firmware as necessary.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 39

In-House Preprovisioning and Provisioning Servers

Provisioning Server Setup

This section describes setup requirements for provisioning an ATA by using various servers and different scenarios. For testing purposes and for the purposes of this document, provisioning servers are installed and run on a local PC. Also, generally available software tools are useful for provisioning these ATAs.

TFTP Provisioning

These ATAs support TFTP for both provisioning resync and firmware upgrade operations. When devices are deployed remotely, HTTP is recommended for provisioning as it offers greater reliability, given NAT and router protection mechanisms. TFTP is useful for the in-house preprovisioning of a large number of un-provisioned devices. See In-House Device Preprovisioning, page 39 for more information.

The ATA is able to obtain a TFTP server IP address directly from the DHCP server through DHCP option 66. If a Profile_Rule is configured with the filepath of that TFTP server, the device downloads its profile from the TFTP server when it is connected to a LAN and powered up.

The Profile_Rule provided with the factory default configuration is /device.cfg. For example, on a SPA962 the filename is spa962.cfg. If the device has the factory default profile, when powered up it resyncs to this file on the local TFTP server specified by DHCP option 66. (The filepath is relative to the TFTP server virtual root directory.)

Remote Endpoint Control and NAT

The ATA accesses the Internet through a router by using network address translation (NAT). For enhanced security, the router might attempt to block unauthorized incoming packets by implementing symmetric NAT (a packet filtering strategy that severely restricts the packets that are allowed to enter the protected network from the Internet). For this reason, remote provisioning by using TFTP is not recommended.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 40

In-House Preprovisioning and Provisioning Servers

Provisioning Server Setup

Voice over IP can co-exist with NAT only when some form of NAT traversal is provided. Configure Simple Traversal of UDP through NAT (STUN). This option requires that the user have (1) a dynamic external (public) IP address from your service, (2) a computer running STUN server software, and (3) an edge device with an asymmetric NAT mechanism.

HTTP Provisioning

The ATA behaves like a browser requesting web pages from a 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 work more reliably than TFTP in remote deployments, especially when the deployed units are connected behind residential firewalls or NAT-enabled routers.

Basic HTTP-based provisioning relies on the HTTP GET method for retrieving configuration profiles. Typically, a configuration file is created for each deployed ATA, and these files are stored within a 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 (using the GET method). The configuration profile is generated dynamically by querying a customer database and producing the profile on-the-fly.

When CGI handles resync requests, the ATA can use the HTTP POST method to request the resync configuration data. The device can be configured to convey certain status and identification information to the server within the body of the HTTP POST request. The server uses this information to generate a desired response configuration profile, or store the status information for later analysis and tracking.

As part of both GET and POST requests, the ATA automatically includes basic identifying information in the request header, in the User-Agent field. This information conveys the manufacturer, product name, current firmware version, and product serial number of the device.

For example, the following example is the User-Agent request field from a SPA962:

User-Agent: cisco/SPA-962-2.0.5 (88012BA01234)

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 41

In-House Preprovisioning and Provisioning Servers

Provisioning Server Setup

When the ATA is configured to resync to a configuration profile by using HTTP, it is recommended that the profile be encrypted to protect confidential information. The ATA supports 256-bit AES in CBC mode to decrypt profiles. Encrypted profiles downloaded by the ATA by using HTTP avoid the danger of exposing confidential information contained in the configuration profile. This resync mode produces a lower computational load on the provisioning server when compared to using HTTPS.

HTTPS Provisioning

For increased security managing remotely deployed units, the ATA supports HTTPS for provisioning. Each ATA carries a unique SLL Client Certificate (and associated private key), in addition to a Sipura CA server root certificate. The latter allows the ATA to recognize authorized provisioning servers, and reject nonauthorized servers. On the other hand, the client certificate allows the provisioning server to identify the individual device that issues the request.

For a service provider to manage deployment by using HTTPS, a server certificate must be generated for each provisioning server to which an ATA resyncs by using HTTPS. The server certificate must be signed by the Cisco 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 Cisco, which signs and returns the server certificate for installation on the provisioning server.

The provisioning server certificate must contain the Common Name (CN) field, and the FQDN of the host running the server in the subject. It might optionally contain information following the host FQDN, separated by a slash (/) character. The following examples are of CN entries that are accepted as valid by the ATA:

CN=sprov.callme.com CN=pv.telco.net/mailto:admin@telco.net CN=prof.voice.com/info@voice.com

In addition to verifying the server certificate, the ATA 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 by using the OpenSSL utility. The following example shows the openssl command that produces a 1024-bit RSA public/private key pair and a certificate signing request:

openssl req –new –out provserver.csr

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 42

In-House Preprovisioning and Provisioning Servers

Provisioning Server Setup

This command generates the server private key in privkey.pem and a corresponding certificate signing request in provserver.csr. The service provider keeps the privkey.pem secret and submits provserver.csr to Cisco for signing. Upon receiving the provserver.csr file Cisco generates provserver.crt, the signed server certificate.

Cisco also provides a Sipura CA Client Root Certificate to the service provider. This root certificate certifies the authenticity of the client certificate carried by each ATA.

The unique client certificate offered by each device 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 example from a SPA962 client certificate subject field shows these elements:

OU=SPA-962, L=88012BA01234, S=000e08abcdef

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 identifying fields:

OU=cisco.com, L=ciscogeneric, S=ciscogeneric

To determine if an ATA carries an individualized certificate, use the $CCERT provisioning macro variable. The variable 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 by using the Sipura CA Client Root Certificate supplied by Cisco. It can then provide the certificate information to a CGI for further processing.

The location for storing certificates might vary. For example, on an Apache installation the file paths for storing the provisioning server–signed certificate, its associated private key, and the Sipura CA client root certificate are as follows:

# Server Certificate: SSLCertificateFile /etc/httpd/conf/provserver.crt

# Server Private Key: SSLCertificateKeyFile /etc/httpd/conf/provserver.key

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 43

In-House Preprovisioning and Provisioning Servers

Provisioning Server Setup

# Certificate Authority (CA): SSLCACertificateFile /etc/httpd/conf/spacroot.crt

Refer to the documentation provided for a HTTPS server for specific information.

Firmware release 2.0.6 and higher supports the following cipher suites for SSL connection to a server by using HTTPS.

Table 1 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

0x002f 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

Redundant Provisioning Servers

The provisioning server can 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 ATA 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 ATA continues to process A-records until a server responds. If no server associated with the A-records responds, the ATA logs an error to the syslog server.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 44

In-House Preprovisioning and Provisioning Servers

Provisioning Server Setup

Syslog Server

If a syslog server is configured on the ATA (using the <Syslog_Server> or <Debug_Server> 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 (indicating 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.

As indicated in the lower half of the diagram, a Cisco Client Certificate Root Authority signs each unique certificate. The corresponding root certificate is made available to service providers for client authentication purposes.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 45

Provisioning Examples

This chapter provides example procedures for transferring configuration profiles between the ATA and the provisioning server:

• Basic Resync, page 46

• Secure HTTPS Resync, page 53

• Profile Management, page 61

Basic Resync

For information about creating configuration profiles, refer to Chapter 2, “Creating

XML Provisioning Scripts.”

This section demonstrates the basic resync functionality of these ATAs.

TFTP Resync

The ATA supports multiple network protocols for retrieving configuration profiles. The most basic profile transfer protocol is TFTP (RFC1350). TFTP, widely used for the provisioning of network devices within private LAN networks. Although not recommended for the deployment of remote endpoints across the Internet, it can be convenient for deployment within small organizations, for in-house preprovisioning, and for development and testing. See “In-House Device

Preprovisioning” section on page 39 for more information on in-house

preprovisioning. In this exercise, a profile is modified after downloading a file from a TFTP server.

Exercise

STEP 1 Within a LAN environment connect a PC and an ATA to a hub, switch, or small

router.

STEP 2 Connect an analog phone to the Phone 1 port of the ATA.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters

Provisioning Examples

Basic Resync

STEP 3 On the PC, install and activate a TFTP server.

STEP 4 Using a text editor, create a configuration profile that sets the value for GPP_A to

STEP 5 Save the profile with the name basic.txt in the root directory of the TFTP

STEP 6 Using an analog phone, obtain the IP address of the ATA (IVR menu **** 110 #).

12345678 as shown in the example.

<flat-profile>

<GPP_A> 12345678 </GPP_A>

</flat-profile>

server.

You can verify that the TFTP server is properly configured by requesting the basic.txt file by using a TFTP client other than the ATA. Preferably, use a TFTP client that is running on a separate host from the provisioning server.

If the configuration has been modified since it was manufactured, perform factory reset on the phone by using the IVR RESET option (**** 73738#).

STEP 7 Open the PC web browser on the admin/advanced configuration page. For

example, if the IP address of the phone is 192.168.1.100:

http://192.168.1.100/admin/advanced

STEP 8 Select the Provisioning tab, and inspect the values of the general purpose

parameters GPP_A through GPP_P. These should be empty.

STEP 9 Resync the test ATA to the basic.txt configuration profile by opening the resync

URL in a web browser window.

Assuming the IP address of the TFTP server is 192.168.1.200 the command should be similar to this example:

http://192.168.1.100/admin/resync?tftp://192.168.1.200/basic.txt

When ATA receives this command, the device 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.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 47

Provisioning Examples

Basic Resync

STEP 1 Install and activate a syslog server on the local PC.

The GPP_A parameter should now contain the value 12345678.

Logging with syslog

The ATA sends a syslog message to the designated syslog server when the device 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). Configure the syslog server IP address into the device and observe the messages generated during the remaining exercises.

Exercise

STEP 2 Program the PC IP address into the Syslog_Server parameter of the profile and

submit the change:

<Syslog_Server ua="na">192.168.1.210</Syslog_Server>

STEP 3 Click the System tab and enter the value of your local syslog server into the

Syslog_Server parameter.

STEP 4 Repeat the resync operation as described in the TFTP Resync exercise.

The device 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.

STEP 5 Verify that your syslog server received messages similar to the following:

SPA-962 00:0e:08:ab:cd:ef –- Requesting resync tftp://192.168.1.200/basic.txt SPA-962 00:0e:08:ab:cd:ef –- Successful resync tftp://192.168.1.200/basic.txt

Detailed messages are available by programming a 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):

<Debug_Server ua="na">192.168.1.210</Debug_Server> <Debug_Level ua="na">3</Debug_Level>

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 48

Provisioning Examples

Basic Resync

The contents of these messages can be configured by using the following parameters:

• Log_Resync_Request_Msg

• Log_Resync_Success_Msg

• Log_Resync_Failure_Msg.

If any of these parameters are cleared, the corresponding syslog message is not generated.

Automatic Device Resync

A device can resync periodically to the provisioning server to ensure that any profile changes made on the server are propagated to the endpoint device (as opposed to sending an explicit resync request to the endpoint).

To cause the ATA to periodically resync to a server, a configuration profile URL is defined by using the Profile_Rule parameter, and a resync period is defined by using the Resync_Periodic parameter.

Exercise

STEP 1 Using a web browser, open the admin/advanced page Provisioning tab.

STEP 2 Define the Profile_Rule parameter. The example assumes a TFTP server IP

address of 192.168.1.200:

<Profile_Rule ua="na">tftp://192.168.1.200/basic.txt</Profile_Rule>

STEP 3 In the Resync_Periodic parameter enter a small value for testing, such as 30

seconds:

<Resync_Periodic ua="na">30</Resync_Periodic>

STEP 4 Click Submit all Changes.

With the new parameter settings, the ATA resyncs to the configuration file specified by the URL twice a minute.

STEP 5 Observe the resulting messages in the syslog trace (as described in the Logging

with syslog section).

STEP 6 Ensure that the Resync_On_Reset parameter is set to yes:

<Resync_On_Reset ua="na">Yes</Resync_On_Reset>

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 49

Provisioning Examples

Basic Resync

STEP 7 Power cycle the ATA to force it to resync to the provisioning server.

STEP 8 (Optional) Set the value of Resync_Error_Retry_Delay is set to a small number,

STEP 9 Disable the TFTP server, and observe the results in the syslog output.

If the resync operation fails for any reason, such as if the server is not responding, the unit waits the number of seconds configured in Resync_Error_Retry_Delay before attempting to resync again. If Resync_Error_Retry_Delay is zero, the ATA does not try to resync after a failed resync attempt.

such as 30:

<Resync_Error_Retry_Delay ua="na">30</Resync_Error_Retry_Delay>

Unique Profiles, Macro Expansion, and HTTP

In a deployment where each ATA must be configured with distinct values for some parameters, such as User_ID or Display_Name, the service provider can create a unique profile for each deployed device and host those profiles on a provisioning server. Each ATA, in turn, must be configured to resync to its own profile according a predetermined profile naming convention.

The profile URL syntax can include identifying information specific to each ATA, such as MAC address or serial number, by using the macro expansion of built-in variables. Macro expansion eliminates the need to specify these values in multiple locations within each profile.

A profile rule undergoes macro expansion before being applied to the ATA. The macro expansion controls a number of values, for example:

• $MA expands to the unit 12-digit MAC address (using lower case hex digits).

For example, 000e08abcdef.

• $SN expands to the unit serial number. For example, 88012BA01234.

Other values can be macro expanded in this way, including all the general purpose parameters, (GPP_A through GPP_P). An example of this process can be seen in the TFTP Resync section. Macro expansion is not limited to the URL file name, but can also be applied to any portion of the profile rule parameter. These parameters are referenced as $A through $P. For a complete list of variables available for macro expansion, see the “Macro Expansion Variables” section on page 77.

In this exercise, a profile specific to an ATA is provisioned on a TFTP server.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 50

Provisioning Examples

Basic Resync

STEP 1 Obtain the MAC address of the ATA from its product label. (The MAC address is

STEP 2 Copy the basic.txt configuration file (described in the TFTP Resync exercise)

STEP 3 Move the new file in the virtual root directory of the TFTP server.

STEP 4 Open the admin/advanced page Provisioning tab.

STEP 5 Enter tftp://192.168.1.200/spa$MA.cfg in the Profile_Rule parameter:

Exercise

the number, using numbers and lower–case hex digits, such as 000e08aabbcc.

to a new file named spa_macaddress.cfg (replacing macaddress with the MAC address of the ATA). For example:

spa_000e08abcdef.cfg

<Profile_Rule ua="na">

tftp://192.168.1.200/spa$MA.cfg

</Profile_Rule>

STEP 6 Click Submit All Changes. This causes an immediate reboot and resync.

When the next resync occurs, the ATA retrieves the new file by expanding the $MA macro expression into its MAC address.

HTTP GET Resync

HTTP provides a more reliable resync mechanism than TFTP because HTTP establishes a TCP connection and TFTP uses the less reliable UDP. In addition, HTTP servers offer improved filtering and logging features compared to TFTP servers.

On the client side, the ATA does not require any special configuration setting on the server to be able to resync by using HTTP. The Profile_Rule parameter syntax for using HTTP with the GET method is similar to the syntax used for TFTP. If a standard web browser can retrieve a profile from a your HTTP server, the ATA should be able to do so as well.

Exercise

STEP 1 Install an HTTP server on the local PC or other accessible host. (The open source

Apache server can be downloaded from the Internet.)

STEP 2 Copy the basic.txt configuration profile (described in the TFTP Resync

exercise) onto the virtual root directory of the installed server.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 51

Provisioning Examples

Basic Resync

STEP 3 Verify proper server installation (and file access to basic.txt) by accessing the

STEP 4 Modify the Profile_Rule of the test ATA to point to the HTTP server in place of the

STEP 5 Click Submit All Changes. This causes an immediate reboot and resync.

STEP 6 Observe the syslog messages sent by the ATA. The periodic resyncs should now

profile by using a web browser.

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:

<Profile_Rule ua="na"> http://192.168.1.200/basic.txt </Profile_Rule>

be obtaining the profile from the HTTP server.

STEP 7 In the HTTP server logs, observe how information identifying the test ATA appears

in the log of user agents.

This should include the manufacturer, product name, current firmware version, and serial number.

URL Resolution by using Macro Expansion

Subdirectories with multiple profiles on the server is a convenient method for managing a large number of deployed devices. The profile URL can contain:

• A provisioning server name or an explicit IP address. If the profile identifies

the provisioning server by name, the ATA performs a DNS lookup to resolve the name.

• A non-standard server port specified in the URL by using the standard

syntax:port following the server name.

• The subdirectory of the server virtual root directory where the profile is

stored, specified by using standard URL notation and managed by macro expansion.

For example, the following Profile_Rule requests the profile spa962.cfg, in the server subdirectory /cisco/config, from the TFTP server running on host prov.telco.com listening for a connection on port 6900:

<Profile_Rule ua="na"> /tftp://prov.telco.com:6900/cisco/config/spa962.cfg </Profile_Rule>

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 52

Provisioning Examples

Secure HTTPS Resync

A profile for each ATA can be identified in a general purpose parameter, with its value referred within a common profile rule by using macro expansion.

For example, assume GPP_B is defined as Dj6Lmp23Q.

The Profile_Rule has the value:

tftp://prov.telco.com/cisco/$B/$MA.cfg

When the device resyncs and the macros are expanded, the ATA with a MAC address of 000e08012345 requests the profile with the name that contains the device MAC address at the following URL:

tftp://prov.telco.com/cisco/Dj6Lmp23Q/000e08012345.cfg

Secure HTTPS Resync

This section demonstrates the mechanisms available on the ATA for resyncing by using a secure communication process. It includes the following topics:

• Basic HTTPS Resync, page 53

• HTTPS With Client Certificate Authentication, page 56

• HTTPS Client Filtering and Dynamic Content, page 57

Basic HTTPS Resync

HTTPS adds SSL to HTTP for remote provisioning so that the:

• ATA can authenticate the provisioning server

• provisioning server can authenticate the ATA

• confidentiality of information exchanged between the ATA and the

provisioning server is ensured.

SSL generates and exchanges secret (symmetric) keys for each connection between the ATA and the server, using public/private key pairs preinstalled in the ATA and the provisioning server.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 53

Provisioning Examples

Secure HTTPS Resync

STEP 1 Install an HTTPS server on a host whose IP address is known to the network DNS

On the client side, the ATA does not require any special configuration setting on the server to be able to resync using HTTPS. The Profile_Rule parameter syntax for using HTTPS with the GET method is similar to the syntax used for HTTP or TFTP. If a standard web browser can retrieve a profile from a your HTTPS server, the ATA should be able to do so as well.

In addition to installing a HTTPS server, a SSL server certificate signed by Cisco must be installed on the provisioning server. The devices cannot resync to a server using HTTPS unless the server supplies a Cisco-signed server certificate. Instructions for creating signed SSL Certificates for SPA Voice products can be found at https://supportforums.cisco.com/docs/DOC-9852.

Exercise

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. For this step, you

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

STEP 3 Submit the CSR file (provserver.csr) to Cisco for signing. (See https://

supportforums.cisco.com/docs/DOC-9852 for more information.) A signed server certificate is returned (provserver.cert) along with a Sipura CA Client Root Certificate, spacroot.cert.

STEP 4 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 Linux, 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

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 54

Provisioning Examples

Secure HTTPS Resync

STEP 5 Restart the server.

STEP 6 Copy the basic.txt configuration file (described in the TFTP Resync exercise)

STEP 7 Verify proper server operation by downloading basic.txt from the HTTPS server

STEP 8 Inspect the server certificate supplied by the server.

onto the virtual root directory of the HTTPS server.

by using a standard browser from the local PC.

The browser probably does not recognize it as valid unless the browser has been preconfigured to accept Cisco as a root CA. However, these ATAs expect the certificate to be signed this way.

Modify the Profile_Rule of the test device to contain a reference to the HTTPS server, for example:

<Profile_Rule ua="na"> https://my.server.com/basic.txt </Profile_Rule>

This example assumes the name of the HTTPS server is my.server.com.

STEP 9 Click Submit All Changes.

STEP 10 Observe the syslog trace sent by the ATA.

The syslog message should indicate that the resync obtained the profile from the HTTPS server.

STEP 11 (Optional) Use an Ethernet protocol analyzer on the ATA subnet to verify that the

packets are encrypted.

In this exercise, client certificate verification was not enabled. The connection between ATA and server 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 exercise described in the

HTTPS With Client Certificate Authentication section.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 55

Provisioning Examples

Secure HTTPS Resync

NOTE Both basic and digest authentication are supported on SPA500 Series phones

HTTPS With Client Certificate Authentication

In the factory default configuration, the server does not request a SSL client certificate from a client. Transfer of the profile is not secure because any client can connect to the server and request the profile. You can edit the configuration to enable client authentication; the server requires a client certificate to authenticate the ATA before accepting a connection request.

Because of this, the resync operation cannot be independently tested by using a browser lacking the proper credentials. The SSL key exchange within the HTTPS connection between the test ATA and the server can be observed using the ssldump utility. The utility trace shows the interaction between client and server.

running firmware version 7.4.9c and higher.

Exercise

STEP 1 Enable client certificate authentication on the HTTPS server.

STEP 2 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 Basic HTTPS

Resync exercise.

STEP 3 Restart the HTTPS server and observe the syslog trace from the ATA.

Each resync to the server now performs symmetric authentication, so that both the server certificate and the client certificate are verified before the profile is transferred.

STEP 4 Use ssldump to capture a resync connection between the ATA 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-toserver) before the encrypted packets containing the profile.

With client authentication enabled, only a ATA 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.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 56

Provisioning Examples

Secure HTTPS Resync

STEP 1 Install Perl on the host running the HTTPS server.

STEP 2 Generate the following Perl reflector script:

HTTPS Client Filtering and Dynamic Content

If the HTTPS server is configured to require a client certificate, then the information in the certificate identifies the resyncing ATA 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

#!/usr/bin/perl -wT use strict; print “Content-Type: text/plain\n\n”; print “<flat-profile><GPP_D>”;

print “OU=$ENV{‘SSL_CLIENT_I_DN_OU’},\n”; print “L=$ENV{‘SSL_CLIENT_I_DN_L’},\n”; print “S=$ENV{‘SSL_CLIENT_I_DN_S’}\n”; print “</GPP_D></flat-profile>”;

STEP 3 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.

STEP 4 Verify accessibility of CGI scripts on the server (as in /cgi-bin/…).

STEP 5 Modify the Profile_Rule on the test device to resync to the reflector script, as in the

following example:

https://prov.server.com/cgi-bin/reflect.pl?

STEP 6 Click Submit All Changes.

STEP 7 Observe the syslog trace to ensure a successful resync.

STEP 8 Open the admin/advanced page, Provisioning tab.

STEP 9 Verify that the GPP_D parameter contains the information captured by the script.

This information contains the product name, MAC address, and serial number if the test device carries a unique certificate from the manufacturer, or else generic strings if it is a unit manufactured before firmware release 2.0.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 57

Provisioning Examples

Secure HTTPS Resync

A similar script could be used to determine information about the resyncing device and then provide it with appropriate configuration parameter values.

HTTPS Certificates

The ATA provides a reliable and secure provisioning strategy based on HTTPS requests from the device to the provisioning server. Both a server certificate and a client certificate are used to authenticate the ATA to the server and the server to the ATA.

To use HTTPS, you must generate a Certificate Signing Request (CSR) and submit it to Cisco. Cisco generates a certificate for installation on the provisioning server. The ATA accepts the certificate when it seeks to establish an HTTPS connection with the provisioning server.

How HTTPS Works

HTTPS encrypts the communication between a client and a server, protecting the message contents from other network devices. The encryption method for the body of the communication between a client and a server is based on symmetric key cryptography. With symmetric key cryptography, a single secret key is shared by a client and a 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 ATA 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 a server and a client engaged in a secure transaction. This feature ensures that a 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.

Server and client authentication is performed by using public/private key encryption with a certificate that contains the public key. Text that is encrypted with a public key can be decrypted only by its corresponding private key (and vice versa). The ATA supports the RSA algorithm for public/private key cryptography.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 58

Provisioning Examples

Secure HTTPS Resync

SSL Server Certificates

Each secure provisioning server is issued a SSL server certificate, directly signed by Cisco. The firmware running on the ATA recognizes only a Cisco certificate as valid. When a client connects to a server by using HTTPS, it rejects any server certificate that is not signed by Cisco.

This mechanism protects the service provider from unauthorized access to the ATA, or any attempt to spoof the provisioning server. Without such protection, an attacker might be able to reprovision the ATA, to gain configuration information, or to use a different VoIP service.

Client Certificates

In addition to a direct attack on an ATA, an attacker might attempt to contact a provisioning server by using a standard web browser or another HTTPS client to obtain the configuration profile from the provisioning server. To prevent this kind of attack, each ATA also carries a unique client certificate, signed by Cisco, including identifying information about each individual endpoint. A certificate 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.

Certificate Structure

The combination of a server certificate and a client certificate ensures secure communication between a remote ATA and its provisioning server. The

“Certificate Authority Flow” figure illustrates the relationship and placement of

certificates, public/private key pairs, and signing root authorities, among the Cisco client, the provisioning server, and the certification authority.

The upper half of the diagram shows the Provisioning Server Root Authority that is used to sign the individual provisioning server certificate. The corresponding root certificate is compiled into the firmware, allowing the ATA to authenticate authorized provisioning servers.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 59

Provisioning Examples

Secure HTTPS Resync

Certificate Authority Flow

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 60

Provisioning Examples

Profile Management

This section demonstrates the formation of configuration profiles in preparation for downloading. To explain the functionality, TFTP from a local PC is used as the resync method, although HTTP or HTTPS can be used as well.

Open Profile gzip Compression

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 ATA supports compression of the XML file, by using the deflate compression format supported by the gzip utility (RFC 1951).

NOTE Compression must precede encryption for the ATA to recognize a compressed and

encrypted XML profile.

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 ATA expects the file to contain a valid gzip header.

Exercise

STEP 1 Install gzip on the local PC.

STEP 2 Compress the basic.txt configuration profile (described in the TFTP Resync

exercise) by invoking gzip from the command line:

gzip basic.txt

This generates the deflated file basic.txt.gz.

STEP 3 Save the basic.txt.gz file in the TFTP server virtual root directory.

STEP 4 Modify the Profile_Rule on the test device to resync to the deflated file in place of

the original XML file, as shown in the following example:

tftp://192.168.1.200/basic.txt.gz

STEP 5 Click Submit All Changes.

STEP 6 Observe the syslog trace from the ATA.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 61

Provisioning Examples

Profile Management

STEP 1 Install OpenSSL on a local PC. This might require that the OpenSSL application be

Upon resync, the new file is downloaded by the ATA and used to update its parameters.

Profile Encryption by using OpenSSL

A compressed or uncompressed profile can be encrypted (however, a file must be compressed before it is 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 the ATA and the provisioning server.

Exercise

recompiled to enable AES.

STEP 2 Using the basic.txt configuration file (described in the TFTP Resync exercise),

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 created in Open Profile gzip Compression also can be used, because the XML profile can be both compressed and encrypted.

STEP 3 Store the encrypted basic.cfg file in the TFTP server virtual root directory.

STEP 4 Modify the Profile_Rule on the test device to resync to the encrypted file in place

of the original XML file. The encryption key is made known to the ATA with the following URL option:

[--key MyOwnSecret ] tftp://192.168.1.200/basic.cfg

STEP 5 Click Submit All Changes.

STEP 6 Observe the syslog trace from the ATA.

On resync, the new file is downloaded by the ATA and is used to update its parameters.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 62

Provisioning Examples

Profile Management

STEP 1 Create a new XML profile, basic2.txt, that specifies a value for a parameter that

STEP 2 Store the basic2.txt profile in the virtual root directory of the TFTP server.

Partitioned Profiles

An ATA downloads 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

makes it distinct from the earlier exercises. For instance, to the basic.txt profile you can add the following:

<GPP_B>ABCD</GPP_B>

STEP 3 Leave the first profile rule from the earlier exercises in the folder, but configure the

second profile rule (Profile_Rule_B) to point to the new file:

<Profile_Rule_B ua="na">tftp://192.168.1.200/basic2.txt </Profile_Rule_B>

STEP 4 Click Submit All Changes.

The ATA now resyncs to both the first and second profiles, in that order, whenever a resync operation is due.

STEP 5 Observe the syslog trace to confirm the expected behavior.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 63

Provisioning Examples

Profile Management

Parameter Name Aliases

When generating an XML profile for the ATA, it might be convenient to assign names to certain configuration parameters that are different from the canonical names recognized by the ATA. For example, a customer account database might 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 canonical names (User_ID_1_ and Password_1_ ) before being applied to Line1.

In many instances, the back-end provisioning solution used by the service provider can perform this mapping. However, the ATA 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

STEP 1 Generate a profile named customer.XML containing the proprietary customer-

account XML form indicated in the following example:

<customer-account> <SIP-number> 17775551234</SIP-number> <SIP-password> 512835907884</SIP-password> </customer-account>

STEP 2 Store the profile in the TFTP server virtual root directory.

STEP 3 Open the web interface on the device to the admin/advanced page, Provisioning

tab, and edit GPP_A to contain the alias map (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_ ;

STEP 4 Edit the Profile_Rule to point to the new XML profile, and specify the alias map as a

URL option, as follows:

[--alias a ] tftp://192.168.1.200/customer.xml

STEP 5 Click Submit All Changes.

When the ATA 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.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 64

Provisioning Examples

Profile Management

STEP 6 View the Line 1 tab to verify the new configuration.

NOTE The ATA supports alias remapping of a limited number of parameters. It is not

meant to rename all parameters in its configuration.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 65

Provisioning Parameters

This chapter describes the Provisioning parameters that can be used in configuration profile scripts. It includes the following sections:

• Delta Configuration Report, page 66

• Status.xml Report, page 67

• Firmware Upgrade Parameters, page 75

• General Purpose Parameters, page 76

• Macro Expansion Variables, page 77

• Internal Error Codes, page 80

The Provisioning parameters described in this chapter are recognized by the these ATAs beginning with firmware release 2.0.6 and higher unless otherwise indicated.

Delta Configuration Report

When the report rule is set, a SPA phone reports the phone profile to the server upon boot-up or receiving a report SIP NOTIFY message. By default the entire profile is reported.

Password or encryption key–related parameter values are not reported to the server:

<Admin_Password> IP Phone admin password

<User_Password> IP Phone user password

<PPPOE_Login_Password>

< VPN_Password>

<Access_Password_N> Camera access password for each camera profile

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters

Provisioning Parameters

Delta Configuration Report

<Password_N> Sip account user password for each SIP extension

<SRTP_Private_Key_N> SRTP private key password for each SIP extension

<Auth_Page_Password_N> Auth page password for each SIP extension

<PIN_Code> BluePhone Pin code

<Directory_Password> Broadsoft directory

<Password> LDAP password

Deltas Report

SPA phones running firmware version 7.4.9c or higher can report deltas to the server if the –delta option is specified in the report rule. For example:

Report Rule: [--delta] http://report.com/delta$$MAC.xml

NOTE The double hyphen (--) required.

The main profile supports all provisionable parameters. Parameters in the main profile include the WiFi profile parameters. The –delta option only applies to the main profile. The deltas can be triggered by changes to the phone parameters entered in the LCD screen, the Web GUI, a SIP event, or remote provisioning. The personal address book, call history, Bluetooth profiles, and so forth are not in the main profile and are not reported.

The delta report is generated if the phone detects changes since the last resync, reboot, or upgrade. The report is done in asynchronous manner (with a random delay) and is sent only when the phone is idle. (The phone is considered idle when there is no active call or key press.)

Status.xml Report

SPA phones running firmware version 7.5.3 or higher have an option to report the status.xml data if [--status] is specified in the report rule. The status report file path should be defined after the [--status] keyword, separated with a comma. If the [-status] keyword or the status report file path is missing, the phone will not report the status.xml data.

For example, if the following is configured:

[--status]http://my_http_server/config-525.xml

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 67

Provisioning Parameters

Delta Configuration Report

The phone will report the status file to http://my_http_server/config-525.xml.

If the following is configured:

[--delta]http://my_http_server/config-525.xml; [--status]http://my_http_server/ status-525.xml

The phone will report the delta report to http://my_http_server/config-525.xml and the status report to http://my_http_server/status-525.xml.

Report Content

An administrator can define the content [--content] that is included in the report in the report rule. When --content path is defined, the main profile, address book and call history are reported to server. Where p reports the main profile parameters, a reports address book information, h reports the call history. This option is only available for UC320W.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 68

Provisioning Parameters

Configuration Profile Parameters

The following table defines the function and usage of each parameter in the Configuration Profile Parameters section under the Provisioning tab.

Parameter Name Description and Default Value

Provision_Enable Controls all resync actions independently of

Resync_On_Reset Triggers a resync after every reboot except

firmware upgrade actions. Set to yes to enable remote provisioning.

The default value is Yes.

for reboots caused by parameter updates and firmware upgrades.

The default value is Yes.

Resync_Random_Delay Prevents an overload of the provisioning

server when a large number of devices power-on simultaneously and attempt initial configuration. This delay is effective only on the initial configuration attempt, following a device power-on or reset.

The parameter is the maximum time interval that the device waits before making contact with the provisioning server. The actual delay is a pseudo-random number between zero and this value.

This parameter is in units of 20 seconds; the default value of 3 represents 60 seconds. This feature is disabled when this parameter is set to zero.

The default value is 2 (40 seconds).

Resync At (SPA500 series phones)

The hour and minutes (HHmm) that the device resyncs with the provisioning server.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 69

The default value is empty. If the value is invalid, the parameter is ignored. If this parameter is set with a valid value, the Resync_Periodic parameter is ignored.

Provisioning Parameters

Configuration Profile Parameters

Parameter Name Description and Default Value

Resync_At_Random_Delay (firmware v7.4.9c and higher)

Resync_Periodic The time interval between periodic resyncs

Prevents an overload of the provisioning server when a large number of devices power-on simultaneously.

To avoid flooding resync requests to the server from multiple phones, the phone resyncs in the range between the hours and minutes, and the hours and minutes plus the random delay (hhmm, hhmm+random_delay). For example, if the random delay = (Resync_At_Random_Delay + 30)/60 minutes.

The input value in seconds is converted to minutes, rounding up to the next minute to calculate the final random_delay interval.

This feature is disabled when this parameter is set to zero. The default value is 600 seconds (10 minutes). If the parameter value is set to less than 600, the default value is used.

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 value is 3600 seconds.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 70

Provisioning Parameters

Configuration Profile Parameters

Parameter Name Description and Default Value

Resync_Error_Retry_Delay 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 value is 3600 seconds.

Forced_Resync_Delay Maximum delay (in seconds) the ATA 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 value is 14,400 seconds.

Resync_From_SIP Enables a resync to be triggered via a SIP

NOTIFY message.

The default value is Yes.

Resync_After_Upgrade_Attempt Triggers a resync after every firmware

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 71

upgrade attempt.

The default value is Yes.

Provisioning Parameters

Configuration Profile Parameters

Parameter Name Description and Default Value

Resync_Trigger_1, Resync_Trigger_2

Resync_Fails_On_FNF Determines whether a file-not-found

Profile_Rule This parameter is a profile script that

Configurable resync trigger conditions. A resync is triggered when the logic equation in these parameters evaluates to TRUE.

The default value is (empty).

response from the provisioning server constitutes a successful or a failed resync. A failed resync activates the error resync timer.

The default value is Yes.

evaluates to the provisioning resync command. The command specifies the protocol (TFTP, HTTP, or HTTPS) and an associated URL.

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 value is /spa$PSN.cfg.

Profile_Rule_B, Profile_Rule_C, Profile_Rule_D

Log_Resync_Request_Msg This parameter contains the message that

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 72

Defines second, third, and fourth resync commands and associated profile URLs. These profile scripts are executed sequentially after the 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 value is (empty).

is sent to the syslog server at the start of a resync attempt.

The default value is $PN $MAC – Requesting resync $SCHEME:// $SERVIP:$PORT$PATH.

Provisioning Parameters

Configuration Profile Parameters

Parameter Name Description and Default Value

Log_Resync_Success_Msg The syslog message that is issued upon

Log_Resync_Failure_Msg The syslog message that is issued after a

successful completion of a resync attempt.

The default value is $PN $MAC – Successful resync $SCHEME:// $SERVIP:$PORT$PATH -- $ERR.

failed resync attempt.

The default value is $PN $MAC – Resync failed: $ERR.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 73

Provisioning Parameters

Configuration Profile Parameters

Parameter Name Description and Default Value

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/$MA/ rep.xml.enc

Additionally, this parameter can trigger the reporting of configuration changes (deltas) to the server since the last resync, reboot, or upgrade using the --delta option.

For example, to store delta configuration changes in a file with a name like SPA504G_<MAC>_<serial#>.xml, add the following to your provisioning file:

[ --delta ] http://reportTargetServer/reportPath/ $PN_$MA_$SN.xml </Report_Rule>

The default value is (empty).

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 74

Provisioning Parameters

Firmware Upgrade Parameters

The following table defines the function and usage of each parameter in the Firmware Upgrade section of the Provisioning tab.

Parameter Name Description and Default Value

Upgrade_Enable Enables firmware upgrade operations

Upgrade_Error_Retry_Delay The upgrade retry interval (in seconds) applied

independently of resync actions.

The default value is Yes.

in case of upgrade failure. The device has a firmware upgrade error 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 value 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 value 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 value is (empty).

Log_Upgrade_Request_Msg The syslog message that is issued at the start

of a firmware upgrade attempt.

The default value is $PN $MAC -- Requesting upgrade $SCHEME://$SERVIP:$PORT$PATH.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 75

Provisioning Parameters

General Purpose Parameters

Parameter Name Description and Default Value

Log_Upgrade_Success_Msg The syslog message that is issued after a

firmware upgrade attempt completes successfully.

The default value is $PN $MAC -- Successful upgrade $SCHEME://$SERVIP:$PORT$PATH -$ERR.

Log_Upgrade_Failure_Msg The syslog message that is issued after a failed

firmware upgrade attempt.

The default value is $PN $MAC -- Upgrade failed: $ERR.

General Purpose Parameters

The following table defines the function and usage of each parameter in the General Purpose Parameters section of the Provisioning tab.

Parameter Name Description and Default Value

GPP_SA, GPP_SB, GPP_SC, GPP_SD

Special purpose provisioning parameters, designed to hold encryption keys and passwords. To ensure the integrity of the encryption mechanism, these parameters must be kept 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.

Note that these parameters are not available on the SPA500 Series phones.

The default value is (empty).

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 76

Provisioning Parameters

Macro Expansion Variables

Parameter Name Description and Default Value

GPP_A through GPP_P

Macro Expansion Variables

Certain macro variables are recognized within the following provisioning parameters:

• Profile_Rule

• Profile_Rule_*

• Resync_Trigger_*

• Log_Resync_*

General purpose provisioning parameters. These parameters 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 value is (empty).

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

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 77

Provisioning Parameters

Macro Expansion Variables

Parameter Name Description and Default Value

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

Note that these variables are not available on the SPA500 Series phones.

MA MAC address using lower case hex digits, for example,

000e08aabbcc.

MAU MAC address using upper case hex digits, for example

000E08AABBCC.

MAC MAC address using lower case hex digits, and colons

to separate hex digit pairs, for example 00:0e:08:aa:bb:cc.

PN Product Name, for example SPA962.

PSN Product Series Number, for example 962.

SN Serial Number string, for example 88012BA01234.

CCERT SSL Client Certificate status: Installed or Not Installed.

IP IP address of the ATA within its local subnet, for

example 192.168.1.100.

EXTIP External IP of the ATA, as seen on the Internet, for

SWVER Software version string, for example 2.0.6(b).

HWVER Hardware version string, for example 1.88.1.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 78

example 66.43.16.52.

Provisioning Parameters

Macro Expansion Variables

Parameter Name Description and Default Value

PRVST Provisioning State, a numeric string:

-1 = explicit resync request,

0 = power-up resync,

1 = periodic resync,

2 = resync failed, retry attempt

UPGST Upgrade State, a numeric string:

1 = 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.

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

METH Deprecated alias for SCHEME, do not use.

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

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

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 79

useful in generating result syslog messages. The value is preserved in the UPGERR variable in the case of upgrade attempts.

Provisioning Parameters

Internal Error Codes

Parameter Name Description and Default Value

UID1 The contents of the Line 1 User_ID configuration

UID2 The contents of the Line 2 User_ID configuration

ISCUST Value=1 if unit is customized, 0 otherwise;

Internal Error Codes

The ATA 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.

parameter (Firmware 2.0.11 and above).

customization status viewable on WebUI Info page.

Parameter Name Description and Default Value

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.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 80

Voice Parameters

This chapter describes the voice parameters for the ATAs.

A note about parameter numbering:

Certain types of parameters apply to multiple elements, such as users and lines. In the configuration file, the parameter name is appended with a number, such as <Line_Enable_1_> and <Line_Enable_2_>. To understand this numbering system, use the following key:

• 1—User 1 or Line1 (PHONE1 port, all models)

• 2—User 2 or Line 2 (PHONE2 port, SPA100 Series only)

<Restricted_Access_Domains> This feature is not currently used.

<Enable_Web_Admin_Access> This feature enables or disables access to the configuration

utility from devices that are connected via the ETHERNET (LAN) port. Default setting: Yes (enabled)

<IVR_Admin_Password> Password for the administrator to manage the ATA by using

the built-in IVR through a connected phone.

<Network_Startup_Delay> The number of seconds of delay between restarting the voice

module and initializing network interface. Default setting: 3

<DNS_Query_TTL_Ignore< In DNS packages, the server will suggest a TTL value to the

client; if this parameter is set to yes, the value from the server will be ignored. Default setting: yes

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters

Voice Parameters

<Syslog_Server> Specify the syslog server name and port. This feature

specifies the server for logging ATA system information and critical events. If both Debug Server and Syslog Server are specified, Syslog messages are also logged to the Debug Server. Default setting: blank

<Debug_Server> The debug server name and port. This feature specifies the

server for logging debug information. The level of detailed output depends on the debug level parameter setting. Default setting: blank

<Debug_Level> Determines the level of debug information that will be

generated. Select 0, 1, 2, 3 or 3+Router from the drop-down list. The higher the debug level, the more debug information will be generated. Level 0 means that no information will be collected. Levels 1, 2 & 3 generate messages related to the voice ports only. Level 3+Router generates debug content for both voice and router components. Default setting: 3

<Provision_Enable> Controls all resync actions independently of firmware

upgrade actions. Set to yes to enable remote provisioning. Default setting: yes

<Resync_On_Reset> Triggers a resync after every reboot except for reboots

caused by parameter updates and firmware upgrades. Default setting: yes

<Resync_Random_Delay> The maximum value for a random time interval that the ATA

waits before making its initial contact with the provisioning server. This delay is effective only on the initial configuration attempt following power-on or reset. The delay is a pseudorandom 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 poweron simultaneously. Default setting: 2 (40 seconds)

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 82

Voice Parameters

<Resync_At_HHmm> The time of day when the device tries to resync. The resync is

performed each day. Used in conjunction with the Resync At Random Delay. Default setting: blank

<Resync_At_Random_Delay> Used in conjunction with the Resync At (HHmm) setting, this

parameter sets a range of possible values for the resync delay. The system randomly chooses a value from this range and waits the specified number of seconds before attempting to resync. This feature is intended to prevent the network jam that would occur if all resynchronizing devices began the resync at the exact same time of day. Default setting: 600

<Resync_Periodic> The time interval between periodic resyncs with the

provisioning server. The associated resync timer is active only after the first successful synchronization with the server. Setting this parameter to zero disables periodic resynchronization. Default setting: 3600 seconds

<Resync_Error_Retry_Delay> Resync retry interval (in seconds) applied in case of resync

failure.

The ATA has an error retry timer that activates if the previous attempt to sync with the provisioning server fails. The ATA 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 ATA immediately retries to sync with the provisioning server following a failed attempt. Default setting: 3600 seconds

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 83

Voice Parameters

<Forced_Resync_Delay> Maximum delay (in seconds) that the ATA waits before

performing a resync.

The ATA does not resync while one of its lines is active. Because a resync can take several seconds, it is desirable to wait until the ATA has been idle for an extended period before resynchronizing. This allows a user to make calls in succession without interruption.

The ATA 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. Default setting: 14400 seconds

<Resync_From_SIP> Enables a resync to be triggered via a SIP NOTIFY message.

Default setting: yes

<Resync_After_Upgrade_Attempt> Triggers a resync after every firmware upgrade attempt.

Default setting: yes

<Resync_Trigger_1> <Resync_Trigger_2>

<Resync_Fails_On_FNF> Determines whether a file-not-found response from the

<Profile_Rule> This parameter is a profile script that evaluates to the

Configurable resync trigger conditions. A resync is triggered when the logic equation in these parameters evaluates to TRUE. Default setting: blank

provisioning server constitutes a successful or a failed resync. A failed resync activates the error resync timer. Default setting: yes

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 ATA MAC address. Default setting: /spa$PSN.cfg

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 84

Voice Parameters

<Profile_Rule_B:> <Profile_Rule_C:> <Profile_Rule_D>

<Log_Resync_Request_Msg> This parameter contains the message that is sent to the

<Log_Resync_Success_Msg> Syslog message issued upon successful completion of a

<Log_Resync_Failure_Msg> Syslog message issued after a failed resync attempt.

<Report_Rule> The target URL to which configuration reports are sent. This

Syslog server at the start of a resync attempt. Default setting: $PN $MAC -- Requesting resync $SCHEME:// $SERVIP:$PORT$PATH

resync attempt. Default setting: $PN $MAC -- Successful resync $SCHEME:// $SERVIP:$PORT$PATH

Default setting: $PN $MAC -- Resync failed: $ERR

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/$MA/rep.xml.enc Default setting: blank

<Upgrade_Enable> Determines whether or not firmware upgrade operations can

occur independently of resync actions. Default setting: yes

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 85

Voice Parameters

<Upgrade_Error_Retry_Delay> The upgrade retry interval (in seconds) applied in case of

upgrade failure. The ATA has a firmware upgrade error 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. Default setting: 3600 seconds

<Downgrade_Rev_Limit> Enforces a lower limit on the acceptable version number

during a firmware upgrade or downgrade. The ATA does not complete a firmware upgrade operation unless the firmware version is greater than or equal to this parameter. Default setting: blank

<Upgrade_Rule> This parameter is a firmware upgrade script with the same

syntax as Profile_Rule. Defines upgrade conditions and associated firmware URLs. Default setting: blank

<Log_Upgrade_Request_Msg> Syslog message issued at the start of a firmware upgrade

attempt. Default setting: $PN $MAC -- Requesting upgrade $SCHEME:/ /$SERVIP:$PORT$PATH

<Log_Upgrade_Success_Msg> Syslog message issued after a firmware upgrade attempt

completes successfully. Default setting: $PN $MAC -- Successful upgrade $SCHEME:/ /$SERVIP:$PORT$PATH -- $ERR

<Log_Upgrade_Failure_Msg> Syslog message issued after a failed firmware upgrade

attempt. Default setting: $PN $MAC -- Upgrade failed: $ERR

<License_Keys> This field is not currently used.

<Custom_CA_URL> The URL of a file location for a custom Certificate Authority

(CA) certificate. 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 ATA MAC address. Default setting: null

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 86

Voice Parameters

<GPP_A> to <GPP_P> General purpose provisioning parameters. These parameters

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. Default setting: blank

<GPP_SA> to <GPP_SD> 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.

<Max_Forward> The maximum times a call can be forwarded. The valid range

is from 1 to 255. Default setting: 70

<Max_Redirection> Number of times an invite can be redirected to avoid an

infinite loop. Default setting: 5.

<Max_Auth_> The maximum number of times (from 0 to 255) a request may

be challenged. Default setting: 2

<SIP_User_Agent_Name> The User-Agent header used in outbound requests. If empty,

the header is not included. Macro expansion of $A to $D corresponding to GPP_A to GPP_D allowed. Default setting: $VERSION

<SIP_Server_Name> The server header used in responses to inbound responses.

Default setting: $VERSION

<SIP_Reg_User_Agent_Name> The User-Agent name to be used in a REGISTER request. If

this value is not specified, the SIP User Agent Name parameter is also used for the REGISTER request. Default setting: blank

<SIP_Accept_Language> Accept-Language header used. There is no default (this

indicates that the ATA does not include this header) If empty, the header is not included. Default setting: blank

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 87

Voice Parameters

<DTMF_Relay_MIME_Type> The MIME Type used in a SIP INFO message to signal a DTMF

event. Default setting: application/dtmf-relay.

<Hook_Flash_MIME_Type> The MIME Type used in a SIP INFO message to signal a hook

flash event. Default setting: application/hook-flash

<Remove_Last_Reg> Determines whether or not the ATA removes the last

registration before submitting a new one, if the value is different. Select yes to remove the last registration, or select no to omit this step. Default setting: no

<Use_Compact_Header> Determines whether or not the ATA uses compact SIP

headers in outbound SIP messages. Select yes or no from the drop-down list. Select yes to use compact SIP headers in outbound SIP messages. Select no to use normal SIP headers. If inbound SIP requests contain compact headers, the ATA reuses the same compact headers when generating the response regardless the settings of the Use Compact Header parameter. If inbound SIP requests contain normal headers, the ATA substitutes those headers with compact headers (if defined by RFC 261) if Use Compact Header parameter is set to yes. Default setting: no

<Escape_Display_Name> Determines whether or not the Display Name is private. Select

yes if you want the ATA to enclose the string (configured in the Display Name) in a pair of double quotes for outbound SIP messages. escaped to \" and \\ within the double quotes. Otherwise, select no. Default setting: no

<RFC_2543_Call_Hold> Configures the type of call hold: a:sendonly or 0.0.0.0. Do not

use the 0.0.0.0 syntax in a HOLD SDP; use the a:sendonly syntax. Default setting: no

<Mark_all_AVT_Packets> Select yes if you want all AVT tone packets (encoded for

redundancy) to have the marker bit set for each DTMF event. Select no to have the marker bit set only for the first packet. Default setting: yes

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 88

If the display name includes " or \, these will be

Voice Parameters

<SIP_TCP_Port_Min> The lowest TCP port number that can be used for SIP

sessions. Default setting: 5060

<SIP_TCP_Port_Max> The highest TCP port number that can be used for SIP

sessions. Default setting: 5080

<CTI_Enable> Enables or disables the Computer Telephone Interface feature

provided by some servers. Default setting: no

<SIP_T1> RFC 3261 T1 value (round-trip time estimate), which can

range from 0 to 64 seconds. Default setting: 0.5

<SIP_T2> RFC 3261 T2 value (maximum retransmit interval for non-

INVITE requests and INVITE responses), which can range from 0 to 64 seconds. Default setting: 4

<SIP_T4> RFC 3261 T4 value (maximum duration a message remains in

the network), which can range from 0 to 64 seconds. Default setting: 5

<SIP_Timer_B> INVITE time-out value, which can range from 0 to 64 seconds.

Default setting: 32

<SIP_Timer_F> Non-INVITE time-out value, which can range from 0 to 64

seconds. Default setting: 32

<SIP_Timer_H> H INVITE final response, time-out value, which can range from

0 to 64 seconds. Default setting: 32

<SIP_Timer_D> ACK hang-around time, which can range from 0 to 64

seconds. Default setting: 32

<SIP_Timer_J> Non-INVITE response hang-around time, which can range

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 89

from 0 to 64 seconds. Default setting: 32

Voice Parameters

<INVITE_Expires> INVITE request Expires header value. If you enter 0, the

Expires header is not included in the request. Range: 0–(2 Default setting: 240

<ReINVITE_Expires> ReINVITE request Expires header value. If you enter 0, the

Expires header is not included in the request. Range: 0–(2 Default setting: 30

<Reg_Min_Expires> Minimum registration expiration time allowed from the proxy

in the Expires header or as a Contact header parameter. If the proxy returns a value less than this setting, the minimum value is used. Default setting: 1

<Reg_Max_Expires> Maximum registration expiration time allowed from the proxy

in the Min-Expires header. If the value is larger than this setting, the maximum value is used. Default setting: 7200

–1)

<Reg_Retry_Intvl> Interval to wait before the ATA retries registration after failing

during the last registration. Default setting: 30

<Reg_Retry_Long_Intvl> When registration fails with a SIP response code that does

not match Retry Reg RSC, the ATA waits for the specified length of time before retrying. If this interval is 0, the ATA stops trying. This value should be much larger than the Reg Retry Intvl value, which should not be 0. Default setting: 1200

<Reg_Retry_Random_Delay> Random delay range (in seconds) to add to Register Retry

Intvl when retrying REGISTER after a failure. Default setting: 0 (disabled)

<Reg_Retry_Long_Random_Delay>

Random delay range (in seconds) to add to Register Retry Long Intvl when retrying REGISTER after a failure. Default setting: 0 (disabled)

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 90

Voice Parameters

<Reg_Retry_Intvl_Cap> The maximum value to cap the exponential back-off retry

delay (which starts at Register Retry Intvl and doubles on every REGISTER retry after a failure) In other words, the retry interval is always at Register Retry Intvl seconds after a failure. If this feature is enabled, Reg Retry Random Delay is added on top of the exponential back-off adjusted delay value. Default setting: 0, which disables the exponential backoff feature.

<SIT1_RSC> <SIT2_RSC> <SIT3_RSC> <SIT4_RSC>

<Try_Backup_RSC> SIP response code that retries a backup server for the current

<Retry_Reg_RSC> Interval to wait before the ATA retries registration after failing

<RTP_Port_Min> Minimum port number for RTP transmission and reception.

SIP response status code for the corresponding Special Information Tone (SIT), SIT1 through SIT4. For example, if you set the SIT1 RSC to 404, when the user makes a call and a failure code of 404 is returned, the SIT1 tone is played. Reorder or Busy tone is played by default for all unsuccessful response status code for SIT 1 RSC through SIT 4 RSC. Default setting: blank

request. Default setting: blank

during the last registration. Default setting: blank

The RTP Port Min and RTP Port Max parameters should define a range that contains at least 4 even number ports, such as 100 –106. Default setting: 16384.

<RTP_Port_Max> Maximum port number for RTP transmission and reception.

<RTP_Packet_Size> Packet size in seconds, which can range from 0.01 to 0.16.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 91

Default setting: 16482.

Valid values must be a multiple of 0.01 seconds. Default setting: 0.030

Voice Parameters

<Max_RTP_ICMP_Err> Number of successive ICMP errors allowed when transmitting

RTP packets to the peer before the ATA terminates the call. If value is set to 0, the ATA ignores the limit on ICMP errors. Default setting: 0

<RTCP_Tx_Interval> Interval for sending out RTCP sender reports on an active

connection. It can range from 0 to 255 seconds. During an active connection, the ATA can be programmed to send out compound RTCP packet on the connection. Each compound RTP packet except the last one contains a SR (Sender Report) and a SDES (Source Description) The last RTCP packet contains an additional BYE packet. Each SR except the last one contains exactly 1 RR (Receiver Report); the last SR carries no RR. The SDES contains CNAME, NAME, and TOOL identifiers. The CNAME is set to <User ID>@<Proxy>, NAME is set to <Display Name> (or Anonymous if user blocks caller ID), and TOOL is set to the Vendor/Hardware-platform-softwareversion. The NTP timestamp used in the SR is a snapshot of the local time for the ATA, not the time reported by an NTP server. If the ATA receives a RR from the peer, it attempts to compute the round trip delay and show it as the Call Round Tri p D e la y va lu e (m s) on th e Information page. Default setting: 0

<No_UDP_Checksum> Select yes if you want the ATA to calculate the UDP header

checksum for SIP messages. Otherwise, select no. Default setting: no

<Stats_In_BYE> Determines whether the ATA includes the P-RTP-Stat header

or response in a BYE message. The header contains the RTP statistics of the current call. Select yes or no from the dropdown list. Default setting: yes

The format of the P-RTP-Stat header is:

P-RTP-State: PS=<packets sent>,OS=<octets sent> ,PR=<packets received>,OR=<octets received>,PL=<packets lost>,JI=<jitter in ms>,LA=<delay in ms>,DU=<call duration ins>,EN=<encoder>,DE=<decoder>.

<NSE_Dynamic_Payload> NSE dynamic payload type. The valid range is 96-127.

Default setting: 100

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 92

Voice Parameters

<AVT_Dynamic_Payload> AVT dynamic payload type. The valid range is 96-127.

Default setting: 101

<INFOREQ_Dynamic_Payload /> INFOREQ dynamic payload type.

Default setting: blank

<G726r32_Dynamic_Payload> G726r32 dynamic payload type.

Default setting: 2

<EncapRTP_Dynamic_Payload> EncapRTP Dynamic Payload type.

Default setting: 112

<RTP-Start-Loopback_Dynamic_ Payload>

<RTP-Start-Loopback_Codec> RTP-Start-Loopback Codec. Select one of the following:

<NSE_Codec_Name> NSE codec name used in SDP.

<AVT_Codec_Name> AVT codec name used in SDP.

<G711u_Codec_Name> G.711u codec name used in SDP.

<G711a_Codec_Name> G.711a codec name used in SDP.

<G726r32_Codec_Name> G.726-32 codec name used in SDP.

<G729a_Codec_Name> G.729a codec name used in SDP.

RTP-Start-Loopback Dynamic Payload type. Default setting: 113

G711u, G711a, G726-32, G729a. Default setting: G711u

Default setting: NSE

Default setting: telephone-event

Default setting: PCMU

Default setting: PCMA

Default setting: G726-32

Default setting: G729a

<G722_Codec_Name> G.722 codec name used in SDP.

<EncapRTP_Codec_Name> EncapRTP codec name used in SDP.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 93

Default setting: G722

Default setting: encaprtp

Voice Parameters

<Handle_VIA_received> If you select yes, the ATA processes the received parameter

in the VIA header (this value is inserted by the server in a response to any one of its requests) If you select no, the parameter is ignored. Select yes or no from the drop-down menu. Default setting: no

<Handle_VIA_rport> If you select yes, the ATA processes the rport parameter in

the VIA header (this value is inserted by the server in a response to any one of its requests) If you select no, the parameter is ignored. Select yes or no from the drop-down menu. Default setting: no

<Insert_VIA_received> Inserts the received parameter into the VIA header of SIP

responses if the received-from IP and VIA sent-by IP values differ. Select yes or no from the drop-down menu. Default setting: no

<Insert_VIA_rport> Inserts the rport parameter into the VIA header of SIP

responses if the received-from IP and VIA sent-by IP values differ. Select yes or no from the drop-down menu. Default setting: no

<Substitute_VIA_Addr> Lets you use NAT-mapped IP:port values in the VIA header.

Select yes or no from the drop-down menu. Default setting: no

<Send_Resp_To_Src_Port> Sends responses to the request source port instead of the

VIA sent-by port. Select yes or no from the drop-down menu. Default setting: no

<STUN_Enable> Enables the use of STUN to discover NAT mapping. Select

yes or no from the drop-down menu. Default setting: no

<STUN_Test_Enable> If the STUN Enable feature is enabled and a valid STUN server

is available, the ATA can perform a NAT-type discovery operation when it powers on. It contacts the configured STUN server, and the result of the discovery is reported in a Warning header in all subsequent REGISTER requests. If the ATA detects symmetric NAT or a symmetric firewall, NAT mapping is disabled. Default setting: no

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 94

Voice Parameters

<STUN_Server> IP address or fully-qualified domain name of the STUN server

to contact for NAT mapping discovery. Default setting: blank

<EXT_IP> External IP address to substitute for the actual IP address of

the ATA in all outgoing SIP messages. If 0.0.0.0 is specified, no IP address substitution is performed.

If this parameter is specified, the ATA assumes this IP address when generating SIP messages and SDP (if NAT Mapping is enabled for that line) However, the results of STUN and VIA received parameter processing, if available, supersede this statically configured value.

This option requires that you have (1) a static IP address from your Internet Service Provider and (2) an edge device with a symmetric NAT mechanism. If the ATA is the edge device, the second requirement is met. Default setting: blank

<EXT_RTP_Port_Min> External port mapping number of the RTP Port Min. number. If

this value is not zero, the RTP port number in all outgoing SIP messages is substituted for the corresponding port value in the external RTP port range. Default setting: blank

<NAT_Keep_Alive_Intvl> Interval between NAT-mapping keep alive messages.

Default setting: 15

<Redirect_Keep_Alive> Interval between NAT Redirect keep alive messages.

Default setting: 15

<Linksys_Key_System> To enable operation with the Cisco SPA9000, choose yes.

Otherwise, choose no. Default setting: no

<Multicast_Address> The multicast address for devices in the Cisco SPA9000 voice

network. Default setting: 224.168.168.168:6061

<Key_System_Auto_Discovery> To enable auto-discovery of the Cisco SPA9000 voice

system, choose yes. Otherwise, choose no. Default setting: yes

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 95

Voice Parameters

<Key_System_IP_Address> The IP address of the Cisco SPA9000.

Default setting: blank

<Force_LAN_Codec> If needed, specify a voice codec.

Default setting: none

<Line_Enable_1_> <Line_Enable_2_>

<Line_Enable_5_> through <Line_ Enable_13_>

<SAS_Enable_1_> <SAS_Enable_2_>

<SAS_DLG_Refresh_Intvl_1_>

<SAS_DLG_Refresh_Intvl_2_>

To enable this line for service, select yes. Otherwise, select no. Default setting: yes

To enable the use of the line as a streaming audio source, select yes. Otherwise, select no. If enabled, the line cannot be used for outgoing calls. Instead, it auto-answers incoming calls and streams audio RTP packets to the caller. Default setting: no

If this value is not zero, it is the interval at which the streaming audio server sends out session refresh (SIP re-INVITE) messages to determine whether the connection to the caller is still active. If the caller does not respond to the refresh message, the ATA ends this call with a SIP BYE message. The range is 0 to 255 seconds (0 means that the session refresh is disabled) Default setting: 30

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 96

Voice Parameters

<SAS_Inbound_RTP_Sink_1_> <SAS_Inbound_RTP_Sink_2_>

<NAT_Mapping_Enable_1_> through <NAT_Mapping_Enable_13_>

The purpose of this parameter is to work around devices that do not play inbound RTP if the SAS line declares itself as a send-only device and tells the client not to stream out audio. This parameter is an FQDN or IP address of an RTP sink to be used by the SAS line in the SDP of its 200 response to inbound INVITE from a client. It will appear in the c = line and the port number, if specified, will appear in the m = line of the SDP. If this value is not specified or is equal to 0, then c =

0.0.0.0 and a=sendonly will be used in the SDP to tell the SAS client to not to send any RTP to this SAS line. If a non-zero value is specified, then a=sendrecv and the SAS client will stream audio to the given address. Special case: If the value is $IP, then the SAS line’s own IP address is used in the c = line and a=sendrecv. In that case the SAS client will stream RTP packets to the SAS line. Default setting: blank

To use externally mapped IP addresses and SIP/RTP ports in SIP messages, select yes. Otherwise, select no. Default setting: no

<NAT_Keep_Alive_Enable_1_> through <NAT_Keep_Alive_Enable_13_>

<NAT_Keep_Alive_Msg_1_> through <NAT_Keep_Alive_Msg_13_>

<NAT_Keep_Alive_Dest_1_> through <NAT_Keep_Alive_Dest_13_>

To send the configured NAT keep alive message periodically, select yes. Otherwise, select no. Default setting: no

Enter the keep alive message that should be sent periodically to maintain the current NAT mapping. If the value is $NOTIFY, a NOTIFY message is sent. If the value is $REGISTER, a REGISTER message without contact is sent. Default setting: $NOTIFY

Destination that should receive NAT keep alive messages. If the value is $PROXY, the messages are sent to the current proxy server or outbound proxy server. Default setting: $PROXY

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 97

Voice Parameters

<Blind_Attn-Xfer_Enable_1_> <Blind_Attn-Xfer_Enable_2_>

<MOH_Server_1_> <MOH_Server_2_>

<Xfer_When_Hangup_Conf_1_> <Xfer_When_Hangup_Conf_2_>

<Conference_Bridge_URL_1_> <Conference_Bridge_URL_2_>

Enables the ATA to perform an attended transfer operation by ending the current call leg and performing a blind transfer of the other call leg. If this feature is disabled, the ATA performs an attended transfer operation by referring the other call leg to the current call leg while maintaining both call legs. To use this feature, select yes. Otherwise, select no. Default setting: no

User ID or URL of the auto-answering streaming audio server. When only a user ID is specified, the current or outbound proxy is contacted. Music-on-hold is disabled if the MOH Server is not specified. Default setting: blank

Makes the ATA perform a transfer when a conference call has ended. Select yes or no from the drop-down menu. Default setting: yes

This feature supports external conference bridging for n-way conference calls (n>2), instead of mixing audio locally. To use this feature, set this parameter to that of the server's name. For example: conf@mysefver.com:12345 or conf (which uses the Proxy value as the domain). Default setting: blank

<Conference_Bridge_Ports_1_> <Conference_Bridge_Ports_2_>

<Enable_IP_Dialing_1_> <Enable_IP_Dialing_2_>

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 98

Select the maximum number of conference call participants. The range is 3 to 10. Default setting: 3

Enable or disable IP dialing. If IP dialing is enabled, one can dial [userid@] a.b.c.d[:port], where ‘@’, ‘.’, and ‘:’ are dialed by entering *, user-id must be numeric (like a phone number) and a, b, c, d must be between 0 and 255, and port must be larger than 255. If port is not given, 5060 is used. Port and User-Id are optional. If the user-id portion matches a pattern in the dial plan, then it is interpreted as a regular phone number according to the dial plan. The INVITE message, however, is still sent to the outbound proxy if it is enabled. Default setting: no

Voice Parameters

<Emergency_Number_1_> <Emergency_Number_2_>

<Mailbox_ID_1_> <Mailbox_ID_2_>

<Proxy_1_> through <Proxy_13_> SIP proxy server for all outbound requests.

<Outbound_Proxy_1_> through <Outbound_Proxy_13_>

<Use_Outbound_Proxy_1_> through <Use_Outbound_Proxy_13_>

Comma separated list of emergency number patterns. If outbound call matches one of the pattern, the ATA will disable hook flash event handling. The condition is restored to normal after the call ends. Blank signifies that there is no emergency number. Maximum number length is 63 characters. Default setting: blank

Enter the ID number of the mailbox for this line. Default setting: blank

Default setting: blank

SIP Outbound Proxy Server where all outbound requests are sent as the first hop. Default setting: blank

Enables the use of an Outbound Proxy. If set to no, the Outbound Proxy and Use OB Proxy in Dialog parameters are ignored. Default setting: no

<Use_OB_Proxy_In_Dialog_1_> through <Use_OB_Proxy_In_Dialog_13_>

<Register_1_> through <Register_13_> Enable periodic registration with the Proxy parameter. This

<Make_Call_Without_Reg_1_> through <Make_Call_Without_Reg_13_>

<Register_Expires_1_> through <Register_Expires_13_>

Whether to force SIP requests to be sent to the outbound proxy within a dialog. Ignored if the parameter Use Outbound Proxy is no, or the Outbound Proxy parameter is empty. Default setting: yes

parameter is ignored if Proxy is not specified. Default setting: yes

Allow making outbound calls without successful (dynamic) registration by the unit. If No, dial tone will not play unless registration is successful. Default setting: no

Expires value in sec in a REGISTER request. The ATA will periodically renew registration shortly before the current registration expired. This parameter is ignored if the Register parameter is no. Range: Default setting: 3600

0 – (2

– 1) sec.

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 99

Voice Parameters

<Ans_Call_Without_Reg_1_> through <Ans_Call_Without_Reg_13_>

<Use_DNS_SRV_1_> through <Use_ DNS_SRV_13_>

<DNS_SRV_Auto_Prefix_1_> through <DNS_SRV_Auto_Prefix_13_>

<Proxy_Fallback_Intvl_1_> through <Proxy_Fallback_Intvl_13_>

Allow answering inbound calls without successful (dynamic) registration by the unit. Default setting: no

Whether to use DNS SRV lookup for Proxy and Outbound Proxy. Default setting: no

If enabled, the ATA will automatically prepend the Proxy or Outbound Proxy name with _sip._udp when performing a DNS SRV lookup on that name. Default setting: no

After failing over to a lower priority server, the ATA waits for the specified Proxy Fallback Interval, in seconds, before retrying the highest priority proxy (or outbound proxy) servers. This parameter is useful only if the primary and backup proxy server list is provided to the ATA via DNS SRV record lookup on the server name. (Using multiple DNS A records per server name does not allow the notion of priority, so all hosts will be considered at the same priority and the ATA will not attempt to fall back after a failover.) Default setting: 3600

<Proxy_Redundancy_Method_1_> through <Proxy_Redundancy_Method_ 13_>

<Mailbox_Subscribe_URL_1_> <Mailbox_Subscribe_URL_2_>

<Mailbox_Subscribe_URL_5_> through <Mailbox_Subscribe_URL_13_>

<Mailbox_Subscribe_Expires_1_> through <Mailbox_Subscribe_Expires_ 13_>

The method that the ATA uses to create a list of proxies returned in the DNS SRV records. If you select Normal, the list will contain proxies ranked by weight and priority. If you select Based on SRV port, the ATA also inspects the port number based on 1st proxy’s port. Default setting: Normal

The URL or IP address of the voicemail server. Default setting: blank

The subscription interval for voicemail message waiting indication. When this time period expires, the ATA sends another subscribe message to the voice mail server. Default: 2147483647

Provisioning Guide for Cisco SPA100 and SPA200 Series Analog Telephone Adapters 100

Cisco SPA1112, SPA232D, SPA122 Provisioning Manual

Specifications and Main Features

Frequently Asked Questions

User Manual