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
@@ -28,6 +28,7 @@ Also readable as `agent.md` (symlink → this file).
 | **us2.wsvc.info** | Vaultwarden + Traefik (+ Soft Serve, …) | `ssh -4 windy@us2.wsvc.info` | [hosts/us2.wsvc.info.md](hosts/us2.wsvc.info.md) |
 | **hk2.chans.xyz** | PowerDNS auth ns1 (`/opt/pdns`) | `ssh -4 windy@hk2.chans.xyz` | [hosts/hk2.chans.xyz.md](hosts/hk2.chans.xyz.md) |
 | **gfw.windy.lan** | OpenWrt LAN gateway / OpenClash | `ssh -4 root@192.168.66.1` | [hosts/gfw.windy.lan.md](hosts/gfw.windy.lan.md) |
 | **gw** | EdgeRouter X primary LAN gateway | `ssh -4 zhiqiang@192.168.66.254` | [hosts/gw.md](hosts/gw.md) |
 | **ubnt** | UniFi Network Controller | `ssh -4 windy@192.168.66.46` | [hosts/ubnt.md](hosts/ubnt.md) |
 ### Public services
@@ -45,6 +45,17 @@ all:
            backup:
              compose_args: [--no-deps, --force-recreate]
          service_reconcile_traefik_restart_targets: [poweradmin]
        us4:
          ansible_host: us4.wsvc.info
          ansible_host_ipv4: 185.201.226.122
          service_role: wireguard
          compose_project_dir: /opt/wireguard
          healthcheck_profile: wireguard
          wireguard_image: >-
            lscr.io/linuxserver/wireguard@sha256:ac43e1226878d2611315172d6ea357a95cb326ee73124b91108118efc8666889
          service_reconcile_services:
            wireguard:
              compose_args: [--no-deps, --force-recreate]
    mailcow:
      hosts:
        mx2:
@@ -54,11 +65,15 @@ all:
    powerdns:
      hosts:
        hk2:
    wireguard:
      hosts:
        us4:
    docker_hosts:
      children:
        mailcow:
        vaultwarden:
        powerdns:
        wireguard:
    # Matrix is a dedicated K3s node and intentionally remains outside the
    # Docker-oriented managed group.
    k3s_servers:
@@ -0,0 +1,62 @@
 ---
 # This owns the non-secret Compose declaration only. WireGuard key material
 # remains under the server-local /opt/wireguard/config bind mount.
 - name: Apply the reviewed WireGuard Compose hardening
  hosts: wireguard
  become: true
  gather_facts: false
  serial: 1
  vars:
    wireguard_harden_confirm: false
    wireguard_compose_candidate: "{{ compose_project_dir }}/compose.yml.candidate"
  tasks:
    - name: Require explicit WireGuard hardening confirmation
      ansible.builtin.assert:
        that:
          - wireguard_harden_confirm | bool
        fail_msg: >-
          This operation replaces the non-secret Compose declaration. Run only
          during the approved maintenance window after a rollback archive exists.
    - name: Verify that a protected pre-change archive exists
      ansible.builtin.find:
        paths: "{{ compose_project_dir }}/backups"
        patterns: 'pre-hardening-*.tar.gz'
        file_type: file
      register: wireguard_pre_hardening_archives
    - name: Require a pre-change rollback archive
      ansible.builtin.assert:
        that:
          - wireguard_pre_hardening_archives.matched | int > 0
        fail_msg: >-
          Create a protected pre-hardening archive before replacing compose.yml.
    - name: Render the candidate non-secret Compose declaration
      ansible.builtin.template:
        src: ../templates/wireguard-compose.yml.j2
        dest: "{{ wireguard_compose_candidate }}"
        owner: root
        group: root
        mode: "0644"
    - name: Validate the candidate Compose declaration
      ansible.builtin.command:
        argv:
          - docker
          - compose
          - --project-directory
          - "{{ compose_project_dir }}"
          - --file
          - "{{ wireguard_compose_candidate }}"
          - config
          - --quiet
      changed_when: false
    - name: Atomically activate the validated Compose declaration
      ansible.builtin.command:
        argv:
          - mv
          - "{{ wireguard_compose_candidate }}"
          - "{{ compose_project_dir }}/compose.yml"
      changed_when: true
