TR069协议初探

1. TR069 协议介绍

TR069，全称“Technical Report 069”是由 DSL Forum（一个非盈利性的全球行业联盟,致力于发展宽带网络范，其成员包括通讯、设备、计算机、网络和服务提供商等行业的领先厂商，现已更名为“Broadband Forum”）修订一份技术规范，该规范是应用层的管理协议，命名为“CPE 广域网管理协议（CPE WAN Management Protocol）”，简称 CWMP。这个协议主要用于网管中心远程管理配置数量较大的网络设备。目前主要应用在企业级路由器、一体化皮基站等网络设备的管理，所以 TR069 是一个功能强大的用于数据中心、网管中心管理它所属的所有网络设备的网管协议。

在 TR069 协议定义的网管模型中管理服务器称为自动配置服务器 (ACS)，负责完成对用户终端设备 (CPE) 的管理。ACS 与 CPE 之间的接口称为南向接口，ACS 与运营商的其他网管系统、业务管理系统、计费系统 (OSS/BSS) 之间的接口称为北向接口，TR069 协议主要定义南向接口的标准。

TR069 协议网络拓扑如下图，ACS 是在网络中的服务器，根据预定制来管理设备，其左侧连接运营商的其他网管系统、业务管理系统等北向接口；右侧为连接用户终端设备的南向接口。

CPE 是客户端设备(Customer Premises Equipment)的简称：CPE 就是网管中心下所有的被管理设备。
ACS 是自动配置服务器(Auto-Configuration Server)的简称：ACS 就是一个在网管中心带有 DHCP 服务和 DNS 服务，符合 CWMP 协议的数据配置服务器；负责完成对用户终端设备(CPE)的管理。
运营支持系统（Operation Support System，OSS）和业务支撑系统（Business Support System，BSS）
通信机制：基于 HTTP/HTTPS，使用 SOAP 封装 XML 格式的消息。

TR069 的核心思想是通过定义一套 ACS 和 CPE 之间的自动协商交互协议，实现终端的自动配置过程。

TR069协议详解-CSDN博客

2. TR069 功能

TR069 的网络架构简化如下：

常见的网管功能都有，如：

提供数据参数配置和自动配置：ACS 可以为连接上的 CPE 进行自动配置，无需手动配置。
文件管理：CPE 可以从 ACS 通过协议标准的数据模型上传或下载文件（包括升级软固件包、日志文件、性能统计文件等等）。
状态和性能监控：ACS 可以通过标准定制的方法监控 CPE 的状态和性能统计，同时 CPE 也可以主动通知 ACS 自身状态的更新。
告警上报：CPE 可以主动向 ACS 上传设备中的告警信息。

CWMP 让运营商“坐在机房”就能完成原本需要上门才能做的配置、升级、监控和排障，实现 CPE 全生命周期管理。

3. TR069 协议栈

TR069 协议在设计上充分借鉴了 Web 技术的优点，基于控制协议 TCP 传输。如协议的核心部分为远程过程调用(RPC)，该方法经过简单对象访问协议(SOAP)封装后使用 HTTP 协议在 ACS 和 CPE 之间传递。其中 ACS 作为 HTTP 服务器，CPE 作为 HTTP 客户端。RPC 方法基于 XML（可扩展标记语言）进行描述。如下表所示为 CPE WAN 管理协议中的协议栈结构。

分类	协议层	描述
应用	CPE/ACS Management Application	应用可以在 CPE 和 ACS 端分别实现 CWMP 协议
远程调用方法	RPC Methods	在 CWMP 中定义的各种 RPC 方法，实现 ACS 与 CPE 之间的交互
报文填写标准	SOAP	消息内容是基于 SOAP 标准封装 XML 文档
传输协议	HTTP	ACS 为 HTTP 服务器，CPE 为 HTTP 客户端
安全传输协议	SSL/TLS	标准的互联网传输层安全协议（可选）
底层协议	TCP/IP	标准的 TCP/IP

