{"id":12787,"date":"2026-03-10T12:49:47","date_gmt":"2026-03-10T12:49:47","guid":{"rendered":"https:\/\/developer.rdkcentral.com\/documentation\/?page_id=12787"},"modified":"2026-03-10T12:51:18","modified_gmt":"2026-03-10T12:51:18","slug":"xdns-extended-dns","status":"publish","type":"page","link":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/components\/xdns-extended-dns\/","title":{"rendered":"XDNS (Extended DNS)"},"content":{"rendered":"\n

The XDNS (Extended DNS) component is a specialized RDK-B middleware component that provides advanced DNS management capabilities for RDK-B gateway devices. This component extends beyond traditional DNS functionality by implementing configurable DNS policies, security features, and integration with RDK-B’s WebConfig framework for dynamic DNS configuration management. The XDNS component serves as a critical networking service that enables service providers to implement DNS-based content filtering, parental controls, and network security policies while maintaining compatibility with standard DNS protocols.<\/p>\n\n\n\n

The XDNS component operates as a middleware layer between the RDK-B networking stack and external DNS services. At its core, the component provides necessary DML support to configure \/etc\/resolv.conf<\/code>, which is consumed by the dnsmasq process for DNS resolution services. It integrates deeply with the RDK-B ecosystem through TR-181 data model support, WebConfig integration for cloud-based configuration management, and R-Bus messaging for real-time communication with other RDK-B components. The component supports both IPv4 and IPv6 DNS configurations.<\/p>\n\n\n\n

At the device level, XDNS enhances the gateway’s networking capabilities by offering DNS-based security services, custom DNS server configurations per client or network segment, and comprehensive logging and monitoring of DNS activities. This enables service providers to offer value-added services such as malware protection, content filtering, and network usage analytics while maintaining transparent operation for end users.<\/p>\n\n\n\n

graph LR\n    subgraph \"External Systems\"\n        RemoteMgmt[\"Remote Management\"]\n        CloudDNS[\"Cloud DNS Services\"]\n        WebConfig[\"WebConfig Server\"]\n    end\n\n    subgraph \"RDK-B Platform\"\n        subgraph \"Remote Management Agents\"\n            ProtocolAgents[\"Protocol Agents<br\/>(TR-069\/WebPA\/TR-369)\"]\n        end\n        \n        subgraph \"RDK-B Core Components\"\n            XDNS[\"XDNS Component\"]\n            WanMgr[\"WAN Manager\"]\n            DHCPv4[\"DHCP v4 Server\"]\n            DHCPv6[\"DHCP v6 Server\"]\n            PSM[\"PSM Component\"]\n        end\n        \n        subgraph \"System Layer\"\n            Dnsmasq[\"dnsmasq Service\"]\n            SystemHAL[\"System HAL\"]\n            LinuxKernel[\"Linux Kernel\"]\n        end\n    end\n\n    %% External connections\n    RemoteMgmt -->|TR-069\/WebPA\/TR-369| ProtocolAgents\n    CloudDNS -->|DNS Services| XDNS\n    WebConfig -->|Configuration Updates| XDNS\n\n    %% Protocol Agents to RDK-B Components\n    ProtocolAgents -->|IPC| XDNS\n\n    %% RDK-B Components interactions\n    XDNS -->|IPC| WanMgr\n    XDNS -->|IPC| PSM\n    XDNS -->|DNS Config| DHCPv4\n    XDNS -->|IPv6 DNS Config| DHCPv6\n\n    %% XDNS to System Layer\n    XDNS -->|Configuration| Dnsmasq\n    XDNS <-->|HAL APIs| SystemHAL\n    \n    %% System integration\n    SystemHAL <-->|Driver Interfaces| LinuxKernel\n    XDNS <-->|System Events| LinuxKernel\n\n    classDef external fill:#fff3e0,stroke:#ef6c00,stroke-width:2px;\n    classDef xdns fill:#e3f2fd,stroke:#1976d2,stroke-width:3px;\n    classDef rdkbComponent fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px;\n    classDef system fill:#fce4ec,stroke:#c2185b,stroke-width:2px;\n\n    class RemoteMgmt,CloudDNS,WebConfig external;\n    class XDNS xdns;\n    class ProtocolAgents,WanMgr,DHCPv4,DHCPv6,PSM rdkbComponent;\n    class Dnsmasq,SystemHAL,LinuxKernel system;<\/pre><\/div>\n\n\n\n
Key Features & Responsibilities<\/strong>:<\/p>\n\n\n\n
    \n
  • DNS Configuration Management<\/strong>: Centralized management of DNS server configurations for IPv4 and IPv6 networks, including primary and secondary DNS server settings<\/li>\n\n\n\n
  • WebConfig Integration<\/strong>: Support for cloud-based DNS configuration updates through RDK-B’s WebConfig framework, enabling remote management and dynamic policy updates<\/li>\n\n\n\n
  • Security Policy Enforcement<\/strong>: Implementation of DNS-based security policies including malware protection, content filtering, and threat intelligence integration for network protection<\/li>\n\n\n\n
  • Multi-Profile Support<\/strong>: Advanced DNS profile management supporting different DNS configurations per client, network segment, or time-based policies for flexible network administration<\/li>\n\n\n\n
  • TR-181 Data Model Integration<\/strong>: Full TR-181 compliance for DNS parameters with support for remote management protocols and standardized device management interfaces<\/li>\n\n\n\n
  • Real-time Event Processing<\/strong>: R-Bus-based event handling for network state changes, WAN interface transitions, and dynamic DNS configuration updates<\/li>\n\n\n\n
  • Logging and Telemetry<\/strong>: Comprehensive DNS activity logging, performance metrics collection, and integration with RDK-B’s telemetry framework for network monitoring<\/li>\n<\/ul>\n\n\n\n
     <\/h2>\n\n\n\n
    Design<\/h2>\n\n\n\n
    The XDNS component is architected as a modular, event-driven middleware service that follows the RDK-B design principles of separation of concerns and loose coupling. The design emphasizes configurability, security, and reliability through a layered architecture that cleanly separates DNS policy management from DNS resolution services. The component provides DML (Data Model Layer) support to configure DNS config file, which is consumed by the dnsmasq process for DNS resolution. XDNS does not implement DNS resolution directly; instead, it manages DNS configuration that dnsmasq uses, ensuring compatibility with existing DNS infrastructure while adding advanced management capabilities.<\/p>\n\n\n\n
    The architectural design centers around three core principles: event-driven configuration management, where changes to network state or policies trigger automatic DNS configuration updates; modular function-based implementation, where DNS operations are implemented as discrete functions that can be called in sequence based on the operational context; and high-availability design, where DNS services remain operational even during component updates or network transitions. The component utilizes RDK-B’s standard IPC mechanisms (R-Bus) for inter-component communication and maintains state consistency through integration with the Persistent Storage Manager (PSM). Note<\/strong>: XDNS does not implement a separate “policy engine” – DNS policies are applied directly through function calls from the main component logic.<\/p>\n\n\n\n
    The northbound interface design focuses on standards compliance and cloud integration, exposing TR-181 compliant data models for traditional management protocols while supporting WebConfig APIs for modern cloud-based management. The southbound interface design emphasizes system integration, directly managing DNS config file and dnsmasq configuration files while monitoring network interface changes through WAN Manager integration. This design ensures that DNS policies are enforced at the system level while maintaining visibility and control at the middleware level, enabling both local and remote management capabilities.<\/p>\n\n\n\n
    flowchart TD\n    subgraph \"XDNS Component Architecture\"\n        SSPFramework([SSP Framework<br\/>ssp_main.c])\n        PluginMain([Plugin Main<br\/>plugin_main.c])\n        CoreAPIs([XDNS Core APIs<br\/>cosa_xdns_apis.c])\n        \n        subgraph \"Data Management Layer\"\n            DataModel([Data Model Layer<br\/>cosa_xdns_dml.c])\n            ParamMgmt([Parameter Management<br\/>xdns_param.c])\n            CompHelpers([Component Helpers<br\/>xdns_comp_helpers.c])\n        end\n        \n        subgraph \"External Integration\"\n            WebConfigAPI([WebConfig Integration<br\/>cosa_xdns_webconfig_api.c])\n        end\n    end\n\n    %% Flow connections\n    SSPFramework --> PluginMain\n    PluginMain --> CoreAPIs\n    CoreAPIs --> DataModel\n    CoreAPIs --> WebConfigAPI\n    DataModel --> ParamMgmt\n    DataModel --> CompHelpers\n    ParamMgmt --> CompHelpers\n\n    %% Styling\n    classDef core fill:#e3f2fd,stroke:#1976d2,stroke-width:2px\n    classDef data fill:#e8f5e8,stroke:#388e3c,stroke-width:2px\n    classDef external fill:#fff3e0,stroke:#f57c00,stroke-width:2px\n\n    class SSPFramework,PluginMain,CoreAPIs core\n    class DataModel,ParamMgmt,CompHelpers data\n    class WebConfigAPI external<\/pre><\/div>\n\n\n\n
    Prerequisites and Dependencies<\/strong><\/p>\n\n\n\n
    Build-Time Flags and Configuration:<\/strong><\/p>\n\n\n\n
    Configure Option<\/td>DISTRO Feature<\/td>Build Flag<\/td>Purpose<\/td>Default<\/td><\/tr>
    --enable-core_net_lib_feature_support<\/code><\/td>core-net-lib<\/code><\/td>CORE_NET_LIB<\/code><\/td>Enable advanced core networking library support for enhanced DNS processing<\/td>Disabled<\/td><\/tr>
    N\/A<\/td>safec<\/code><\/td>SAFEC_DUMMY_API<\/code> (when disabled)<\/td>Enable\/disable SafeC memory-safe API library for secure string operations<\/td>Enabled in production builds<\/td><\/tr>
    N\/A<\/td>kirkstone<\/code> \/ dunfell<\/code><\/td>Build system compatibility<\/td>Yocto distribution version compatibility and Python version selection<\/td>Auto-detected<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
    RDK-B Platform and Integration Requirements<\/strong><\/p>\n\n\n\n
      \n
    • RDK-B Components<\/strong>: WAN Manager (interface monitoring), PSM (Persistent Storage Manager), DHCP Server components (DNS distribution), TR-181 Data Model Provider (parameter management), CcspCr (Component Registry), dnsmasq service (DNS resolution)<\/li>\n\n\n\n
    • System-Level API Dependencies<\/strong>:\n
        \n
      • syscfg<\/code>\u00a0library for persistent system configuration storage and retrieval (used for storing XDNS enable\/disable state and configuration parameters)<\/li>\n\n\n\n
      • sysevent<\/code>\u00a0library for system event notification and monitoring (used for WAN interface change detection via\u00a0current_wan_ifname<\/code>\u00a0events)<\/li>\n\n\n\n
      • Linux\u00a0inotify<\/code>\u00a0API for file system monitoring (used to detect changes to DNS config file and dnsmasq configuration files)<\/li>\n\n\n\n
      • Standard POSIX file I\/O for configuration file management<\/li>\n\n\n\n
      • Note<\/strong>: XDNS does NOT use HAL APIs – all platform integration is through system-level APIs and middleware components<\/li>\n<\/ul>\n<\/li>\n\n\n\n
      • Systemd Services<\/strong>:\u00a0CcspPsmSsp<\/strong>.service<\/code>\u00a0(storage),\u00a0CcspCrSsp<\/strong>.service<\/code>\u00a0(component registry),\u00a0CcspMtaAgentSsp<\/strong>.service<\/code>\u00a0(management) must be active;\u00a0dnsmasq<\/strong>.service<\/code>\u00a0must be available but controlled by XDNS component<\/li>\n\n\n\n
      • Message Bus<\/strong>: DBus registration under\u00a0com<\/strong>.cisco.spvtg.ccsp.xdns<\/code>\u00a0namespace with R-Bus event subscription capabilities for WAN Manager interface change notifications and configuration updates<\/li>\n\n\n\n
      • Configuration Files<\/strong>:\u00a0\/usr\/ccsp\/xdns\/CcspXdns_dm.xml<\/code>\u00a0(TR-181 data model),\u00a0\/etc\/ccsp_msg.cfg<\/code>\u00a0(message bus configuration),\u00a0\/nvram\/syscfg.db<\/code>\u00a0(system configuration storage),\u00a0\/tmp\/dnsmasq.conf<\/code>\u00a0(DNS service config) must be accessible with read\/write permissions<\/li>\n\n\n\n
      • Startup Order<\/strong>: PSM \u2192 Component Registry \u2192 WAN Manager \u2192 DHCP Services \u2192 dnsmasq service \u2192 XDNS component initialization sequence must be strictly maintained for proper dependency resolution<\/li>\n<\/ul>\n\n\n\n
        Threading Model<\/strong><\/p>\n\n\n\n
        The XDNS component implements a hybrid threading model combining single-threaded event processing with dedicated worker threads for specific tasks, ensuring thread safety while maintaining responsive operation and preventing DNS service interruptions.<\/p>\n\n\n\n
          \n
        • Main Thread Architecture<\/strong>: Single-threaded event loop handles all IPC communications, configuration updates, and DNS policy management to ensure atomic operations and prevent race conditions in critical DNS configuration paths<\/li>\n\n\n\n
        • Threading Architecture<\/strong>: Event-driven with selective multi-threading for I\/O intensive operations<\/li>\n\n\n\n
        • Main Thread<\/strong>: Handles R-Bus message processing, TR-181 data model operations, WebConfig API processing, DNS policy validation and application, state management and persistence operations<\/li>\n\n\n\n
        • Worker Threads<\/strong>:\n
            \n
          • File Monitor Thread<\/strong>: Monitors DNS config file, dnsmasq configuration files, and network interface changes using inotify for real-time detection of external configuration changes<\/li>\n\n\n\n
          • Network Event Thread<\/strong>: Processes WAN Manager events (CurrentActiveInterface<\/code>\u00a0and\u00a0CurrentActiveDNS<\/code>\u00a0R-Bus events) and interface state changes<\/li>\n<\/ul>\n<\/li>\n\n\n\n
          • Synchronization<\/strong>: Mutex-protected shared data structures for DNS configuration state, atomic operations for critical configuration updates, condition variables for worker thread coordination and graceful shutdown signaling<\/li>\n<\/ul>\n\n\n\n
            Component State Flow<\/h3>\n\n\n\n
            Initialization to Active State<\/strong><\/p>\n\n\n\n
            The XDNS component follows a structured initialization sequence that ensures all dependencies are established before processing DNS requests. The component starts in an uninitialized state and progresses through configuration loading, dependency connection, and service activation phases before reaching the fully operational active state.<\/p>\n\n\n\n
            sequenceDiagram\n    participant SystemD as SystemD Service\n    participant XDNS as XDNS Component\n    participant PSM as PSM Storage\n    participant WanMgr as WAN Manager\n    participant Dnsmasq as dnsmasq Service\n    participant R-Bus as R-Bus Message Bus\n\n    SystemD->>XDNS: Initialize Component\n    Note over XDNS: State: Initializing<br\/>Setup logging, memory, basic structures\n    \n    XDNS->>PSM: Load Stored Configuration\n    PSM-->>XDNS: Configuration Data Retrieved\n    Note over XDNS: State: LoadingConfig \u2192 ValidatingConfig\n    \n    XDNS->>XDNS: Validate Configuration Parameters\n    Note over XDNS: Validate DNS servers, policies, network settings\n    \n    XDNS->>R-Bus: Register Data Model & Events\n\u00a0 \u00a0 R-Bus-->>XDNS: Registration Complete\n    Note over XDNS: State: ValidatingConfig \u2192 ConnectingDeps\n    \n    XDNS->>WanMgr: Subscribe to WAN Events\n    WanMgr-->>XDNS: Subscription Confirmed\n    \n    XDNS->>Dnsmasq: Apply DNS Configuration\n    Dnsmasq-->>XDNS: Configuration Applied\n    Note over XDNS: State: ConnectingDeps \u2192 Active\n    \n    XDNS->>SystemD: Initialization Complete (Active State)\n    \n    loop Runtime Operations\n        Note over XDNS: State: Active<br\/>Process DNS configs & policy updates\n        XDNS->>XDNS: Handle Configuration Changes\n        XDNS->>XDNS: Process WAN Events\n        XDNS->>XDNS: Apply Security Policies\n    end\n    \n    SystemD->>XDNS: Stop Request\n    Note over XDNS: State: Active \u2192 Shutdown\n    XDNS->>PSM: Save Current State\n    XDNS->>SystemD: Shutdown Complete<\/pre><\/div>\n\n\n\n
            Runtime State Changes and Context Switching<\/strong><\/p>\n\n\n\n
            During normal operation, XDNS responds to various network and configuration events that trigger state transitions and context switches. These changes ensure that DNS services remain optimal and secure as network conditions and policies evolve.<\/p>\n\n\n\n
            State Change Triggers:<\/strong><\/p>\n\n\n\n
              \n
            • WAN Interface Changes<\/strong>: Interface up\/down transitions and new default route assignments trigger DNS server re-evaluation and automatic configuration updates<\/li>\n\n\n\n
            • WebConfig Updates<\/strong>: Cloud-based policy updates, security rule changes, and DNS profile modifications trigger validation and deployment of new configurations<\/li>\n\n\n\n
            • Network Topology Changes<\/strong>: DHCP lease events, client connection\/disconnection, and VLAN configuration changes trigger client-specific DNS policy application<\/li>\n\n\n\n
            • Security Events<\/strong>: Threat detection, malware alerts, and security policy violations trigger DNS filtering rule updates and emergency policy enforcement<\/li>\n<\/ul>\n\n\n\n
              Context Switching Scenarios:<\/strong><\/p>\n\n\n\n
                \n
              • DNS Profile Switching<\/strong>: Component switches between different DNS configurations based on client identity, network segment, or time-based policies without service interruption<\/li>\n\n\n\n
              • Security Context Switching<\/strong>: Dynamic switching between normal and restricted DNS policies based on threat detection or parental control schedules<\/li>\n<\/ul>\n\n\n\n
                Call Flow<\/h3>\n\n\n\n
                Initialization Call Flow:<\/strong><\/p>\n\n\n\n
                sequenceDiagram\n    participant Init as SystemD Init\n    participant XDNS as XDNS Main<br\/>(CosaXDNSInitialize)\n    participant Syscfg as syscfg Library\n    participant PSM as PSM Storage<br\/>(CosaDmlGetSelfHealCfg)\n    participant Sysevent as sysevent Library<br\/>(xdns_handle_sysevent_async)\n    participant R-Bus as R-Bus Event System\n\n    Init->>XDNS: Start Component Process\n    XDNS->>Syscfg: syscfg_init()\n    Syscfg-->>XDNS: System Config Initialized\n    XDNS->>PSM: Load DNS Mappings<br\/>(pMappingContainer = CosaDmlGetSelfHealCfg)\n    PSM-->>XDNS: DNS Configuration Retrieved\n    XDNS->>Sysevent: Start Event Monitoring<br\/>(xdns_handle_sysevent_async)\n    Sysevent-->>XDNS: Event Handler Active\n    XDNS->>R-Bus: Subscribe to WAN Events<br\/>(R-BusEvent_Subscribe)\n\u00a0 \u00a0 R-Bus-->>XDNS: Subscriptions Confirmed\n    XDNS->>Init: Initialization Complete (Active State)\n    \n    Note over XDNS: No separate Config Manager or<br\/>Policy Engine modules exist.<br\/>All logic in CosaXDNSInitialize()<br\/>in cosa_xdns_apis.c<\/pre><\/div>\n\n\n\n
                DNS Configuration Update Call Flow:<\/strong><\/p>\n\n\n\n
                The most critical flow supported by XDNS is the dynamic DNS configuration update process, which handles both local configuration changes and cloud-based policy updates while ensuring service continuity.<\/p>\n\n\n\n
                sequenceDiagram\n    participant WebConfig as WebConfig Server\n    participant XDNS as XDNS Component<br\/>(cosa_xdns_webconfig_api.c)\n    participant Validators as Validation Functions<br\/>(CheckIfIpIsValid, isValidIPv4Address)<br\/>XDNS_Validate() in cosa_xdns_dml.c\n    participant DnsmasqConf as Dnsmasq Config Files<br\/>(\/tmp\/dnsmasq_servers.conf)\n    participant PSM as PSM Storage\n\n    WebConfig->>XDNS: Configuration Update Request\n    Note over XDNS: Receive & parse JSON payload<br\/>(process_dnsparams)\n    \n    XDNS->>Validators: Validate DNS Parameters<br\/>CheckIfIpIsValid(ipAddress)\n    XDNS->>Validators: Validate MAC Addresses<br\/>CheckIfMacIsValid(macAddress)\n    \n    alt Validation Success\n        Validators-->>XDNS: All Parameters Valid\n        XDNS->>DnsmasqConf: Write Config File<br\/>(CreateDnsmasqServerConf)\n        DnsmasqConf-->>XDNS: Configuration Written\n        XDNS->>PSM: Store Configuration<br\/>(PSM_Set_Record_Value2)\n        PSM-->>XDNS: Storage Complete\n        XDNS-->>WebConfig: Success Response (200)\n    else Validation Failure\n        Validators-->>XDNS: Invalid IP\/MAC Detected\n        XDNS->>XDNS: Rollback Changes<br\/>(rollback_XDNS)\n        XDNS-->>WebConfig: Error Response (400)\n    end\n    \n    Note over XDNS: No separate Policy Engine or<br\/>Config Validator modules exist.<br\/>Validation functions called directly<br\/>from WebConfig API handlers<\/pre><\/div>\n\n\n\n
                Internal Modules<\/h2>\n\n\n\n
                The XDNS component is structured into several specialized modules, each responsible for specific aspects of DNS management and system integration. These modules work together to provide comprehensive DNS services while maintaining clear separation of concerns and enabling independent testing and maintenance.<\/p>\n\n\n\n
                Module\/Class<\/td>Description<\/td>Key Files<\/td><\/tr>
                XDNS Core APIs<\/strong><\/td>Main component initialization, lifecycle management, and core DNS configuration APIs providing the primary interface for DNS policy management<\/td>cosa_xdns_apis.c<\/code>, cosa_xdns_apis<\/strong>.h<\/code><\/td><\/tr>
                Data Model Layer<\/strong><\/td>TR-181 compliant data model implementation handling get\/set operations for DNS parameters and WebUI integration<\/td>cosa_xdns_dml.c<\/code>, cosa_xdns_dml<\/strong>.h<\/code><\/td><\/tr>
                WebConfig Integration<\/strong><\/td>Cloud configuration management module handling JSON-based configuration updates and validation from WebConfig server<\/td>cosa_xdns_webconfig_api.c<\/code>, cosa_xdns_webconfig_api<\/strong>.h<\/code><\/td><\/tr>
                SSP Framework<\/strong><\/td>Service Provider abstraction layer managing component registration, message bus integration, and system service lifecycle<\/td>ssp_main.c<\/code>, ssp_internal<\/strong>.h<\/code>, ssp_global<\/strong>.h<\/code><\/td><\/tr>
                Parameter Management<\/strong><\/td>System configuration parameter handling module managing syscfg integration and persistent storage of DNS settings<\/td>xdns_param.c<\/code>, xdns_param<\/strong>.h<\/code><\/td><\/tr>
                Component Helpers<\/strong><\/td>Utility functions and helper modules providing common DNS validation, string manipulation, and system integration functions<\/td>xdns_comp_helpers.c<\/code>, xdns_comp_helpers<\/strong>.h<\/code><\/td><\/tr>
                Plugin Main<\/strong><\/td>Component plugin interface managing dynamic loading, initialization callbacks, and integration with RDK-B component framework<\/td>plugin_main.c<\/code>, plugin_main<\/strong>.h<\/code>, plugin_main_apis.c<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                Component Interactions<\/h2>\n\n\n\n
                The XDNS component operates as a central DNS management hub within the RDK-B ecosystem, maintaining active communication channels with multiple middleware components, system services, and external management systems. These interactions enable comprehensive DNS service management while ensuring integration with network management, security policies, and device configuration frameworks.<\/p>\n\n\n\n
                Interaction Matrix<\/h3>\n\n\n\n
                Target Component\/Layer<\/td>Interaction Purpose<\/td>Key APIs\/Endpoints<\/td><\/tr>
                RDK-B Middleware Components<\/strong><\/td><\/td><\/td><\/tr>
                WAN Manager<\/td>Network state monitoring, interface change notifications<\/td>Device<\/strong>.X_RDK_WanManager.CurrentActiveInterface<\/code>, Device<\/strong>.X_RDK_WanManager.CurrentActiveDNS<\/code><\/td><\/tr>
                PSM (Persistent Storage)<\/td>DNS configuration persistence, system state storage, backup and recovery operations<\/td>PSM_Set_Record_Value2()<\/code>, PSM_Get_Record_Value2()<\/code>, \/config\/xdns\/<\/code> namespace<\/td><\/tr>
                DHCP v4\/v6 Servers<\/td>DNS server assignment to clients, DHCP option configuration, lease management integration<\/td>\/dmcli eRT setv Device.DHCPv4.Server.Pool.{i}.DNSServers<\/code>, DHCPv6 DNS options<\/td><\/tr>
                TR-181 Provider<\/td>Standards-compliant parameter management, remote device management, data model updates<\/td>Device<\/strong>.X_RDKCENTRAL-COM_XDNS.*<\/code> parameters, TR-181 commit\/validate operations<\/td><\/tr>
                WebConfig Framework<\/td>RDK-B cloud configuration framework integration for receiving DNS policy updates from management platforms<\/td>webconfig_framework<\/strong>.h<\/code> API, Process_XDNS_WebConfigRequest()<\/code>, msgpack payload processing<\/td><\/tr>
                System & Platform Layers<\/strong><\/td><\/td><\/td><\/tr>
                dnsmasq Service<\/td>DNS resolver configuration, DNS policy enforcement, DNS caching and forwarding<\/td>\/tmp\/dnsmasq.conf<\/code>, \/tmp\/dnsmasq.d\/<\/code>, configuration file management<\/td><\/tr>
                System Configuration<\/td>Parameter persistence, factory reset recovery, system-level DNS settings<\/td>syscfg get<\/strong>\/set<\/strong> X_RDKCENTRAL-COM_XDNS<\/code>, \/nvram\/syscfg.db<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                Events Published by XDNS:<\/strong><\/p>\n\n\n\n
                Event Name<\/td>Event Topic\/Path<\/td>Trigger Condition<\/td>Subscriber Components<\/td><\/tr>
                DNS_Configuration_Changed<\/td>Device<\/strong>.X_RDKCENTRAL-COM_XDNS.ConfigurationChanged<\/code><\/td>DNS server list updates, policy changes, security rule modifications<\/td>DHCP Servers, Telemetry Agent, Network Monitor<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                | Security_Policy_Applied | Device<\/strong>.X_RDKCENTRAL-COM_XDNS.SecurityEvent<\/code> | Malware domain blocked, content filter activated, threat detected | Security Components, Logging System, Parental Controls |<\/p>\n\n\n\n
                IPC Flow Patterns<\/h3>\n\n\n\n
                Primary IPC Flow – DNS Configuration Update:<\/strong><\/p>\n\n\n\n
                sequenceDiagram\n    participant WebUI as Web UI\/TR-181 Client\n    participant XDNS as XDNS Component\n    participant PSM as PSM Storage\n    participant Dnsmasq as dnsmasq Service\n\n    WebUI->>XDNS: Set DNS Configuration (R-Bus)\n    Note over XDNS: Validate DNS server addresses<br\/>Check policy compliance\n    XDNS->>PSM: Store Configuration\n    PSM-->>XDNS: Storage Confirmed\n    XDNS->>Dnsmasq: Update DNS Config Files\n    Dnsmasq-->>XDNS: Configuration Applied\n    XDNS-->>WebUI: Configuration Success<\/pre><\/div>\n\n\n\n
                Implementation Details<\/h2>\n\n\n\n

                System-Level API Integration<\/h3>\n\n\n\n
                The XDNS component operates at the middleware level and does not<\/strong> utilize HAL (Hardware Abstraction Layer) APIs. Instead, it integrates directly with system-level configuration and event APIs for platform-specific functionality.<\/p>\n\n\n\n
                Core System APIs:<\/strong><\/p>\n\n\n\n
                System API<\/td>Purpose<\/td>Implementation File<\/td><\/tr>
                syscfg_get\/syscfg_set<\/code><\/td>System configuration parameter management for DNS settings persistence (stores XDNS enable state and configuration in \/nvram\/syscfg.db<\/code>)<\/td>xdns_param.c<\/code>, cosa_xdns_apis.c<\/code><\/td><\/tr>
                sysevent_get\/sysevent_set\/sysevent_open<\/code><\/td>Network event monitoring and state change notifications (monitors current_wan_ifname<\/code> for WAN interface changes)<\/td>cosa_xdns_apis.c<\/code><\/td><\/tr>
                inotify_init\/inotify_add_watch<\/code><\/td>File system monitoring for configuration file changes and automatic updates (monitors DNS config file for external DNS changes)<\/td>cosa_xdns_apis.c<\/code><\/td><\/tr>
                PSM APIs (PSM_Get_Record_Value2<\/code>, PSM_Set_Record_Value2<\/code>)<\/td>Persistent storage of DNS mappings and configuration through RDK-B middleware (not a system-level API but middleware component)<\/td>cosa_xdns_dml.c<\/code>, cosa_xdns_apis<\/strong>.h<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
                Key Implementation Logic<\/h3>\n\n\n\n
                  \n
                • DNS Configuration State Machine<\/strong>: The core DNS configuration management is implemented through a sequence of function calls with distinct phases for validation, application, and verification.\u00a0Note<\/strong>: There are no separate “Config Manager” or “Policy Engine” modules – all logic is implemented directly in the core functions.\n
                    \n
                  • Main initialization logic in\u00a0cosa_xdns_apis.c<\/code>\u00a0(function:\u00a0CosaXDNSInitialize()<\/code>\u00a0– handles syscfg init, PSM loading, R-Bus subscriptions)<\/li>\n\n\n\n
                  • Configuration validation in\u00a0cosa_xdns_dml.c<\/code>\u00a0(function:\u00a0XDNS_Validate()<\/code>\u00a0– validates DNS parameters before applying)<\/li>\n\n\n\n
                  • DNS parameter validation helpers:\u00a0isValidIPv4Address<\/strong>()<\/code>,\u00a0isValidIPv6Address<\/strong>()<\/code>\u00a0in\u00a0cosa_xdns_dml.c<\/code><\/li>\n\n\n\n
                  • TR-181 data model handlers in\u00a0cosa_xdns_dml.c<\/code>\u00a0(functions:\u00a0XDNS_GetParamStringValue()<\/code>,\u00a0XDNS_SetParamStringValue()<\/code>)<\/li>\n<\/ul>\n<\/li>\n\n\n\n
                  • WebConfig Integration Processing<\/strong>: Cloud-based configuration updates are processed through a validation pipeline that ensures configuration integrity and system compatibility.\u00a0Note<\/strong>: There is no separate “Config Validator” module – validation is performed by individual functions.\n
                      \n
                    • WebConfig JSON payload processing in\u00a0cosa_xdns_webconfig_api.c<\/code>\u00a0(function:\u00a0process_dnsparams<\/strong>()<\/code>\u00a0– parses msgpack configuration)<\/li>\n\n\n\n
                    • IP address validation functions:\u00a0CheckIfIpIsValid()<\/code>,\u00a0isValidIPv4Address<\/strong>()<\/code>,\u00a0isValidIPv6Address<\/strong>()<\/code><\/li>\n\n\n\n
                    • MAC address validation:\u00a0CheckIfMacIsValid()<\/code>\u00a0ensures proper MAC address format<\/li>\n\n\n\n
                    • Configuration blob decoding, schema validation, and security checks<\/li>\n\n\n\n
                    • Atomic configuration updates with rollback capability via\u00a0rollback_XDNS<\/strong>()<\/code>\u00a0function on validation failure<\/li>\n<\/ul>\n<\/li>\n\n\n\n
                    • Real-time Network Event Handling<\/strong>: Network state changes are monitored through R-Bus event subscriptions and sysevent monitoring for immediate DNS configuration adaptation\n
                        \n
                      • WAN Manager event subscription and processing in\u00a0cosa_xdns_apis.c<\/code>\u00a0(function:\u00a0eventReceiveHandler<\/strong>()<\/code>)<\/li>\n\n\n\n
                      • Network interface monitoring with automatic detection of WAN interface changes via\u00a0current_wan_ifname<\/code>\u00a0sysevent<\/li>\n\n\n\n
                      • Automatic DNS configuration updates based on WAN interface state changes with firewall restart to apply routing rules<\/li>\n<\/ul>\n<\/li>\n\n\n\n
                      • Error Handling Strategy<\/strong>: Comprehensive error handling with graceful degradation ensures DNS services remain functional even during configuration errors or network issues\n
                          \n
                        • Configuration validation with detailed error reporting and rollback mechanisms<\/li>\n\n\n\n
                        • Logging and telemetry integration for troubleshooting and monitoring<\/li>\n<\/ul>\n<\/li>\n\n\n\n
                        • Logging & Debugging<\/strong>: Multi-level logging system with component-specific debug categories and integration with RDK-B’s centralized logging framework\n
                            \n
                          • XDNS-specific logging macros in\u00a0ccsp_xdnsLog_wrapper<\/strong>.h<\/code><\/li>\n\n\n\n
                          • Configuration change tracking and DNS resolution performance monitoring<\/li>\n\n\n\n
                          • Debug hooks for real-time DNS policy troubleshooting and configuration validation<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n
                            Key Configuration Files<\/h3>\n\n\n\n
                            Configuration File<\/td>Purpose<\/td>Override Mechanisms<\/td><\/tr>
                            \/usr\/ccsp\/xdns\/CcspXdns_dm.xml<\/code><\/td>TR-181 Data Model definition<\/td>Environment variables, build-time customization<\/td><\/tr>
                            \/etc\/ccsp_msg.cfg<\/code><\/td>R-Bus message bus configuration<\/td>SystemD environment overrides<\/td><\/tr>
                            \/tmp\/dnsmasq.conf<\/code><\/td>dnsmasq service configuration<\/td>XDNS runtime configuration<\/td><\/tr>
                            \/nvram\/syscfg.db<\/code><\/td>System parameter storage<\/td>Factory reset, rescue mode<\/td><\/tr>
                            \/etc\/resolv.conf<\/code><\/td>System DNS resolver configuration<\/td>Network Manager overrides<\/td><\/tr><\/tbody><\/table><\/figure>\n","protected":false},"excerpt":{"rendered":"
                            The XDNS (Extended DNS) component is a specialized RDK-B middleware component that provides advanced DNS […]<\/p>\n","protected":false},"author":659,"featured_media":0,"parent":9575,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"_bbp_topic_count":0,"_bbp_reply_count":0,"_bbp_total_topic_count":0,"_bbp_total_reply_count":0,"_bbp_voice_count":0,"_bbp_anonymous_reply_count":0,"_bbp_topic_count_hidden":0,"_bbp_reply_count_hidden":0,"_bbp_forum_subforum_count":0,"footnotes":""},"class_list":["post-12787","page","type-page","status-publish","hentry"],"yoast_head":"\nXDNS (Extended DNS) - RDK Documentation Portal | Documentation<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/components\/xdns-extended-dns\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"XDNS (Extended DNS) - RDK Documentation Portal | Documentation\" \/>\n<meta property=\"og:description\" content=\"The XDNS (Extended DNS) component is a specialized RDK-B middleware component that provides advanced DNS […]\" \/>\n<meta property=\"og:url\" content=\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/components\/xdns-extended-dns\/\" \/>\n<meta property=\"og:site_name\" content=\"RDK Documentation Portal | Documentation\" \/>\n<meta property=\"article:modified_time\" content=\"2026-03-10T12:51:18+00:00\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data1\" content=\"10 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/components\/xdns-extended-dns\/\",\"url\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/components\/xdns-extended-dns\/\",\"name\":\"XDNS (Extended DNS) - RDK Documentation Portal | Documentation\",\"isPartOf\":{\"@id\":\"https:\/\/developer.rdkcentral.com\/documentation\/#website\"},\"datePublished\":\"2026-03-10T12:49:47+00:00\",\"dateModified\":\"2026-03-10T12:51:18+00:00\",\"breadcrumb\":{\"@id\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/components\/xdns-extended-dns\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/components\/xdns-extended-dns\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/components\/xdns-extended-dns\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/developer.rdkcentral.com\/documentation\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Documentation\",\"item\":\"https:\/\/developer.rdkcentral.com\/documentation\/\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"RDK Broadband\",\"item\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/\"},{\"@type\":\"ListItem\",\"position\":4,\"name\":\"Components\",\"item\":\"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/components\/\"},{\"@type\":\"ListItem\",\"position\":5,\"name\":\"XDNS (Extended DNS)\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/developer.rdkcentral.com\/documentation\/#website\",\"url\":\"https:\/\/developer.rdkcentral.com\/documentation\/\",\"name\":\"RDK Documentation Portal | Documentation\",\"description\":\"\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/developer.rdkcentral.com\/documentation\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-US\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"XDNS (Extended DNS) - RDK Documentation Portal | Documentation","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/components\/xdns-extended-dns\/","og_locale":"en_US","og_type":"article","og_title":"XDNS (Extended DNS) - RDK Documentation Portal | Documentation","og_description":"The XDNS (Extended DNS) component is a specialized RDK-B middleware component that provides advanced DNS […]","og_url":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/components\/xdns-extended-dns\/","og_site_name":"RDK Documentation Portal | Documentation","article_modified_time":"2026-03-10T12:51:18+00:00","twitter_card":"summary_large_image","twitter_misc":{"Est. reading time":"10 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/components\/xdns-extended-dns\/","url":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/components\/xdns-extended-dns\/","name":"XDNS (Extended DNS) - RDK Documentation Portal | Documentation","isPartOf":{"@id":"https:\/\/developer.rdkcentral.com\/documentation\/#website"},"datePublished":"2026-03-10T12:49:47+00:00","dateModified":"2026-03-10T12:51:18+00:00","breadcrumb":{"@id":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/components\/xdns-extended-dns\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/components\/xdns-extended-dns\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/components\/xdns-extended-dns\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/developer.rdkcentral.com\/documentation\/"},{"@type":"ListItem","position":2,"name":"Documentation","item":"https:\/\/developer.rdkcentral.com\/documentation\/"},{"@type":"ListItem","position":3,"name":"RDK Broadband","item":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/"},{"@type":"ListItem","position":4,"name":"Components","item":"https:\/\/developer.rdkcentral.com\/documentation\/documentation\/rdk_broadband_documentation\/components\/"},{"@type":"ListItem","position":5,"name":"XDNS (Extended DNS)"}]},{"@type":"WebSite","@id":"https:\/\/developer.rdkcentral.com\/documentation\/#website","url":"https:\/\/developer.rdkcentral.com\/documentation\/","name":"RDK Documentation Portal | Documentation","description":"","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/developer.rdkcentral.com\/documentation\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-US"}]}},"_links":{"self":[{"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/pages\/12787","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/users\/659"}],"replies":[{"embeddable":true,"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/comments?post=12787"}],"version-history":[{"count":1,"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/pages\/12787\/revisions"}],"predecessor-version":[{"id":12788,"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/pages\/12787\/revisions\/12788"}],"up":[{"embeddable":true,"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/pages\/9575"}],"wp:attachment":[{"href":"https:\/\/developer.rdkcentral.com\/documentation\/wp-json\/wp\/v2\/media?parent=12787"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}