Skip to content

Introduction

Jump to bottom
Dirk Feytons edited this page Feb 16, 2017 · 8 revisions

A brief introduction to why Transformer was created and define some terminology that is used throughout the codebase.

TR-069

Description

Broadband Forum defined a protocol for network service providers to remotely manage deployed network devices (CPEs) from an Auto-Configuration Server (ACS). This protocol is described in Technical Report 069, or TR-069 for short. Several versions have been released; the latest one (Amendment 5 at the time of writing) can be downloaded from the BBF website.

As described in the specification the protocol is intended to be used for the following

  • Auto-configuration and dynamic service provisioning
  • Software/firmware image management
  • Software module management
  • Status and performance monitoring
  • Diagnostics

Protocol Overview

Communication between CPE and ACS primarily happens using RPCs encoded in SOAP over HTTP(S). Most of the time it's the CPE who decides to contact the ACS (because of a periodic timer expiring, an earlier configured timestamp is reached, a notification needs to be delivered, ...) but the ACS can trigger a CPE by means of a Connection Request to setup a new connection.

When a connection with the ACS is established by the CPE it will initiate a new session by sending an Inform RPC to the ACS, who will acknowledge it with an InformResponse message. After that additional RPCs can be invoked.

Some RPCs used often by the ACS are:

  • GetParameterValues: Retrieve configuration data from the device. How this data is organized and exposed is explained in the section on datamodels.
  • SetParameterValues: Change configuration parameters on the device. The specification requires that all parameters sent in this RPC are either successfully changed or on error none are changed. In other words, a SetParameterValues RPC must be executed as a transaction.
  • GetParameterNames: Allows the ACS to get a view on the available configuration parameters and whether they can be changed.
  • GetParameterAttributes: Retrieve attributes associated with configuration parameters. Currently there are two attributes defined: notification and access list.
  • SetParameterAttributes: Change the attributes associated with configuration parameters. By changing the notification attribute the ACS can subscribe to updates of those parameters. The CPE has to either report changes in the next Inform it sends (passive notification) or as soon as possible (active notification). By changing the access list attribute the ACS can grant or revoke access to configuration parameters for other management channels.
  • AddObject: Add a new object instance to the configuration of the device.
  • DeleteObject: Remove an existing object instance from the configuration of the device.
  • Reboot: Perform a reboot of the device. This shouldn't happen immediately but at the end of the ongoing management session between the CPE and the ACS.
  • FactoryReset: Reset the device to factory defaults.

Example RPC Exchange

A GetParameterValues RPC sent by the ACS:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:cwmp="urn:dslforum-org:cwmp-1-1">
  <SOAP-ENV:Header>
    <cwmp:ID SOAP-ENV:mustUnderstand="1">11</cwmp:ID>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <cwmp:GetParameterValues>
      <ParameterNames SOAP-ENC:arrayType="xsd:string[3]">
        <string>InternetGatewayDevice.DeviceInfo.SoftwareVersion</string>
        <string>InternetGatewayDevice.Layer3Forwarding.ForwardNumberOfEntries</string>
        <string>InternetGatewayDevice.WANDevice.2.WANConnectionDevice.1.WANPPPConnection.1.ExternalIPAddress</string>
      </ParameterNames>
    </cwmp:GetParameterValues>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Example response by the CPE:

<soapenv:Envelope soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:cwmp="urn:dslforum-org:cwmp-1-2">
  <soapenv:Header>
    <cwmp:ID soapenv:mustUnderstand="1">11</cwmp:ID>
  </soapenv:Header>
  <soapenv:Body>
    <cwmp:GetParameterValuesResponse>
      <ParameterList soap:arrayType="cwmp:ParameterValueStruct[03]">
        <ParameterValueStruct><Name>InternetGatewayDevice.DeviceInfo.SoftwareVersion</Name><Value xsi:type="xsd:string">17.1.7590-0010000</Value></ParameterValueStruct>
        <ParameterValueStruct><Name>InternetGatewayDevice.Layer3Forwarding.ForwardNumberOfEntries</Name><Value xsi:type="xsd:unsignedInt">12</Value></ParameterValueStruct>
        <ParameterValueStruct><Name>InternetGatewayDevice.WANDevice.2.WANConnectionDevice.1.WANPPPConnection.1.ExternalIPAddress</Name><Value xsi:type="xsd:string">80.0.0.1</Value></ParameterValueStruct>
      </ParameterList>
    </cwmp:GetParameterValuesResponse>
  </soapenv:Body>
</soapenv:Envelope>

Datamodels

OpenWrt/LEDE and Transformer

Clone this wiki locally