Content
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 settings | Internal settings |
|---|---|
| tr69_acs_url | tr69_events |
| tr69_acs_user | tr69_params |
| tr69_acs_passwd | download_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
- Setup provisioning server via DHCP
- Phone contacts provisioning server
- Provision common settings and TR-069 information to the phone
- 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:
Snom Firmware Upgrade Image
Snom XML configuration file
Snom Parameter Mapping File if supported by the ACS (see Using the TR-069 Download RPC)
Snom Factory Defaults setting file (Type: X 000413 Defaults)
Certificates (Type: X 000413 Certificate)
Upload
This method can be used to instruct the phone to upload
the current configuration
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 Advanced → Update 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.
| Modifier | Description |
|---|---|
| = | 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.
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.
Further Information
Related articles
Overview
Content Tools
Tasks
