fn_registry/bash/functions/infra/wg_status.md

name, kind, lang, domain, version, purity, signature, description, tags, params, output, uses_functions, uses_types, returns, returns_optional, error_type, imports, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	params	output	uses_functions	uses_types	returns	returns_optional	error_type	imports	tested	tests	test_file_path	file_path
wg_status	function	bash	infra	1.0.0	impure	wg_status([interface_name]) -> json	Parsea `wg show <iface> dump` a JSON estructurado con peers, handshake age, status (online/stale/never), bytes rx/tx. Resuelve device_id desde comentarios en wg0.conf. Para dashboards (agents_dashboard Mesh panel).	wireguard status observability json infra	name desc interface_name Nombre de la interface WireGuard (default wg0)	JSON con interface info + array de peers. Cada peer incluye public_key, device_id (de comentario # DeviceID:<id> en wg0.conf), endpoint, allowed_ips, latest_handshake_unix, latest_handshake_ago_s, rx_bytes, tx_bytes, persistent_keepalive, status (online/stale/never).				false	error_go_core		true	interface con 2 peers online y stale interface sin peers devuelve array vacio interface inexistente devuelve error JSON WG_FAKE_DUMP carga dump de archivo	bash/functions/infra/wg_status_test.sh	bash/functions/infra/wg_status.sh

Ejemplo

# Estado real de wg0
source bash/functions/infra/wg_status.sh
wg_status | jq .

# Interface distinta
wg_status wg1 | jq .peers[].status

# Sin sudo real (testing / CI)
WG_FAKE_DUMP=bash/functions/infra/wg_status_test_dump.tsv wg_status wg0 | jq .

Salida representativa:

{
  "interface": "wg0",
  "public_key": "abcXYZ123...",
  "listen_port": "51820",
  "peers": [
    {
      "public_key": "peerKey1...",
      "device_id": "pc-aurgi",
      "endpoint": "1.2.3.4:54321",
      "allowed_ips": ["10.42.0.10/32"],
      "latest_handshake_unix": 1716000000,
      "latest_handshake_ago_s": 42,
      "rx_bytes": 12345,
      "tx_bytes": 67890,
      "persistent_keepalive": 25,
      "status": "online"
    }
  ]
}

Cuando usarla

Cuando necesites saber el estado del mesh WireGuard desde un script, dashboard o agente. Usa antes de mostrar el panel Mesh en agents_dashboard. Llama cada N segundos para polling ligero desde shell sin depender de la API de WireGuard.

Gotchas

• Requiere CAP_NET_ADMIN / root: wg show falla sin permisos. En produccion ejecutar via sudo -n wg show wg0 dump o dar permiso al binario. Para tests sin sudo: WG_FAKE_DUMP=<path> carga el dump desde archivo.
• listen_port se devuelve como string (tal como lo emite wg show dump). El campo es "0" si wg no esta activo pero la interface existe.
• device_id queda "" si no hay comentario # DeviceID:<id> antes del [Peer] correspondiente en /etc/wireguard/<iface>.conf.
• Status stale cubre desde 180s hasta cualquier valor mayor. No hay distincion entre "hace 5 min" y "hace 3 dias" — ambos son stale. Para un threshold mas fino, usar latest_handshake_ago_s directamente.
• Si /etc/wireguard/<iface>.conf no existe o no es legible, device_id sera "" para todos los peers (la funcion no falla, solo omite el lookup).