Alpine's base image doesn't create /usr/local/sbin, so the heredoc failed with "can't create /usr/local/sbin/autologin-root: nonexistent directory" on fresh containers. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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:
- 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, 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.
Shell access
No password, no SSH. Access is via the Proxmox Console button or pct enter <VMID> from the host:
tty1is wired togetty -n -l /usr/local/sbin/autologin-root, which execslogin -f root→ you land directly in a root shell with no prompt.- This is safe in practice: anyone who can open the web Console is already a Proxmox admin and could
pct enteranyway.
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:
- 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
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.confand/etc/wirecon/wirecon.confin-browser; saving triggers a restart of the affected services and returns their stdout. - Logs — tail of
wirecon-watchdog.logandwirecon-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.