cclohmar/zoraxy-dhcp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: update README — systemd path unit, Edit action, inline toast, remove CAP_SYS_ADMIN

Browse source
This commit is contained in:
Claus Lohmar 2026-07-29 10:10:42 +00:00
parent 4ef2208418
commit 4e49d27528
1 changed files with 39 additions and 29 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

64
README.md
View file

@ -16,7 +16,7 @@ The installer is fully interactive — it asks for your network settings and the
- dnsmasq DHCP + DNS server with NAT/routing - dnsmasq DHCP + DNS server with NAT/routing
- dhcp-lease-manager plugin inside Zoraxy - dhcp-lease-manager plugin inside Zoraxy
- Group-based permissions for secure config access - 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/`. 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 | | Feature | Description |
|---------|-------------| |---------|-------------|
| **View leases** | Active DHCP leases with hostname, IP, MAC, expiry | | **View leases** | Active DHCP leases with hostname, IP, MAC, expiry |
| **Pin leases** | Make a lease permanent — sets static DHCP and optional DNS name | | **Pin** | One click — makes a lease permanent with static DHCP + optional DNS name |
| **DNS names** | When pinning, give the device a hostname (e.g. `printer.lan`) — resolves network-wide via dnsmasq DNS | | **Edit** | Change the hostname/DNS record on a pinned lease |
| **Unpin leases** | Remove static DHCP assignment and DNS record | | **Unpin** | Remove static DHCP assignment and DNS record |
| **Reload** | Apply changes + scrub expired leases from the lease file | | **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 | | **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 ## 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 ```bash
# Before pinning # Before pinning
$ nslookup printer.lan # → NXDOMAIN $ 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 ✓ $ 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 │ │ dhcp-lease-manager │
│ Go binary • PluginUiRouter • JSON API │ │ 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 │ │ /opt/zoraxy/ │ │ systemd path unit │
│ conf/dhcp/ │ │ DHCP: 10.1.0.100-150 │ │ conf/dhcp/ │ │ dnsmasq-reload.path │
│ dnsmasq.conf ────┼────► DNS: address=/name/ │ │ dnsmasq.conf ────┼────► watches .reload file │
│ dnsmasq.leases │ │ NAT: MASQUERADE │ │ dnsmasq.leases │ │ → systemctl reload │
└─────────────────────┘ └───────────────────────┘ └─────────────────────┘ └───────────┬───────────┘
▲ │ ▲ │
│ DNS queries ▼ │ DNS queries ▼
│ "printer.lan?" ┌──────────────┐ │ "printer.lan?" ┌──────────────┐
└──────────────────────┤ DHCP clients │ └──────────────────────┤ dnsmasq │
10.1.0.50 └──────────────┘ 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 | | Method | Path | Purpose |
|--------|------|---------| |--------|------|---------|
| `GET` | `/ui/api/leases` | List all active + permanent leases | | `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/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` | | `LEASE_FILE` | `/opt/zoraxy/conf/dhcp/dnsmasq.leases` |
| `CONF_FILE` | `/opt/zoraxy/conf/dhcp/dnsmasq.conf` | | `CONF_FILE` | `/opt/zoraxy/conf/dhcp/dnsmasq.conf` |
| `RELOAD_CMD` | `/usr/bin/systemctl` |
| `RELOAD_ARGS` | `reload dnsmasq` |
--- ---
## Permissions ## 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 Group: dnsmasq-edit
→ zoraxy user added → zoraxy user added
→ Read/write on /opt/zoraxy/conf/dhcp/ → Read/write on /opt/zoraxy/conf/dhcp/
Zoraxy systemd service: systemd path unit: dnsmasq-reload.path
→ CapabilityBoundingSet=CAP_SYS_ADMIN → Watches /opt/zoraxy/conf/dhcp/dnsmasq.conf.reload
→ AmbientCapabilities=CAP_SYS_ADMIN → On change: systemctl reload dnsmasq (runs as root)
``` ```
--- ---
@ -140,7 +150,7 @@ Zoraxy systemd service:
sudo bash install.sh --remove 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.
--- ---