RPC 方法：ACS 通过执行一系列操作来管理和监控 CPE，这些操作在 TR069 协议中称为 RPC 方法。
SSL：SSL 协议指定了一种在应用程序协议和 TCP/IP 协议之间提供数据安全性分层的机制，它为 TCP/IP 连接提供数据加密、服务器人证、消息完整性以及可选的客户机人证，确保数据在传送中不被改变。TR069 协议实现的是远程管理，安全的信息交换是必需的，借此实现 CPE 和 ACS 之间的安全信息交换。

3.1 RPC 方法

RPC（Remote Procedure Call）远程过程调用是一种通过网络从远程计算机程序上请求服务。
远程过程调用（RPC）是 TR069 的核心交互机制：

CPE 函数：由 ACS 主动调用，对 CPE 进行读写、升级、重启等管理操作。
ACS 函数：由 CPE 主动调用，向 ACS 上报事件、状态或传输结果。

RPC 协议的处理流程回路：

当客户端要发起一个远程调用时，先通过本地调用的 Stub 将调用的接口、方法和参数，通过约定的协议进行编码，并通过本地的 RPCRuntime 进行传输
服务器端的 RPCRuntime 在接收到请求之后，交给 Stub 进行解码，然后调用服务器端的方法
服务器端方法执行完成之后，再返回给 Stub 进行编码并通过 RPCRuntime 返回给客户端
客户端 RPCRuntime 接收到结果，交给 Stub 进行解码，最终在本地返回

Stub（存根）是 RPC 中的一个重要组件，它在客户端和服务端都有对应的实现：

客户端 Stub（调用方 Stub）：
- 负责将客户端的函数调用转换为可以在网络上传输的消息格式。
- 负责将服务器返回的消息解封装，转换回客户端可以理解的格式。
服务端 Stub（提供方 Stub）：
- 负责将接收到的网络消息解封装，提取出调用的参数。
- 负责将服务的返回结果封装成网络消息，发送回客户端。

Stub 的目的是隐藏底层的网络通信细节，使得调用远程服务就像调用本地函数一样简单。这样，开发者可以专注于业务逻辑的实现，而不需要关心网络通信的具体细节。

3.1.2 CPE 函数

CPE 函数由 ACS 调用，用来对 CPE 进行管理，例如：设置/获取 CPE 参数属性、设置/获取 CPE 参数值、硬件升级和重启设备等。

CPE 侧 RPC 方法	说明
GetRPCMethods	获取 RPC 方法列表
SetParameterValues	ACS 设置参数值
GetParameterValues	ACS 获取参数值
GetParameterNames	ACS 获取参数列表
SetParameterAttributes	ACS 设置参数属性
GetParameterAttributes	ACS 获取参数属性
AddObject	ACS 增加一个新实例
DeleteObject	ACS 删除特定实例
Reboot	重启
Download	下载指定文件
Upload	上传指定文件
FactoryReset	恢复出厂设置

3.1.3 ACS 函数

ACS 函数由 CPE 调用，是 CPE 用来向 ACS 上报状态信息，请求硬件镜像文件下载（用来升级硬件）等。

ACS 侧 RPC 方法	说明
GetRPCMethods	获取 RPC 方法列表
Inform	任何时刻要建立与 ACS 的连接，CPE 必须调用 Inform 方法进行上报，来初始化一个传输序列
TransferComplete	通知传输完成情况

3.2 SOAP 简单对象访问协议

SOAP（Simple Object Access Protocol，简单对象访问协议）是一种基于 XML 的轻量级协议，用于在网络中交换结构化信息；在 TR069 协议中用于封装 RPC 请求/响应，确保 CPE 和 ACS 之间的跨平台、安全通信。

3.2.1 请求头和正文

SOAP 将请求和回复放在了一个信封里边，分别包括了请求头和正文：

