docs: update README with DNS name service, systemctl capabilities, architecture diagram

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
+- Group-based permissions for secure config access
-- Sudoers rule for dnsmasq reloads
+- 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) |
+| **Pin leases** | Make a lease permanent — sets static DHCP and optional DNS name |
-| **Unpin leases** | Remove permanent lease assignments |
+| **DNS names** | When pinning, give the device a hostname (e.g. `printer.lan`) — resolves network-wide via dnsmasq DNS |
-| **Reload** | Apply changes by reloading dnsmasq (uses sudo) |
+| **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
+       │ read/write                     │ systemctl reload
-┌──────▼──────────┐          ┌──────────▼──────────┐
+┌──────▼──────────────┐    ┌────────────▼──────────┐
-│  /opt/zoraxy/   │          │     dnsmasq          │
+│  /opt/zoraxy/       │    │      dnsmasq           │
-│  conf/dhcp/     │          │  systemctl reload    │
+│  conf/dhcp/         │    │  DHCP: 10.1.0.100-150  │
-│  dnsmasq.conf   │          │                      │
+│  dnsmasq.conf   ────┼────►  DNS:  address=/name/  │
-│  dnsmasq.leases │          └─────────────────────┘
+│  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) |
+| `GET` | `/ui/api/leases` | List all active + permanent leases |
-| `POST` | `/ui/api/pin` | Pin a lease (body: `mac`, `ip`, `hostname`) |
+| `POST` | `/ui/api/pin` | Pin a lease — set static IP + optional DNS name (body: `mac`, `ip`, `hostname`) |
-| `POST` | `/ui/api/unpin` | Unpin a lease (body: `mac`) |
+| `POST` | `/ui/api/unpin` | Unpin a lease — removes static IP + DNS record (body: `mac`) |
-| `POST` | `/ui/api/reload` | Run `sudo systemctl reload dnsmasq` |
+| `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_CMD` | `/usr/bin/systemctl` |
-| `RELOAD_ARGS` | `systemctl reload dnsmasq` |
+| `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.
 
 ---