From b55754ee49b61c67cbabcbd79d08df77bfe8c937 Mon Sep 17 00:00:00 2001
From: tim <tim@stack.local>
Date: Wed, 22 Jul 2026 11:15:35 -0700
Subject: [PATCH] Document gluetun unhealthy caused by stale WireGuard endpoint
 IP

Note re-resolving provider endpoints and PersistentKeepalive when the
tunnel sets up but healthchecks fail with DNS i/o timeouts.
---
 quickstart.md              | 3 ++-
 wireguard/wg0.conf.example | 5 +++++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/quickstart.md b/quickstart.md
index a3dcd71..23b8947 100644
--- a/quickstart.md
+++ b/quickstart.md
@@ -80,7 +80,8 @@ Images are from **GHCR** (`ghcr.io/all-hands-ai/...`); the old `docker.all-hands
 ### Manual config (once)
 
 **qBittorrent** — temp password in `docker logs qbittorrent`; user `admin`.  
-Advanced → Network interface: `tun0`.
+Advanced → Network interface: `tun0`.  
+Depends on **gluetun** healthy. If gluetun is unhealthy with `lookup … i/o timeout`, WireGuard is not passing traffic — usually a **stale Endpoint IP** in `wireguard/wg0.conf`. Re-resolve the provider hostname (`dig +short …`), update `Endpoint`, add `PersistentKeepalive = 25`, then `docker compose up -d gluetun --force-recreate`.
 
 Default save path + categories (WebUI):
 
diff --git a/wireguard/wg0.conf.example b/wireguard/wg0.conf.example
index dbaab99..8c1dafb 100644
--- a/wireguard/wg0.conf.example
+++ b/wireguard/wg0.conf.example
@@ -23,5 +23,10 @@
 #    something like `Endpoint = se3.vpn.example.org:51820`, resolve it first:
 #      dig +short se3.vpn.example.org
 #    and paste the IP back into the file.
+#    Re-check if gluetun goes unhealthy with "i/o timeout" — provider DNS
+#    may have moved to a new IP (common with multi-A hostnames).
+#
+# 3. Optional but recommended behind NAT:
+#      PersistentKeepalive = 25
 #
 # Keep AllowedIPs = 0.0.0.0/0 as-is; gluetun handles the routing itself.