From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [45.144.208.40]) by lore.proxmox.com (Postfix) with ESMTPS id 292CE1FF0AA for ; Tue, 17 Nov 2026 19:36:25 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id A2E3D21754; Tue, 17 Nov 2026 19:35:35 +0100 (CET) From: Stefan Hanreich To: pve-devel@lists.proxmox.com Subject: [PATCH docs/manager/network/proxmox{,-ve-rs,-perl-rs} v2 00/11] Status reporting for WireGuard fabrics Date: Tue, 17 Nov 2026 19:34:47 +0100 Message-ID: <20261117183500.750636-1-s.hanreich@proxmox.com> X-Mailer: git-send-email 2.47.3 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1794940507141 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.251 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: LPNZ3RTIM67X22NGRLTMCH3FVCOY3RSD X-Message-ID-Hash: LPNZ3RTIM67X22NGRLTMCH3FVCOY3RSD X-MailFrom: s.hanreich@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: ## Introduction This patch series adds status reporting for WireGuard fabrics to pvestatd and exposes additional information about WireGuard interfaces and neighbors (= peers) via the pre-existing interface/neighbors endpoints for fabrics. ## Implementation This patch series uses the `wg show all dump` CLI command included in the wireguard-tools package to obtain the current state of WireGuard interfaces and neighbors. Matching peers to the respective section config entry happens based on their public key, scoped to the interface the peer is configured on. WireGuard identifies the peers of an interface by their public key, so it is guaranteed to be unique per interface. Status reporting for WireGuard is trickier than for the other protocols in the stack, since there's not really a notion of up / down and no way of distinguishing whether a connection hasn't been used for a while or has gone down. Utilizing persistent keepalive can fix this, but this is currently optional, so the status needs to work for both cases. The fabric status reported by pvestatd therefore does not rely on handshakes, while the status of neighbors only reports a peer as 'down' if persistent keepalive is enabled (see below). The interfaces are taken from the fabric configuration, so that interfaces missing from the `wg show` output still show up in the status. The general state of an interface is determined by looking at the type and flags of the virtual WireGuard interface and the `wg show` output. The possible states are: * 'missing': the interface does not exist, e.g. because applying the configuration failed on the node * 'error': the interface exists, but is not a WireGuard interface * 'unknown': the interface exists, but `wg show` could not read it - it skips such interfaces and still exits successfully as long as at least one interface could be read * 'down': the interface does not have the 'UP' flag set * 'up': the interface has the 'UP' flag set If WireGuard does not report the public key or listen port of an interface, the interface status shows the values from the fabric configuration instead. Values that WireGuard reports as unset, such as the endpoint before the first handshake, a missing handshake or a disabled persistent keepalive, are omitted from the neighbor status. pvestatd reports a WireGuard fabric as 'ok' if all of its interfaces on the node are 'up' and use their configured public key and listen port, and the running WireGuard configuration of each interface contains exactly the peers of the SDN running configuration, otherwise as 'not ok'. This catches nodes where applying the configuration failed, including stale peers and failed key rotations. Handshakes are not considered for this, since peers do not exchange any without traffic, unless persistent keepalive is enabled. pvestatd only calls `wg show` on nodes that are part of a WireGuard fabric. If the command fails, the interface and neighbor endpoints return an error, while pvestatd reports only the WireGuard fabrics as 'not ok' - the status of the other fabrics is still reported. The status of a neighbor is derived from its latest handshake: * 'active': the latest handshake is less than 180 seconds old (with persistent keepalive: 180 seconds plus the keepalive interval plus 90 seconds) * 'down': persistent keepalive is enabled, but there was no handshake in that time * 'idle': persistent keepalive is disabled and there was no handshake within the last 180 seconds 180 seconds is the lifetime of WireGuard session keys. Keys older than that are used neither for sending nor for receiving, so a handshake within that time means that the peer has a working session. While traffic is sent, a new handshake happens after 120 seconds, so the latest handshake of an active peer stays below 180 seconds. Without persistent keepalive, there are no handshakes without traffic, so an unused but working peer cannot be distinguished from an unreachable one - reporting it as 'down' would be misleading, so it is reported as 'idle'. With persistent keepalive, a reachable peer exchanges a new handshake before its session expires. The keepalive interval and the 90 seconds for which WireGuard retries a handshake serve as margin before reporting a peer as 'down'. The GUI shows additional columns for WireGuard fabrics in the interface and neighbor panels (e.g. status, public key, allowed IPs, latest handshake and transferred bytes), and the documentation describes the interface states, the neighbor properties and how the fabric status is determined. ## Open questions The return schema of the neighbor status endpoint had some non-optional strings. This series makes 'uptime' optional, since it is not returned for the WireGuard fabric, as well as 'neighbor', since the endpoint of a WireGuard peer is not known before the first handshake if it has none configured. Initially, I returned hard-coded strings for those fields for the WireGuard fabric, but decided to omit them instead, since they could be potentially misleading and don't really add anything. Still a bit unsure about this, since it is technically a breaking API change. It should be easy to just add this in a new iteration again - even if only 'n/a' or something similar is returned for the non-optional fields. The uptime of neighbors was omitted, since there's no way of obtaining the uptime of the connection to a peer - the kernel simply doesn't track it. We could track it ourselves in a runtime dir, but that seems clunky. It also doesn't really add a lot in the case of WireGuard, as compared to BGP / OpenFabric / OSPF. ## Dependencies libpve-rs-perl depends on proxmox-network-api libpve-rs-perl depends on proxmox-ve-config libpve-rs-perl depends on proxmox-wireguard pve-network depends on libpve-rs-perl pve-manager depends on pve-network (libpve-network-api-perl) ## Changelog Changes from v1 -> v2: * rebased on top of current master * drop the proxmox-iproute2 refactor to avoid additional churn * use proxmox_sys::command::run_command and call wg directly instead of via sh * match peers to the fabric configuration based on their public key * report peers that are not part of the fabric configuration without a name, instead of failing the whole request * show the interface of the referenced node in the name of internal neighbors * base the interface list on the fabric configuration and report the new states 'missing' and 'unknown' * omit values that WireGuard reports as unset instead of returning (none) as string * report the status of WireGuard neighbors ('active', 'down' or 'idle'), derived from their latest handshake * document the new interface states, omitted values and how the fabric status is determined * report WireGuard fabrics as 'not ok' in pvestatd if an interface is not up, does not use its configured public key or listen port, or the peers in the running WireGuard configuration differ from the configured ones * improve test cases proxmox: Stefan Hanreich (3): network-api: add missing getters network-api: add support for parsing interface flags wireguard: derive additional traits for public key proxmox-network-api/src/config/helper.rs | 42 ++++++++++++++++++++++++ proxmox-network-api/src/config/mod.rs | 5 ++- proxmox-wireguard/src/lib.rs | 5 ++- 3 files changed, 50 insertions(+), 2 deletions(-) proxmox-ve-rs: Stefan Hanreich (2): ve-config: sdn: wireguard: add getters for interface listen port and public key ve-config: sdn: wireguard: add helper for resolving the peers of an interface proxmox-ve-config/src/sdn/fabric/mod.rs | 88 ++++++++++++++++++- .../section_config/protocol/wireguard.rs | 10 +++ 2 files changed, 97 insertions(+), 1 deletion(-) proxmox-perl-rs: Stefan Hanreich (3): sdn status: fabrics: add status reporting for wireguard sdn status: fabrics: check interfaces and peers for wireguard status sdn status: fabrics: report status of wireguard neighbors pve-rs/Cargo.toml | 1 + pve-rs/src/bindings/sdn/fabrics.rs | 62 +- pve-rs/src/sdn/status.rs | 1315 +++++++++++++++++++++++++++- 3 files changed, 1364 insertions(+), 14 deletions(-) pve-network: Stefan Hanreich (1): api: fabric status: add schema for wireguard properties src/PVE/API2/Network/SDN/Nodes/Fabric.pm | 80 +++++++++++++++++++++++- 1 file changed, 77 insertions(+), 3 deletions(-) pve-manager: Stefan Hanreich (1): ui: fabric content: add wireguard protocol www/manager6/sdn/FabricsContentView.js | 179 +++++++++++++++++++------ www/manager6/sdn/NetworkBrowser.js | 40 +++--- 2 files changed, 160 insertions(+), 59 deletions(-) pve-docs: Stefan Hanreich (1): sdn: add documentation for wireguard status reporting pve-gui.adoc | 1 + pvesdn.adoc | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+) Summary over all repositories: 13 files changed, 1848 insertions(+), 79 deletions(-) -- Generated by murpp 0.12.0