DHCP Direct Link Only Service

A Docker-based DHCP server that only serves IP addresses to whitelisted MAC addresses on a specific ethernet interface. Designed for secure, controlled network environments where only authorized devices should receive DHCP leases.

Features

• MAC Address Whitelisting: Only responds to DHCP requests from pre-authorized MAC addresses
• Interface Binding: Binds to a specific ethernet interface only
• Docker-Based: Runs in an isolated container environment
• Systemd Integration: Can be installed as a system service on Arch/Manjaro
• Auto-Configuration: Automatically detects network settings and connected devices
• Testing Environment: Includes isolated test environment with virtual networks

Requirements

• Docker
• Docker Compose
• Make
• systemd (for service installation)
• sudo (for service installation)

Quick Start

1. Auto-configure for current network:

make autoconfig

2. Start the DHCP server:

make up

3. Stop the server:

make down

Configuration

Manual Configuration

Edit the following files in the config/ directory:

• interface.conf: Specify the ethernet interface to bind to
• whitelist.conf: List MAC addresses (one per line) that should be served

Auto Configuration

Run make autoconfig to automatically:

• Detect your ethernet interface
• Find connected devices on the network
• Generate configuration files

Make Targets

Target	Description	Requires sudo
up	Start DHCP server in userland mode	No
down	Stop DHCP server	No
install	Install as systemd service	Yes
service_up	Enable and start systemd service	No
service_down	Disable and stop systemd service	No
test	Run isolated test environment	No
autoconfig	Auto-generate configuration	No
clean	Remove generated files	No

Installation as System Service

To install and run as a systemd service:

# Install the service (requires sudo)
sudo make install

# Start the service
make service_up

# Check service status
systemctl status dhcp-whitelist

# Stop the service
make service_down

The service configuration will be stored in /etc/dhcp-whitelist/ and will persist across system reboots.

Testing

Run the test environment with virtual networks:

make test

This creates an isolated Docker network with:

• A DHCP server with test whitelist
• Test clients with different MAC addresses
• Validation of whitelist enforcement

Network Configuration

Default DHCP settings:

• Subnet: 192.168.75.0/24
• Range: 192.168.75.10 - 192.168.75.100
• Gateway: 192.168.75.1
• DNS: 8.8.8.8, 8.8.4.4
• Lease time: 12 hours

Troubleshooting

DHCP server not responding

• Check that the interface in config/interface.conf is correct
• Verify the MAC address is in config/whitelist.conf
• Check Docker logs: docker-compose logs dhcp-server

Permission denied errors

• Service installation requires sudo: sudo make install
• Ensure Docker daemon is running
• Check that your user is in the docker group

Service won't start

• Check systemd logs: journalctl -u dhcp-whitelist -f
• Verify Docker and docker-compose are installed
• Check configuration files in /etc/dhcp-whitelist/

Security Considerations

• This server uses MAC address filtering as the primary security mechanism
• MAC addresses can be spoofed; use additional security measures in production
• The server runs with host networking to access the physical interface
• Consider firewall rules to restrict DHCP traffic further

License

MIT