# DHCP Lease Manager

**Zoraxy plugin** — Manage dnsmasq DHCP leases, assign static IPs, and create network-wide hostnames 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 + DNS server with NAT/routing
- dhcp-lease-manager plugin inside Zoraxy
- Group-based permissions for secure config access
- 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/`.

---

## Features

| Feature | Description |
|---------|-------------|
| **View leases** | Active DHCP leases with hostname, IP, MAC, expiry |
| **Pin** | One click — makes a lease permanent with static DHCP + optional DNS name |
| **Edit** | Change the hostname/DNS record on a pinned lease |
| **Unpin** | Remove static DHCP assignment and DNS record |
| **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 |

---

## 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

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
# Before pinning
$ nslookup printer.lan          # → NXDOMAIN

# Click Pin, enter "printer.lan", reload
$ nslookup printer.lan 10.1.0.10  # → 10.1.0.50 ✓
```

Unpinning removes both records. Editing a pinned hostname updates the DNS record.

---

## 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  •  Touches reload trigger   │
└──────┬────────────────────────────────┬──────────┘
       │ read/write                     │ touch .reload
┌──────▼──────────────┐    ┌────────────▼──────────┐
│  /opt/zoraxy/       │    │  systemd path unit      │
│  conf/dhcp/         │    │  dnsmasq-reload.path    │
│  dnsmasq.conf   ────┼────►  watches .reload file  │
│  dnsmasq.leases     │    │  → systemctl reload    │
└─────────────────────┘    └───────────┬───────────┘
       ▲                               │
       │     DNS queries               ▼
       │   "printer.lan?"     ┌──────────────┐
       └──────────────────────┤ dnsmasq       │
                10.1.0.50     │ DHCP / DNS    │
                              └──────────────┘
```

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.

---

## API Endpoints

| Method | Path | Purpose |
|--------|------|---------|
| `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`). 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/reload` | Scrub expired leases + trigger dnsmasq reload (rate-limited: 5s cooldown) |

---

## 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` |

---

## Permissions

The installer creates a `dnsmasq-edit` group for config file access and a systemd path unit for reloads:

```
Group: dnsmasq-edit
  → zoraxy user added
  → Read/write on /opt/zoraxy/conf/dhcp/

systemd path unit: dnsmasq-reload.path
  → Watches /opt/zoraxy/conf/dhcp/dnsmasq.conf.reload
  → On change: systemctl reload dnsmasq (runs as root)
```

---

## Uninstall

```bash
sudo bash install.sh --remove
```

Removes dnsmasq, the plugin, config files, group, systemd units, and NAT rules — 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