103 lines
3.5 KiB
Markdown
103 lines
3.5 KiB
Markdown
# VHost Manager & Reverse Proxy Notes
|
|
|
|
**Version:** 1.0.0
|
|
**Last Updated:** 2025-12-28
|
|
**Status:** Active
|
|
|
|
SecuBox ships `luci-app-vhost-manager` (LuCI dashboard + RPC backend) and now the `scripts/vhostctl.sh` helper so apps, wizards, and profiles can declaratively publish HTTP services behind nginx with optional TLS and HTTP auth.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
1. **Packages**: `luci-app-vhost-manager` installed (installs RPCD script + LuCI UI) and nginx with SSL (`nginx-ssl`).
|
|
2. **Certificates**: ACME via `acme.sh` (auto) or manual PEM files for `tls manual`.
|
|
3. **Apps**: Ensure the upstream service listens on localhost or LAN (e.g., Zigbee2MQTT UI on `http://127.0.0.1:8080`).
|
|
4. **Firewall**: Allow inbound 80/443 on the WAN interface.
|
|
|
|
---
|
|
|
|
## CLI (`scripts/vhostctl.sh`)
|
|
|
|
This helper manipulates `/etc/config/vhosts` and can be invoked by future wizards/App Store installers.
|
|
|
|
```sh
|
|
# List existing mappings
|
|
scripts/vhostctl.sh list
|
|
|
|
# Add HTTPS reverse proxy for Zigbee2MQTT UI
|
|
scripts/vhostctl.sh add \
|
|
--domain zigbee.home.lab \
|
|
--upstream http://127.0.0.1:8080 \
|
|
--tls acme \
|
|
--websocket \
|
|
--enable
|
|
|
|
# Enable/disable or remove later
|
|
scripts/vhostctl.sh disable --domain zigbee.home.lab
|
|
scripts/vhostctl.sh remove --domain zigbee.home.lab
|
|
|
|
# Reload nginx after edits
|
|
scripts/vhostctl.sh reload
|
|
```
|
|
|
|
Options:
|
|
|
|
| Option | Purpose |
|
|
|--------|---------|
|
|
| `--domain` | Public hostname (required). |
|
|
| `--upstream` | Local service URL (`http://127.0.0.1:8080`). |
|
|
| `--tls off|acme|manual` | TLS strategy. Use `manual` + `--cert/--key` for custom certs. |
|
|
| `--auth-user/--auth-pass` | Enable HTTP basic auth. |
|
|
| `--websocket` | Add `Upgrade` headers for WebSocket apps. |
|
|
| `--enable` / `--disable` | Toggle without deleting. |
|
|
|
|
The script is idempotent: running `add` with an existing domain updates the entry.
|
|
|
|
---
|
|
|
|
## LuCI Dashboard
|
|
|
|
Navigate to **Services → SecuBox → VHost Manager** to:
|
|
- View active/disabled vhosts, TLS status, certificate expirations.
|
|
- Edit or delete entries, request ACME certificates, tail access logs.
|
|
- Use the form to create entries (domain, upstream, TLS, auth, WebSocket).
|
|
|
|
The LuCI backend writes to the same `/etc/config/vhosts` file, so changes from `vhostctl.sh` appear immediately.
|
|
|
|
---
|
|
|
|
## Example: Publish Zigbee2MQTT
|
|
|
|
1. Install Zigbee2MQTT (Docker) and confirm the UI listens on port 8080 (see `docs/embedded/zigbee2mqtt-docker.md`).
|
|
2. Map it behind HTTPS:
|
|
```sh
|
|
scripts/vhostctl.sh add \
|
|
--domain zigbee.secubox.local \
|
|
--upstream http://127.0.0.1:8080 \
|
|
--tls acme \
|
|
--websocket
|
|
scripts/vhostctl.sh reload
|
|
```
|
|
3. (Optional) Use LuCI to request certificates and monitor logs.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
| Issue | Fix |
|
|
|-------|-----|
|
|
| `scripts/vhostctl.sh add ...` errors “Unknown option” | Ensure busybox `sh` is used (`/bin/sh`). |
|
|
| ACME cert missing | Confirm `acme.sh` installed, domain resolves to router, 80/443 reachable. |
|
|
| 502/504 errors | Check upstream service, firewall, or change `--upstream` to LAN IP. |
|
|
| TLS manual mode fails | Provide full paths to PEM files and verify permissions. |
|
|
| Changes not visible | Run `scripts/vhostctl.sh reload` or `ubus call luci.vhost-manager reload_nginx`. |
|
|
|
|
---
|
|
|
|
## Automation Notes
|
|
|
|
- Wizards/App Store can shell out to `scripts/vhostctl.sh` to register services as they are installed.
|
|
- Profiles can keep declarative manifests (domain → upstream) and call `vhostctl.sh add/remove` when switching modes.
|
|
- `/etc/config/vhosts` remains the single source of truth, consumed by the LuCI app and the RPC backend.
|