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.

---

Credits

• Zoraxy — Reverse proxy and plugin system
• dnsmasq — DNS/DHCP server