Child pages
  • TR-069 - Full Endpoint Management

Contents


Introduction

TR-069 is a standard for remote management of CPE (Customer Premises Equipment) defined by the DSL Broadband Forum. TR-069 uses common transport mechanisms (HTTP and HTTPS) for communication with CPE. The HTTP(S) messages contain XML-RPC methods defined in the standard for configuration and management of the device.











Figure 1: TR-069 schematic design


Typically one router on customer premises provides Internet connectivity to many phones as indicated in Figure 1. The ACS can now manage the router remotely, and all phones located behind it.

What does „remote management“ mean?

Where provisioning is used to provide configuration information to many phones at once, remote management takes this one step further. Of course it is still possible to configure the phone remotely when it boots up, but with TR-069 the phone can actually be managed remotely. In addition to the provisioning of configuration you can also e.g.

  • Reboot the phone

  • Customise the phone look and feel

  • Push XML-Minibrowser pages to the phone

  • Update the firmware of the device

Additionally, the TR-069 the server can be notified whenever a user makes changes to a setting. This enables the administrator to correct possible misconfigurations right away.

Supported phones and firmware versions

The TR-069 support has been introduced in firmware version 8.2.16. 

Enabling TR-069 on Snom phones

In order to use Snom phones with TR-069, some phone settings need to be adjusted first. Adjusting the settings can be accomplished in one of the following ways.

PLEASE NOTE that enabling TR-069 management will automatically disable the default snom provisioning.

TR-069 specific phone settings

Firmware 8.2.16 introduced a couple of TR-069 specific phone settings. These can be divided into two main groups.

ACS settingsInternal settings
tr69_acs_urltr69_events
tr69_acs_usertr69_params
tr69_acs_passwddownload_status
tr69_use_acs
tr69_bootstrap
tr69_cnr_user
tr69_cnr_pass



ACS settings are the settings specific to the ACS connection and need to be adjusted to the specific environment.

Internal settings are used internally to control the TR-069 stack, and should not be modified.

Modifying the internal settings manually may result in unexpected phone behaviour.

Table 1 describes the ACS settings with the data types and default values.

Setting name

Valid values

Default value

Description

tr69_acs_url 

URLs (STRING)

empty

URL of the TR-069 ACS. This ist he URL the phone will send TR-069 messages to. Please contact your ACS vendor to find out about this URL.

tr69_acs_user

STRING

empty

Username for HTTP authentication against the ACS

tr69_acs_passwd

STRING

empty

Password for HTTP authentication against the ACS

tr69_use_acs

BOOLEAN (off, 0, on, 1)

off

Turn TR-069 management on and off.

tr69_bootstrap

BOOLEAN (off, 0, on, 1)

on

Send BOOTSTRAP event in the Inform Message. Needs to be set to on when a new ACS is contacted.

tr69_cnr_user

STRING

empty

Username to authenticate incoming connection requests.

tr69_cnr_pass

STRING

empty

Password to authenticate incoming connection requests.

Table 1: TR-069 ACS settings


Configure TR-069 support manually

The TR-069 settings cannot be configured using the web interface of the phone. This behaviour is intentional as the makes it more difficult for non-administrative users to accidentally change something. In order to manipulate any of the ACS settings manually, you can use the dummy.htm page of the phone as described in the snom FAQ.

Configure TR-069 automatically on many phones

While the above method is a quick way to test the TR-069 integration it is not suitable for large-scale installations. In case many phones need to be connected to an ACS it is strongly recommended to use Snom auto provisioning method for ACS initialisation. Add the settings described in “TR-069 specific phone settings” to your setting XML file.

Best practice

The best practice for getting many phones under TR-069 management out of the box is

  1. Setup provisioning server via DHCP
  2. Phone contacts provisioning server
  3. Provision common settings and TR-069 information to the phone
  4. Phone contacts ACS an is now under management

Supported TR-069 RPC methods

The following section gives an overview over the supported XML-RPC methods.

In addition to the methods defined in the TR-069 standard, we have implemented a couple of vendor specific methods:

X_000413_Minibrowser, X_000413_GetDownloadTypes, X_000413_Defaults, X_000413_GetWebContent and X_000413_Customize

GetRPCMethods

The ACS can call this method to find out all the XML-RPC methods supported by the CPE.

GetParameterNames

When called, this method returns a list of parameter names on the device. Depending on the method parameters this can be called for complete and partial parameter paths on the device. In case the path is empty the result just contains Device. indicating that the phone is a LAN device and not an Internet Gateway Device. When called with Device. as path the phone will return a complete list of the parameters.

GetParameterValues

Returns the values of parameters on the device. This can be called for both complete and partial paths.

SetParameterValues

Sets the value of one or more parameters on the device.

AddObject

Adds a new instance of an object defined on the device.

DeleteObject

Deletes an instance of an object defined on the device.

Reboot

Triggers a reboot of the device.

GetAttributeValues

Gets the attributes (modifiers) of the specified path. The path can be complete or partial.

SetAttributeValues

Changes the attributes (modifiers) of the specified path. The path can be complete or partial.

