crdhcpc - Comprehensive DHCP Client

A comprehensive, secure DHCP client written in Rust, supporting DHCPv4, DHCPv6, PXE boot, Dynamic DNS, and more.

Quick Start

# Build
cd crdhcpc
cargo build --release

# Start on an interface
crdhcpc -c /etc/dhcp-client.toml start eth0

# Run as daemon
crdhcpc -c /etc/dhcp-client.toml daemon

# Check status
crdhcpc status eth0

Features

Protocol Support

• DHCPv4 (RFC 2131) - Full DORA cycle (Discover, Offer, Request, Acknowledge)
• BOOTP (RFC 951) - Bootstrap Protocol compatibility
• DHCPv6 (RFC 8415) - Stateful and stateless address autoconfiguration
• Prefix Delegation (RFC 3633) - IPv6 prefix delegation for routers

Advanced Features

• PXE Boot - Preboot Execution Environment support with TFTP integration
• Dynamic DNS - Automatic DNS record updates (RFC 4702/4704)
• Load Balancing - Distribute requests across multiple DHCP servers
• Failover - Automatic failover to backup servers
• TFTP Client - Download boot files for PXE

Security Features

• Message Validation - Strict parsing and validation of all DHCP messages
• Server Authentication - Whitelist of allowed DHCP servers
• Rate Limiting - Prevent DHCP exhaustion attacks
• Lease Time Validation - Reject suspiciously short or long leases
• DHCP Snooping - Optional layer-2 security
• Secure Random - Cryptographically secure transaction IDs
• No Unsafe Code - 100% safe Rust (except in dhcproto library)

Control Interface

• Unix Socket API - JSON-RPC 2.0 control interface
• CLI Commands - Start, stop, renew, release, status
• Signal Handling - SIGHUP (reload), SIGUSR1 (status), SIGTERM (shutdown)

Architecture

┌─────────────────────────────────────────────────┐
│            REST API (Axum)                      │
│    GET  /api/dhcp-client/status                 │
│    POST /api/dhcp-client/start                  │
│    POST /api/dhcp-client/renew                  │
└─────────────────┬───────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────┐
│       JSON-RPC Plugin (crrouterd)               │
│    dhcpclient.status                            │
│    dhcpclient.start                             │
│    dhcpclient.renew                             │
└─────────────────┬───────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────┐
│         DHCP Client Manager                     │
│  ┌──────────────┬───────────────┐               │
│  │ DHCPv4       │ DHCPv6        │               │
│  │ - DORA       │ - SARR        │               │
│  │ - BOOTP      │ - Prefix Del. │               │
│  └──────────────┴───────────────┘               │
│  ┌──────────────┬───────────────┐               │
│  │ PXE          │ DDNS          │               │
│  │ TFTP         │ Failover      │               │
│  └──────────────┴───────────────┘               │
└─────────────────┬───────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────┐
│       Network Integration                       │
│  NetworkManager │ Unbound │ lnxnetctl           │
└─────────────────────────────────────────────────┘

Installation

From Source

cargo install --path .

Build with Feature Flag

When building as part of crrouter-web:

cargo build --features dhcp-client

Systemd Services

For systemd-based systems:

# Daemon mode (recommended) - manages all interfaces
sudo cp systemd/dhcp-client-standalone.service /etc/systemd/system/
sudo systemctl enable dhcp-client-standalone.service
sudo systemctl start dhcp-client-standalone.service

# Per-interface mode
sudo cp systemd/dhcp-client@.service /etc/systemd/system/
sudo systemctl enable dhcp-client@eth0.service
sudo systemctl start dhcp-client@eth0.service

See systemd/README.md for complete systemd integration details.

Configuration

Example configuration file (/etc/dhcp-client.toml):

[general]
enabled = true
interfaces = ["eth0"]

[dhcpv4]
enabled = true
hostname = "router"
send_hostname = true
timeout = 30
retry_count = 3

[dhcpv6]
enabled = false
prefix_delegation = true
rapid_commit = true