@@ -0,0 +1,114 @@
 ---
 # Deliberately narrow maintenance path for the us4 WireGuard service. The
 # Compose file and all private key material remain on the server; this playbook
 # only pulls its declared immutable image and recreates the named service.
 - name: Update and recreate the approved WireGuard service
  hosts: wireguard
  become: true
  gather_facts: false
  serial: 1
  vars:
    wireguard_maintenance_confirm: false
  tasks:
    - name: Require explicit WireGuard maintenance confirmation
      ansible.builtin.assert:
        that:
          - wireguard_maintenance_confirm | bool
        fail_msg: >-
          This operation pulls the image declared in /opt/wireguard/compose.yml
          and briefly recreates WireGuard. Set wireguard_maintenance_confirm=true
          only during the approved maintenance window.
    - name: Create the local WireGuard rollback directory
      ansible.builtin.file:
        path: "{{ compose_project_dir }}/backups"
        state: directory
        owner: root
        group: root
        mode: "0700"
    - name: Create a timestamp for the rollback archive
      ansible.builtin.command:
        argv: [date, +%Y%m%dT%H%M%SZ]
      changed_when: false
      register: wireguard_backup_timestamp
    - name: Create a protected local rollback archive of WireGuard configuration
      ansible.builtin.shell:
        cmd: >-
          umask 077 && tar --create --gzip
          --file={{ compose_project_dir }}/backups/config-{{ wireguard_backup_timestamp.stdout }}.tar.gz
          --directory={{ compose_project_dir }} config
        executable: /bin/bash
      changed_when: true
    - name: Verify the compose declaration uses an immutable image digest
      ansible.builtin.command:
        argv:
          - docker
          - compose
          - --project-directory
          - "{{ compose_project_dir }}"
          - config
      changed_when: false
      register: wireguard_compose_config
    - name: Reject mutable WireGuard image declarations
      ansible.builtin.assert:
        that:
          - "'@sha256:' in wireguard_compose_config.stdout"
        fail_msg: >-
          Pin the WireGuard image to an approved immutable digest before using
          this maintenance playbook.
    - name: Pull the declared WireGuard image
      ansible.builtin.command:
        argv:
          - docker
          - compose
          - --project-directory
          - "{{ compose_project_dir }}"
          - pull
          - wireguard
      changed_when: true
    - name: Recreate the WireGuard container
      ansible.builtin.command:
        argv:
          - docker
          - compose
          - --project-directory
          - "{{ compose_project_dir }}"
          - up
          - -d
          - --no-deps
          - --force-recreate
          - wireguard
      changed_when: true
    - name: Verify WireGuard container state
      ansible.builtin.command:
        argv:
          - docker
          - compose
          - --project-directory
          - "{{ compose_project_dir }}"
          - ps
          - --all
      changed_when: false
      register: wireguard_compose_ps
    - name: Display WireGuard container state
      ansible.builtin.debug:
        var: wireguard_compose_ps.stdout_lines
    - name: Run the deployed WireGuard health check
      ansible.builtin.command:
        argv: [/usr/local/lib/vps-health/run]
      changed_when: false
      register: wireguard_health_report
      failed_when: wireguard_health_report.rc not in [0, 1]
    - name: Display sanitized WireGuard health result
      ansible.builtin.debug:
        msg: "{{ wireguard_health_report.stdout | default(wireguard_health_report.stderr, true) }}"
@@ -11,3 +11,4 @@ healthcheck_profiles:
  mailcow: mailcow.sh
  vaultwarden: vaultwarden.sh
  pdns: pdns.sh
  wireguard: wireguard.sh
@@ -1,3 +1,4 @@
 #!/usr/bin/env bash
-set -uo pipefail
+set -o pipefail
-exec '{{ healthcheck_install_root }}/{{ healthcheck_profiles[healthcheck_profile] }}' >> '{{ healthcheck_log_dir }}/healthcheck.log' 2>&1
+'{{ healthcheck_install_root }}/{{ healthcheck_profiles[healthcheck_profile] }}' 2>&1 | tee -a '{{ healthcheck_log_dir }}/healthcheck.log'
 exit "${PIPESTATUS[0]}"
