chrisbrace/ha-vpn-watch

Purpose and Host Runtime

WireGuard VPN Watch is a Home Assistant custom integration. It polls a Linux WireGuard gateway over SSH, evaluates peer handshake freshness, and exposes per-peer connection entities for automations and dashboards. Home Assistant loads it from custom_components/wg_vpn_watch/, with integration metadata in custom_components/wg_vpn_watch/manifest.json.

Integration Lifecycle and Setup

custom_components/wg_vpn_watch/__init__.py owns Home Assistant entry setup/unload and wires configured entries to runtime services. custom_components/wg_vpn_watch/config_flow.py implements initial setup and options editing: it collects gateway/SSH/interface settings, discovers current peers, and persists friendly names keyed by WireGuard public key. UI labels and flow text are defined in custom_components/wg_vpn_watch/strings.json.

Gateway Access Boundary

custom_components/wg_vpn_watch/ssh.py is the remote-access boundary. It connects to the configured Linux gateway and executes the configured command template, normally wg show {interface} dump; deployments may instead use passwordless sudo. SSH host, port, credentials, command, and WireGuard interface are integration configuration rather than entity concerns.

WireGuard Data Interpretation

custom_components/wg_vpn_watch/wireguard.py converts wg show ... dump output into peer records, including public keys and latest handshake timestamps. This isolates WireGuard CLI-format parsing from Home Assistant lifecycle and presentation logic. The primary raw-data flow is: SSH command output → parser → peer handshake data.

Polling and Connection State

custom_components/wg_vpn_watch/coordinator.py is the central refresh stage. It periodically retrieves and parses gateway state, compares each peer’s latest handshake against the configured timeout, and maintains observed-connected timing. A peer is connected only when its handshake is recent; displayed duration starts when this integration instance first observes connectivity and resets on reload/restart.

Entity Projection

custom_components/wg_vpn_watch/binary_sensor.py projects coordinator state as a boolean connected/disconnected entity per configured peer, suited to automations. custom_components/wg_vpn_watch/sensor.py exposes a status-oriented entity per peer, including connection state and observed duration. Both entity families consume shared coordinator data rather than independently querying the gateway.

Configuration and Identity Boundaries

custom_components/wg_vpn_watch/const.py centralizes integration identifiers, defaults, and configuration keys used across setup, coordinator, and platforms. Peer identity is the WireGuard public key; friendly names are user-managed labels. Options changes rediscover peers and trigger integration reload/entity recreation, making configuration the boundary between gateway-discovered topology and Home Assistant entity naming.