Download

Initiates a download on the device. The download can be one of the following:

  1. Snom Firmware Upgrade Image

  2. Snom XML configuration file

  3. Snom Parameter Mapping File if supported by the ACS (see Using the TR-069 Download RPC)

  4. Snom Factory Defaults setting file (Type: X 000413 Defaults)

  5. Certificates (Type: X 000413 Certificate)

Upload

This method can be used to instruct the phone to upload

  1. the current configuration

  2. the current log file

to a server using HTTP PUT (WebDAV).

FactoryReset

Initiates a factory reset on the phone.

Once the reset has been performed the phone goes back to standard provisioning and loses all ACS data and information in the parameter mapping file.

X_000413_Customize

This method can be used to customise the device look and feel as described in the snom User Wiki.

Syntax
<cwmp:X_000413_Customize> <skinUrl>http://location of the tarball</skinUrl> </cwmp:X_000413_Customize>


If your ACS does not support vendor specific methods you can use the SetParameterValues on the Device.X_Snom_UploadGUI and Device.X_Snom_UploadWeb parameters to accomplish the same.

X_000413_Minibrowser

This method can be used to push XML Minibrowser content on to the phone.

Syntax
<cwmp:X_000413_Minibrowser> XML Content </cwmp:X_000413_Minibrowser>

X_000413_GetWebContent

This method (available since 8.2.30 and 8.4.3) can be used to get any web page on the phone. This way it is possible to e.g. get the content of the “System Information” page.

Syntax
<cwmp:X_000413_GetWebContent> <URL>/path_on_the_phone.htm</URL> </cwmp:X_000413_GetWebContent>


The response contains the response as you would get it in a browser (mostly HTML).

X_000413_Defaults

This method can be used to change the factory default settings of a snom phone.

Syntax
<soapenv:Body> <cwmp:X_000413_Defaults> <ParameterList soap-env:arrayType="cwmp:ParameterValueStruct[2]"> <ParameterValuePermStruct> <Name>admin_mode</Name> <Value>on</Value> <Perm>RW</Perm> </ParameterValuePermStruct> <ParameterValuePermStruct> <Name>user_name1</Name> <Value>filip</Value> <Perm>RW</Perm> </ParameterValuePermStruct> </ParameterList> </cwmp:X_000413_Defaults> </soapenv:Body>

X_000413_GetDownloadTypes

This method can be used to obtain all download file types supported in the firmware. The response is a list of string objects with the type names.

Syntax
<cwmp:X_000413_GetDownloadTypes> </cwmp:X_000413_ GetDownloadTypes >

Parameter mapping

This section describes how the snom settings are mapped to TR-104 and TR-106 parameters. It also explains the syntax of the parameter mapping file and how this can be used to store service specific data on the phone.

The param_map file

The parameter-mapping file (param_map) is the heart of the TR-069 implementation. This is the place where TR-069, TR-104 and TR-106 as well as some snom specific extensions to the parameters are stored and mapped to internal snom settings.

Editing the param_map file manually may result in damaging the TR-069 stack. Most of the Parameters have already been mapped by snom and should remain unchanged. param_map edits should only be used to store user specific parameters on the device if necessary.


Retrieving and uploading the parameter mapping via the Web UI

The fastest way to view and upload the parameter-mapping file is to use the web interface of the phone.

To upload the parameter mapping file to the phone open the phone web user interface and choose AdvancedUpdate  from the left-hand menu. Use the Load TR069 Parameter Map Manually section to upload a parameter-mapping file to the phone.


Figure 4: Uploading a parameter mapping file to the phone


If you want to download or view the parameter mapping file, you can go to Menu → Settings and use the „Click here to save the TR069 Parameter Map“ download link.

Figure 5: Downloading the parameter mapping file

Provisioning the parameter mapping onto the device

In some cases it is necessary to provide a custom parameter map upon deployment (e.g. if you want to adopt the device type by adding a custom prefix or postfix). In these cases you can use the snom provisioning mechanism to deploy the parameter-mapping file.

Add a param-map tag in your setting-files section to do this.

<setting-files> <param-map url=“http://yourserver/yourmap.txt“> </setting-files>

Using TR-069 to update the parameter mapping

There are two different options to change the parameter mapping file using TR-069.

Using the TR-069 Download RPC

You can use the standard Download RPC (also used for Firmware updates) to download a customised parameter mapping on to the device. The Download File type be be used is

X 000413 ParameterMap

Using the TR-069 SetParameterValues RPC

In order to download a custom parameter mapping file to the phone you can pass the URL of the file to the phone by setting the  Device.X_Snom_ParamMapUrl object to the URL. The phone will then download the parameter mapping from the given URL and replace it.

Modifying the parameter mapping

The following section gives an introduction into the syntax of the parameter mapping file.

Editing the param_map file manually may result in damaging the TR-069 stack. Most of the Parameters have already been mapped by snom and should remain unchanged. param_map edits should only be used to store user specific parameters on the device if necessary.

General syntax

The parameter-mapping file (param_map) is a plain text file containing the mapping of TR-104, TR106 and some vendor specific snom parameters to the internal snom settings.

