TR-069

What Is TR-069 And Why

The World Need It?
TR-069 is the document number of the technical report, defined by
the Broadband Forum, that specifies the CPE WAN Management
Protocol, or..

CWMP

4
 Terms
ACS Auto-Configuration Server, performs the management of the CPE.
Generally, operated by an ISP and plugs into their Operational or Billing Support
Systems (OSS/BSS)

CPE customer premises equipment, or the device that is being managed; may
include Integrated Gateways (IGD), Set-top-boxes (STB), Network Attached
Storage (NAS), etc.

Data Model a set of objects defined for the management of a particular kind of
CPE, usually defined in a companion Technical Report by the Broadband Forum

RPC Remote Procedure Call. A use of SOAP that allows two applications to
make procedure calls on each other.

SOAP The Simple Object Access Protocol; an XML based specification for
performing application function calls between web app components

XML The eXtensible Markup Language

5
 TR Protocols
TR-069: Transport / Features
TR-106: Datamodel Template

TR-098: DM DSL

TR-104: DM VoIP

TR-135: DM STB
.
.
.
TR-111: NAT

6
 Protocol Stack

CPE/ACS Management Application

RPC Methods

SOAP

HTTP

SSL/TLS

TCP/IP

8
 TR-069 XML Schemas
RPC Schema (contained in TR-069 document, section A.6)

CWMP Data Model Schema (TR-106) or cwmp-datamodel.xsd

The Data Models are xml documents that are schema-like, but describe the
objects and parameters used for a particular TR-069 use case.

9
 SOAP
The Simple Object Access Protocol

Is just XML, defined in a schema, that describes how to convey information

between peers.

RPC (Remote Procedure Call) is one application of SOAP that:

Describes how to convey methods and their arguments to be invoked on the peer

Describes how the response should look

Describes how to convey fault information

CWMP uses RPC application of SOAP for faults, call/response format, message ID

11
 Message Structure
<soapenv:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://
www.w3.org/2001/XMLSchema" xmlns:cwmp="urn:dslforum-org:cwmp-1-0" xmlns:soapenv="http://
schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<cwmp:ID soapenv:mustUnderstand="1">1323392</cwmp:ID>
</soapenv:Header>
<soapenv:Body>
<cwmp:SetParameterValues>
<ParameterList soap:arrayType="cwmp:ParameterValueStruct[1]">
<ParameterValueStruct>
<Name>InternetGatewayDevice.ManagementServer.URL</Name>
<Value xsi:type="xsd:string">http://someacs.cwmp.org/path/</Value>
</ParameterValueStruct>
</ParameterList>
<ParameterKey>1323392</ParameterKey>
</cwmp:SetParameterValues>
</soapenv:Body>
</soapenv:Envelope>

This is the SOAP Body. It contains the actual RPC call or response,
as well as all of the arguments they contain.
The CPE establishes a connection to the server on a number of occasions:
The first time it isinstalled/connected
On startup
Periodically
When requested by the server
Whenever particular parameter values change (via Connection Request)
When a file transfer is complete (e.g. after firmware upgrade)
When a diagnostics test iscomplete
On each connection establishment, the CPE sends the Inform RPC to the
server which contains the reason/event1f2or the connectionestablishment.
What does a session look like?
CPE ACS
Open Connection

SSL Initiation

HTTP post
Inform request

HTTP response
Inform response

HTTP post

HTTP response
GetParameterValues request

HTTP post
GetParameterValues response

HTTP response
SetParameterValues request

HTTP post
SetParameterValues response

HTTP response

Close connection

13
 What does a session look like?
The CPE initiates the connection. The CPE is always the initiator, though the ACS can make a Connection
Request to stimulate the CPE to initiate a connection. The underlying protocols establish a connection.
TR-069 is almost always performed over Secure Socket Layer (SSL), unless for testing purposes.

Remember, the CPE is always the initiator of the session. It begins EVERY new session by making an Inform
RPC on the ACS, with arguments that include the reason for the session and a list of parameters it must
inform the ACS about.

