Document network operations and WireGuard maintenance

2026-08-06 10:20:43 +08:00
parent 64484cd484
commit 29bdf06383
14 changed files with 678 additions and 4 deletions
@@ -0,0 +1,61 @@
+# us4.wsvc.info
+
+| Item | Value |
+|------|-------|
+| Role | WireGuard VPN server (LinuxServer Docker image) |
+| SSH | `ssh -4 windy@us4.wsvc.info` (prefer IPv4 from WSL) |
+| IPv4 | `185.201.226.122` |
+| Compose project | `/opt/wireguard` |
+| Compose file | `/opt/wireguard/compose.yml` |
+| Container | `wireguard` |
+| Image policy | Immutable digest, updated only in an approved maintenance window |
+| Public port | UDP `51820` on IPv4 and IPv6 |
+| Tunnel subnet | `10.13.13.0/24` |
+| Routing policy | IPv4-only full tunnel (`ALLOWEDIPS=0.0.0.0/0`); IPv6 traffic is not guaranteed to use the VPN |
+
+## Safety
+
+- Private keys, preshared keys, peer configuration files, and QR codes remain
+  only in `/opt/wireguard/config`; do not copy them to this repository or
+  Linear.
+- Local rollback archives are stored in `/opt/wireguard/backups` (directory
+  mode `0700`, archives mode `0600`). They contain private keys, are not an
+  off-host disaster-recovery backup, and must never leave the server.
+- Do not delete, move, or regenerate `/opt/wireguard/config` during
+  maintenance.
+- Before a container recreation, validate `docker compose config` and retain a
+  verified SSH session for rollback. Do not run `docker compose down -v`.
+
+## Routine operations
+
+Run read-only checks through Ansible:
+
+```bash
+cd ansible
+ansible-playbook playbooks/health-report.yml --limit wireguard
+```
+
+The image update and recreate procedure is deliberately separate and requires
+an immutable image digest in the server-side Compose file plus an explicit
+maintenance-window confirmation:
+
+```bash
+cd ansible
+ansible-playbook playbooks/wireguard-maintenance.yml --limit wireguard \
+  -e '{"wireguard_maintenance_confirm": true}'
+```
+
+Before that recreate, apply the reviewed Compose hardening from the repository:
+
+```bash
+ansible-playbook playbooks/wireguard-harden.yml --limit wireguard \
+  -e '{"wireguard_harden_confirm": true}'
+```
+
+## Verification
+
+- Container `wireguard` is running and interface `wg0` exists.
+- UDP `51820` is listening on the host.
+- Validate a known client can handshake and sends IPv4 traffic through the VPN.
+- Do not treat inactive mobile peers as a failure solely because their latest
+  handshake is old.