6.4 KiB
DHCP Lease Manager
Zoraxy plugin — Manage dnsmasq DHCP leases, assign static IPs, and create network-wide hostnames 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 + DNS server with NAT/routing
- dhcp-lease-manager plugin inside Zoraxy
- Group-based permissions for secure config access
- systemd path unit for automatic dnsmasq reload (no sudo needed)
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 | One click — makes a lease permanent with static DHCP + optional DNS name |
| Edit | Change the hostname/DNS record on a pinned lease |
| Unpin | Remove static DHCP assignment and DNS record |
| DNS names | Pinned hostnames (e.g. printer.lan) resolve network-wide via dnsmasq DNS |
| Reload | Scrub expired leases + trigger dnsmasq config reload |
| Status badges | Green "permanent" / grey "active" indicators |
Actions
| Lease state | Buttons | Behavior |
|---|---|---|
| Active + hostname | Pin |
One click — pins immediately with existing hostname |
| Active, no hostname | Pin → input → OK |
Click Pin, type a hostname, confirm |
| Pinned | Edit Unpin |
Edit shows inline input to change hostname, Unpin removes it |
DNS Name Service
When you pin a lease with a hostname, the plugin writes both a dhcp-host and address=/name/IP record to dnsmasq. Every DHCP client using this server for DNS can resolve the name:
# Before pinning
$ nslookup printer.lan # → NXDOMAIN
# Click Pin, enter "printer.lan", reload
$ nslookup printer.lan 10.1.0.10 # → 10.1.0.50 ✓
Unpinning removes both records. Editing a pinned hostname updates the DNS record.
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 • Touches reload trigger │
└──────┬────────────────────────────────┬──────────┘
│ read/write │ touch .reload
┌──────▼──────────────┐ ┌────────────▼──────────┐
│ /opt/zoraxy/ │ │ systemd path unit │
│ conf/dhcp/ │ │ dnsmasq-reload.path │
│ dnsmasq.conf ────┼────► watches .reload file │
│ dnsmasq.leases │ │ → systemctl reload │
└─────────────────────┘ └───────────┬───────────┘
▲ │
│ DNS queries ▼
│ "printer.lan?" ┌──────────────┐
└──────────────────────┤ dnsmasq │
10.1.0.50 │ DHCP / DNS │
└──────────────┘
All DHCP + DNS configuration lives under /opt/zoraxy/conf/dhcp/. The plugin never needs root — it touches a trigger file, and systemd's path unit handles the privileged reload.
API Endpoints
| Method | Path | Purpose |
|---|---|---|
GET |
/ui/api/leases |
List all active + permanent leases |
POST |
/ui/api/pin |
Pin a lease — set static IP + optional DNS name (body: mac, ip, hostname). Idempotent — repinning with a different hostname updates it. |
POST |
/ui/api/unpin |
Unpin a lease — removes static IP + DNS record (body: mac) |
POST |
/ui/api/reload |
Scrub expired leases + trigger dnsmasq reload (rate-limited: 5s cooldown) |
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 |
Permissions
The installer creates a dnsmasq-edit group for config file access and a systemd path unit for reloads:
Group: dnsmasq-edit
→ zoraxy user added
→ Read/write on /opt/zoraxy/conf/dhcp/
systemd path unit: dnsmasq-reload.path
→ Watches /opt/zoraxy/conf/dhcp/dnsmasq.conf.reload
→ On change: systemctl reload dnsmasq (runs as root)
Uninstall
sudo bash install.sh --remove
Removes dnsmasq, the plugin, config files, group, systemd units, and NAT rules — 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.