POST / HTTP/1.1
Host: acs.uztelecom.local:80
SoapAction:
Connection: Keep-Alive
Content-Type: text/xml; charset=UTF-8
User-Agent: HW_WAP_CWMP_V02
Content-Length: 2418

Host: acs 域名或 ip:端口
SoapAction：SOAP 协议中用于描述此次操作的目的，当 HTTP 请求中含有 SOAP 回应或者 SOAP 失败回应时，HTTP 请求中的 SOAPAction 头必须为空(没有引用)，。
Content-Type: 内容类型，text/xml（SOAP 1.1）
Content-Length: 字节为单位
空 HTTP POST 不能含有 SOAPAction 头和 Content-Type 头。

SOAP 的正文的结构为：

<soap:Envelope 省略 />
      <soap:Header>
        <cwmp:ID soap:mustUnderstand="1">ID  值（值必须与响应对应，起“消息关联”作用）</cwmp:ID>
      </soap:Header>
      <soap:Body>
        <cwmp:RPC的调用方法或Response>
        </cwmp:RPC的调用方法或Response>
      </soap:Body>
</soap:Envelope>

正文中 SOAP 专用的 Header 块， CWMP 规范只强制要求一个 Header 元素：

1	<cwmp:ID soap:mustUnderstand="1">ID值（关联请求与响应，值由 ACS 或 CPE 生成，必须唯一）</cwmp:ID>

下面这两个是可选的：

1 2	<cwmp:NoMoreRequests>0</cwmp:NoMoreRequests> <cwmp:HoldRequests>0</cwmp:HoldRequests>

NoMoreRequests：用于在 CPE 和 ACS 之间明确告知当前请求序列是否结束，0 为否，1 为是。
- 如果 CPE 在会话中发送了一个空的 HTTP POST（表示没有更多请求），并且收到的响应中包含 NoMoreRequests=1，则 CPE 应该关闭连接。
HoldRequests：用于控制 CPE 在当前请求处理期间是否发送新的请求，0 为否，1 为是。
- 如果 CPE 收到一个带有 HoldRequests=1 的 HTTP 响应，CPE 应该暂停发送新的请求，直到收到一个带有 HoldRequests=0 的响应。
- 如果 CPE 收到一个没有 HoldRequests 头部的响应，这等同于收到 HoldRequests=0

3.2.2 以 SetParameterValues 为例

例子：以 ACS 通过 RPC 方法中的 SetParameterValues 设置参数值消息通信为例：

ACS SetParameterValues Request

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
					xmlns:SOAP-ENC="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-0">
   <SOAP-ENV:Header>
       <cwmp:ID SOAP-ENV:mustUnderstand="1">48</cwmp:ID>
       <cwmp:NoMoreRequests>0</cwmp:NoMoreRequests>
       <cwmp:HoldRequests>0</cwmp:HoldRequests>
   </SOAP-ENV:Header>
   <SOAP-ENV:Body>
       <cwmp:SetParameterValues>
           <ParameterList SOAP-ENC:arrayType="cwmp:ParameterValueStruct[3]">
               <ParameterValueStruct>
                   <Name>InternetGatewayDevice.ManagementServer.ConnectionRequestPassword</Name>
                   <Value xsi:type="xsd:string">uztelec0m</Value>
               </ParameterValueStruct>
               <ParameterValueStruct>
                   <Name>InternetGatewayDevice.ManagementServer.ConnectionRequestUsername</Name>
                   <Value xsi:type="xsd:string">ACS</Value>
               </ParameterValueStruct>
               <ParameterValueStruct>
                   <Name>InternetGatewayDevice.ManagementServer.PeriodicInformInterval</Name>
                   <Value xsi:type="xsd:unsignedInt">21600</Value>
               </ParameterValueStruct>
           </ParameterList>
           <ParameterKey></ParameterKey>
       </cwmp:SetParameterValues>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

