The server side is out of scope — this repo now ships only the Alpine LXC tooling (installer, OpenRC watchdog/monitor, MTU probe) and the Proxmox-host creator. Rewrite the README around that focus.
4.3 KiB
4.3 KiB
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
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:
- picks the next free VMID (
pvesh get /cluster/nextid) - downloads the latest Alpine template if missing
- creates an unprivileged LXC (
concad, 1 core, 256 MiB RAM, 2 GiB disk, DHCP onvmbr0, nesting+keyctl features) - appends the
/dev/net/tunpassthrough to/etc/pve/lxc/<VMID>.conf - starts the container, waits for DHCP
- chains into
lxc/bootstrap.shinside the LXC, which clones this repo to/opt/wireconand runslxc/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.
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
tail -F /var/log/wirecon-watchdog.log /var/log/wirecon-monitor.log
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
etc/wirecon/wirecon.conf tunable thresholds (peer IP, handshake age, MTU bounds…)
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
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:
- Interface check —
ip link show wg0; if missing → reconnect immediately. - Handshake age —
wg show wg0 latest-handshakes; if older thanHANDSHAKE_MAX_AGE(default 180 s), mark failure. - In-tunnel ping —
ping -I wg0 -c 3 -W 2 $PEER_IP; if loss ≥PING_LOSS_THRESHOLD, mark failure. - Failure streak — only after
FAIL_STREAK_THRESHOLDconsecutive failed ticks (default 2 = 40 s) does it actuallywg-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