From 1b645ea8218f006cf59876a927edb420fae33587 Mon Sep 17 00:00:00 2001 From: cclohmar Date: Wed, 29 Jul 2026 09:25:14 +0000 Subject: [PATCH] docs: update README with DNS name service, systemctl capabilities, architecture diagram --- README.md | 73 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 49 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 2faecf5..cd3b17f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # DHCP Lease Manager -**Zoraxy plugin** — View, pin, and unpin dnsmasq DHCP leases from the Zoraxy web UI. +**Zoraxy plugin** — Manage dnsmasq DHCP leases, assign static IPs, and create network-wide hostnames from the Zoraxy web UI. --- @@ -13,10 +13,10 @@ curl -sSL https://git.lohmar.co.uk/cclohmar/zoraxy-dhcp/raw/branch/main/install. 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 +- dnsmasq DHCP + DNS server with NAT/routing - dhcp-lease-manager plugin inside Zoraxy -- Group-based permissions for secure management -- Sudoers rule for dnsmasq reloads +- Group-based permissions for secure config access +- Linux capabilities (`CAP_SYS_ADMIN`) for dnsmasq reloads After installation, open Zoraxy → Plugins → enable **DHCP Lease Manager** → access at `/plugin.ui/dhcp-lease-manager/`. @@ -27,13 +27,30 @@ After installation, open Zoraxy → Plugins → enable **DHCP Lease Manager** | 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) | +| **Pin leases** | Make a lease permanent — sets static DHCP and optional DNS name | +| **DNS names** | When pinning, give the device a hostname (e.g. `printer.lan`) — resolves network-wide via dnsmasq DNS | +| **Unpin leases** | Remove static DHCP assignment and DNS record | +| **Reload** | Apply changes + scrub expired leases from the lease file | | **Status badges** | Green "permanent" / grey "active" indicators | --- +## DNS Name Service + +When you pin a lease with a hostname, the plugin writes an `address=/name/IP` record to dnsmasq's config. Every DHCP client using this server for DNS can then resolve the name: + +```bash +# Before pinning +$ nslookup printer.lan # → NXDOMAIN + +# Click Pin, enter "printer.lan" +$ nslookup printer.lan 10.1.0.10 # → 10.1.0.50 ✓ +``` + +No extra configuration needed — dnsmasq serves the records automatically on reload. Unpinning removes both the static DHCP assignment and the DNS record. + +--- + ## Requirements | Component | Detail | @@ -59,16 +76,21 @@ After installation, open Zoraxy → Plugins → enable **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 │ └─────────────────────┘ -└─────────────────┘ + │ read/write │ systemctl reload +┌──────▼──────────────┐ ┌────────────▼──────────┐ +│ /opt/zoraxy/ │ │ dnsmasq │ +│ conf/dhcp/ │ │ DHCP: 10.1.0.100-150 │ +│ dnsmasq.conf ────┼────► DNS: address=/name/ │ +│ dnsmasq.leases │ │ NAT: MASQUERADE │ +└─────────────────────┘ └───────────────────────┘ + ▲ │ + │ DNS queries ▼ + │ "printer.lan?" ┌──────────────┐ + └──────────────────────┤ DHCP clients │ + 10.1.0.50 └──────────────┘ ``` -All DHCP configuration lives under `/opt/zoraxy/conf/dhcp/` — a single, unified location regardless of whether Zoraxy runs bare-metal or in Docker. +All DHCP + DNS configuration lives under `/opt/zoraxy/conf/dhcp/` — a single, unified location regardless of whether Zoraxy runs bare-metal or in Docker. --- @@ -76,10 +98,10 @@ All DHCP configuration lives under `/opt/zoraxy/conf/dhcp/` — a single, unifie | 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` | +| `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`) | +| `POST` | `/ui/api/unpin` | Unpin a lease — removes static IP + DNS record (body: `mac`) | +| `POST` | `/ui/api/reload` | Reload dnsmasq + scrub expired leases (rate-limited: 5s cooldown) | --- @@ -91,20 +113,23 @@ Overridable defaults for custom deployments: |----------|---------| | `LEASE_FILE` | `/opt/zoraxy/conf/dhcp/dnsmasq.leases` | | `CONF_FILE` | `/opt/zoraxy/conf/dhcp/dnsmasq.conf` | -| `RELOAD_CMD` | `sudo` | -| `RELOAD_ARGS` | `systemctl reload dnsmasq` | +| `RELOAD_CMD` | `/usr/bin/systemctl` | +| `RELOAD_ARGS` | `reload dnsmasq` | --- ## Permissions -The installer creates a `dnsmasq-edit` group with access to the DHCP config files and a sudoers rule for reloading dnsmasq: +The installer creates a `dnsmasq-edit` group for config file access and adds `CAP_SYS_ADMIN` to the Zoraxy systemd service so the plugin can reload dnsmasq without sudo: ``` Group: dnsmasq-edit → zoraxy user added → Read/write on /opt/zoraxy/conf/dhcp/ - → Passwordless sudo for systemctl reload dnsmasq + +Zoraxy systemd service: + → CapabilityBoundingSet=CAP_SYS_ADMIN + → AmbientCapabilities=CAP_SYS_ADMIN ``` --- @@ -115,7 +140,7 @@ Group: dnsmasq-edit sudo bash install.sh --remove ``` -Removes dnsmasq, the plugin, config files, NAT rules, and the sudoers rule — leaving the system clean. +Removes dnsmasq, the plugin, config files, group, and NAT rules — leaving the system clean. ---