The ACS sends an InformReponse to the CPE for the Inform RPC. This means the Inform RPC is complete.
Here the CPE indicated that it has no more RPCs to make on the ACS. This is indicated by an empty HTTP
post. This post may happen at any time, since the TCP session is still open.
The CPE sends a GetParameterValuesResponse, containing the information the ACS wants. This means the
GetParameterValues RPC is over.
The ACS makes any other Remote Procedure Calls that it needs to make on the CPE during this particular
CWMP session. Here, it is a SetParameterValues RPC.
Finally, the ACS sends an empty HTTP response to indicate it has no more RPCs to make on the CPE. Since
the CPE has already done the same thing, this ends the CWMP session.
With the session closed, the underlying protocols close their connections and the session is successfully
terminated.

14
 Connection Request
While the CPE always initiates a session, the ACS can stimulate it to
do so

It does this by issuing a Connection Request

A Connection Request is a simple HTTPGet made on the CPE at an

arbitrary URL/port set by the CPE

The CPE tells the ACS what its CR URL is during the Inform

15
 Authentication
TR-069 requires the use of HTTP basic, HTTP digest, or Certificate
based authentication

Authentication occurs in both directions

The CPE authenticates the ACSs Connection Requests

The ACS authenticates the CPEs session initiation

Digest always

Basic, Digest or Certified

16
 Remote Procedure Calls
CPE Methods Upload
GetRPCMethods FactoryReset
SetParameterValues GetQueuedTransfers
GetParameterValues GetAllQueuedTransfers
GetParameterNames ScheduleInform
SetVouchers
SetParameterAttributes
ACS Methods
GetParameterAttributes
GetRPCMethods
AddObject
Inform
DeleteObject
TransferComplete
Reboot
AutonomousTransferComplete
Download

17
 The Inform
The Inform RPC is a an RPC made on the ACS by the CPE

It MUST be called FIRST in every session

It contains the reason(s) for the session (an Event)

Contains a list of parameters that are required by the Data Model to

be included (Forced Inform)

Contains parameters that the ACS set to be notified upon changes.

18
 Events
THE INFORM EVENT ARRAY CONTAINS ALIST OF ONE OR MORE
PRE-DEFINED REASONS FOR THE SESSION BEING INITIATED.

0 BOOTSTRAP 8 DIAGNOSTICS COMPLETE

1 BOOT 9 REQUEST DOWNLOAD
2 PERIODIC 10 AUTONOMOUS TRANSFER COMPLETE
3 SCHEDULED M Reboot
4 VALUE CHANGE M Scheduled Inform
5 KICKED M Download
6 CONNECTION REQUEST M Upload
7 TRANSFER COMPLETE Vendor Specific Functions and Events

19
 Stu the ACS Can Do to the CPE
(required)
Learn what methods it supports

Learn what objects or parameters exist

Create or delete an object

Read or edit a parameter

Read or edit a parameters attributes

Reboot the CPE

Tell it to download a file or firmware image

Monitor the CPE

20
 GetRPCMethods
Allows the ACS (or the <soapenv:Body>
CPE) to learn the <cwmp:GetRPCMethods/> ACS Call
</soapenv:Body>
RPCs supported by
the CPE (or ACS)

May contain vendor <soap:Body>

<cwmp:GetRPCMethodsResponse>
extensions or custom
<MethodList soap-enc:arrayType="xsd:string[12]">
RPCs <string>GetRPCMethods</string>
<string>SetParameterValues</string>
<string>GetParameterValues</string>
<string>GetParameterNames</string>
<string>SetParameterAttributes</string>
<string>GetParameterAttributes</string>
CPE Response <string>AddObject</string>
<string>DeleteObject</string>
<string>Download</string>
<string>Reboot</string>
<string>ScheduleInform</string>
<string>FactoryReset</string>
</MethodList>
</cwmp:GetRPCMethodsResponse>
</soap:Body>

21
 Vendor Extensions
Companies may make custom RPCs , events, objects, and parameters.

All follow the same format.

X_{OUI of Company}_{NameOfNewThing} For example: X_012345_MyMethod

22
 GetParameterNames