The file contains one line per parameter and all lines have the same syntax.

[parameter type] : [parameter name][modifier][parameter value]

Parameter types

The parameter type can be any of the types defined in the TR-069 specification except for the object type as multiple lines in the parameter-mapping file represent this.

Type

Description

string

For text values

int

For numeric values

unsignedInt

For positive numeric values

boolean

For truth values (true, false, 1, 0)

dateTime

For date and time values

Table 3: Supported parameter types

Modifiers

A modifier specifies access and notification options for a parameter. The phone understands the following modifiers.

ModifierDescription
=

Read/Write with passive notification

!=Read only
&=

Parameter not supported (used for standard parameters)

$=

Notification disabled

*=

Active notification


Values

Values can be dynamic, static or mixed. Static values are stored in the parameter-mapping file itself whereas dynamic values are mapped to the phone settings.
Static values are written directly behind the modifier:

string:Device.ManagementServer.PeriodicInformInterval=3600

For dynamic values the respective setting or special value5 is written in curly brackets:

string:Device.ManagementServer.ConnectionRequestUsername={tr69_cnr_user}

in case of „normal settings“ and

string:Device.VoiceService.1.Line.1.SIP.AuthPassword={user_pass|n}

where n is the index in case of array settings (i.e. for identities). It is also possible to have static and dynamic values mixed:

string:Device.X_Snom_SomeParam=This is my {LCS2_PRODUCT}

Would result in „This is my snom370“ for a snom370 and „This is my snom820“ for a snom820.

Comments

Any line in the parameter mapping file which starts with a # is treated as a comment and ignored.

Only complete lines can be comments. DO NOT ADD COMMENTS AFTER A 
VALUE OF A PARAMETER!!!

Generic parameter access

If you do not want to add all needed settings to a customized parameter mapping you can use the generic parameter support for GetParameterValues and SetParameterValues RPCs. This support is enabled by default. It can be disabled by setting

Device.X_Snom_Enable_GenericParameters
to 0.

Generic parameters provide access to any phone setting by its setting name. The TR-069 path is
constructed as follows:

Device.X_Snom.X_Snom_{setting name}

where {setting_name} is replaced by the name of the setting as found on the snom wiki or 

the settings page of the phone.

Generic parameters are only supported in GetParameterValues 
and SetParameterValues. They will not be part of the GetParameterNames response.


TR-111 support

About TR-111

The TR-111 standard defines two ways of managing CPE located behind NAT routers. These CPE
cannot be contacted directly using HTTP because they are not exposed to the Internet. In many cases the periodic inform interval6 is set to 24 hours or more. With TR-111 Parts I and II the DSL Broadband Forum defines two ways of enabling the server to contact these devices anyway.

TR-111 Part I: Device Gateway Association

The first method is to associate the phone with the modem or router it is connected to. This association is communicated to the ACS in the Inform message sent by the phone. The ACS creates port-forwarding rules on the router, which enable the ACS to contact the phone. Figure 6 shows the process of associating the phone with the router.


Figure 6: Device Gateway Association
The DISCOVER request contains DHCP Option 125 with sub-options 1,2 and 3 set the respective CPE values. The DHCP OFFER response. Contains the DHCP Option 125 with sub-options 4,5 and 6 set to the respective Gateway Device options. The CPE is required to set the correct values for the following TR-069 parameters and send them in the Inform request.

This procedure requires the gateway to be managed by the same ACS as the phone.


Snom VoIP phones fully support TR-111 Part I and the connection requests specified herein.


TR-111 Part II: Connection request via NAT gateway

TR-111 Part II specifies a way of communicating the current NAT binding to the ACS. This method is similar to STUN.

This method is currently NOT supported by snom VoIP phones.

Normative references

For further information on the standards described in this document you can find the standard
papers at the following URLs:


TR-069: http://www.broadband-forum.org/technical/download/TR-069Amendment2.pdf
TR-104: http://www.broadband-forum.org/technical/download/TR-104.pdf
TR-106: http://www.broadband-forum.org/technical/download/TR-106_Amendment-3.pdf
TR-111: http://www.broadband-forum.org/technical/download/TR-111.pdf

ACS specific information

As TR-069 is a standard any ACS should work fine. Our experience is that every ACS is a little bit different though. This section describes ACS specifics we are aware of.

Axiros Axess

The Axiros Axess system is fully tested and supported by snom phones. In addition to the standard TR-069 features Axiros – unlike other solutions – supports the vendor specific RPC Methods, especially the XML Minibrowser support.

ALU Motive HDM

The Motive HDM requires a vendor specific device data model in XML format before any devices can be connected to it. This XML file can be obtained from snom by contacting snom sales (sales@snom.com).

Friendly ACS

Just like Axiros the Friendly ACS does not require any information as it fetches the required information upon the first contact with the CPE. The process of fetching the information might take a while so please be patient.

Call to action

If you have successfully tested Snom phones to work with your ACS please send an email with your ACS details to marketing@snom.com and we will be happy to add your ACS to the above list.




Related articles: