WebConfig

Created on November 13, 2024

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

architecture-webconfig

Comparison of Cloud Protocol Agents 

FeatureWEBPAWEBCONFIG

Logic

Synchronous Cloud PUSHAsynchronous Device PULL
InitiationCloudDevice
Data flowConfig pushed to device from CloudConfig pulled in device from Cloud
ConnectionAlways connected when onlineConnected only during sync
Functions supported

HTTP GET, PATCH, POST, PUT, DELETE, Asynch event notifications.  

SET i.e., configuration apply
Number of RequestsOne 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 clientAt 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.

schema_diagram

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.

Bootup_sync

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.

Force_sync

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.               

    RDKB_WebConfig_Client_BLOB_Support_Diag

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
Go To Top