diff --git a/README.md b/README.md index cd3b17f..1d86049 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ The installer is fully interactive — it asks for your network settings and the - dnsmasq DHCP + DNS server with NAT/routing - dhcp-lease-manager plugin inside Zoraxy - Group-based permissions for secure config access -- Linux capabilities (`CAP_SYS_ADMIN`) for dnsmasq reloads +- 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/`. @@ -27,27 +27,38 @@ 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 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 | +| **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 an `address=/name/IP` record to dnsmasq's config. Every DHCP client using this server for DNS can then resolve the name: +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" +# Click Pin, enter "printer.lan", reload $ 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. +Unpinning removes both records. Editing a pinned hostname updates the DNS record. --- @@ -74,23 +85,24 @@ No extra configuration needed — dnsmasq serves the records automatically on re ┌───────────────────────▼──────────────────────────┐ │ dhcp-lease-manager │ │ Go binary • PluginUiRouter • JSON API │ -│ Reads/writes config + triggers dnsmasq reload │ +│ Reads/writes config • Touches reload trigger │ └──────┬────────────────────────────────┬──────────┘ - │ read/write │ systemctl reload + │ read/write │ touch .reload ┌──────▼──────────────┐ ┌────────────▼──────────┐ -│ /opt/zoraxy/ │ │ dnsmasq │ -│ conf/dhcp/ │ │ DHCP: 10.1.0.100-150 │ -│ dnsmasq.conf ────┼────► DNS: address=/name/ │ -│ dnsmasq.leases │ │ NAT: MASQUERADE │ -└─────────────────────┘ └───────────────────────┘ - ▲ │ - │ DNS queries ▼ +│ /opt/zoraxy/ │ │ systemd path unit │ +│ conf/dhcp/ │ │ dnsmasq-reload.path │ +│ dnsmasq.conf ────┼────► watches .reload file │ +│ dnsmasq.leases │ │ → systemctl reload │ +└─────────────────────┘ └───────────┬───────────┘ + ▲ │ + │ DNS queries ▼ │ "printer.lan?" ┌──────────────┐ - └──────────────────────┤ DHCP clients │ - 10.1.0.50 └──────────────┘ + └──────────────────────┤ dnsmasq │ + 10.1.0.50 │ DHCP / DNS │ + └──────────────┘ ``` -All DHCP + DNS 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/`. The plugin never needs root — it touches a trigger file, and systemd's path unit handles the privileged reload. --- @@ -99,9 +111,9 @@ All DHCP + DNS configuration lives under `/opt/zoraxy/conf/dhcp/` — a single, | 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`) | +| `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` | Reload dnsmasq + scrub expired leases (rate-limited: 5s cooldown) | +| `POST` | `/ui/api/reload` | Scrub expired leases + trigger dnsmasq reload (rate-limited: 5s cooldown) | --- @@ -113,23 +125,21 @@ Overridable defaults for custom deployments: |----------|---------| | `LEASE_FILE` | `/opt/zoraxy/conf/dhcp/dnsmasq.leases` | | `CONF_FILE` | `/opt/zoraxy/conf/dhcp/dnsmasq.conf` | -| `RELOAD_CMD` | `/usr/bin/systemctl` | -| `RELOAD_ARGS` | `reload dnsmasq` | --- ## Permissions -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: +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/ -Zoraxy systemd service: - → CapabilityBoundingSet=CAP_SYS_ADMIN - → AmbientCapabilities=CAP_SYS_ADMIN +systemd path unit: dnsmasq-reload.path + → Watches /opt/zoraxy/conf/dhcp/dnsmasq.conf.reload + → On change: systemctl reload dnsmasq (runs as root) ``` --- @@ -140,7 +150,7 @@ Zoraxy systemd service: sudo bash install.sh --remove ``` -Removes dnsmasq, the plugin, config files, group, and NAT rules — leaving the system clean. +Removes dnsmasq, the plugin, config files, group, systemd units, and NAT rules — leaving the system clean. ---