[security]
validate_server = true
allowed_servers = ["192.168.1.1"]
min_lease_time = 300
max_lease_time = 604800

[ddns]
enabled = false
update_forward = true
update_reverse = true

See docs/QUICK_REFERENCE.md for complete configuration reference.

Usage

Command Line Interface

# Start DHCP client on an interface
crdhcpc -c /etc/dhcp-client.toml start eth0

# Run as a daemon (manages all configured interfaces)
crdhcpc -c /etc/dhcp-client.toml daemon

# Check status
crdhcpc status              # All interfaces
crdhcpc status eth0         # Specific interface

# Renew lease
crdhcpc renew eth0

# Release lease
crdhcpc release eth0

# Stop client
crdhcpc stop eth0

JSON-RPC API

The daemon provides a JSON-RPC 2.0 interface on /var/run/crdhcpc.sock:

# Get status
curl -X POST http://localhost:8080/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "dhcpclient.status",
    "params": {},
    "id": 1
  }'

# Start client on interface
curl -X POST http://localhost:8080/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "dhcpclient.start",
    "params": {"interface": "eth0"},
    "id": 1
  }'

# Renew lease
curl -X POST http://localhost:8080/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "dhcpclient.renew",
    "params": {"interface": "eth0"},
    "id": 1
  }'

Integration with crrouter-web

When running as part of crrouter-web:

# The plugin is automatically loaded when crrouterd starts
sudo systemctl start crrouterd

# Status is available via REST API
curl http://localhost:8080/api/dhcp-client/status

# Control via REST API
curl -X POST http://localhost:8080/api/dhcp-client/start \
  -H "Content-Type: application/json" \
  -d '{"interface": "eth0"}'

Security Best Practices

1. Server Whitelisting

Always configure allowed servers in production:

[security]
allowed_servers = ["192.168.1.1", "192.168.1.2"]
validate_server = true

2. Lease Time Validation

Set reasonable lease time bounds:

[security]
min_lease_time = 300     # 5 minutes
max_lease_time = 604800  # 7 days

3. Rate Limiting

Prevent DHCP exhaustion attacks:

[security]
max_request_rate = 10  # requests per second per interface

4. DDNS Security

Use TSIG for secure DNS updates:

[ddns]
tsig_key_name = "dhcp-update-key"
tsig_key = "base64-encoded-key"

Integration

Unbound DNS Integration

• DNS servers from DHCP are configured as forwarders in Unbound
• Hostname is registered via Dynamic DNS
• Search domains are updated

NetworkManager Integration

• Interface configuration is applied via NetworkManager
• Connection profiles are updated
• Network state is synchronized

SIEM Integration

All DHCP events are logged:

• Lease acquisitions, renewals, and releases
• Security violations
• Server failures

Troubleshooting

Enable Debug Logging

RUST_LOG=debug crdhcpc daemon

Mock Mode for Testing

MOCK_DHCP_CLIENT=true crdhcpc daemon

Common Issues

1. No lease acquired: Check network connectivity and server configuration
2. Security violation: Verify allowed_servers configuration
3. Rate limit exceeded: Reduce request rate or increase limit
4. DDNS failed: Check unbound configuration and TSIG keys

Documentation

• IMPLEMENTATION.md - Implementation details, RFCs, state machines
• QUICK_REFERENCE.md - Configuration and command reference
• Systemd Integration - Systemd service setup

RFCs Implemented

• RFC 951: Bootstrap Protocol (BOOTP)
• RFC 2131: Dynamic Host Configuration Protocol (DHCPv4)
• RFC 2132: DHCP Options and BOOTP Vendor Extensions
• RFC 3396: Encoding Long Options in DHCPv4
• RFC 3633: IPv6 Prefix Options for DHCPv6
• RFC 4702: The DHCP Client FQDN Option
• RFC 4704: The DHCPv6 Client FQDN Option
• RFC 8415: Dynamic Host Configuration Protocol for IPv6 (DHCPv6)
• RFC 1350: TFTP Protocol
• RFC 2347-2349: TFTP Option Extension

License

MIT OR Apache-2.0