@@ -0,0 +1,35 @@
 #!/usr/bin/env bash
 set -uo pipefail
 source '{{ healthcheck_install_root }}/health-common.sh'
 require_command docker
 require_command ss
 check_compose
 container='wireguard'
 if ! docker inspect "$container" >/dev/null 2>&1; then
  record critical 'wireguard_container_missing'
 else
  running="$(docker inspect "$container" --format '{{ '{{' }}.State.Running{{ '}}' }}' 2>/dev/null)"
  [[ "$running" == true ]] || record critical 'wireguard_container_not_running'
  interface="$(docker exec "$container" wg show interfaces 2>/dev/null || true)"
  grep -qw 'wg0' <<<"$interface" || record critical 'wireguard_wg0_missing'
  configured_peer_count="$(docker exec "$container" sh -c 'find /config -mindepth 1 -maxdepth 1 -type d -name "peer_*" | wc -l' 2>/dev/null || true)"
  runtime_peer_count="$(docker exec "$container" wg show wg0 dump 2>/dev/null | awk 'NR > 1 { count++ } END { print count + 0 }')"
  [[ "$configured_peer_count" =~ ^[0-9]+$ ]] || record unknown 'wireguard_configured_peer_count_unknown'
  [[ "$runtime_peer_count" =~ ^[0-9]+$ ]] || record unknown 'wireguard_runtime_peer_count_unknown'
  if [[ "$configured_peer_count" =~ ^[0-9]+$ && "$runtime_peer_count" =~ ^[0-9]+$ ]]; then
    [[ "$configured_peer_count" -eq "$runtime_peer_count" ]] || record warning "wireguard_peer_count_mismatch_${configured_peer_count}_${runtime_peer_count}"
  fi
 fi
 if ss -H -uln 2>/dev/null | awk '{print $4}' | grep -Eq '(^|:)51820$'; then
  record ok 'wireguard_udp_51820_listening'
 else
  record critical 'wireguard_udp_51820_missing'
 fi
 emit_result
 exit "$EXIT_CODE"
@@ -0,0 +1,24 @@
 services:
  wireguard:
    image: {{ wireguard_image }}
    container_name: wireguard
    cap_add:
      - NET_ADMIN
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
      - SERVERURL=us4.wsvc.info
      - SERVERPORT=51820
      - PEERS=ha,phone,mbp
      - PEERDNS=1.1.1.1
      # Intentional: client IPv6 traffic is not tunneled.
      - ALLOWEDIPS=0.0.0.0/0
    ports:
      - 51820:51820/udp
    volumes:
      - ./config:/config
    read_only: true
    tmpfs:
      - /run:exec
    restart: unless-stopped