Allows the ACS to <soapenv:Body>
learn the objects and <cwmp:GetParameterNames>
<ParameterPath>Device.LAN.IPAddress
parameters that exist </ParameterPath> ACS Call
<NextLevel>0</NextLevel>
on the CPE </cwmp:GetParameterNames>
</soapenv:Body>
Often used to
determine device
characteristics
May be complete or
partial path <soap:Body>
<cwmp:GetParameterNamesResponse>
<ParameterList soap enc:arrayType="cwmp:ParameterInfoStruct[1]">
<ParameterInfoStruct>
<Name>Device.LAN.IPAddress</Name>
<Writable>0</Writable>
CPE Response </ParameterInfoStruct>
</ParameterList>
</cwmp:GetParameterNamesResponse>
</soap:Body>

23
 Complete and Partial Paths
For any Get RPC, and the SetParameterAtrributes RPC

The ParameterPath tag can take a Complete or Partial path

A Complete path references a single parameter, for example,

Device.LAN.IPAddress

A Partial path references all objects and parameters under a given

tree
- Referenced by parameter path that ends in .
- For example, Device.LAN.

24
 Next Level True and False
For GetParameterNames , partial paths can be Next Level True or
Next Level False

If Next Level is True, the CPE returns only those parameters

directly under the ., without any sub-objects.

If Next Level is False, ALL parameters, and sub-objects and their

parameters are returned

25
 GPN Examples
<soapenv:Body> <soapenv:Body>
<cwmp:GetParameterNames> <cwmp:GetParameterNames>
<ParameterPath>Device.LAN. <ParameterPath>Device.LAN.
</ParameterPath> </ParameterPath>
<NextLevel>1</NextLevel> <NextLevel>0</NextLevel>
</cwmp:GetParameterNames> </cwmp:GetParameterNames>
</soapenv:Body> </soapenv:Body>

<soap:Body> <soap:Body>
<cwmp:GetParameterNamesResponse> <cwmp:GetParameterNamesResponse>
<ParameterList soap- <ParameterList soap-
enc:arrayType="cwmp:ParameterInfoStruct[9] enc:arrayType="cwmp:ParameterInfoStruct[35
"> ]">
<ParameterInfoStruct> <ParameterInfoStruct>
<Name>Device.LAN.Stats.</Name> <Name>Device.LAN.</Name>
<Writable>0</Writable> <Writable>0</Writable>
</ParameterInfoStruct> </ParameterInfoStruct>
<ParameterInfoStruct> <ParameterInfoStruct>
<Name>Device.LAN.IPPingDiagnostics.</Name> <Name>Device.LAN.AddressingType</Name>
<Writable>0</Writable> <Writable>0</Writable>
</ParameterInfoStruct> </ParameterInfoStruct>
<ParameterInfoStruct> ...
<Name>Device.LAN.TraceRouteDiagnostics.</ <Name>Device.LAN.Stats.</Name>
Name> <Writable>0</Writable>
<Writable>0</Writable> </ParameterInfoStruct>
</ParameterInfoStruct> <ParameterInfoStruct>
... <Name>Device.LAN.Stats.ConnectionUpTime</
<ParameterInfoStruct> Name>
<ParameterInfoStruct> <Writable>0</Writable>
<Name>Device.LAN.MACAddress</Name> </ParameterInfoStruct>
<Writable>0</Writable> <ParameterInfoStruct>
</ParameterInfoStruct> <Name>Device.LAN.Stats.TotalBytesSent</
</ParameterList> Name>
</cwmp:GetParameterNamesResponse> <Writable>0</Writable>
</soap:Body> </ParameterInfoStruct>
<ParameterInfoStruct>
...
<Name>Device.LAN.IPPingDiagnostics.</Name>
<Writable>0</Writable>
...

26
 GetParameterValues
CPE returns name/value pairs listing requested parameters and their
current values

Can be complete, partial, or contain multiple of each in the RPC

arguments

<soap:Body>
<cwmp:GetParameterValuesResponse>
<ParameterList soap-enc:arrayType="cwmp:ParameterValueStruct[1]">
<ParameterValueStruct>
<Name>Device.ManagementServer.URL</Name>
<Value xsi:type="xsd:string">http://someacs.tr69.com:9999/acs/</Value>
</ParameterValueStruct>
</ParameterList>
</cwmp:GetParameterValuesResponse>
</soap:Body>

27
 SetParameterValues
Allows ACS to write parameters on CPE

Always complete path

<soap:Body>
<cwmp:SetParameterValues>
<ParameterList soap-enc:arrayType="cwmp:ParameterValueStruct[1]">
<ParameterValueStruct>
<Name>Device.ManagementServer.URL</Name>
<Value xsi:type="xsd:string">http://someacs.tr69.com:9999/acs/</Value>
</ParameterValueStruct>
</ParameterList>
</cwmp:SetParameterValuesResponse>
</soap:Body>

<soap:Body>
<cwmp:SetParameterValuesResponse>
<Status>0</Status>
</cwmp:SetParameterValuesResponse>
</soap:Body>

28
 About the Status argument
SetParameterValues , AddObject , DeleteObject , and Download all
use the Status argument in the Response

A Status of 0 means the changes have already been immediately

applied.

A Status of 1 means they will be applied later, possibly after a

reboot.

Source of a LOT of interoperability problems!

29
 Notifications
Attribute can be Active (2), Passive (1), or None (0)

Active CPE must start a session and inform the ACS of a value
change as soon as it occurs

Passive CPE must inform the ACS of a value change when it next
contacts it for whatever other reason

CPE may deny a parameter being set to Active, but may NOT deny a
parameter being set to Passive!

Inform contains 4 VALUE CHANGE event code when a notification

occurs, and must contain the parameter and value in the Inform
RPC.

30
 Add Object / Delete Object
Allows the ACS to create or
delete instances of objects
available on the CPE, such as
PortMapping entries
Creates the associated
parameters and sub-objects
with it.
Returns an instance number that
the CPE then uses to
reference the object
Instance numbers are not
standardized and must
remain! If something is
deleted with an instance
number between two other
instances, the others cannot
change!
<soapenv:Body>
<cwmp:AddObject>
<ObjectName>InternetGatewayDevice.WANDevice.
1.WANConnectionDevice.1.WANPPPConnection.1.PortMapping.
</ObjectName>
<ParameterKey>3544041</ParameterKey>
</cwmp:AddObject>
</soapenv:Body>
<SOAP-ENV:Body SOAP-ENV:encodingStyle="http://
schemas.xmlsoap.org/soap/encoding/">
<cwmp:AddObjectResponse>
<InstanceNumber>4</InstanceNumber>
<Status>0</Status>
</cwmp:AddObjectResponse>
</SOAP-ENV:Body>
In this example, the CPE would then have an entry in its database called:
InternetGatewayDevice.WANDevice.1.WANConnectionDevice.
1.WANPPPConnection.1.Portmapping.4.
31
 Reboot
Very straightforward ACS asks the CPE to reboot.

Only for diagnostic or troubleshooting purposes CPE should

reboot on its own if it needs to change configuration or firmware.

Triggers the M Reboot event

32
 Download
Used by ACS to trigger the CPE to download
- New Firmware
- Other files or web content

Right now, almost always for firmware, which causes some interop problems

Triggers the M Download and 7 TRANSFER COMPLETE events

Can be immediate or delayed a time specified by the ACS

CPE then calls the TransferComplete function on the ACS

- Only done AFTER firmware has been applied

33
 Other RPCs on the CPE
Upload triggers an upload by the CPE to a specified location

ScheduledInform schedules a CWMP session for a particular time and

triggers the 3 SCHEDULED event

FactoryReset

GetAllQueuedTransfers returns the current uploads/downloads waiting

to complete

34
Stu the CPE can do on the ACS
Send it an Inform and expect a response

Let it know that a file transfer has completed, either one that was
called for by the ACS or an Autonomous Transfer

Request that a file transfer be started, such as a firmware download

35
 Faults
Handled through SOAP

CPE fault codes are 9000 series

ACS fault codes are 8000 series

SetParameterValues faults include the oending parameters!

36