Simple DHCP Daemon (simple-dhcpd)

A lightweight, high-performance DHCP server implementation designed for modern networking environments.

Overview

Simple DHCP Daemon is a C++17 DHCP server under active development. It targets small to medium deployments with a clear core (daemon, parser, leases, UDP, multi-format config).

Honest status (April 2026): See project/PROGRESS_REPORT.md. The production binary builds, simple_dhcpd_tests builds and passes (ctest, 60 tests on the default target). DhcpServer can use LeaseManager or AdvancedLeaseManager (config), optional DhcpSecurityManager when security is enabled, config-driven options and server identifier, declined-IP hold, and packet statistics. Treat the project as pre–1.0 until you validate field deployment, relay/multi-subnet behavior, coverage, and packaging on your platforms.

What is in good shape today

• Core daemon entrypoint, signals, config load, UDP receive loop (receive thread joins reliably via receive timeout)
• DHCP message handling with lease allocation, optional security on the packet path, statistics, Decline with quarantine
• JSON config with validation; YAML/INI supported to varying depth (see PROGRESS_REPORT.md)
• CMake production target, CTest, optional packaging hooks

What still needs real-world validation

• End-to-end DHCP against hardware clients (tests are mostly in-process / loopback)
• High-scale RPS figures and “50k RPS”-style claims — not CI-benchmarked here
• Windows and every packaged artifact on every distro

Version 0.6.0 (CMake)

Label only — pre–1.0; progress and gaps are summarized in project/PROGRESS_REPORT.md.

Configuration

Simple DHCP Daemon supports multiple configuration formats for maximum flexibility:

Supported Formats

• JSON (.json) - JavaScript Object Notation
• YAML (.yaml or .yml) - YAML Ain't Markup Language
• INI (.ini) - Windows-style configuration files

Configuration Examples

Comprehensive configuration examples are organized by use case in the config/examples/ directory:

# View available examples
ls config/examples/

# Simple configurations for basic setups
ls config/examples/simple/

# Advanced configurations for complex networks
ls config/examples/advanced/

# Production configurations for enterprise environments
ls config/examples/production/

# Security configurations for high-security requirements
ls config/examples/security/

# Validate a configuration file
./config/examples/validate_config.sh simple-dhcpd.yaml

# Convert between formats
python3 config/examples/convert_config.py simple-dhcpd.json simple-dhcpd.yaml

Organized Examples

The configuration examples are organized by use case:

• simple/ - Basic configurations for home networks and small offices
• advanced/ - Complex multi-VLAN and load-balanced setups
• production/ - Enterprise-grade configurations for mission-critical environments
• security/ - High-security configurations with comprehensive protection

Each directory contains:

• Configuration files in JSON, YAML, and INI formats
• Detailed README files with usage instructions
• Specific examples for different scenarios

Quick Configuration

Create a minimal configuration file:

# minimal.yaml
server:
  listen_addresses: ["0.0.0.0:67"]
  enable_logging: true
  enable_security: false

subnets:
  - name: "default"
    network: "192.168.1.0"
    prefix_length: 24
    range_start: "192.168.1.100"
    range_end: "192.168.1.200"
    gateway: "192.168.1.1"
    dns_servers: ["192.168.1.1", "8.8.8.8"]
    domain_name: "local"
    lease_time: 86400
    max_lease_time: 172800

Running with Configuration

# Use specific configuration file
./simple-dhcpd -c /path/to/config.yaml

# Validate configuration without starting
./simple-dhcpd -c /path/to/config.yaml --validate

# Run with debug logging
./simple-dhcpd -c /path/to/config.yaml --verbose --log-level DEBUG

Quick Start

Installation

From Source

git clone https://github.com/SimpleDaemons/simple-dhcpd.git
cd simple-dhcpd
mkdir build && cd build
cmake ..
make
sudo make install

Using Package Managers

Ubuntu/Debian:

# Add repository (when available)
sudo apt update
sudo apt install simple-dhcpd

CentOS/RHEL:

# Add repository (when available)
sudo yum install simple-dhcpd

macOS (Homebrew):

# Add tap (when available)
brew tap simpledaemons/simple-dhcpd
brew install simple-dhcpd

Configuration Examples

We provide ready-to-use configuration examples for different environments:

Simple Environment (Home/Small Office)

# Copy simple configuration
sudo cp config/examples/simple/simple-dhcpd.conf /etc/simple-dhcpd/
sudo systemctl start simple-dhcpd

Features:

• Single subnet (192.168.1.0/24)
• 100 IP addresses for dynamic allocation
• Static reservations for router and NAS
• Basic logging and monitoring

Advanced Environment (Medium Office)

# Copy advanced configuration
sudo cp config/examples/advanced/simple-dhcpd.conf /etc/simple-dhcpd/
sudo systemctl start simple-dhcpd

Features:

• Multiple subnets (main office, guest, IoT)
• MAC filtering and rate limiting
• Option 82 support
• Performance optimization with caching
• Prometheus metrics

Production Environment (Enterprise)

# Copy production configuration
sudo cp config/examples/production/simple-dhcpd.conf /etc/simple-dhcpd/
sudo systemctl start simple-dhcpd

Features:

• 4 subnets with different security levels
• MySQL database with connection pooling
• Comprehensive security (authentication, access control)
• High availability with failover
• Advanced monitoring and alerting

Configuration Examples

Simple DHCP Daemon includes comprehensive configuration examples:

• Simple: Basic home/office network setup
• Advanced: Multi-subnet enterprise configuration
• Production: High-availability production environment
• Security: Comprehensive security-focused configuration

See the config/examples/ directory for detailed examples and the config/SECURITY_CONFIG.md for complete security configuration reference.

Basic Configuration

Create a minimal configuration file:

{
  "dhcp": {
    "listen": ["0.0.0.0:67"],
    "subnets": [
      {
        "name": "main-subnet",
        "network": "192.168.1.0/24",
        "range": "192.168.1.100-192.168.1.200",
        "gateway": "192.168.1.1",
        "dns_servers": ["8.8.8.8", "8.8.4.4"],
        "domain_name": "local",
        "lease_time": 86400
      }
    ],
    "logging": {
      "enable": true,
      "level": "info"
    }
  }
}

Running the Server

# Run in foreground
sudo simple-dhcpd -c /etc/simple-dhcpd/simple-dhcpd.conf

# Run as daemon
sudo simple-dhcpd -d -c /etc/simple-dhcpd/simple-dhcpd.conf

# Run with verbose logging
sudo simple-dhcpd -v -c /etc/simple-dhcpd/simple-dhcpd.conf

Features

The bullets below describe intended and partially implemented capabilities. For what is verified in this repo today (build, tests, wiring), use project/PROGRESS_REPORT.md — some marketing-style claims (e.g. SQLite lease DB, full RFC “complete”) are not accurate for the current code path.

Core DHCP Protocol

• ✅ Complete DORA Process: Discover/Offer/Request/ACK with full RFC compliance
• ✅ DHCP Operations: Release, Decline, and Inform message handling
• ✅ Standard Options: Full support for DHCP options 1-255
• ✅ Message Validation: Comprehensive message validation and error handling
• ✅ State Machine: Robust DHCP state machine implementation

Advanced Security Features (v0.3.0)

• ✅ DHCP Snooping: Trusted interface validation and binding verification
• ✅ MAC Address Filtering: Wildcard pattern support (00:11:22:33:44:*)
• ✅ IP Address Filtering: Exact match filtering with allow/deny modes
• ✅ Rate Limiting: Sliding time windows with per-client overrides
• ✅ Option 82 Support: Relay agent information validation and trusted agents
• ✅ Client Authentication: HMAC-SHA256 with credential management
• ✅ Security Event Logging: Comprehensive audit trails and real-time monitoring
• ✅ Security Statistics: Real-time security metrics and alerting