@@ -0,0 +1,120 @@
 # EdgeRouter X configuration record
 This is a read-only, sanitized configuration record for
 [gw](../hosts/gw.md), taken on 2026-08-05. It intentionally excludes PPPoE
 credentials, user/password configuration, key material, and full DHCP client
 or reservation inventories.
 ## Platform and topology
 | Item | Current configuration |
 |---|---|
 | Appliance / OS | EdgeRouter X 5-Port; EdgeOS `v3.0.1` build `5862409` |
 | WAN physical interface | `eth4`, described as `Internet (PPPoE)` |
 | WAN routed interface | `pppoe0`; dynamic IPv4 default route; MTU `1492` |
 | LAN66 | `eth0`, `192.168.66.254/24` |
 | LAN55 | `switch0`, `192.168.55.254/24`; member ports `eth1`–`eth3` |
 | IPv4 routing | Both LAN prefixes are directly connected; default route is through `pppoe0` |
 Despite its name, LAN55 is not currently an 802.1Q VLAN configuration:
 `switch0` has `vlan-aware` disabled. It is a separate Layer-3 subnet carried
 by the built-in switch ports, while LAN66 is connected through `eth0`.
 ## IPv6
 The PPPoE uplink requests a delegated `/60`, enables rapid commit and assigns
 SLAAC-capable `/64` networks to the LANs:
 | Interface | Delegated prefix slot | Router address suffix |
 |---|---|---|
 | `eth0` (LAN66) | `:1` | `::1` |
 | `switch0` (LAN55) | `:2` | `::1` |
 IPv6 has a default route through `pppoe0`. The currently delegated prefixes
 are dynamic and are deliberately not treated as persistent configuration
 facts.
 ## Effective firewall policy
 | Ruleset | Direction / attachment | Effective policy |
 |---|---|---|
 | `WAN_IN` | `pppoe0`, IPv4 `in` | Active; default drop; permits established/related, drops invalid |
 | `WAN_LOCAL` | `pppoe0`, IPv4 `local` | Active; default drop; permits established/related, drops invalid |
 | `WANv6_IN` | `pppoe0`, IPv6 `in` | Active; default drop; permits established/related and ICMPv6; drops invalid |
 | `WANv6_LOCAL` | `pppoe0`, IPv6 `local` | Active; default drop; permits established/related, ICMPv6, and DHCPv6 replies; drops invalid |
 | `LAN_IN` | None | Inactive; configured default drop with explicit LAN55 ↔ LAN66 allows |
 | `LAN_OUT` | None | Inactive; configured default drop with an Internet allow |
 Therefore, LAN55 and LAN66 currently have ordinary bidirectional routed
 access. The configured `LAN_IN`/`LAN_OUT` rules do **not** enforce an access
 boundary because neither is bound to an interface. From source
 `192.168.55.254`, the controller at `192.168.66.46` replied to 3/3 ICMP probes
 on 2026-08-05. The online LAN55 AP also confirms the operational Inform path
 to `192.168.66.46:9080`.
 Global firewall settings enable normal ICMP echo replies, disable broadcast
 ping and IPv4/IPv6 source routing, enable SYN cookies and martian logging, set
 an MSS clamp of `1412`, and leave source validation disabled. Receive redirects
 are disabled; IPv4 send redirects remain enabled.
 The [official EdgeOS User Guide](https://dl.ubnt.com/guides/edgemax/EdgeOS_UG.pdf)
 describes the distinction: a firewall policy is a ruleset that must be applied
 to its target interface and direction before it affects traffic.
 ## NAT and inbound exposure
 IPv4 traffic leaving `pppoe0` is covered by NAT masquerade rule `5010`.
 Port-forward auto-firewall and hairpin NAT are enabled. The configured WAN
 forwards are below; their external reachability was not tested in this review.
 | WAN protocol / port | Internal destination | Purpose |
 |---|---|---|
 | TCP/UDP `8123` | `192.168.55.11:8123` | Home Assistant |
 | TCP/UDP `51413` | `192.168.66.51:51413` | Transmission |
 | TCP/UDP `5822` | `192.168.66.36:22` | SSH forward |
 | TCP/UDP `1194` | `192.168.66.32:1194` | OpenVPN |
 Treat every forward as an intentional public attack surface. Changes require
 the normal firewall/change review and external verification from a trusted
 network.
 ## LAN services
 | Service | LAN66 | LAN55 |
 |---|---|---|
 | DHCP pool | `.38`–`.243` | `.38`–`.243` |
 | Default gateway | `.254` | `.254` |
 | DNS server handed out | `192.168.66.36` | `192.168.66.36` |
 | Lease duration | 24 hours | 24 hours |
 | UniFi Controller DHCP option | `192.168.66.46` | `192.168.66.46` |
 DNS forwarding listens on `eth0` and `switch0` with a cache size of `512`.
 Management services are SSH/TCP `22`, HTTP/TCP `80`, and HTTPS/TCP `443`.
 Since no active LAN-local firewall is documented, treat access to this gateway
 management plane from either LAN as permitted unless verified otherwise.
 Infrastructure devices, including the two APs and the UniFi controller, have
 DHCP static mappings. Keep the authoritative full mapping list only in the
 gateway configuration; do not copy unrelated household device inventories into
 this operations repository.
 ## Acceleration and maintenance implications
 At verification time, `show ubnt offload` reported that both IPSec and HWNAT
 offload modules were not loaded. No `system offload` enablement was present in
 the inspected configuration. This may constrain routing/NAT throughput under
 load; it is an observation, not authorization to alter the router.
 Use these safe effective-state checks after any planned change:
 ```bash
 show interfaces
 show ip route
 show ipv6 route
 show firewall
 show nat rules
 show ubnt offload
 ```
 Avoid recording raw `show configuration commands` output: it includes PPPoE
 credentials and may include other secrets.
@@ -0,0 +1,129 @@
 # UniFi network configuration
 ## Controller
 | Item | Value |
 |---|---|
 | Host | [ubnt](../hosts/ubnt.md) |
 | Address | `192.168.66.46` |
 | Deployment | Docker, `jacobalberty/unifi:v9.5.21`, host networking |
 | Inform endpoint | `http://192.168.66.46:9080/inform` |
 | MongoDB database / port | `ace` / `27117` |
 Although `8080` is a common UniFi inform port, this controller uses `9080`.
 All AP adoption and recovery procedures must use the endpoint above.
 ## Inter-VLAN reachability
 The AP management networks are routed by [gw](../hosts/gw.md),
 `192.168.66.254`. On 2026-08-05, a probe sourced from the LAN55 gateway
 (`192.168.55.254`) reached the controller (`192.168.66.46`) with 3/3 ICMP
 replies. The UAP-AC-Lite is online through the `:9080/inform` endpoint, which
 also confirms the required application path in practice.
 `LAN_IN` contains explicit allow rules for `192.168.55.0/24 ↔
 192.168.66.0/24`, but the firewall set is currently inactive (not attached to
 an interface). Treat the networks as bidirectionally reachable by default;
 do not rely on those inactive rules as an access boundary. Recheck this after
 attaching any LAN firewall policy or changing VLAN routing.
 To inspect device records from the controller host:
 ```bash
 docker exec -it unifi-controller bash
 mongo --port 27117
 ```
 ```javascript
 use ace
 db.device.find(
  { type: "uap" },
  { name: 1, ip: 1, model: 1, inform_url: 1 }
 ).pretty()
 ```
 ## Managed access points
 | Name | Model | Management IP | Firmware | Management network | Inform port |
 |---|---|---|---|---|---|
 | U6 Lite | U6 Lite (`UAL6`) | `192.168.66.6` | `6.7.54.15663` | LAN66 (`192.168.66.0/24`, gateway `192.168.66.254`) | `9080` |
 | UAP-AC-Lite | `U7LT` | `192.168.55.5` | `6.8.2.15592` | LAN55 (`192.168.55.0/24`, gateway `192.168.55.254`) | `9080` |
 AP MAC addresses are recorded only where operationally needed: U6 Lite
 `78:45:58:4d:cc:30`; UAP-AC-Lite `f0:9f:c2:20:04:e9`.
 ## SSH administration
 Adopted APs use the SSH account configured in the controller, rather than the
 factory `ubnt/ubnt` credential. The password is stored in the password manager
 and must not be added to this repository.
 In UniFi Network `9.5.21`, configure it at:
 ```text
 Devices → Device Updates and Settings → Device SSH Settings
 → Device SSH Authentication
 ```
 Use `ssh zhiqiangf@AP_IP` for the adopted-device account. Do not query or copy
 the controller's `mgmt` database setting into logs or documentation: it can
 contain the managed SSH password.
 On 2026-08-06, key-only IPv4 SSH was verified for both managed APs using the
 `zhiqiangf` account. Verify future access without permitting password or
 keyboard-interactive fallback:
 ```bash
 ssh -4 -o BatchMode=yes -o PasswordAuthentication=no \
  -o KbdInteractiveAuthentication=no -o StrictHostKeyChecking=yes \
  zhiqiangf@192.168.66.6 'mca-cli-op info'
 ssh -4 -o BatchMode=yes -o PasswordAuthentication=no \
  -o KbdInteractiveAuthentication=no -o StrictHostKeyChecking=yes \
  zhiqiangf@192.168.55.5 'mca-cli-op info'
 ```
 Both devices reported `Connected` to
 `http://192.168.66.46:9080/inform` during that verification. The AP shell maps
 this management account to UID 0, so treat it as administrative access.
 ## Offline AP recovery
 An AP can be reachable via ICMP and SSH but offline in the controller when its
 saved inform URL still points to port `8080`. This occurred for UAP-AC-Lite
 after its inform configuration had diverged from the controller endpoint.
 From the AP, inspect the active endpoint and test controller reachability:
 ```bash
 info
 nc 192.168.66.46 9080
 ```
 The AP's BusyBox `nc` may not support `-zv`; use the plain `nc` invocation
 above when testing the TCP path.
 If `info` reports `http://192.168.66.46:8080/inform` (or another obsolete
 endpoint), correct it. UniFi devices commonly require the command twice while
 adoption is completed:
 ```bash
 set-inform http://192.168.66.46:9080/inform
 set-inform http://192.168.66.46:9080/inform
 ```
 Verify that the AP changes to connected/online in the controller.
 ## Controller migration check
 After a controller migration or restore, inspect stored device records for a
 stale default-port endpoint before treating an AP as faulty:
 ```javascript
 use ace
 db.device.find(
  { inform_url: /8080/ },
  { name: 1, ip: 1, inform_url: 1 }
 )
 ```
 Do not include credentials or controller database dumps in incident notes.
@@ -0,0 +1,102 @@
 # gw — EdgeRouter X primary LAN gateway
 ## Role and access
 | Item | Value |
 |---|---|
 | Role | Primary router for the `192.168.66.0/24` and `192.168.55.0/24` LANs |
 | IPv4 | `192.168.66.254` |
 | Verified hostname | `gw` |
 | SSH | `ssh -4 zhiqiang@192.168.66.254` |
 | Platform | Ubiquiti EdgeRouter X 5-Port, EdgeOS `v3.0.1` (Build `5862409`) |
 | Kernel | `4.14.54-UBNT` |
 | Time zone | `Asia/Shanghai` |
 Use `zhiqiang` as the default account for all routine gateway operations. Its
 key-only SSH login and passwordless `sudo` were verified on 2026-08-04; use
 `BatchMode=yes` for unattended read-only checks. `ubnt` remains an existing
 administrative account, but is not the routine operations entry point.
 Do not store account passwords, PPPoE credentials, SSH keys, configuration
 password hashes, or UISP/UNMS connection strings in this repository. Both
 administrative accounts have EdgeOS configuration and sudo privileges. Verify a
 new SSH host key out of band before accepting it.
 ## Network topology
 | Interface | Address / role |
 |---|---|
 | `eth0` | `192.168.66.254/24`; LAN 66 |
 | `switch0` (`eth1`–`eth3`) | `192.168.55.254/24`; LAN 55 |
 | `eth4` | WAN physical port; PPPoE uplink |
 | `pppoe0` | WAN default route; MTU `1492`; IPv6 prefix delegation `/60` |
 IPv6 prefix delegation assigns SLAAC-capable `/64` networks to both LANs.
 `eth4` applies the WAN IPv4 and IPv6 firewall policies.
 Detailed effective configuration, including firewall binding and WAN exposure,
 is recorded in [the EdgeRouter X configuration record](../docs/edgerouter-x-configuration.md).
 ## Services and policy
 - DHCP serves both LANs with 24-hour leases. Client DNS is `192.168.66.36`.
  Pools are `.38`–`.243` on both networks; selected infrastructure and client
  addresses have static mappings. The UniFi controller is advertised as
  `192.168.66.46`.
 - DNS forwarding listens on `eth0` and `switch0` with a cache size of 512.
 - WAN NAT masquerades all IPv4 traffic leaving `pppoe0`.
 - `WAN_IN` and `WAN_LOCAL` default to drop, permitting established/related
  sessions and rejecting invalid state. Equivalent IPv6 policies permit
  necessary ICMPv6 and DHCPv6 traffic.
 - `LAN_IN` defines a default drop plus explicit `55 → 66` and `66 → 55`
  allows, but it is **not currently applied to an interface**. The active
  inter-VLAN posture is therefore ordinary routed access: LAN55 and LAN66 can
  communicate bidirectionally unless a different active policy intervenes.
  `LAN_OUT` is likewise defined but inactive; WAN policies are active on
  `pppoe0`.
 - Management services: SSH on TCP 22; EdgeOS GUI on HTTP 80 and HTTPS 443.
 ## Safe inspection
 Use the EdgeOS operational CLI for routine inspection. `show configuration
 commands` can expose credentials and remote-management tokens, so either avoid
 copying it or filter sensitive lines before recording output.
 ```bash
 ssh -4 -o BatchMode=yes zhiqiang@192.168.66.254
 show version
 show interfaces
 show ip route
 show system uptime
 show firewall
 ```
 The [official EdgeOS User Guide](https://dl.ubnt.com/guides/edgemax/EdgeOS_UG.pdf)
 explains that a firewall policy is a ruleset and must be applied to the
 relevant interface/direction to take effect. Use the operational `show
 firewall` output—not merely the configured rule definitions—to determine the
 effective policy.
 ## Maintenance notes
 - EdgeOS writes persistent changes through its configuration tree: enter
  `configure`, make the intended change, then run `commit` and `save`.
 - The current SSH service reported a non-post-quantum key-exchange warning.
  Treat any cryptography or SSH-policy maintenance as a planned, lockout-safe
  change following the repository SSH safety procedure.
 - This device is distinct from `gfw.windy.lan` (`192.168.66.1`), the OpenWrt
  OpenClash gateway. Do not apply OpenWrt procedures to this router.
 ## Verification record
 Configuration and reachability were checked by read-only SSH on 2026-08-04.
 No network policy changes were made during that inspection. The `zhiqiang`
 account password was subsequently rotated using the EdgeOS configuration tree
 and verified by a separate SSH login; the password is intentionally not
 recorded here.
 Inter-VLAN access was rechecked by read-only SSH on 2026-08-05. A probe sourced
 from `192.168.55.254` reached the UniFi controller at `192.168.66.46` with
 3/3 ICMP replies. This supports the AP Inform path to
 `192.168.66.46:9080`; the controller listener and an online LAN55 AP provide
 the corresponding application-level evidence. No firewall changes were made.
@@ -25,6 +25,7 @@ Verify a changed key out of band before accepting it.
 | Image | `jacobalberty/unifi:v9.5.21` |
 | Network mode | host |
 | HTTPS UI | `https://192.168.66.46:8443` |
 | Device inform endpoint | `http://192.168.66.46:9080/inform` |
 The controller binds `*:8443`. A local HTTPS request to
 `https://127.0.0.1:8443/` is the primary quick health check.
@@ -43,6 +44,14 @@ Without this bypass, a controller request to `localhost:8443` can be sent to
 the OpenClash gateway instead of remaining local. Details and verification are
 in [the UniFi localhost proxy note](../docs/unifi-openclash-localhost.md).
 ## Managed access points
 The controller manages the APs listed in [the UniFi network record](../docs/unifi-network.md).
 The inform endpoint is deliberately on port `9080`, not UniFi's common default
 of `8080`. During adoption or recovery, use the documented `:9080/inform` URL;
 an AP left on `:8080` can remain reachable by ping and SSH while showing
 offline in the controller.
 ## Safe reconciliation and verification
 ```bash
@@ -55,4 +64,3 @@ curl -k -sS -o /dev/null -w '%{http_code}\n' https://127.0.0.1:8443/
 Recreating the service briefly interrupts the controller. Do not use `docker
 compose down -v`; it can remove persistent data.
@@ -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.
@@ -13,7 +13,7 @@ diagnosis and procedures that are deliberately interactive or destructive; see
 | repo.windy.me | Soft Serve git (on us2) | `ssh -p 2222 windy@repo.windy.me` | 193.9.44.165 | stub | see us2 |
 | auth.wsvc.info | Vaultwarden public hostname | — (HTTPS) | → us2 | active | see us2 |
 | us1.wsvc.info | PowerDNS secondary (ns2 host) | TBD | 202.91.35.141 | stub | Auth 5.0.5; see hk2 |
-| us4.wsvc.info | Traefik / services | TBD | TBD | stub | — |
+| us4.wsvc.info | WireGuard VPN | `ssh -4 windy@us4.wsvc.info` | 185.201.226.122 | active | [hosts/us4.wsvc.info.md](../hosts/us4.wsvc.info.md) |
 | hk2.chans.xyz | PowerDNS auth (ns1) | `ssh -4 windy@hk2.chans.xyz` | 154.36.174.161 | active | [hosts/hk2.chans.xyz.md](../hosts/hk2.chans.xyz.md) |
 | ns1.wsvc.info | PowerDNS public NS name | — (DNS) | → hk2 `154.36.174.161` | active | see hk2 |
 | ns2.wsvc.info | Secondary NS (AXFR/NOTIFY peer) | — (DNS) | → us1 `202.91.35.141` | active | see hk2 |
@@ -21,6 +21,7 @@ diagnosis and procedures that are deliberately interactive or destructive; see
 | pgweb.wsvc.info | PowerDNS Postgres UI | — (HTTPS) | → hk2 | active | see hk2 |
 | **synapse.chans.xyz** | Matrix homeserver (ESS: Synapse + MAS + Element) | `ssh -4 windy@synapse.chans.xyz` | `169.58.86.13` | **active** | [hosts/synapse.chans.xyz.md](../hosts/synapse.chans.xyz.md) |
 | **gfw.windy.lan** | OpenWrt LAN gateway / OpenClash | `ssh -4 root@192.168.66.1` | `192.168.66.1` | **active** | [hosts/gfw.windy.lan.md](../hosts/gfw.windy.lan.md) |
 | **gw** | EdgeRouter X primary LAN gateway | `ssh -4 zhiqiang@192.168.66.254` | `192.168.66.254` | **active** | [hosts/gw.md](../hosts/gw.md) |
 | **ubnt** | UniFi Network Controller | `ssh -4 windy@192.168.66.46` | `192.168.66.46` | **active** | [hosts/ubnt.md](../hosts/ubnt.md) |
 `status: stub` = known to exist; fill `hosts/<name>.md` when next touched.