docs: update README with DNS name service, systemctl capabilities, architecture diagram
This commit is contained in:
parent
646b708104
commit
1b645ea821
1 changed files with 49 additions and 24 deletions
71
README.md
71
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
|
||||
┌──────▼──────────┐ ┌──────────▼──────────┐
|
||||
│ read/write │ systemctl reload
|
||||
┌──────▼──────────────┐ ┌────────────▼──────────┐
|
||||
│ /opt/zoraxy/ │ │ dnsmasq │
|
||||
│ conf/dhcp/ │ │ systemctl reload │
|
||||
│ dnsmasq.conf │ │ │
|
||||
│ dnsmasq.leases │ └─────────────────────┘
|
||||
└─────────────────┘
|
||||
│ 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.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue