TR-069
TR-069 (Technical Report 069) is a specification published by Broadband Forum (www.broadband-forum.org) entitled CPE WAN Management Protocol (CWMP). It defines an application layer protocol for remote management of end-user devices.
TR-069 uses a bi-directional SOAP/HTTP protocol for communication between the customer premises equipment (CPE) and the Auto Configuration Servers (ACS). The TR-069 connection to the ACS can be done on the LAN or WAN interface.
The protocol stack looks as follows:
TR-069 Protocol Stack
|
CPE/ACS Management Application |
|---|
|
RPC Methods |
|
SOAP |
|
HTTP |
|
TLS |
|
TCP/IP |
Communication is typically established by the CPE; hence, messages from CPE to ACS are typically carried in HTTP requests, and messages from ACS to CPE in HTTP responses.
Communication between ACS and CPE is defined via Remote Procedure Call (RPC) methods. TR-069 defines a generic mechanism by which an ACS can read or write parameters to configure a CPE and monitor CPE status and statistics. It also defines the mechanism for file transfer and firmware/software management. However, it does not define individual parameters; these are defined in separate documents, as described below. Some of the RPC methods are Configuration File Download, Firmware upgrade, Get Parameter Value, Set Parameter Value, Reboot, and the upload and download files.
The device (CPE) supports the TR-069 Session Retry Policy. The CPE retries failed sessions to attempt to redeliver events that it has previously failed to deliver and to allow the ACS to make additional requests in a timely fashion. The CPE retries a failed session after waiting for an interval of time specified by the TR-069 protocol or when a new event occurs, whichever comes first. The CPE chooses the wait interval by randomly selecting a number of seconds from a range given by the post-reboot session retry count. This time is random to prevent large numbers of CPEs from trying to reconnect to the ACS at the same time.
TR-106 defines the “data model” template for TR-069 enabled devices. The Data Model consists of objects and parameters hierarchically organized in a tree with a single Root Object, typically named Device. Arrays of objects are supported by appending a numeric index to the object name (e.g. ABCService.1 in the example below); such objects are called “multi-instance objects”.
Below is a list of some of the TR-069 methods:
| ■ | CPE Methods: |
| ● | GetRPCMethods: Used by the CPE or ACS to discover the set of methods supported by the Server or CPE it is in communication with. |
| ● | SetParameterValues: Used by the ACS to modify the value of CPE parameter(s). |
| ● | GetParameterValues: Used by the ACS to obtain the value of CPE parameter(s). |
| ● | GetParameterNames: Used by the ACS to discover the parameters accessible on a particular CPE. |
| ● | SetParameterAttributes: Used by the ACS to modify attributes associated with CPE parameter(s). |
| ● | GetParameterAttributes: Used by the ACS to read the attributes associated with CPE parameter(s). |
| ● | AddObject: Used by the ACS to create a new instance of a multi-instance object—a collection of parameters and/or other objects for which multiple instances are defined. |
| ● | DeleteObject: Removes a particular instance of an object. |
| ● | ScheduleDownload: Used by the ACS to cause the CPE to download files from a designated location during a specific period (window). This method includes a TimeWindowList with the following: |
| ◆ | WindowStart: Start of time window (in seconds) |
| ◆ | WindowEnd: End of time window (in seconds) |
| ◆ | WindowMode: Specifies when within this time window the CPE is permitted to perform and apply the download: - “1 At Any Time”: The CPE may perform and apply a download at any time during the time window even if this results in interruption of service. - “2 Immediately”: The CPE must perform and apply a download immediately at the start of the time window even if this results in interruption of service. - “3 When Idle”: The download commences according to the CPE's Idle period parameters (TR069IdleTimeDayWeek, TR069IdleTimeStart, and TR069IdleTimeEnd). The device starts downloading the files at a randomly chosen time within the configured Idle period. |
The device reports the status of the ScheduleDownload to Syslog:
- Received request - "Received ScheduleDownload request. time mode"
- Start download process - "Transfer Scheduler Download started"
- Complete download process (after reset and events sending) - "Transfer Scheduler Download completed"
Refer to the Download method for additional information.
| ● | Download: Used by the ACS to cause the CPE to download the following file(s) from a designated location: |
| ◆ | Firmware Upgrade Image (File Type = 1): >> If the sent file has the extension “.cert”, the file is applied to the device as a Trusted Root Certificate. It is loaded for the TLS Context associated with the TR-069 service. After file load, no reset is done and the loaded certificate is active for the next HTTPS connection. The loaded file may contain a list of Trusted Root Certificates. These certificates don’t replace the existing certificate, but they are concatenated to the existing certificates. If the loaded file contains certificates that are identical to the existing ones, a merge is done. New certificates are burned to flash immediately. >> If the sent file has the extension ".pfx" or “.p12”, the file is applied to the device as the device certificate together with the private key (it can also include the root certificate). It is loaded for the TLS Context associated with the TR-069 service. After file loade, the device resets. >> In all other cases, the file is applied as a “.cmp” file for software upgrade. After the file is loaded, the device resets. |
| ◆ | Vendor Configuration File (File Type = 3): >> If the sent file has the extension “.ini” and the first line in the file is "[ClientDefaults]", the file is applied as a Client Default. After file load, the device resets. >> If the file has an extension other than “.ini” and the first line is “Incremental” (case in-sensitive), the file is applied as an incremental CLI script. After file load, no reset is done. >> In all other cases, the loaded file is applied as a Startup CLI script. After file load, the device resets twice. |
The CPE responds to the Download method, indicating successful or unsuccessful completion via one of the following:
| ◆ | A DownloadResponse with the Status argument set to zero (indicating success), or a fault response to the Download request (indicating failure). |
| ◆ | A TransferComplete message sent later in the same session as the Download request (indicating either success or failure). In this case, the Status argument in the corresponding DownloadResponse has a value of one. |
| ◆ | A TransferComplete message sent in a subsequent session (indicating success or failure). In this case, the Status argument in the corresponding DownloadResponse has a value of one. |
| ● | Upload: Used by the ACS to cause the CPE to upload (to the ACS) the following files to a designated location: |
| ◆ | Vendor Configuration File (File Type = 3): Output of show running-config CLI command, which includes Data and Voice configuration. |
The CPE responds to the Upload method, indicating successful or unsuccessful completion via the UploadResponse or TransferComplete method.
For a complete description of the Upload method, refer to TR-069 Amendment 3 section A.4.1.5.
| ● | Reboot: Reboots the CPE. The CPE sends the method response and completes the remainder of the session prior to rebooting. |
| ● | X_0090F8_CommandResponse: Runs CLI commands. |
| ■ | ACS Methods: |
| ● | Inform: A CPE must call this method to initiate a transaction sequence whenever a connection to an ACS is established. |
| ● | TransferComplete: Informs the ACS of the completion (either successful or unsuccessful) of a file transfer initiated by an earlier Download or Upload method call. |