Initial skills documentation — 25 categories, all SKILL.md + references + scripts

2026-07-15 17:42:20 -04:00
commit 1b4fcd4427
976 changed files with 188344 additions and 0 deletions
@@ -0,0 +1,43 @@
+# Telegram IPv6 Timeout on Netcup
+
+On this netcup box, the Hermes gateway (and specifically the Telegram polling adapter) can get stuck trying to connect via IPv6 to `api.telegram.org` (resolves to `2001:67c:4e8:f004::9`). The connection attempt times out, and the gateway appears stuck at "Connecting to Telegram (attempt 1/8)…" indefinitely.
+
+## Symptoms
+
+- Gateway starts and runs, but Telegram never connects
+- `journalctl` shows only: "Discovering Telegram API fallback IPs via DNS-over-HTTPS…" and "Connecting to Telegram (attempt 1/8)…"
+- Gateway zombies accumulate after repeated restarts — a PID is running but no actual TCP connection established
+- `ss -tnp | grep <pid>` shows no ESTABLISHED connections to Telegram's IPs
+- Direct connection test: `timeout 5 bash -c 'echo > /dev/tcp/api.telegram.org/443 && echo "OK"'` fails, but connecting via IPv4 IP (149.154.166.110:443) succeeds
+
+## Root Cause
+
+The netcup server prefers IPv6 DNS resolution (AAAA record) over IPv4 (A record). Telegram's IPv6 endpoint at `2001:67c:4e8:f004::9` is unreachable from this provider, likely due to netcup's IPv6 routing or firewall on the KVM hypervisor.
+
+The Hermes Telegram adapter has an internal "fallback IP discovery via DNS-over-HTTPS" mechanism, but the timeout on the initial IPv6 connection exceeds the gateway's connection budget.
+
+## Fix
+
+Disable IPv6 system-wide on the netcup box:
+```bash
+sysctl -w net.ipv6.conf.all.disable_ipv6=1
+sysctl -w net.ipv6.conf.default.disable_ipv6=1
+```
+
+To make permanent:
+```bash
+cat >> /etc/sysctl.d/99-disable-ipv6.conf << 'EOF'
+net.ipv6.conf.all.disable_ipv6 = 1
+net.ipv6.conf.default.disable_ipv6 = 1
+EOF
+```
+
+## After Fix
+
+1. Restart the profile's gateway
+2. Confirm clean connection via `ss -tnp | grep <pid>` — should show `ESTABLISHED` connections to `149.154.166.110:443`
+3. `journalctl` should no longer show connection retries
+
+## Profiles Affected
+
+This affects ANY profile gateway trying to reach Telegram from this netcup box. The `default` profile's gateway was originally started before this was noticed; Anita's profile was the one that exposed it during the migration because her gateway was started fresh.