CPE SetParameterValuesResponse

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
					xmlns:SOAP-ENC="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-0">
   <SOAP-ENV:Header>
       <cwmp:ID SOAP-ENV:mustUnderstand="1">48</cwmp:ID>
   </SOAP-ENV:Header>
   <SOAP-ENV:Body>
       <cwmp:SetParameterValuesResponse>
           <Status>0</Status>
       </cwmp:SetParameterValuesResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

五个 xmlns：用来定义一些编码规则
- soap: SOAP 1.1 信封规范（Envelope/Header/Body/Fault）
- soapenc: SOAP 1.1 编码规则（arrayType 等）
- cwmp: TR069 CWMP 私有标签（SetParameterValues、ParameterValueStruct …）
- xsd: / xsi: W3C XML Schema 数据类型与实例声明（string、boolean …）
soapenc:arrayType=“cwmp:ParameterValueStruct[3]”：cwmp:ParameterValueStruct 为数组类型，3 表示数组有三个元素（参数）。
ParameterKey：ACS 给这次写参数动作起的“任务编号”，方便以后追踪、去重或回滚。

4. TR069 的业务流程

TR069 中规定的远程管理系统的工作过程主要包括 ACS 发现的过程、ACS 与网络终端设备建立连接的过程，以及 ACS 对 CPE 终端设备进行认证的过程。

在建立安全的 HTTP 连接以后，每次连接 CPE 都必须首先对 ACS 发出一个 Inform 的 RPC 调用请求来向 ACS 汇报本次连接的信息，ACS 会返回给一个 InformResponse 作为确认连接。

只有 Inform 交互完成之后，后续才可以进行其他的操作。
ACS 需要与 CPE 建立过连接，保存其 IP 地址，后续才可以随时向 CPE 发送 Connection Request（HTTP 请求）。

4.1 Inform 交互

标准的 Inform 方法的参数如下表所示。

参数名称	参数说明
DeviceID	CPE 设备描述信息
Event	标识此次 Inform 发起的原因
MaxEnvelopes	HTTP Response 可携带 SOAP 信封数，0 表示无限制
CurrentTime	CPE 当前的时间
RetryCount	完成 inform 调用前尝试的次数每次加一
ParameterList	这次 Inform 所需携带的参数

Inform 交互中 ACS 和 CPE 的 SOAP 报文：

CPE Inform：

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
					xmlns:SOAP-ENC="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-0">
   <SOAP-ENV:Header>
       <cwmp:ID SOAP-ENV:mustUnderstand="1">48</cwmp:ID>
   </SOAP-ENV:Header>
   <SOAP-ENV:Body>
       <cwmp:Inform>
           <DeviceId>
               <Manufacturer>Huawei Technologies Co., Ltd</Manufacturer>
               <OUI>00259E</OUI>
               <ProductClass>HG8245H5</ProductClass>
               <SerialNumber>485754438E460B9F</SerialNumber>
           </DeviceId>
           <Event SOAP-ENC:arrayType="cwmp:EventStruct[1]">
               <EventStruct>
                   <EventCode>6 CONNECTION REQUEST</EventCode>
                   <CommandKey/>
               </EventStruct>
           </Event>
           <MaxEnvelopes>1</MaxEnvelopes>
           <CurrentTime>2025-07-17T05:55:17+00:00</CurrentTime>
           <RetryCount>0</RetryCount>
           <ParameterList SOAP-ENC:arrayType="cwmp:ParameterValueStruct[8]">
               <ParameterValueStruct>
                   <Name>InternetGatewayDevice.ManagementServer.ParameterKey</Name>
                   <Value xsi:type="xsd:string"/>
               </ParameterValueStruct>
               <ParameterValueStruct>
                   <Name>InternetGatewayDevice.ManagementServer.ConnectionRequestURL</Name>
                   <Value xsi:type="xsd:string">http://10.156.190.210:7547/0179e86452d4cf0cba3c245d28ebe400</Value>
               </ParameterValueStruct>
               <ParameterValueStruct>
                   <Name>InternetGatewayDevice.DeviceSummary</Name>
                   <Value xsi:type="xsd:string">InternetGatewayDevice:1.4[](Baseline:1, EthernetLAN:1, WiFiLAN:2, Time:1, IPPing:1, DeviceAssociation:1), VoiceService:1.0[1](Endpoint:1, SIPEndpoint:1)</Value>
               </ParameterValueStruct>
               <ParameterValueStruct>
                   <Name>InternetGatewayDevice.DeviceInfo.SpecVersion</Name>
                   <Value xsi:type="xsd:string">1.0</Value>
               </ParameterValueStruct>
               <ParameterValueStruct>
                   <Name>InternetGatewayDevice.DeviceInfo.HardwareVersion</Name>
                   <Value xsi:type="xsd:string">150D.A</Value>
               </ParameterValueStruct>
               <ParameterValueStruct>
                   <Name>InternetGatewayDevice.DeviceInfo.SoftwareVersion</Name>
                   <Value xsi:type="xsd:string">V5R019C10S395</Value>
               </ParameterValueStruct>
               <ParameterValueStruct>
                   <Name>InternetGatewayDevice.DeviceInfo.ProvisioningCode</Name>
                   <Value xsi:type="xsd:string"/>
               </ParameterValueStruct>
               <ParameterValueStruct>
                   <Name>InternetGatewayDevice.WANDevice.1.WANConnectionDevice.8.WANIPConnection.1.ExternalIPAddress</Name>
                   <Value xsi:type="xsd:string">10.156.190.210</Value>
               </ParameterValueStruct>
           </ParameterList>
       </cwmp:Inform>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

