DHCP Client Manager
The DHCP Client Manager is a component of the RDK-B (Reference Design Kit for Broadband) framework that provides centralized management of DHCP operations for both IPv4 and IPv6 protocols. This implementation ensures efficient IP address management, seamless IPv4/IPv6 coexistence, and dynamic lease monitoring in RDK-B networking environments.
Key Features
- Dual Protocol Support: Comprehensive support for both DHCPv4 and DHCPv6 clients
- Centralized Management: Single point of control for all DHCP client operations across multiple interfaces
- Real-time Lease Monitoring: IPC-based system for receiving and processing lease updates from DHCP clients
- TR-181 Integration: Full integration with TR-181 Data Model for standardized management
- Recovery and Persistence: Automatic recovery of DHCP client states and lease information after system restarts
- MAP-T Support: Implementation of RFC 7599 for IPv4-over-IPv6 transition technology
- Custom Options: Support for vendor-specific and custom DHCP options
- Event-driven Architecture: Reactive system that responds to network state changes and lease events
Architecture Overview
The DHCP Client Manager follows a modular, event-driven architecture with the following main components:
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Rbus Thread │ │ Main Controller │ │ Lease Monitor │
│ │ │ │ │ │
│ • TR-181 DML │◄──►│ • Client Control│◄──►│ • IPC Listener │
│ • Set/Get Ops │ │ • Status Monitor│ │ • Lease Updates │
│ • Subscriptions │ │ • Interface Mgmt│ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Recovery Handler│ │ Lease Handlers │ │ Client Plugins │
│ │ │ │ │ │
│ • Persistence │ │ • DHCPv4 Process│ │ • udhcpc Plugin │
│ • State Restore │ │ • DHCPv6 Process│ │ • dibbler Plugin│
│ • Crash Recovery│ │ • Event Updates │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Directory Structure
docs/
├── README.md # This overview document
├── configuration-guide.md # Comprehensive PSM configuration guide
├── architecture/
│ └── component-diagram.md # Detailed component relationships and diagrams
└── components/
├── lease-monitor.md # Lease monitoring system
├── main-controller.md # Main controller logic
├── lease-handlers.md # DHCPv4/v6 lease processing
├── recovery-handler.md # Persistence and recovery
└── mapt-apis.md # MAP-T implementation
Documentation Links
Configuration & Setup
- Configuration Guide – Complete PSM parameter configuration with examples
Architecture Documentation
- Component Diagram – System architecture and component relationships
Component Documentation
- Lease Monitor – IPC-based lease monitoring system
- Main Controller – Central coordination and client management
- Lease Handlers – DHCPv4/v6 lease processing logic
- Recovery Handler – Persistence and crash recovery
- MAP-T APIs – IPv4-over-IPv6 transition support
Quick Start
Building the Component
The DHCP Client Manager is built as part of the RDK-B build system:
# Build the entire DHCP Manager bitbake ccsp-dhcp-mgr
Configuration
The component is configured through TR-181 Data Model entries:
Device.DHCPv4.Client.{i}.*– DHCPv4 client configurationDevice.DHCPv6.Client.{i}.*– DHCPv6 client configuration
Key Interfaces
- IPC Address:
tcp://127.0.0.1:50324(for lease monitoring) - Configuration Files: Dynamic creation based on TR-181 settings
- Log Output: Standard RDK logging framework
Configuration
The DHCP Client Manager is configured through PSM (Persistent Storage Manager) parameters and TR-181 Data Model entries. Configuration covers both DHCPv4 and DHCPv6 clients with support for custom options, vendor-specific information, and WAN Manager integration.
Configuration Structure
dmsb.dhcpmanager
├── ClientNoOfEntries # Number of DHCPv4 clients
├── Client.{i} # DHCPv4 client instances
│ ├── Alias # Client alias/name
│ ├── ReqOptionNoOfEntries # Number of requested options
│ ├── ReqOption.{i}.Tag # DHCP option tag
│ ├── SendOptionNoOfEntries # Number of sent options
│ ├── SendOption.{i}.Tag # DHCP option tag
│ └── SendOption.{i}.Value # Option value (hex-encoded)
└── dhcpv6
├── ClientNoOfEntries # Number of DHCPv6 clients
└── Client.{i} # DHCPv6 client instances
├── Alias # Client alias/name
├── ReqAddr # Request IPv6 address (IANA)
├── ReqPrefix # Request prefix delegation (IAPD)
├── RequestedOptions # Comma-separated option list
├── SentOptNoOfEntries # Number of sent options
├── SentOption.{i}.Tag # DHCPv6 option tag
└── SentOption.{i}.Value # Option value (hex-encoded)
Core Components
1. Main Controller (dhcpmgr_controller.c/h)
- Manages DHCP client lifecycle
- Monitors interface status changes
- Coordinates lease processing
- Handles client startup/shutdown
- Monitors client process health
2. Lease Monitor (dhcp_lease_monitor_thrd.c/h)
- IPC server for receiving lease updates
- Processes messages from DHCP client plugins
- Routes lease information to appropriate handlers
3. Lease Handlers (dhcpmgr_v*_lease_handler.c)
- DHCPv4 Handler: Processes IPv4 lease information
- DHCPv6 Handler: Processes IPv6 lease information (IANA/IAPD)
- Updates TR-181 data model
- Configures network interfaces
4. Recovery Handler (dhcpmgr_recovery_handler.c/h)
- Persists lease information to filesystem (/tmp/)
- Restores state after process restart
5. MAP-T Support (dhcpmgr_map_apis.c/h)
- Implements RFC 7599 for IPv4-over-IPv6
- Processes DHCP option 95 for MAP-T configuration
- Validates MAP-T parameters
Client Plugin Architecture
The DHCP Manager works with external DHCP clients through a plugin architecture:
DHCPv4 (udhcpc)
- Config Creator: Generates udhcpc-compatible configuration
- Plugin Binary:
dhcpmgr_udhcpc_plugin– executed on lease events by the dhcp client - Communication: IPC socket to lease monitor
DHCPv6 (dibbler)
- Config Creator: Generates dibbler-compatible configuration
- Plugin Binary:
dhcpmgr_dibbler_plugin– executed on lease events by the dhcp client - Communication: IPC socket to lease monitor
Message Flow
- Initialization: Main controller starts and initializes all components
- Client Start: TR-181 configuration triggers DHCP client startup
- Lease Acquisition: External DHCP client acquires lease
- Plugin Execution: Client executes plugin with lease information
- IPC Communication: Plugin sends lease data to lease monitor
- Processing: Lease handlers process and validate lease information
- TR-181 Update: Data model is updated with new lease information
- Persistence: Lease information is stored for recovery
- Event Notification: System events are generated for other components
Integration Points
- TR-181 Data Model: Primary configuration and status interface
- WAN Manager: Lease status notifications
- System Events: Network configuration updates
- RBUS/DBUS: Management interface for external components
Error Handling and Recovery
- Process Monitoring: Tracks DHCP client process health
- Automatic Restart: Restarts failed DHCP clients
- Lease Persistence: Maintains lease information across restarts
- State Recovery: Restores full system state after crashes
Performance Considerations
- Asynchronous Processing: Non-blocking lease processing
- Memory Management: Efficient cleanup of lease structures
- IPC Optimization: Fast message processing in lease monitor
- Thread Safety: Proper synchronization across components
Troubleshooting
Common issues and debugging approaches are documented in each component’s specific documentation. Key areas to check:
- IPC Communication: Verify lease monitor is listening
- Plugin Execution: Check plugin binary permissions and paths
- Configuration: Validate TR-181 settings
- Logs: Review component logs for error messages
- Process Status: Verify DHCP client processes are running
Contributing
When modifying the DHCP Client Manager:
- Follow existing code patterns and style
- Update relevant documentation
- Test with both IPv4 and IPv6 scenarios
- Verify TR-181 compliance
- Test recovery scenarios
References

