142 lines
6.4 KiB
Markdown
142 lines
6.4 KiB
Markdown
# wirecon
|
|
|
|
WireGuard **client** tooling for an unprivileged Alpine LXC on Proxmox. Connects the LXC to an existing WireGuard server over a flaky uplink (built for Telekom DSL/LTE Hybrid, where MTU pitfalls cause silent stalls) with:
|
|
|
|
- a Proxmox-host one-liner that creates the LXC from scratch
|
|
- an OpenRC **watchdog** that detects stale handshakes / ping loss and re-dials fast
|
|
- a continuous **monitor** that emits structured logs for post-mortem analysis
|
|
- an **MTU probe** that finds the real path MTU via DF-ping binary search
|
|
- an optional **web UI** (busybox httpd + CGI, dark theme) for status, config editing, and log viewing — switch off anytime to save resources
|
|
|
|
The server side is intentionally out of scope — point the LXC at any existing WireGuard endpoint.
|
|
|
|
## Install
|
|
|
|
Run on the **Proxmox host** as root:
|
|
|
|
```
|
|
curl -fsSL https://git.d4nn13.de/d4nn13/wirecon/raw/branch/main/proxmox/create-lxc.sh | bash
|
|
```
|
|
|
|
That script:
|
|
|
|
1. picks the next free VMID (`pvesh get /cluster/nextid`)
|
|
2. downloads the latest Alpine template if missing
|
|
3. creates an unprivileged LXC (`concad`, 1 core, 256 MiB RAM, 2 GiB disk, DHCP on `vmbr0`, nesting+keyctl features)
|
|
4. appends the `/dev/net/tun` passthrough to `/etc/pve/lxc/<VMID>.conf`
|
|
5. starts the container, waits for DHCP
|
|
6. chains into `lxc/bootstrap.sh` inside the LXC, which clones this repo to `/opt/wirecon` and runs `lxc/install.sh`
|
|
|
|
Override defaults via env vars:
|
|
|
|
```
|
|
HOSTNAME=tunbox MEMORY=512 STORAGE=fast-nvme \
|
|
bash -c "$(curl -fsSL https://git.d4nn13.de/d4nn13/wirecon/raw/branch/main/proxmox/create-lxc.sh)"
|
|
```
|
|
|
|
Available overrides: `HOSTNAME`, `CORES`, `MEMORY`, `DISK`, `BRIDGE`, `STORAGE`, `TEMPLATE_STORAGE`, `WIRECON_REPO`, `WIRECON_REF`, `ROOT_PASSWORD`, `WIRECON_WEB_AUTOSTART` (yes/no).
|
|
|
|
The script also asks (interactively, default **yes**) whether to enable the web UI on boot. Edit configs in-browser right after provisioning instead of `vi`'ing over `pct enter`.
|
|
|
|
### Root login
|
|
|
|
The script prompts for a root password (reads from `/dev/tty`, works under `curl | bash`) and, if one is given, installs `openssh`, flips `PermitRootLogin yes`, and enables `sshd`. You can also preset it:
|
|
|
|
```
|
|
ROOT_PASSWORD='hunter2' bash -c "$(curl -fsSL …/create-lxc.sh)"
|
|
```
|
|
|
|
Leave it empty / skip the prompt and the container has **no root password** — you enter it from the Proxmox host with `pct enter <VMID>`. SSH won't work in that case.
|
|
|
|
## Finishing up (inside the LXC)
|
|
|
|
```
|
|
pct enter <VMID>
|
|
|
|
vi /etc/wireguard/wg0.conf # PrivateKey, Peer PublicKey, Endpoint, MTU, LAN iface in PostUp
|
|
vi /etc/wirecon/wirecon.conf # PEER_IP + watchdog thresholds (optional)
|
|
|
|
rc-update add wg-quick.wg0 default && rc-service wg-quick.wg0 start
|
|
rc-update add wirecon-watchdog default && rc-service wirecon-watchdog start
|
|
rc-update add wirecon-monitor default && rc-service wirecon-monitor start
|
|
rc-update add wirecon-web default && rc-service wirecon-web start # optional
|
|
|
|
tail -F /var/log/wirecon-watchdog.log /var/log/wirecon-monitor.log
|
|
```
|
|
|
|
Then open **`http://<lxc-ip>:8080/`** in a browser.
|
|
|
|
## Layout
|
|
|
|
```
|
|
lxc/
|
|
install.sh idempotent apk + OpenRC installer (runs inside the LXC)
|
|
bootstrap.sh clones repo into /opt/wirecon then calls install.sh
|
|
etc/init.d/ OpenRC services: wirecon-watchdog, wirecon-monitor, wirecon-web
|
|
etc/wirecon/wirecon.conf tunable thresholds (peer IP, handshake age, MTU bounds, WEB_PORT…)
|
|
etc/wirecon/httpd.conf busybox httpd config (HTTP Basic Auth template)
|
|
etc/wireguard/wg0.conf.example
|
|
usr/local/bin/
|
|
wirecon-watchdog.sh one tick: handshake age + in-tunnel ping → reconnect if needed
|
|
wirecon-watchdog-loop.sh supervise-daemon target that re-runs the tick every WATCHDOG_INTERVAL
|
|
wirecon-monitor.sh long-running structured-log emitter
|
|
wirecon-mtu-probe.sh DF-ping binary search → recommended WG MTU
|
|
var/www/wirecon/ web UI assets + CGI scripts (status / config / logs)
|
|
|
|
proxmox/
|
|
create-lxc.sh host-side LXC provisioner (the one-liner above)
|
|
lxc.conf.snippet tun passthrough lines (also appended by create-lxc.sh)
|
|
```
|
|
|
|
## How the watchdog decides to reconnect
|
|
|
|
Every `WATCHDOG_INTERVAL` seconds (default 20 s), one tick runs:
|
|
|
|
1. **Interface check** — `ip link show wg0`; if missing → reconnect immediately.
|
|
2. **Handshake age** — `wg show wg0 latest-handshakes`; if older than `HANDSHAKE_MAX_AGE` (default 180 s), mark failure.
|
|
3. **In-tunnel ping** — `ping -I wg0 -c 3 -W 2 $PEER_IP`; if loss ≥ `PING_LOSS_THRESHOLD`, mark failure.
|
|
4. **Failure streak** — only after `FAIL_STREAK_THRESHOLD` consecutive failed ticks (default 2 = 40 s) does it actually `wg-quick down && up`. This prevents a single LTE hiccup from thrashing the tunnel.
|
|
|
|
Every decision — pass, fail, streak bump, reconnect — is logged as a single `key=value` line with a reason.
|
|
|
|
## Tuning
|
|
|
|
| File | What to tune |
|
|
|---|---|
|
|
| `/etc/wireguard/wg0.conf` | `MTU` (run `wirecon-mtu-probe.sh` first), LAN iface in the `PostUp` iptables MASQ rules |
|
|
| `/etc/wirecon/wirecon.conf` | `PEER_IP`, `HANDSHAKE_MAX_AGE`, `PING_LOSS_THRESHOLD`, `FAIL_STREAK_THRESHOLD`, `WATCHDOG_INTERVAL`, `MONITOR_INTERVAL` |
|
|
|
|
## Logs
|
|
|
|
Both services write `key=value` structured lines; grep and `awk` friendly:
|
|
|
|
```
|
|
tail -F /var/log/wirecon-watchdog.log /var/log/wirecon-monitor.log
|
|
grep event=reconnect /var/log/wirecon-watchdog.log
|
|
awk -F'rtt_ms=' '/rtt_ms=/{split($2,a," "); print $0}' /var/log/wirecon-monitor.log
|
|
```
|
|
|
|
## Web UI
|
|
|
|
Optional. Serves at `http://<lxc-ip>:8080/` — dark theme, three tabs:
|
|
|
|
- **Status** — running/stopped state for each service, live wg0 endpoint + handshake age + rx/tx (auto-refresh every 5s).
|
|
- **Config** — edit `/etc/wireguard/wg0.conf` and `/etc/wirecon/wirecon.conf` in-browser; saving triggers a restart of the affected services and returns their stdout.
|
|
- **Logs** — tail of `wirecon-watchdog.log` and `wirecon-monitor.log`.
|
|
|
|
Runs on **busybox httpd** (~2 MiB RSS) with shell CGI — no Python/Go runtime needed. Disable anytime:
|
|
|
|
```
|
|
rc-service wirecon-web stop
|
|
rc-update del wirecon-web
|
|
```
|
|
|
|
**Security:** the UI edits `wg0.conf` (contains private keys) and restarts services, so expose it on the LAN only. Enable HTTP Basic Auth by adding a line to `/etc/wirecon/httpd.conf`:
|
|
|
|
```
|
|
# generate hash: openssl passwd -1 'your-password'
|
|
/:admin:$1$salt$hash
|
|
```
|
|
|
|
Change `WEB_PORT` / `WEB_BIND` in `/etc/wirecon/wirecon.conf` and restart `wirecon-web` to move it.
|