shadowdhcp

A reservation-only DHCPv4 and DHCPv6 server designed for internet service providers.

Beta Software - This project is under active development. APIs and configuration formats may change.

Features

• Reservation only, external software generates the reservations (e.g., ISP billing system)
• In-memory only, no database backend
• Simple configuration with ids.json, config.json, and reservations.json
• Only responds to relayed requests
• Correlates DHCPv6 with DHCPv4 Option 82 reservations. When premises equipment doesn't support DHCPv6 Option 37, the server uses MAC addresses learned from DHCPv4 sessions to match IPv6 requests
• Reload reservations from disk on SIGHUP or via management socket
• Analytics events for monitoring and troubleshooting
• Runs on Linux (glibc or musl), macOS, and Windows

Quick start

See Installation on Alpine Linux for a complete guide.

Configuration

config.json:

{
    "dns_v4": ["8.8.8.8", "8.8.4.4"],
    "dns_v6": ["2001:4860:4860::8888", "2001:4860:4860::8844"],
    "subnets_v4": [
        {"net": "100.100.1.0/24", "gateway": "100.100.1.1"},
        {"net": "100.100.2.0/24", "gateway": "100.100.2.1"}
    ],
    "option82_extractors": [
        "remote_only",
        "subscriber_only",
        "circuit_and_remote",
        "remote_first_12"
    ],
    "option1837_extractors": ["interface_only", "remote_only", "interface_and_remote"],
    "mac_extractors": ["client_linklayer_address"]
}

reservations.json:

[
    {
        "ipv4": "100.100.1.100",
        "ipv6_na": "2001:db8:1::100",
        "ipv6_pd": "2001:db8:100::/56",
        "mac": "00-11-22-33-44-55"
    },
    {
        "ipv4": "100.100.1.101",
        "ipv6_na": "2001:db8:1::101",
        "ipv6_pd": "2001:db8:101::/56",
        "option82": {"remote": "AA-BB-CC-DD-EE-FF"}
    }
]

Documentation

• Installation on Alpine Linux - Complete installation guide
• Configuration - All configuration options
• Reservations - Reservation format and extractors
• Management - TCP management interface
• Events - Analytics events and ClickHouse setup
• Logging - Logging to stdout or a rotating file

Current limitations

• No high availability
• Single-threaded per protocol
• No duplicate reservation checking
• MAC to Option 82 bindings aren't persisted to disk

For a mature, full-featured DHCP server, consider the Kea DHCP server.