ACS InformResponse

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
			xmlns:SOAP-ENC="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-0">
   <SOAP-ENV:Header>
       <cwmp:ID SOAP-ENV:mustUnderstand="1">48</cwmp:ID>
       <cwmp:NoMoreRequests>0</cwmp:NoMoreRequests>
       <cwmp:HoldRequests>0</cwmp:HoldRequests>
   </SOAP-ENV:Header>
   <SOAP-ENV:Body>
       <cwmp:InformResponse>
           <MaxEnvelopes>1</MaxEnvelopes>
       </cwmp:InformResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

4.2 ACS 修改 CPE 的值 CWMP 工作流程

下图为 ACS 修改 CPE 的值时的 CWMP 工作流程：

会话建立（两种情况）
- CPE 主动发起：手动上报、周期上报、断线重连时自动发起等。
- ACS 主动发起：ACS 可随时向 CPE 发送 Connection Request（HTTP 请求），前提是在首次通信后，ACS 已保存了 CPE 的 IP 地址。
安全连接
- 双方通过 SSL/TLS 建立加密通道
  - CPE 验证(CPE 主动发起)：CPE 发送 Inform 请求，携带用户名/密码，ACS 核对本地配置。
  - ACS 验证(ACS 主动发起)：ACS 发 Connection Request 时，CPE 核对 HTTP 用户名/密码。
会话阶段
- 会话启动阶段
  - CPE 发送 Inform 请求（含设备信息、事件码等）。
  - ACS 返回 InformResponse → 会话确立。
  - CPE 发送空 HTTP POST，表示“无更多主动 RPC”。
- 通信阶段
  - 调用 RPC 方法进行操作。
- 会话终止阶段
  • 仅 CPE 有权终止会话。
  • 当双方 RPC 交互完毕且收到空 HTTP 响应后，CPE 主动关闭连接。

【HUAWEI】CWMP Implementation

5. EasyCwmp

EasyCwmp 是当前最为成熟的 CWMP 客户端软件，其中 EasyCWMP Core 是开源的。

EasyCwmp 主体分为两个部分：

EasyCwmp Core：包含了负责与 ACS 服务器交互的功能，C 语言开发，这部分写好后一般不会动了。
EasyCwmp DataModel：包含了 TR098、TR181、TR104 等与 TR069 相关的数据模型规范，shell 脚本开发，增删改查节点都在这里实现。

