# crdhcpc - Comprehensive DHCP Client
A comprehensive, secure DHCP client written in Rust, supporting DHCPv4, DHCPv6, PXE boot, Dynamic DNS, and more.
## Quick Start
```bash
# 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
```bash
cargo install --path .
```
### Build with Feature Flag
When building as part of crrouter-web:
```bash
cargo build --features dhcp-client
```
### Systemd Services
For systemd-based systems:
```bash
# 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](systemd/README.md) for complete systemd integration details.
## Configuration
Example configuration file (`/etc/dhcp-client.toml`):
```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](docs/QUICK_REFERENCE.md) for complete configuration reference.
## Usage
### Command Line Interface
```bash
# 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`:
```bash
# 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:
```bash
# 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:
```toml
[security]
allowed_servers = ["192.168.1.1", "192.168.1.2"]
validate_server = true
```
### 2. Lease Time Validation
Set reasonable lease time bounds:
```toml
[security]
min_lease_time = 300 # 5 minutes
max_lease_time = 604800 # 7 days
```
### 3. Rate Limiting
Prevent DHCP exhaustion attacks:
```toml
[security]
max_request_rate = 10 # requests per second per interface
```
### 4. DDNS Security
Use TSIG for secure DNS updates:
```toml
[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
```bash
RUST_LOG=debug crdhcpc daemon
```
### Mock Mode for Testing
```bash
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](docs/IMPLEMENTATION.md)** - Implementation details, RFCs, state machines
- **[QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md)** - Configuration and command reference
- **[Systemd Integration](systemd/README.md)** - 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