182 lines
6.4 KiB
Markdown
182 lines
6.4 KiB
Markdown
# DHCP Lease Manager
|
|
|
|
**Zoraxy plugin** — Manage dnsmasq DHCP leases, assign static IPs, and create network-wide hostnames from the Zoraxy web UI.
|
|
|
|
---
|
|
|
|
## Quick Install
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
sudo bash install.sh --remove
|
|
```
|
|
|
|
Removes dnsmasq, the plugin, config files, group, systemd units, and NAT rules — leaving the system clean.
|
|
|
|
---
|
|
|
|
## Manual Install
|
|
|
|
```bash
|
|
# 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](https://github.com/tobychui/zoraxy) — Reverse proxy and plugin system
|
|
- [dnsmasq](https://thekelleys.org.uk/dnsmasq/doc.html) — DNS/DHCP server
|