# 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