EasyCwmp 模块化设计图如下：

TR-098（InternetGatewayDevice，老 DSL 终端模型）
TR-181（Device:2，新统一终端模型）
TR-104（VoIP 扩展）

EasyCWMP 文件结构如下表所示：

目录	作用	备注
/src	EasyCwmp 核心 CWMP 引擎，负责与 ACS 通信	含 backup.c、base64.c、basicauth.c、 config.c、cwmp.c、digestauth.c、 easycwmp.c、external.c、http.c、 json.c、log.c、md5.c、time.c、 ubus.c、xml.c
/ext/openwrt/config	cwmp 配置文件，使用 uci 模块进行配置	文件：easycwmp
/ext/openwrt/scripts	1. 命令的入参处理 2. 与系统接口的定义	文件：easycwmp.sh
/ext/openwrt/scripts/functions/common	1. 操作方法的具体实现 2. Json 相关函数 3. 其他函数封装，数据模型	例如：common、device_info、 ipping_launch、management_server
/ext/openwrt/scripts/functions/tr098	tr098 数据模型	例如：ipping_diagnostic、lan_device、 root、wan_device
/ext/openwrt/scripts/functions/tr181	tr181 数据模型	例如：dhcpv4、ip、ipping_diagnostic、 root、wifi

架构上，EasyCwmp 主要可以分为以下几个组件：

协议栈组件：负责实现 TR-069 协议的底层通信，包括 SOAP 协议的封装和解封装
核心服务组件：提供核心的服务功能，如设备管理、任务调度等。
数据模型组件：定义了与设备通信时所使用的数据结构。
API 接口组件：为外部程序提供与 EasyCwmp 通信的接口。

5.1 添加子节点

添加子节点实现就是调动 common_execute_method_param 函数设置不同的参数，参数的入参如下：
子节点最后是没有一点 . 的。

入参	说明	样例	类型
$1	节点名称	InternetGatewayDevice.X_CT_COM_MacFilterCfg	字符串
$2	权限 permission	0	0：只读 R 1：读写 RW
$3	GET 方法		函数
$4	SET 方法		函数
$5	数据类型	xsd:unsignedInt xsd:string	数据类型表
$6	inform 上报	0	0：不上报，默认值 1：上报

1	common_execute_method_param "$DMROOT.X_CT_COM_MacFilterCfg.Enable" "1" "config_MacFilter_param get Enable" "config_MacFilter_param set Enable" "xsd:string" ""

5.2 添加多实例的节点

添加含多实例的节点实现就是调动 common_execute_method_obj 函数进行定义执行操作，参数的入参如下：
多实例的节点最后是有一点 . 的。

入参	说明	样例	类型
$1	节点名称	InternetGatewayDevice.X_CT_COM_MacFilterCfg	字符串
$2	权限 permission	0	0：只读 R 1：读写 RW
$3	add 添加实例方法	add_MacFilterCfg_cfg	函数
$4	del 删除实例方法	del_MacFilterCfg_cfg	函数
$5	遍历实例下子节点方法	browse_MacFilterCfg_instances	函数

1	common_execute_method_obj "$DMROOT.X_CT_COM_MacFilterCfg.X_CT_COM_MacFilterListCfgObj." "1" "add_MacFilterCfg_cfg" "del_MacFilterCfg_cfg" "browse_MacFilterCfg_instances $1"

‍
easycwmp get 命令查看当前节点的情况：

参考资料

TR069 协议详解-CSDN 博客
 CWMP\TR069 协议学习随笔 1——入门基础知识及环境搭建-CSDN 博客
 easycwmp 解读（1.3.1）-添加自定的数据模型 - 代码先锋网
 Tutorial – EasyCwmp
TR069 智能分支管理_H3C 技术_新浪博客
 TR-069 协议完整的通信过程
 TR069网管流程–设备启动到挂上网管
 《TR-069_Amendment-2》翻译_provisioningcode-CSDN博客