4.7 KiB
DHCP Lease Manager
Zoraxy plugin — View, pin, and unpin dnsmasq DHCP leases from the Zoraxy web UI.
Quick Install
curl -sSL https://git.lohmar.co.uk/cclohmar/zoraxy-dhcp/raw/branch/main/install.sh | sudo bash
The installer is fully interactive — it asks for your network settings and then installs everything.
What it sets up:
- dnsmasq DHCP server with NAT/routing
- dhcp-lease-manager plugin inside Zoraxy
- Group-based permissions for secure management
- Sudoers rule for dnsmasq reloads
After installation, open Zoraxy → Plugins → enable DHCP Lease Manager → access at /plugin.ui/dhcp-lease-manager/.
Features
| Feature | Description |
|---|---|
| View leases | Active DHCP leases with hostname, IP, MAC, expiry |
| Pin leases | Make a temporary lease permanent (adds dhcp-host to config) |
| Unpin leases | Remove permanent lease assignments |
| Reload | Apply changes by reloading dnsmasq (uses sudo) |
| Status badges | Green "permanent" / grey "active" indicators |
Requirements
| Component | Detail |
|---|---|
| Zoraxy | v3.2.0+ (plugin system required) |
| OS | Debian, Ubuntu, RHEL, Fedora, Alpine, Arch |
| dnsmasq | Installed by the script |
| Go | Installed by the script (for building the plugin) |
| Permissions | Script must run as root |
Architecture
┌──────────────────────────────────────────────────┐
│ Zoraxy UI │
│ /plugin.ui/dhcp-lease-manager/ ─────► iframe │
└───────────────────────┬──────────────────────────┘
│ reverse proxy
┌───────────────────────▼──────────────────────────┐
│ dhcp-lease-manager │
│ Go binary • PluginUiRouter • JSON API │
│ Reads/writes config + triggers dnsmasq reload │
└──────┬────────────────────────────────┬──────────┘
│ read/write │ sudo reload
┌──────▼──────────┐ ┌──────────▼──────────┐
│ /opt/zoraxy/ │ │ dnsmasq │
│ conf/dhcp/ │ │ systemctl reload │
│ dnsmasq.conf │ │ │
│ dnsmasq.leases │ └─────────────────────┘
└─────────────────┘
All DHCP configuration lives under /opt/zoraxy/conf/dhcp/ — a single, unified location regardless of whether Zoraxy runs bare-metal or in Docker.
API Endpoints
| Method | Path | Purpose |
|---|---|---|
GET |
/ui/api/leases |
List all leases (active + permanent) |
POST |
/ui/api/pin |
Pin a lease (body: mac, ip, hostname) |
POST |
/ui/api/unpin |
Unpin a lease (body: mac) |
POST |
/ui/api/reload |
Run sudo systemctl reload dnsmasq |
Environment Variables
Overridable defaults for custom deployments:
| Variable | Default |
|---|---|
LEASE_FILE |
/opt/zoraxy/conf/dhcp/dnsmasq.leases |
CONF_FILE |
/opt/zoraxy/conf/dhcp/dnsmasq.conf |
RELOAD_CMD |
sudo |
RELOAD_ARGS |
systemctl reload dnsmasq |
Permissions
The installer creates a dnsmasq-edit group with access to the DHCP config files and a sudoers rule for reloading dnsmasq:
Group: dnsmasq-edit
→ zoraxy user added
→ Read/write on /opt/zoraxy/conf/dhcp/
→ Passwordless sudo for systemctl reload dnsmasq
Uninstall
sudo bash install.sh --remove
Removes dnsmasq, the plugin, config files, NAT rules, and the sudoers rule — leaving the system clean.
Manual Install
# 1. Clone the repo
git clone https://git.lohmar.co.uk/cclohmar/zoraxy-dhcp.git /opt/zoraxy/plugins/dhcp-lease-manager
# 2. Build
cd /opt/zoraxy/plugins/dhcp-lease-manager
go build -buildvcs=false -o dhcp-lease-manager .
# 3. Run setup (as root)
sudo bash install.sh
License
Zoraxy plugin SDK is LGPL. This plugin is open source.