141ac1c9dd
Features: - Docker-based DHCP server with MAC address whitelisting - Binds to specific ethernet interface only - NO DNS/gateway advertised (direct link only, not a router) - Configurable network parameters (subnet, DHCP range, lease times) - Systemd service integration for Arch/Manjaro - Test environment with isolated network (172.20.0.0/24) - Auto-configuration script to detect network settings - Complete Makefile with management targets Security: - Only responds to whitelisted MAC addresses - deny unknown-clients configuration - Runs in Docker container for isolation Configuration: - Copy .example files to create your config - interface.conf: Network interface to bind to - whitelist.conf: Allowed MAC addresses - network.conf: Network parameters (optional)
136 lines
3.6 KiB
Markdown
136 lines
3.6 KiB
Markdown
# 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:
|
|
```bash
|
|
make autoconfig
|
|
```
|
|
|
|
2. Start the DHCP server:
|
|
```bash
|
|
make up
|
|
```
|
|
|
|
3. Stop the server:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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 |