docs: add README.md with install guide, remove redundant setup.sh
This commit is contained in:
parent
026c97598b
commit
45ad3a2b9b
2 changed files with 147 additions and 69 deletions
147
README.md
Normal file
147
README.md
Normal file
|
|
@ -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
|
||||||
69
setup.sh
69
setup.sh
|
|
@ -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"
|
|
||||||
Loading…
Reference in a new issue