TR-069 https://www.iol.unh.edu/sites/default/files/knowledgebase/hnc/TR-069_Crash_Course.pdf

Parts of the DM - Objects

• An object is a data structure in the data model. It has attributes and elements. • An object can be single instance or multiinstance (remember Add/Delete Object)? - Defined by the "minEntries"/"maxEntries" attributes

Stuff 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

TR-098

Device Data Model for Internet Gateway Devices

TR-069

Document number of the technical report, defined by the Broadband Forum, that specifies the "CPE WAN Management Protocol", or "CWMP"

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.

HTTP

The Hypertext Transfer Protocol (HTTP) is an application protocol for distributed, collaborative, hypermedia information systems. HTTP is the foundation of data communication for the World Wide Web. Hypertext is structured text that uses logical links (hyperlinks) between nodes containing text.

Add Object/Delete Object

Allows 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 CPE then uses to reference the object • Instance numbers aren't standardized and must remain! If something is deleted with an instance number "between" two other instances, the others cannot change!

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.

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

Protocol Stack

CPE (Customer premises equipment) /ACS (Auto-Configuration Server) Management Application RPC (Remote Procedure Call) Methods SOAP (Simple Object Access Protocol) HTTP (Hypertext Transfer Protocol) SSL(Secure Sockets Layer)/TLS (Transport Layer Security) TCP (Transmission Control Protocol/IP (Internet Protocol)

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.

CPE ACS session

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 Authentication: • TR-069 requires the use of HTTP basic, HTTP digest, or Certificate based authentication • Authentication occurs in both directions • The CPE authenticates the ACS's Connection Requests • The ACS authenticates the CPE's session initiation

RPC

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

Importing models

Data models import from one another, then add or refine definitions of objects and parameters, creating a new version

TR-069 - CWMP

Currently Amendment 2, which is CWMPv1.1 - Defines protocol, message structure, session rules, and RPCs - Annexes deal with NAT traversal and association of gateways to LAN devices

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.

XML Documents and Versioning

Data models are published on the Broadband Forum website: - http://www.broadband-forum.org/cwmp.php • Document versions are of the format "majorminor-corregendum", for example, tr-098-1-1-0.xml • Intention is for minor revisions are backwards compatible, major revisions not

FTP

File Transfer Protocol

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

ACS Methods

GetRPCMethods • Inform • TransferComplete • AutonomousTransferComplete • RequestDownload • Kicked

IPDV

IP Delay Variation

ICMP

Internet Control Message Protocol

RG

Residential Gateway

POP

Point of Presence

QoS

Quality of Service

The Future... a slew of other WTs and PDs

Redefining generic device model, adding proxy functions, etc.

SOAP Message Structure

SOAP Body contains RPC call or response, as well as all of the arguments they contain. In this case, we see a SetParameterValues RPC (procedure that exists on CPE, that's called by ACS, to which CPE will respond.). The RPC uses the SOAP definition of an array, further specified by the cwmp namespace to refer to a "ParameterValueStruct" ( a name/value pair, and the XML tags represent that). The Soap Header, in CWMP, contains transaction info. In this case, it contains the CWMP message ID, which is used by the system to associate calls and responses. Note use of namespace - cwmp:ID - it's saying "use the ID data type defined in the cwmp namespace in the envelope attributes, above." SOAP envelope tag contains, as attributes, the namespace references that the later tags will draw from. This one draws from "Schema of Schemas", the Broadband Forum (once, the DSL Forum, and has been maintained for backwards compatibility) CWMP Schema, and the SOAP schema.

SSL

SSL (Secure Sockets Layer) is the standard security technology for establishing an encrypted link between a web server and a browser. This link ensures that all data passed between the web server and browsers remain private and integral.

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!

SOAP

Simple Object Access Protocol

TCP/IP

TCP/IP (Transmission Control Protocol/Internet Protocol) is the basic communication language or protocol of the Internet. It can also be used as a communications protocol in a private network (either an intranet or an extranet).

TR

Technical Report

What is TR-069

Technical Report is a Broadband Forum (formerly DSL Forum) technical specification entitled CPE WAN Management Protocol (CWMP). It defines an application layer protocol for remote management of end-user devices. As a bidirectional SOAP/HTTP-based protocol, it provides the communication between customer-premises equipment (CPE) and Auto Configuration Servers (ACS). It includes both a safe auto configuration and the control of other CPE management functions within an integrated framework. The protocol addresses different Internet access devices such as modems, routers, gateways, set-top boxes, and VoIP-phones for the end-users.

The Inform RPC "event"

The Inform "event" array contains a list of one or more pre-defined reasons for the session being initiated. • "0 BOOTSTRAP" • "1 BOOT" •"2 PERIODIC" •"3 SCHEDULED" •"4 VALUE CHANGE" •"5 KICKED" •"6 CONNECTION REQUEST" •"7 TRANSFER COMPLETE •"8 DIAGNOSTICS COMPLETE" •"9 REQUEST DOWNLOAD" •"10 AUTONOMOUS TRANSFER COMPLETE" • "M Reboot" • "M Scheduled Inform" • "M Download" • "M Upload" • Vendor Specific Functions and Events...

UDP

User Datagram Protocol

Why does a CPE start a session?

When it first contacts this ACS <= "0 BOOTSTRAP" When it reboots <= "1 BOOT" When its periodic inform interval's met <= "2 PERIODIC" When an inform was scheduled <= "3 SCHEDULED" When a parameter set for notification has changed <= "4 VALUE CHANGED When it is asked to by the ACS <= "6 CONNECTION REQUEST" When it has completed an upload or download and is going to call "TransferComplete" <= "7 TRANSFER COMPLETE" <= "10 AUTOMOUS TRANSFER COMPLETE When it has completed diagnostics <= "8 DIAGNOSTICS COMPLETE" The CPE wants to request a download <= "9 REQUEST DOWNLOAD"

Why Use TR-069

With it, Service Providers can use one common platform to manage, through the Internet, all of their Customer Premise Devices, no matter the device nor the manufacturer. This common app has never been achieved before due to CPE vendors creating proprietary mechanisms for management.

TR-106

XML Schema definition and common objects for Device Data Models

GetParameterNames

• Allows the ACS to learn the objects and parameters that exist on the CPE • Often used to determine device characteristics • May be complete or partial path

Parts of a DM - Parameters

• A Parameter is a variable of an object in the Data Model

XML Schema, Namespaces

• A particular use of XML is described in a "Schema" (.xsd) • Schemas inherit, like in other languages, through "namespaces"

What's a Data Model?

• A structured representation of the objects, parameters, and their syntax that can be used to "model" a particular use case of TR-069 • Most often, models a particular "kind" of CPE or the services that might exist on one • The docs have evolved over time and inherit or build on each other

Reboot

• 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

SetParameterValues

• Allows ACS to write parameters on CPE • Always complete path

GetRPCMethods

• Allows the ACS (or the CPE) to learn the RPCs supported by the CPE (or ACS) • May contain "vendor extensions" or custom RPCs

Devices, Components and Services...

• At the heart of each data model are devices, components, and services • Devices: - The root of the data model. In the firs generation of the data models, the this is separated into Device. & InternetGatewayDevice., which are different root models. In TR-181i2 (Device:2), Device. is the root of the data model. • Components: - Specified in TR-157 - Indicate common objects and parameters that can be included in any Device (such as .ManagementServer.) and/or services (such as diagnostic objects specified in TR-143) • Services: - Data models that add additional functionality related to the delivery of specific services. These include TR-135 (Set Top Boxes), TR-104 (VoIP), TR-140 (Network Attached Storage), TR-192 (Femto Access Points), etc.

More Resources

• Broadband Forum Website: - http://www.broadband-forum.org • UNH-IOL TR-069 Consortium - http://www.iol.unh.edu/services/testing/tr069/ • TR-069 XML Tools Repository - http://tr69xmltool.iol.unh.edu/ • W3 Schools XML Primer - http://www.w3schools.com/xml/default.asp

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

The Device Type Schema

• Defined in Annex B of TR-106 • Can be shared beforehand or passed in SupportedDataModel parameter. • A DT instance an XML document that is based on the DT schema and imports some or all of a particular Data Model.

Object Elements

• Description - contains description and normative text, including any functionality requirements • Unique Key - specifies the parameter that acts as a unique key for the table (in multi-instance objects) • Parameter(s) - the meat of an object - parameters have their own sub elements and attributes

Publishing of the Documents

• Descriptive text is published as pdf • Normative text is published as XML • Tools exist to trace the xml import tree and generate html tables explaining the data models • Open source tools exist at: - https://tr69xmltool.iol.unh.edu/

What about these "M" Events?!

• Events that start with "M" are associated with an RPC recently completed by the CPE • Usually show up with other events • Example: - "1 BOOT" and "M Reboot" • The CPE rebooted, and it was because it completed the "Reboot" RPC - "7 TRANSFER COMPLETE" and "M Download" • The CPE is going to call "transfer complete", and it was because it finished a download caused by the ACS use of the Download RPC

Get/Set Parameter Attributes

• Every parameter in CWMP has two XML attributes, Notification and Access List • Changed and read with GetParameterAttributes and SetParameterAttributes, respectively • SetParameterAttributes has additional argument stating whether or not each of the two (Notification or Access List) are being asked to be changed from their current state.

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

CPE Methods

• GetRPCMethods • SetParameterValues • GetParameterValues • GetParameterNames • SetParameterAttributes • GetParameterAttributes • AddObject • DeleteObject • Reboot • Download • Upload • FactoryReset • GetQueuedTransfers • GetAllQueuedTransfers • ScheduleInform • SetVouchers • GetOptions

Faults

• Handled through SOAP • Listed in section A.5 of TR-069a2 • CPE fault codes are 9000 series • ACS fault codes are 8000 series • SetParameterValues faults include the offending parameters!

Example Device Type

• Imports Data Model XML, or parts of them The Device Type Instance specifies the parameters in the imported data model that it supports, what their access permissions are, as well as the version. It also indicates (with the "activeNotify" attribute) whether or not device will deny attempts to set Active Notification on the parameter.

... and Interfaces

• In Device:2, the concept of interfaces and the interface stack are introduced • An interface is a particular OSI stack component, with its objects and paramters specified within it • The interface stack is a table containing the links between interfaces - thus any necessary combination of internetworking protocols can be assembled • The interface stack is read-only, and can be used to learn a device's configuration quickly

What do the curly braces mean?

• In the description element, text enclosed by {{curly braces}} indicates a reference to another object, parameter, or document in the bibliography. • The reporting tool for BBF XML will change these into hyperlinks

Stuff 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 parameter's attributes • Reboot the CPE • Tell it to download a file or firmware image

Object Attributes

• Name - name of object. Can also be "Base", (indicates that it's being extended from an object in one of the imported data models). • Access - readOnly objects can't be altered with Add/Delete Object • minEntries - The min. number of instances of the object that must exist • maxEntries - The max. number of instances that can exist

Parameter Attributes

• Name - the name of the parameter. This can also be "Base", which indicates that it is being extended from a similar parameter in one of the imported data models. • Access - readOnly or readWrite. readOnly parameters cannot be affected by SetParameterValues

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 docs that are "schema-like", but describe the objects and parameters used for a particular TR- 069 use case.

TransferComplete

• RPC called on ACS by CPE after an upload or download has completed (AND has been applied, if firmware) • Accompanied by the "7 TRANSFER COMPLETE" if being called in a new session • AutonomousTransferComplete - similar, but used only if the transfer was requested by a source other than the ACS

The Documents...

• TR-069 - Specifies CWMP • TR-098 - Specifies the root data model for Internet Gateway Devices (in Device:1) • TR-106 - Specifies the schema for device models and device types (used by all other data model docs) - more about device type schema later! • TR-111 - (was subsumed into Annexes F and G of TR-069 Amendment 2) • TR-157 - Specifies Component objects for use in data models • TR-143 - Specifies diagnostics objects for use in data models • TR-181i1 / 181i2 - Specifies Device:1 / Specifies Device:2 • TR-104, TR-135, TR-140, TR-192 - specifies service data models for VoIP, IPTV, NAS, and FAP, respectively

How do we know what CPE supports?

• The Hard Way - using GetParameterNames multiple times • Profiles - Defined in each DM, profiles indicate the minimum requirements to support a particular functionality and are conveyed by the CPE in the "DeviceSummary" parameter. This was deprecated, however, in favor of...

The Inform RPC

• 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. • The ACS completes the RPC by sending an InformResponse.

Document and Version Alignment

• The doc. version and the data model version may be different! • There's not a direct correlation between a data model and a doc. A data model may be changed by multiple docs, tracked through imports. • Data Model versions are denoted as Name:Version, for example InternetGatewayDevice:1.4, or Device:2 Though the majority of the InternetGatewayDevice data model is specified in TR-098, updates resulting in version InternetGatewayDevice:1.3 were released in TR-143.

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

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

XML

• eXtensible Markup Language • Used to describe information • Through SOAP, allows client/server application transactions through Remote Procedure Calls (RPCs)

Parameter Elements

•Description - contains description and normative text, including any functionality requirements •Syntax - the data type of the parameter and any restrictions on the values - Syntaxes are usually self explanatory. They are defined in the Data Model schema