olisrobotics/interactive-dhcp-server repository overview

⁠Interactive DHCP Server 🌐

A modern web-based DHCP server with real-time device monitoring and IP binding management.

⁠Use Case

This DHCP server is designed for selective IP assignment - perfect when you want to hand out IPs to specific devices while ignoring others. This is particularly useful in scenarios where:

• Most devices have static IPs - You only need DHCP for a few specific devices
• Connecting devices one at a time - You want to assign IPs manually as devices connect, without knowing their MAC addresses beforehand
• Controlled network environments - You want to see DHCP requests in real-time and decide which devices get IPs
• Testing and development - You need to monitor DHCP traffic and assign IPs selectively

Unlike traditional DHCP servers that assign IPs automatically from a pool, this server lets you see incoming requests and bind specific MAC addresses to IPs through the web interface.

⁠Interface Preview

The web interface provides real-time monitoring of DHCP activity with separate sections for active devices and static IP bindings. You can see device details, DHCP packet information, and manage IP assignments all from one clean dashboard.

⁠Quick Start

⁠Option 1: Pre-built Image (Coming Soon)

# Kill any existing instance and run fresh
docker stop dhcp-server 2>/dev/null || true && \
docker run --rm --name dhcp-server --privileged --network host \
  -e PORT=8000 \
  -v dhcp-server-data:/data \
  interactive-dhcp-server

⁠Option 2: Build from Source

# Clone, build, and run in one command
git clone <repository-url> && cd interactive_dhcp_server && \
docker build -t interactive-dhcp-server . && \
docker stop dhcp-server 2>/dev/null || true && \
docker run --rm --name dhcp-server --privileged --network host \
  -e PORT=8000 \
  -v dhcp-server-data:/data \
  interactive-dhcp-server

Or step by step:

git clone <repository-url>
cd interactive_dhcp_server
docker build -t interactive-dhcp-server .

# Kill any existing instance and run fresh
docker stop dhcp-server 2>/dev/null || true
docker run --rm --name dhcp-server --privileged --network host \
  -e PORT=8000 \
  -v dhcp-server-data:/data \
  interactive-dhcp-server

Web Interface: http://localhost:8000⁠

⁠Environment Variables

Set these when running the container:

• PORT (optional) - Web server port, defaults to 8000
• DEBUG (optional) - Enable debug logging with true

Note: Network interface is now set dynamically via the web interface API, not through environment variables.

⁠Features

• 📱 Real-time Device Discovery - See DHCP requests as they happen
• 🔗 Static IP Binding - Assign fixed IPs to MAC addresses
• 🌐 Modern Web Interface - Clean, responsive design
• ⚡ WebSocket Updates - Live data without page refresh
• 🐳 Docker Ready - Single container deployment

⁠Network Requirements

• Privileged mode required for raw socket access
• Host networking required for DHCP broadcast handling
• UDP port 67 for DHCP server
• TCP port (default 8000, configurable via PORT env var) for web interface

⁠Find Your Interface

# List available network interfaces
ip link show

# Or on older systems
ifconfig -a

⁠API Control

Once the container is running, control the DHCP server via API:

⁠Start DHCP monitoring on an interface:

curl -X POST http://localhost:8000/api/start \
  -H "Content-Type: application/json" \
  -d '{"interface": "eth0"}'

⁠Stop DHCP monitoring:

curl -X POST http://localhost:8000/api/stop

⁠Get available interfaces:

curl http://localhost:8000/api/interfaces

⁠Examples

⁠Basic usage:

docker stop dhcp-server 2>/dev/null || true
docker run --rm --name dhcp-server --privileged --network host \
  interactive-dhcp-server

⁠With persistent data:

docker stop dhcp-server 2>/dev/null || true
docker run --rm --name dhcp-server --privileged --network host \
  -v dhcp-server-data:/data \
  interactive-dhcp-server

⁠Custom web port:

docker stop dhcp-server 2>/dev/null || true
docker run --rm --name dhcp-server --privileged --network host \
  -e PORT=8080 \
  interactive-dhcp-server

⁠Development with debug:

docker stop dhcp-server 2>/dev/null || true
docker run --rm --name dhcp-server --privileged --network host \
  -e DEBUG=true \
  interactive-dhcp-server

⁠Data Persistence

IP bindings are stored in /data/dhcp_bindings.json. Mount this directory to persist configurations across container restarts.

Docker will automatically create any named volume if it doesn't exist. To use a specific host directory instead:

# Use a host directory for data
docker run --privileged --network host \
  -e DHCP_INTERFACE=eth0 \
  -v /opt/dhcp-server:/data \
  interactive-dhcp-server

⁠License

MIT License

Copyright (c) 2025 Olis Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.