Configure your phone for profile resync

Resync the phone profile over TFTP

The phone supports multiple network protocols for retrieving configuration profiles. The most basic profile transfer protocol is TFTP (RFC1350). TFTP is widely used for the provisioning of network devices within private LAN networks. Although not recommended for the deployment of remote endpoints across the Internet, TFTP can be convenient for deployment within small organizations, for in-house preprovisioning, and for development and testing. In the following procedure, a profile is modified after downloading a file from a TFTP server.

1

Within a LAN environment, connect your computer and the phone to a hub, switch, or small router.

2

On the computer, install and activate a TFTP server.

3

Use a text editor to create a configuration profile.

To verify if the profile has been provisioned to your phone later, you can set some of the values as marks. For example, set the value for GPP_A to 12345678 as shown in the following example:

<flat-profile>
  <GPP_A> 12345678
  </GPP_A>
</flat-profile>
4

Save the XML configuration file in the root directory of the TFTP server.

You can verify that the TFTP server is properly configured: request the configuration profile file by using a TFTP client other than the phone. Preferably, use a TFTP client that is running on a separate host from the provisioning server.

5

In the web browser on your computer, open the administration web page. For example, assume the IP address of the phone is 192.168.1.100, open the following URL in your web browser:


http://192.168.1.100/admin/advanced
6

Select the Voice > Provisioning tab, and inspect the values of the general purpose parameters GPP_A through GPP_P. These should be empty.

7

Resync the test phone to the configuration profile that you created by opening the resync URL in a web browser.

Example:

If the IP address of the TFTP server is 192.168.1.200, the command should be similar to the following example:


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

When the phone receives this command, the device at address 192.168.1.100 requests the configuration profile file basic.txt from the TFTP server at IP address 192.168.1.200. The phone then parses the downloaded file and updates the GPP_A parameter with the value 12345678.

8

Verify that the parameter was correctly updated. Refresh the administration web page and go to Voice > Provisioning.

The GPP_A parameter should now contains the value 12345678.

Provision a phone-specific profile on a TFTP server
1