Advanced Lease Management (v0.3.0)

• ✅ Dynamic Allocation: Intelligent IP allocation with conflict detection
• ✅ Static Reservations: MAC-to-IP binding with vendor class support
• ✅ Lease Renewal: Automatic renewal handling with grace periods
• ✅ Lease Expiration: Cleanup and reclamation of expired leases
• ✅ Conflict Resolution: Multiple strategies for lease conflicts
• ⚠️ Database persistence: Advanced lease backend uses line-oriented text (LEASE: / STATIC:), not SQLite
• ✅ Lease Analytics: Utilization monitoring and historical tracking

DHCP Options System (v0.3.0)

• ✅ Standard Options: Complete support for RFC-defined options
• ✅ Vendor-Specific Options: Custom vendor option handling
• ✅ Custom Options: User-defined option support with validation
• ✅ Option Validation: Length, format, and range validation
• ✅ Option Inheritance: Global, subnet, pool, and host-level inheritance
• ✅ Option Templates: Reusable option configurations

Performance & Reliability

• ✅ High-Performance: 50,000+ requests per second with optimized UDP handling
• ✅ Asynchronous Processing: Non-blocking message processing architecture
• ✅ Memory Efficiency: Optimized lease storage and management
• ✅ Graceful Shutdown: Clean shutdown with lease persistence
• ✅ Hot Reloading: Configuration updates without service interruption
• ✅ Cross-Platform: Native support for Linux, macOS, and Windows

Monitoring & Logging

• ✅ Comprehensive Logging: Multi-level logging with structured output
• ✅ Security Event Tracking: Real-time security event monitoring
• ✅ Statistics Collection: Performance and usage metrics
• ✅ Health Monitoring: Built-in health check capabilities
• ✅ Audit Trails: Complete audit logging for compliance
• ✅ Multiple Formats: JSON, text, and structured log formats

Configuration Examples

Simple Home Network

{
  "dhcp": {
    "listen": ["0.0.0.0:67"],
    "subnets": [
      {
        "name": "home-network",
        "network": "192.168.1.0/24",
        "range": "192.168.1.100-192.168.1.200",
        "gateway": "192.168.1.1",
        "dns_servers": ["8.8.8.8", "8.8.4.4"],
        "domain_name": "home.local",
        "lease_time": 86400,
        "reservations": [
          {
            "mac_address": "00:11:22:33:44:55",
            "ip_address": "192.168.1.10",
            "hostname": "router"
          }
        ]
      }
    ]
  }
}

Enterprise Network

{
  "dhcp": {
    "listen": ["0.0.0.0:67", "[::]:67"],
    "subnets": [
      {
        "name": "main-office",
        "network": "10.0.1.0/24",
        "range": "10.0.1.100-10.0.1.200",
        "gateway": "10.0.1.1",
        "dns_servers": ["10.0.1.10", "10.0.1.11"],
        "domain_name": "company.local",
        "lease_time": 43200
      }
    ],
    "security": {
      "mac_filtering": {
        "enabled": true,
        "mode": "allow"
      },
      "rate_limiting": {
        "enabled": true,
        "requests_per_minute": 1000
      }
    },
    "logging": {
      "enable": true,
      "level": "info",
      "format": "json"
    }
  }
}

Security-Focused Configuration

For high-security environments, see the comprehensive security configuration:

{
  "dhcp": {
    "security": {
      "dhcp_snooping": {
        "enabled": true,
        "trusted_interfaces": ["eth0"],
        "validation": true
      },
      "mac_filtering": {
        "enabled": true,
        "mode": "allow",
        "rules": [
          {
            "mac_address": "00:11:22:33:44:*",
            "allow": true,
            "description": "Corporate devices"
          }
        ]
      },
      "rate_limiting": {
        "enabled": true,
        "rules": [
          {
            "identifier": "*",
            "identifier_type": "mac",
            "max_requests": 100,
            "time_window": 60,
            "block_duration": 300
          }
        ]
      },
      "authentication": {
        "enabled": true,
        "key": "your-secret-key",
        "client_credentials": []
      }
    }
  }
}

