From 45ad3a2b9b48f37ac8834b6a1be634c1a8167c5e Mon Sep 17 00:00:00 2001 From: cclohmar Date: Fri, 24 Jul 2026 11:36:56 +0000 Subject: [PATCH] docs: add README.md with install guide, remove redundant setup.sh --- README.md | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ setup.sh | 69 ------------------------- 2 files changed, 147 insertions(+), 69 deletions(-) create mode 100644 README.md delete mode 100755 setup.sh diff --git a/README.md b/README.md new file mode 100644 index 0000000..2faecf5 --- /dev/null +++ b/README.md @@ -0,0 +1,147 @@ +# DHCP Lease Manager + +**Zoraxy plugin** — View, pin, and unpin dnsmasq DHCP leases from the Zoraxy web UI. + +--- + +## Quick Install + +```bash +curl -sSL https://git.lohmar.co.uk/cclohmar/zoraxy-dhcp/raw/branch/main/install.sh | sudo bash +``` + +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 +- dhcp-lease-manager plugin inside Zoraxy +- Group-based permissions for secure management +- Sudoers rule for dnsmasq reloads + +After installation, open Zoraxy → Plugins → enable **DHCP Lease Manager** → access at `/plugin.ui/dhcp-lease-manager/`. + +--- + +## Features + +| 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) | +| **Status badges** | Green "permanent" / grey "active" indicators | + +--- + +## Requirements + +| Component | Detail | +|-----------|--------| +| **Zoraxy** | v3.2.0+ (plugin system required) | +| **OS** | Debian, Ubuntu, RHEL, Fedora, Alpine, Arch | +| **dnsmasq** | Installed by the script | +| **Go** | Installed by the script (for building the plugin) | +| **Permissions** | Script must run as root | + +--- + +## Architecture + +``` +┌──────────────────────────────────────────────────┐ +│ Zoraxy UI │ +│ /plugin.ui/dhcp-lease-manager/ ─────► iframe │ +└───────────────────────┬──────────────────────────┘ + │ reverse proxy +┌───────────────────────▼──────────────────────────┐ +│ 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 │ └─────────────────────┘ +└─────────────────┘ +``` + +All DHCP configuration lives under `/opt/zoraxy/conf/dhcp/` — a single, unified location regardless of whether Zoraxy runs bare-metal or in Docker. + +--- + +## API Endpoints + +| 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` | + +--- + +## Environment Variables + +Overridable defaults for custom deployments: + +| Variable | Default | +|----------|---------| +| `LEASE_FILE` | `/opt/zoraxy/conf/dhcp/dnsmasq.leases` | +| `CONF_FILE` | `/opt/zoraxy/conf/dhcp/dnsmasq.conf` | +| `RELOAD_CMD` | `sudo` | +| `RELOAD_ARGS` | `systemctl reload dnsmasq` | + +--- + +## Permissions + +The installer creates a `dnsmasq-edit` group with access to the DHCP config files and a sudoers rule for reloading dnsmasq: + +``` +Group: dnsmasq-edit + → zoraxy user added + → Read/write on /opt/zoraxy/conf/dhcp/ + → Passwordless sudo for systemctl reload dnsmasq +``` + +--- + +## Uninstall + +```bash +sudo bash install.sh --remove +``` + +Removes dnsmasq, the plugin, config files, NAT rules, and the sudoers rule — leaving the system clean. + +--- + +## Manual Install + +```bash +# 1. Clone the repo +git clone https://git.lohmar.co.uk/cclohmar/zoraxy-dhcp.git /opt/zoraxy/plugins/dhcp-lease-manager + +# 2. Build +cd /opt/zoraxy/plugins/dhcp-lease-manager +go build -buildvcs=false -o dhcp-lease-manager . + +# 3. Run setup (as root) +sudo bash install.sh +``` + +--- + +## License + +Zoraxy plugin SDK is LGPL. This plugin is open source. + +--- + +## Credits + +- [Zoraxy](https://github.com/tobychui/zoraxy) — Reverse proxy and plugin system +- [dnsmasq](https://thekelleys.org.uk/dnsmasq/doc.html) — DNS/DHCP server diff --git a/setup.sh b/setup.sh deleted file mode 100755 index be0fb05..0000000 --- a/setup.sh +++ /dev/null @@ -1,69 +0,0 @@ -#!/usr/bin/env bash -# Setup script for dhcp-lease-manager Zoraxy plugin -# Run as root to configure group permissions for dnsmasq management. - -set -euo pipefail - -ZORAXY_USER="${ZORAXY_USER:-zoraxy}" -GROUP="dnsmasq-edit" -CONF_FILE="/etc/dnsmasq.conf" -LEASES_FILE="/var/lib/misc/dnsmasq.leases" -SUDOERS_FILE="/etc/sudoers.d/dnsmasq-edit" - -echo "=== DHCP Lease Manager — Permission Setup ===" -echo "" - -# 1. Create group if it doesn't exist -if ! getent group "$GROUP" >/dev/null 2>&1; then - echo "[+] Creating group: $GROUP" - groupadd "$GROUP" -else - echo "[i] Group '$GROUP' already exists" -fi - -# 2. Add zoraxy user to group -if ! groups "$ZORAXY_USER" 2>/dev/null | grep -qw "$GROUP"; then - echo "[+] Adding user '$ZORAXY_USER' to group '$GROUP'" - usermod -a -G "$GROUP" "$ZORAXY_USER" -else - echo "[i] User '$ZORAXY_USER' already in group '$GROUP'" -fi - -# 3. Set group ownership and permissions on dnsmasq.conf -if [ -f "$CONF_FILE" ]; then - echo "[+] Setting group ownership on $CONF_FILE" - chgrp "$GROUP" "$CONF_FILE" - chmod g+w "$CONF_FILE" -else - echo "[!] WARNING: $CONF_FILE not found" -fi - -# 4. Set group read permissions on leases file -if [ -f "$LEASES_FILE" ]; then - echo "[+] Setting group ownership on $LEASES_FILE" - chgrp "$GROUP" "$LEASES_FILE" - chmod g+r "$LEASES_FILE" -else - echo "[!] WARNING: $LEASES_FILE not found" -fi - -# 5. Add sudoers entry for dnsmasq reload -if [ ! -f "$SUDOERS_FILE" ]; then - echo "[+] Creating sudoers rule: $SUDOERS_FILE" - cat > "$SUDOERS_FILE" <<'EOF' -# Allow dnsmasq-edit group to reload dnsmasq without a password -%dnsmasq-edit ALL=(root) NOPASSWD: /usr/bin/systemctl reload dnsmasq -EOF - chmod 0440 "$SUDOERS_FILE" -else - echo "[i] Sudoers file '$SUDOERS_FILE' already exists" -fi - -echo "" -echo "=== Setup complete! ===" -echo "" -echo "Next steps:" -echo " 1. Verify Zoraxy discovers the plugin (restart Zoraxy if needed)" -echo " 2. Enable the plugin from Zoraxy's plugin manager" -echo " 3. Access UI at /plugin.ui/dhcp-lease-manager/" -echo " 4. Note: The zoraxy user must log out/in for group membership to take effect"