WebConfig
Introduction
WebConfig is an open-source cloud service for network configuration management. RDK devices download configurations from the WebConfig cloud during bootup or are notified when updates are available. It has significantly improved the reliability, effectiveness, and simplicity of the systems and tools used to manage, measure, maintain, and troubleshoot Customer Premise Equipment (CPE). It uses a single document with all configurations for devices to download.
Key Features
- The system consolidates and stores device settings, customer personalization, and MSO default settings in a single cloud entity as the source of truth.
- Reduced operational costs
- Improved customer experience when interacting with applications
- Reduced latency between cloud applications and devices
- Reduced overall network load
- Improved quality of experience for customers by centralizing storage of configurable settings and validating reconciliation across platforms, in the cloud, across the account
- Atomic operation: If any setting within the blob is deemed invalid, none of the settings should be applied. Each blob transaction must be atomic; if a single failure occurs, the entire transaction must be aborted, and appropriate failure codes should be provided.
- The client-pull from cloud model allows the CPE to fetch configurations on reboot or poked at its own convenient time, while the cloud-push model requires the CPE to be online and non-busy.
Architecture

Comparison of Cloud Protocol Agents
Feature | WEBPA | WEBCONFIG |
---|---|---|
Logic | Synchronous Cloud PUSH | Asynchronous Device PULL |
Initiation | Cloud | Device |
Data flow | Config pushed to device from Cloud | Config pulled in device from Cloud |
Connection | Always connected when online | Connected only during sync |
Functions supported | HTTP GET, PATCH, POST, PUT, DELETE, Asynch event notifications. | SET i.e., configuration apply |
Number of Requests | One for each use case | One for all use cases (Multipart response) |
Cloud retries | Required Cloud will do retries when device is offline or apply fails | Not Required, Config can be saved in server and pulled on device whenever it comes online |
Error Handling, apply settings and rollback | At webpa client | At RDK component using webconfig-framework |
Schema
- The Webconfig schema defines the structure and parameters of the data that the blob will contain. Each parameter within the blob/schema is predefined.
All RDK TR181 parameters and non TR181 parameters can be mapped to “name”, “value” key value param schema
DataType is optional from schema perspective but mandatory for RDKB TR181 parameters
Dynamic table data will be a msgpack BLOB packed as string in the param msgpack string value field
So basically, all parameters will be treated as scalar by Webconfig client
Webconfig client will call bulk SET API for parameters in the doc response after grouping based on components
The components owning the dynamic table need to support new scalar string parameter to accept the BLOB like Device.NAT.PortMapping.Data
Support for parsing/decoding the BLOB will be added in the RDK component handling the blob for each schema.

Multipart response
Device.X_RDK_WebConfig.URL defined per PARTNER-ID
On every reboot, GET request will be done to Device.X_RDK_WebConfig.URL webconfig server
ETAG HTTP request header will contain the comma separated list of the root and sub doc versions previously applied and saved on device
Cloud Server will compare the version shared by device with what it has and returns only the multipart sub doc for the version mismatch cases
Multipart response will have ROOT doc version in HTTP header Etag
Multipart is HTTP response containing multiple content types or sections separated by boundary
Multipart response received is parsed based on boundary to extract each sub doc headers and content
Parse Namespace sub doc header to find the sub doc identifier/name
Parse ETAG sub doc header to find the sub doc version
Parse body to get sub doc content
Decode sub doc body msgpack to get the TR181 name value pairs.
Group based on RDKB component and make bulk SET
For BLOB value cases, pass the msgpack value over BUS to the component to handle
After sync with the sub doc component if the doc apply status is success persist the new version
In case of error, self-heal and error handling will be done
Webconfig Sync Types
Primary or Bootup Sync
- Each time the device boots up, the Webconfig sends a multipart HTTP GET request to the Operator cloud containing the root and sub-document versions.
- The cloud compares these versions with those currently stored and sends only the mismatched sub-documents as a multipart response (in a MsgPack-encoded BLOB structure) to the CPE.
- The Webconfig then parses the multipart response and forwards it to the RDKB component, which applies the updates and sends the status back to the cloud.
Force sync
For cases when cloud gets device configuration at a later point in time the Webconfig will initiate a POKE.
Using WEBPA, poke or force sync SET request will be sent to the device.
The Webconfig will then request the cloud for the root and sub-document versions, similar to the process during boot.
The parameter X_RDK_WebConfig.ForceSync will be set to “root.”
The new sub-document will be retrieved and applied.
The RDKB component will apply the changes and send the status back to the cloud.
Supplementary sync
- The CPE should sync with the cloud at least once a day.
- This maintenance sync is performed to update various device configurations (such as boot time, health status, and other information) in the cloud for that day.
Blob and Msgpack
Blob
RDK-B components receive bulk configuration in blobs from WebPA.
An additional API allows them to set the entire blob configuration, including:
- Deletion of existing tables
- Adding new tables
- Applying configurations
The components also sync TR-181 to support TR-069.
This approach minimizes ADD, DELETE, GET, and SET bus calls to a single call, enabling faster processing and reducing CPU load.
Msgpack
- The async device pull mechanism retrieves configuration instead of applying it online at runtime as in WebPA.
- It utilizes multipart document requests and responses with a root version, where the multipart HTTP response contains multiple content types separated by boundaries.
- We propose changing the current GET webconfig response format from JSON to MessagePack for faster processing and compression.
- BLOBs are MessagePack wrapped as strings, base64 encoded, and sent over the bus. The webconfig is transparent and sends SET commands to apply each config value as is to the owning components over the bus.
RDKM Webconfig Server Setup
Webconfig supports two types of transport between the cloud and devices: HTTP/WEBPA and MQTT. The RDKM reference server supports only HTTP/WEBPA. For more details, refer to the RDKM Webconfig Server Setup and https://github.com/rdkcentral/webconfig/blob/develop/README.md .
Releases
The Webconfig code is available on GitHub as open source and is designed generically for easy deployment on RDKB, RDKV, or PODs. The generic code can be found below:
Webcfg/WebConfig Framework: webcfg is the client implementation of Webconfig. For more details, refer to xmidt-org/webcfg
CPEABS: cpeabs serves as an abstraction layer for consumer preference equipment systems. For more details, refer to xmidt-org/cpeabs
- Webconfig Server: This project is to implement a configuration management server. For more details, refer to rdkcentral/webconfig