Obtain the MAC address of the phone from its product label. (The MAC address is the number, using numbers and lower–case hex digits, for example, 000e08aabbcc.

2

Rename your configuration file to CP-xxxx macaddress.cfg (replacing xxxx with the model number and macaddress with the MAC address of the phone).

Example:

CP-8875 000e08aabbcc.cfg

3

Move the new file to the virtual root directory of the TFTP server.

4

Access the phone administration web page.

5

Select Voice  > Provisioning.

6

Enter the path of the profile file in the Profile Rule field.

Example: Assume that the TFTP server IP address is 192.168.1.200 and the profile file name is 


<Profile_Rule>
tftp://192.168.1.200/CP-8875$MA.cfg
</Profile_Rule>
7

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

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

Resync the phone profile with HTTP GET
1

Install an HTTP server on the local computer or other accessible host.

The open source Apache server can be downloaded from the internet.

2

Upload the configuration profile file onto the virtual root directory of the installed server.

3

To verify proper server installation and access to the profile file, open the profile with a web browser.

4

Modify the Profile_Rule of the test phone to point to the HTTP server in place of the TFTP server, so as to download its profile periodically.

For example, assuming the HTTP server is at 192.168.1.300 and the profile filename is basic.txt, enter the following value:

<Profile_Rule>
http://192.168.1.200/basic.txt
</Profile_Rule>
5

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

6

Observe the syslog messages that the phone sends. The periodic resyncs should now be obtaining the profile from the HTTP server.

7

In the HTTP server logs, observe how information that identifies the test phone appears in the log of user agents.

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

Resync the phone profile automatically

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

1

Access the phone administration web page.

2

Select Voice  > Provisioning.

3

Define the Profile_Rule parameter. This example assumes a TFTP server IP address of 192.168.1.200.

4

In the Resync Periodic field, enter a small value for testing, such as 30 seconds.

5

Click Submit all Changes.

With the new parameter settings, the phone resyncs twice a minute to the configuration file that the URL specifies.

6

Observe the resulting messages in the syslog trace.

7

Ensure that the Resync On Reset field is set to Yes.


<Resync_On_Reset>Yes</Resync_On_Reset>
8

Power cycle the phone to force it to resync to the provisioning server.

If the resync operation fails for any reason, such as if the server is not responding, the unit waits (for the number of seconds configured in Resync Error Retry Delay) before it attempts to resync again. If Resync Error Retry Delay is zero, the phone does not try to resync after a failed resync attempt.

9

(Optional) Set the value of Resync Error Retry Delay field to a small number, such as 30.


<Resync_Error_Retry_Delay>30</Resync_Error_Retry_Delay>
10

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

Profile resync parameters

The following table defines the function and usage of the profile resync parameters in the Configuration Profile section under the Voice > Provisioning tab in the phone web page. It also defines the syntax of the string that is added in the phone configuration file (cfg.xml) with XML code to configure a parameter.

Table 1. Profile resync parameters

Parameter

Description

Provision Enable

Allows or denies configuration profile resync actions.

  • In the phone configuration file (cfg.xml) with XML, enter a string in this format:

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

  • On the phone web page, set this field to Yes to allow resync actions, or No to block resync actions.

Default: Yes

Resync On Reset

Specifies whether the phone resynchronizes configurations with the provisioning server after power-up and after each upgrade attempt.

  • In the phone configuration file (cfg.xml) with XML, enter a string in this format:

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

  • On the phone web page, set this field to Yes to allow resync on power-up or reset, or No to block resync on power-up or reset.

Default: 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 0 and this value.

This parameter is in units of 20 seconds.

The valid value ranges between 0 and 65535.

  • In the phone configuration file (cfg.xml) with XML, enter a string in this format:

    <Resync_Random_Delay ua="na">2</Resync_Random_Delay>

  • On the phone web page, specify the number of the units (20 seconds) for the phone to delay resync after power-up or reset.

The default value is 2 (40 seconds).

Resync At (HHmm)

The time (HHmm) that the phone resynchronizes with the provisioning server.

The value for this field must be a four-digit number ranging from 0000 to 2400 to indicate the time in HHmm format. For example, 0959 indicates 09:59.

  • In the phone configuration file (cfg.xml) with XML, enter a string in this format:

    <Resync_At__HHmm_ ua="na">0959</Resync_At__HHmm_>

  • On the phone web page, specify the time in HHMM format for the phone to start resync.

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.

Resync At Random Delay

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

  • In the phone configuration file (cfg.xml) with XML, enter a string in this format:

    <Resync_At_Random_Delay ua="na">600</Resync_At_Random_Delay>

  • On the phone web page, specify the time period in seconds.

The valid value ranges between 600 and 65535.

If the value is less than 600, the random delay internal is between 0 and 600.

The default value is 600 seconds (10 minutes).

Resync Periodic

The time interval between periodic resynchronization with the provisioning server. The associated resync timer is active only after the first successful sync with the server.

The valid formats are as follows:

  • An integer

    Example: An input of 3000 indicates that the next resync occurs in 3000 seconds.

  • Multiple integers

    Example: An input of 600,1200,300 indicates that the first resync occurs in 600 seconds, the second resync occurs in 1200 seconds after the first one, and the third resync occurs in 300 seconds after the second one.

  • A time range

    Example, an input of 2400+30 indicates that the next resync occurs in between 2400 and 2430 seconds after a successful resync.

  • In the phone configuration file (cfg.xml) with XML, enter a string in this format:

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

  • On the phone web page, specify the time period in seconds.

Set this parameter to zero to disable periodic resynchronization.

The default value is 3600 seconds.

Resync Error Retry Delay

If a resync operation fails because the phone was unable to retrieve a profile from the server, or the downloaded file is corrupt, or an internal error occurs, the phone tries to resync again after a time specified in seconds.

The valid formats are as follows:

  • An integer

    Example: An input of 300 indicates that the next retry for resync occurs in 300 seconds.

  • Multiple integers

    Example: An input of 600,1200,300 indicates that the first retry occurs in 600 seconds after the failure, the second retry occurs in 1200 seconds after the failure of the first retry, and the third retry occurs in 300 seconds after the failure of the second retry.

  • A time range

    Example, an input of 2400+30 indicates that the next retry occurs in between 2400 and 2430 seconds after a resync failure.

If the delay is set to 0, the device does not try to resync again following a failed resync attempt.

  • In the phone configuration file (cfg.xml) with XML, enter a string in this format:

    <Resync_Error_Retry_Delay ua="na">60,120,240,480,960,1920,3840,7680,15360,30720,61440,86400</Resync_Error_Retry_Delay>

  • On the phone web page, specify the time period in seconds.

Default: 60,120,240,480,960,1920,3840,7680,15360,30720,61440,86400

Forced Resync Delay

Maximum delay (in seconds) the phone waits before performing a resynchronization.

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 resynchronizing. 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 valid value ranges between 0 and 65535.

  • In the phone configuration file (cfg.xml) with XML, enter a string in this format:

    <Forced_Resync_Delay ua="na">14400</Forced_Resync_Delay>

  • On the phone web page, specify the time period in seconds.

The default value is 14,400 seconds.

Resync From SIP

Controls requests for resync operations via a SIP NOTIFY event sent from the service provider proxy server to the phone. If enabled, the proxy can request a resync by sending a SIP NOTIFY message containing the Event: resync header to the device.

  • In the phone configuration file (cfg.xml) with XML, enter a string in this format:

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

  • On the phone web page, select Yes to enable this feature, or No to disalbe it.

Default: Yes

Resync After Upgrade Attempt

Enables or disables the resync operation after any upgrade occurs. If Yes is selected, sync is triggered after a firmware upgrade.

  • In the phone configuration file (cfg.xml) with XML, enter a string in this format:

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

  • On the phone web page, select Yes to trigger resync after a firmware upgrade, or No to not resync.

Default: Yes

Resync Trigger 1

Resync Trigger 2

If the logical equation in these parameters evaluates to FALSE, resync is not triggered even when Resync On Reset is set to TRUE. Only the resync via direct action URL and SIP notify ignores these resync triggers.

The parameters can be programmed with a conditional expression that undergoes macro expansion. For the valid macro expansions, see Macro expansion variables under Provisioning parameters.

  • In the phone configuration file (cfg.xml) with XML, enter a string in this format:

    <Resync_Trigger_1 ua="na">$UPGTMR gt 300 and $PRVTMR ge 600</Resync_Trigger_1>

    <Resync_Trigger_2 ua="na"/>

  • On the phone web page, specify the triggers.

Default: Blank

User Configurable Resync

Allows a user to resync the phone from the phone screen menu. When set to Yes, a user can resync the phone configuration by entering the profile rule from the phone. When set to No, the Profile rule parameter isn't displayed on the phone screen menu.

  • In the phone configuration file (cfg.xml) with XML, enter a string in this format:

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

  • On the phone web page, select Yes to show the Profile rule parameter on the phone menu, or select No to hide this parameter.

Default: Yes

Resync Fails On FNF

A resync is typically considered unsuccessful if a requested profile is not received from the server. This parameter override this behavior. When set to No, the device accepts a file-not-found response from the server as a successful resync.

  • In the phone configuration file (cfg.xml) with XML, enter a string in this format:

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

  • On the phone web page, select Yes to take a file-not-found response as an unsuccessful resync, or select No to take a file-not-found response as a successful resync.

Default: Yes

Profile Authentication Type

Specifies the credentials to use for profile account authentication. The available options are:

  • Disabled: Disables the profile account feature. When this feature is disabled, the Profile account setup menu doesn't display on the phone screen.

  • Basic HTTP Authentication: The HTTP login credentials are used to authenticate the profile account.

  • XSI Authentication: XSI login credentials or XSI SIP credentials are used to authenticate the profile account. The authentication credentials depend on the XSI Authentication Type for the phone:

    • When the XSI Authentication Type for the phone is set to Login Credentials, the XSI login credentials are used.

    • When the XSI Authentication Type for the phone is set to SIP Credentials, the XSI SIP credentials are used.

  • In the phone configuration file (cfg.xml) with XML, enter a string in this format:

    <Profile_Authentication_Type ua="na">Basic Http Authentication</Profile_Authentication_Type>

  • On the phone web page, select an option from the list for the phone to authenticate profile resync.

Default: Basic HTTP Authentication

For more information, see Specify the profile authentication type under Specify the phone for profile resync.

Profile Rule

Profile Rule B

Profile Rule C

Profile Rule D

Each profile rule informs the phone of a source from which to obtain a profile (configuration file). During every resync operation, the phone applies all the profiles in sequence.

If you are applying AES-256-CBC encryption to the configuration files, specify the encryption key with the --key keyword as follows:

[--key <encryption key>]

You can enclose the encryption key in double-quotes (") optionally.

  • In the phone configuration file (cfg.xml) with XML, enter a string in this format:

    <Profile_Rule ua="na">/$PSN.xml</Profile_Rule>

    <Profile_Rule_B ua="na"/>

    <Profile_Rule_C ua="na"/>

    <Profile_Rule_D ua="na"/>

  • On the phone web page, specify the profile rule.

Default: /$PSN.xml

DHCP Option To Use

DHCP options, delimited by commas, used to retrieve firmware and profiles.

Default: 66,160,159,150,60,43,125

DHCPv6 Option To Use

DHCP options, delimited by commas, used to retrieve firmware and profiles.

Default: 17,160,159

Provisioning through Cisco XML

You can provision phones through Cisco XML functions.

You can send an XML object to the phone by a SIP Notify packet or an HTTP Post to the CGI interface of the phone: http://PhoneIPAddress/CGI/Execute.

The CP-xxxx-3PCC extends the Cisco XML feature to support provisioning via an XML object:


<CP-xxxx-3PCCExecute>
        <ExecuteItem URL=Resync:[profile-rule]/>
</CP-xxxx-3PCCExecute>

After the phone receives the XML object, it downloads the provisioning file from [profile-rule]. This rule uses macros to simplify the development of the XML services application.

URL resolution with macro expansion

Subdirectories with multiple profiles on the server provide 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 phone performs a DNS lookup to resolve the name.

  • A nonstandard server port that is 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 file ($PN.cfg), in the server subdirectory /cisco/config, from the TFTP server that is running on host prov.telco.com listening for a connection on port 6900: 


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

A profile for each phone 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 phone 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
Specify the profile authentication type

Profile Authentication allows phone users to resynchronize the provisioning profile onto the phone. Authentication information is required while the phone tries to resynchronize and download configuration file for the first time and gets an HTTP or HTTPS 401 authentication error. When you enable this feature, the Profile account setup screen is displayed on the phone for the following situations:

  • When the HTTP or HTTPs 401 authentication error occurs during first-time provisioning after the phone reboots

  • When the profile account username and password are empty

  • When there are no username and password in the Profile Rule

If the Profile account setup screen is missed or ignored, the user can also access the setup screen through the phone screen menu, or the Setup softkey, which displays only when no line on the phone is registered.

When you disable the feature, the Profile account setup screen doesn't display on the phone.

The username and password in the Profile Rule field have a higher priority than the profile account.

  • When you provide a correct URL in the Profile Rule field without a username and password, the phone requires authentication or digest to resynchronize the profile. With the correct profile account, authentication passes. With an incorrect profile account, authentication fails.

  • When you provide a correct URL in the Profile Rule field with a correct username and password, the phone requires authentication or digest to resynchronize the profile. The profile account is not used for phone resynchronization. Sign-in is successful.

  • When you provide a correct URL in the Profile Rule field with an incorrect username and password, the phone requires authentication or digest to resynchronize the profile. The profile account isn't used for phone resynchronization. Sign-in always fails.

  • When you provide an incorrect URL in the Profile Rule field, sign-in always fails.

You can also configure the parameters in the phone configuration file with XML(cfg.xml) code.

You can specify the profile authentication type from the phone administration web page.

1

Access the phone administration web page.

2

Select Voice > Provisioning.

3

In the Configuration Profile section, set the Profile Authentication Type parameter to specify the credentials to use for profile account authentication.

You can configure this parameter in the phone configuration XML file (cfg.xml) by entering a string in this format:

<Profile_Authentication_Type ua="na">Disabled</Profile_Authentication_Type>

Options:

  • Disabled: Disables the profile account feature.When this feature is disabled, the Profile account setup menu doesn't display on the phone screen.

  • Basic HTTP Authentication: The HTTP login credentials are used to authenticate the profile account.

  • XSI Authentication: XSI login credentials or XSI SIP credentials are used to authenticate the profile account. The authentication credentials depend on the XSI Authentication Type for the phone:

    When the XSI Authentication Type for the phone is set to Login Credentials, the XSI login credentials are used.

    When the XSI Authentication Type for the phone is set to SIP Credentials, the XSI SIP credentials are used.

Default: Basic HTTP Authentication

4

Click Submit All Changes.

Manually apply a profile to your phone

Download the configuration file to the phone from a TFTP server

Complete these steps to download the configuration file to a TFTP server application on your PC.

1

Connect your computer to the LAN port of the phone.

2

Run a TFTP server application on the computer and ensure that the configuration file is available in the TFTP root directory.

3

In a web browser, enter the phone LAN IP address, the IP address of the computer, the filename, and the login credentials. Use 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
Download the configuration file to the phone with cURL

Complete these steps to download the configuration to the phone by using cURL. This command-line tool is used to transfer data with a URL syntax. To download cURL, visit:

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

We recommend that you don't use cURL to post the configuration to the phone because the username and password might get captured while using cURL.

1

Connect your computer to the LAN port of the phone.

2

Download the configuration file to the phone by entering the following cURL command:

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

Configuration Profiles

The phone accepts configurations in XML format.

The examples in this section use configuration profiles with XML syntax.

Configuration profile formats

The configuration profile defines the parameter values for the phone.

The configuration profile XML format uses standard XML authoring tools to compile the parameters and values.

Only the UTF-8 charset is supported. If you modify the profile in an editor, do not change the encoding format; otherwise, the phone cannot recognize the file.

Each phone has a different feature set and therefore, a different set of parameters.

Open profile format

The open format 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. An XML configuration file can be sent from the provisioning server to the phone during a resync operation, without compilation as a binary object.

The phone can accept configuration formats that standard tools generate. This feature eases the development of back-end provisioning server software that generates configuration profiles from existing databases.

To protect confidential information in the configuration profile, the provisioning server delivers the XML configuration file to the phone over a channel secured by TLS. Optionally, the file can be compressed by using the gzip deflate algorithm (RFC1951).

The file can be encrypted with one of these encryption methods:

  • AES-256-CBC encryption

  • RFC-8188 based HTTP content encryption with AES-128-GCM ciphering

A configuration file can include these components:

  • Element tags

  • Attributes

  • Parameters

  • Formatting features

  • XML comments

Example: Open profile format


<flat-profile>
<Resync_On_Reset> Yes </Resync_On_Reset>
<Resync_Periodic> 7200 </Resync_Periodic>
<Profile_Rule> tftp://prov.telco.com:6900/cisco/config/CP_xxxx_MPP.cfg</Profile_Rule>
</flat-profile>

The <flat-profile> element tag encloses all parameter elements that the phone recognizes.

Element tag properties

Keep the following rules in mind when you create or update the configuration file.

  • The XML provisioning format and the Web UI allow the configuration of the same settings. The XML tag names and the field names in the Web UI are similar but vary due to XML element name restrictions. For example, underscores ( _ ) in XML configuration file instead of spaces on the Web UI.

  • The phone recognizes elements with proper parameter names that are encapsulated in the special <flat-profile> element.

  • Element names are enclosed in angle brackets.

  • Most element names are similar to the field names on the phone Web UI, with the following modifications:

    • Element names may not include spaces or special characters. To derive the element name from the web field name, substitute an underscore for every space or the special characters [, ], (, ), or /.

      Example: The <Resync_On_Reset> element represents the Resync On Reset field.

    • Each element name must be unique. In the phone Web UI, the same fields can appear on multiple web pages, such as the Line, User, and Extension pages. Append [n] to the element name to indicate the number that is shown in the page tab.

      Example: The <Dial_Plan_1_> element represents the Dial Plan for Line 1.

  • Each opening element tag must have a matching closing element tag. For example:

    
<flat-profile>
<Resync_On_Reset> Yes
  </Resync_On_Reset>
<Resync_Periodic> 7200
  </Resync_Periodic>
<Profile_Rule>tftp://prov.telco.com: 6900/cisco/config/CP_xxxx_MPP.cfg
  </Profile_Rule>
</flat-profile>

  • Element tags are case-sensitive.

  • Empty element tags are allowed and will be interpreted as configuring the value to be empty. Enter the opening element tag without a corresponding element tag, and insert a space and a forward slash before the closing angle bracket (>). In this example, Profile Rule B is empty:

    
<Profile_Rule_B />

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

    <flat-profile>
<Speed_Dial_2_Name ua="rw"/>
<Speed_Dial_2_Number ua="rw"/>
<Speed_Dial_3_Name ua="rw"/>
<Speed_Dial_3_Number ua="rw"/>
<Speed_Dial_4_Name ua="rw"/>
<Speed_Dial_4_Number ua="rw"/>
<Speed_Dial_5_Name ua="rw"/>
<Speed_Dial_5_Number ua="rw"/>
<Speed_Dial_6_Name ua="rw"/>
<Speed_Dial_6_Number ua="rw"/>
<Speed_Dial_7_Name ua="rw"/>
<Speed_Dial_7_Number ua="rw"/>
<Speed_Dial_8_Name ua="rw"/>
<Speed_Dial_8_Number ua="rw"/>
<Speed_Dial_9_Name ua="rw"/>
<Speed_Dial_9_Number ua="rw"/>
</flat-profile>

  • Use an empty value 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>

  • Unrecognized element names are ignored.

Parameter properties

These properties apply to the parameters:

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

  • Unrecognized parameters are ignored.

  • If the Open format profile contains multiple occurrences of the same parameter tag, the last such occurrence overrides any earlier ones. To avoid inadvertent override of configuration values for a parameter, we recommend that each profile specify at most one instance of a parameter.

  • The last profile processed takes precedence. If multiple profiles specify the same configuration parameter, the value of the latter profile takes precedence.

String formats

These properties apply to the formatting of the strings:

  • Comments are allowed through standard XML syntax.

    <!-- My comment is typed here -->

  • Leading and trailing white space is allowed for readability but is removed from the parameter value.

  • New lines within a value are converted to spaces.

  • An XML header of the form <? ?> is allowed, but the phone ignores it.

  • To enter special characters, use basic XML character escapes, as shown in the following table.

    Special Character

    XML Escape Sequence

    & (ampersand)

    &amp;

    < (less than)

    &lt;

    > (greater than)

    &gt;

    ’ (apostrophe)

    &apos;

    ” (double quote)

    &quot;

    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 (Admin Login > advanced > Voice > Ext (n)) equal to (S0 <:18005551212>).

    
<flat-profile>
 <Dial_Plan_1_>
  (S0 &lt;:18005551212&gt;)
 </Dial_Plan_1_>
</flat-profile>

  • Numeric character escapes, using decimal and hexadecimal values (s.a. &#40; and &#x2e;), are translated.

  • The phone firmware only supports ASCII characters.

Open profile (XML) compression and encryption

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

Open profile compression

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 compression, the phone expects the compressed file to contain a gzip compatible header. Invocation of the gzip utility on the original Open profile generates the header. The phone inspects the downloaded file header to determine the file format.

For example, if profile.xml is a valid profile, the file profile.xml.gz is also accepted. Either of the following commands can generate this profile type:

  • >gzip profile.xml

    Replaces original file with compressed file.

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

    Leaves original file in place and produces new compressed file.

Open profile encryption

Symmetric key encryption can be used to encrypt an open configuration profile, whether the file is compressed or not. Compression, if applied, must be applied before encryption.

The provisioning server uses HTTPS to handle initial provisioning of the phone after deployment. Pre-encrypting configuration profiles offline allows the use of HTTP for resynchronizing profiles subsequently. This reduces the load on the HTTPS server in large-scale deployments.

The phone supports two methods of encryption for configuration files:

  • AES-256-CBC encryption

  • RFC 8188-based HTTP content encryption with AES-128-GCM ciphering

The key or Input Keying Material (IKM) must be preprovisioned into the unit at an earlier time. Bootstrap of the secret key can be accomplished securely by using HTTPS.

The configuration file name doesn't require a specific format, but a file name that ends with the .cfg extension normally indicates a configuration profile.

AES-256-CBC Encryption

The phone supports AES-256-CBC encryption for configuration files.

The OpenSSL encryption tool, available for download from various Internet sites, can perform the encryption. Support for 256-bit AES encryption may require recompilation of the tool to enable the AES code. The firmware has been tested against version openssl-1.1.1d.

For an encrypted file, 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 lowercase -k precedes the secret key, which can be any plain text phrase, and which is used to generate a random 64-bit salt. With the secret specified by 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 on a configuration profile, the phone 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.

Macro expansion

Several provisioning parameters undergo macro expansion internally prior to being evaluated. This preevaluation step provides greater flexibility in controlling the phone resync and upgrade activities.

These parameter groups undergo macro expansion before evaluation:

  • Resync_Trigger_*

  • Profile_Rule*

  • Log_xxx_Msg

  • Upgrade_Rule

Under certain conditions, some general-purpose parameters (GPP_*) also undergo macro expansion, as explicitly indicated in the Optional resync arguments section below.

During macro expansion, the contents of the named variables replace expressions of the form $NAME and $(NAME). These variables include general-purpose parameters, several product identifiers, certain event timers, and provisioning state values. For a complete list, see Macro expansion variables under Provisioning parameters.

In the following example, the expression $(MAU) is used to insert the MAC address 000E08012345.

The administrator enters: $(MAU)config.cfg

The resulting macro expansion for a device with MAC address 000E08012345 is: 000E08012345config.cfg

If a macro name is not recognized, it remains unexpanded. For example, the name STRANGE is not recognized as a valid macro name, while MAU is recognized as a valid macro name.

The administrator enters: $STRANGE$MAU.cfg

The resulting macro expansion for a device with MAC address 000E08012345 is: $STRANGE000E08012345.cfg

Macro expansion is not applied recursively. For example, $$MAU” expands into $MAU” (the $$ is expanded), and does not result in the MAC address.

The contents of the special purpose parameters, GPP_SA through GPP_SD, are mapped to the macro expressions $SA through $SD. These parameters are only macro expanded as the argument of the --key , --uid, and --pwd options in a resync URL.

Conditional expressions

Conditional expressions can trigger resync events and select from alternate URLs for resync and upgrade operations.

Conditional expressions consist of a list of comparisons, separated by the and operator. All comparisons must be satisfied for the condition to be true.

Each comparison can relate to one of the following three types of literals:

  • Integer values

  • Software or hardware version numbers

  • Doubled-quoted strings

Version Numbers

The software version for Cisco Video Phone 8875 uses this format (where BN is the Build Number):

PHONEOSyyyy.1-0-1-0001-BN

where yyyy indicates the phone model or phone series; 1 is the major version; 0 is the minor version; 1-0001 is the micro version; and BN is the build number.

The comparing string must use the same format. Otherwise, a format parsing error results.

When comparing the software version, the major version, minor version, and micro version are compared in sequence, and the leftmost digits take precedence over the latter ones. When version numbers are identical, the build number is compared.

Examples of Valid Version Number

PHONEOS-8875.1-0-1-0001-19

Comparison

Quoted strings can be compared for equality or inequality. Integers and version numbers can also be compared arithmetically. The comparison operators can be expressed as symbols or as acronyms. Acronyms are convenient for expressing the condition in an Open format profile.

Operator

Alternate Syntax

Description

Applicable to Integer and Version Operands

Applicable to Quoted String Operands

=

eq

equal to

Yes

Yes

!=

ne

not equal to

Yes

Yes

<

lt

less than

Yes

No

<=

le

less than or equal to

Yes

No

>

gt

greater than

Yes

No

>=

ge

greater than or equal to

Yes

No

AND

and

Yes

Yes

It is important to enclose macro variables in double quotes where a string literal is expected. Don't do so where a number or version number is expected.

When used in the context of the Profile_Rule* and Upgrade_Rule parameters, conditional expressions must be enclosed within the syntax “(expr)?” as in this upgrade rule example. Remember to replace BN with the build number of your firmware load to upgrade to.

($SWVER ne PHONEOS-8875.1-0-1-0001-19)? http://ps.tell.com/sw/PHONEOS-8875.1-0-1-0001-BN.loads

Do not use the preceding syntax with parentheses to configure the Resync_Trigger_* parameters.

URL syntax

Use the Standard URL syntax to specify how to retrieve configuration files and firmware loads in Profile_Rule* and Upgrade_Rule parameters, respectively. The syntax is as follows:

[ scheme:// ] [ server [:port]] filepath

Where scheme is one of these values:

  • tftp

  • http

  • https

If scheme is omitted, tftp is assumed. The server can be a DNS-recognized hostname or a numeric IP address. The port is the destination UDP or TCP port number. The filepath must begin with the root directory (/); it must be an absolute path.

If server is missing, the tftp server specified through DHCP (option 66) is used.

For upgrade rules, the server must be specified.

If port is missing, the standard port for the specified scheme is used. Tftp uses UDP port 69, http uses TCP port 80, https uses TCP port 443.

A filepath must be present. It need not necessarily refer to a static file, but can indicate dynamic content obtained through CGI.

Macro expansion applies within URLs. The following are examples of valid URLs:


/$MA.cfg
/cisco/cfg.xml
192.168.1.130/profiles/init.cfg
tftp://prov.call.com/cpe/cisco$MA.cfg
http://neptune.speak.net:8080/prov/$D/$E.cfg
https://secure.me.com/profile?Linksys

When using DHCP option 66, the empty syntax is not supported by upgrade rules. It is only applicable for Profile Rule*.

RFC 8188-Based HTTP Content Encryption

The phone supports RFC 8188-based HTTP content encryption with AES-128-GCM ciphering for configuration files. With this encryption method, any entity can read the HTTP message headers. However, only the entities that know the Input Keying Material (IKM) can read the payload. When the phone is provisioned with the IKM, the phone and the provisioning server can exchange configuration files securely, while allowing third-party network elements to use the message headers for analytic and monitoring purposes.

The XML configuration parameter IKM_HTTP_Encrypt_Content holds the IKM on the phone. For security reasons, this parameter is not accessible on the phone administration web page. It is also not visible in the phone's configuration file, which you can access from the phone's IP address or from the phone's configuration reports sent to the provisioning server.

If you want to use the RFC 8188-based encryption, ensure the following:

  • Provision the phone with the IKM by specifying the IKM with the XML parameter IKM_HTTP_Encrypt_Content in the configuration file that is sent from the provisioning server to the phone.

  • If this encryption is applied to the configuration files sent from the provisioning server to the phone, ensure that the Content-Encoding HTTP header in the configuration file has aes128gcm.

    In the absence of this header, the AES-256-CBC method is given precedence. The phone applies AES-256-CBC decryption if a AES-256-CBC key is present in a profile rule, regardless of IKM.

  • If you want the phone to apply this encryption to the configuration reports that it sends to the provisioning server, ensure that there is no AES-256-CBC key specified in the report rule.

Optional resync arguments

Optional arguments, key, uid, and pwd, can precede the URLs entered in Profile_Rule* parameters, collectively enclosed by square brackets.

key

The --key option tells the phone that the configuration file that it receives from the provisioning server is encrypted with AES-256-CBC encryption, unless the Content-Encoding header in the file indicates aes128gcm encryption. The key itself is specified as a string following the term --key. The key can be enclosed in double-quotes (") optionally. The phone uses the key to decrypt the configuration file.

Usage Examples

[--key VerySecretValue]
[--key “my secret phrase”]
[--key a37d2fb9055c1d04883a0745eb0917a4]

The bracketed optional arguments are macro expanded. Special purpose parameters, GPP_SA through GPP_SD, are macro expanded into macro variables, $SA through $SD, only when they are used as key option arguments. See these examples:

[--key $SC]
[--key “$SD”]

In Open format profiles, the argument to --key must be the same as the argument to the -k option that is given to openssl.

uid and pwd

The uid and pwd options can be used to specify the userID and password that will be sent in response to HTTP Basic and Digest authentication challenges when the specified URL is requested. The bracketed optional arguments are macro expanded. Special purpose parameters, GPP_SA through GPP_SD, are macro expanded into macro variables, $SA through $SD, only when they are used as key option arguments. See these examples:

GPP_SA = MyUserID
GPP_SB = MySecretPassword

[--uid $SA --pwd $SB] https://provisioning_server_url/path_to_your_config/your_config.xml

would then expand to:

[--uid MyUserID --pwdMySecretPassword] https://provisioning_server_url/path_to_your_config/your_config.xml

Data types

These data types are used with configuration profile parameters:

  • {a,b,c,…}—A choice among a, b, c, …

  • Bool—Boolean value of either “yes” or “no.”

  • CadScript—A miniscript that specifies the cadence parameters of a signal. Up to 127 characters.

    Syntax: S1[;S2], where:

    • Si=Di(oni,1/offi,1[,oni,2/offi,2[,oni,3/offi,3[,oni,4/offi,4[,oni,5/offi,5[,oni,6/offi,6]]]]]) and is known as a section.

    • oni,j and offi,j are the on/off duration in seconds of a segment. i = 1 or 2, and j = 1 to 6.

    • Di is the total duration of the section in seconds.

    All 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)

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

  • DialPlanScript—Scripting syntax that is used to specify Line 1 and Line 2 dial plans.

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

  • FQDN—Fully Qualified Domain Name. It can contain up to 63 characters. Examples are as follows:

    • sip.Cisco.com:5060 or 109.12.14.12:12345

    • sip.Cisco.com or 109.12.14.12

  • FreqScript—A miniscript that specifics the frequency and level parameters of a tone. Contains up to 127 characters.

    Syntax: F1@L1[,F2@L2[,F3@L3[,F4@L4[,F5@L5[,F6@L6]]]]], where:

    • F1–F6 are frequency in Hz (unsigned integers only).

    • L1–L6 are corresponding levels in dBm (with up to one decimal place).

    White spaces before and after the comma are allowed but not recommended.

    Example 1—Call Waiting Tone:

    
440@-10

Number of Frequencies = 1
Frequency 1 = 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

  • IP— Valid IPv4 Address in the form of x.x.x.x, where x is between 0 and 255. Example: 10.1.2.100.

  • UserID—User ID as it appears in a URL; 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. The string can contain up to 39 characters.

  • PhTmplt—A phone number template. Each template may contain one or more patterns that are separated by a comma (,). White space at the beginning of each pattern is ignored. “?” and “*” represent wildcard characters. To represent literally, use %xx. For example, %2a represents *. The template can contain up to 39 characters. Examples: “1408*, 1510*”, “1408123????, 555?1.”.

  • Port—TCP/UDP Port number (0-65535). It can be specified in decimal or hex format.

  • ProvisioningRuleSyntax—Scripting syntax that is used to define configuration resync and firmware upgrade rules.

  • PwrLevel—Power level expressed in dBm with one decimal place, such as –13.5 or 1.5 (dBm).

  • RscTmplt—A template of SIP Response Status Code, such as “404, 5*”, “61?”, “407, 408, 487, 481”. It can contain up to 39 characters.

  • Sig<n>—Signed n-bit value. It can be specified in decimal or hex format. A “-” sign must precede negative values. A + sign before positive values is optional.

  • Star Codes—Activation code for a supplementary service, such as *69. The code can contain up to 7 characters.

  • Str<n>—A generic string with up to n nonreserved characters.

  • Time<n>—Time duration in seconds, with up to n decimal places. Extra specified decimal places are ignored.

  • ToneScript—A miniscript that specifies the frequency, level, and cadence parameters of a call progress tone. Script may contain up to 127 characters.

    Syntax: FreqScript;Z1[;Z2].

    The section Z1 is similar to the S1 section in a CadScript, except that each on/off segment is followed by a frequency components parameter: Z1 = D1(oni,1/offi,1/fi,1[,oni,2/offi,2/fi,2 [,oni,3/offi,3/fi,3 [,oni,4/offi,4/fi,4 [,oni,5/offi,5/fi,5 [,oni,6/offi,6/fi,6]]]]]) where:

    • fi,j = n1[+n2]+n3[+n4[+n5[+n6]]]]].

    • 1 < nk < 6 specifies the frequency components in the FreqScript that 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

Total Tone Length = 12s

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

Keep these under consideration:

  • <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 phone continues to use the last configured values for tags that are not present in a given profile.
  • Templates are compared in the order given. The first, not the closest, match is selected. The parameter name must match exactly.
  • If more than one definition for a parameter is given in a profile, the last such definition in the file is the one that takes effect in the phone.
  • 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.