See config/examples/security/ for complete security configuration examples.

Command Line Options

simple-dhcpd [OPTIONS]

Options:
  -c, --config FILE    Configuration file path (default: /etc/simple-dhcpd/simple-dhcpd.conf)
  -d, --daemon         Run as daemon
  -p, --pid-file FILE  PID file path (default: /var/run/simple-dhcpd.pid)
  -l, --log-file FILE  Log file path
  -v, --verbose        Verbose logging
  -h, --help           Show this help message
  -V, --version        Show version information

System Integration

systemd Service

# Enable and start the service
sudo systemctl enable simple-dhcpd
sudo systemctl start simple-dhcpd

# Check status
sudo systemctl status simple-dhcpd

# View logs
sudo journalctl -u simple-dhcpd -f

Docker

# Run with Docker
docker run -d \
  --name simple-dhcpd \
  --net host \
  -v /etc/simple-dhcpd:/etc/simple-dhcpd \
  simpledaemons/simple-dhcpd:latest

Docker Compose

version: '3.8'
services:
  simple-dhcpd:
    image: simpledaemons/simple-dhcpd:latest
    network_mode: host
    volumes:
      - ./config:/etc/simple-dhcpd
      - ./logs:/var/log/simple-dhcpd
    restart: unless-stopped

Development

Building from Source

# Clone repository
git clone https://github.com/SimpleDaemons/simple-dhcpd.git
cd simple-dhcpd

# Create build directory
mkdir build && cd build

# Configure with CMake
cmake .. -DCMAKE_BUILD_TYPE=Release

# Build
make -j$(nproc)

# Run tests
make test

# Install
sudo make install

Development Status

Current Version: 0.6.0 (pre–1.0; Phase 3+ integration and docs reconciliation)

Completed Phases:

• ✅ Phase 1: Core DHCP Protocol (v0.1.0)
• ✅ Phase 2: Core Implementation (v0.2.0)
• ✅ Phase 3: Advanced Features (v0.3.0)

Upcoming Phases:

• 📋 Phase 4: Enterprise Features (Q1 2025)
• 📋 Phase 5: Performance Optimization (Q2 2025)
• 📋 Phase 6: Production Readiness (Q3 2025)

Dependencies

• CMake 3.16+
• C++17 compatible compiler
• OpenSSL (for security features)
• jsoncpp (for JSON configuration)

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

Performance

Benchmarks

• Requests per Second: 50,000+ RPS
• Concurrent Leases: 100,000+
• Latency: <1ms for DHCP operations
• Memory Usage: <50MB base + 1KB per lease
• CPU Usage: <5% under normal load

Optimization

For high-performance deployments, see the Performance Tuning Guide.

Security

Simple DHCP Daemon includes several security features:

• MAC Address Filtering: Allow/deny specific MAC addresses
• Rate Limiting: Prevent DHCP flooding attacks
• Option 82 Support: Relay agent information validation
• Authentication: Framework for client authentication
• Access Control: IP-based access control lists

See the Security Guide for detailed information.

Documentation

• Getting Started
• Configuration Guide
• User Guide
• Deployment Guide
• Troubleshooting
• API Reference

Configuration Examples

We provide comprehensive configuration examples for different environments:

• Simple Environment: Home networks and small offices
• Advanced Environment: Medium offices with security requirements
• Production Environment: Enterprise deployments with high availability

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@simpledaemons.com

Roadmap

See ROADMAP.md for planned features and development timeline.

Changelog

See CHANGELOG.md for version history and changes.

---

Simple DHCP Daemon - Modern DHCP server for the cloud era.

Made with ❤️ by SimpleDaemons