From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [IPv6:2a01:7e0:0:424::9]) by lore.proxmox.com (Postfix) with ESMTPS id A93CB1FF14F for ; Wed, 17 Jun 2026 13:12:15 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 4BE6431944; Wed, 17 Jun 2026 13:11:21 +0200 (CEST) From: Stefan Hanreich To: pve-devel@lists.proxmox.com Subject: [PATCH docs/manager/network/proxmox{,-backup,-datacenter-manager,-firewall,-network-interface-pinning,-ve-rs,-perl-rs} 00/13] Status reporting for wireguard fabrics Date: Wed, 17 Jun 2026 13:09:57 +0200 Message-ID: <20260617111012.312710-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: 1781694568355 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.596 Adjusted score from AWL reputation of From: address BAYES_00 -1.9 Bayes spam probability is 0 to 1% DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment 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: 7VDC4BTYXDVVXQEYC6VYQJTBGVUPEKLN X-Message-ID-Hash: 7VDC4BTYXDVVXQEYC6VYQJTBGVUPEKLN 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. ## Refactoring This patch series includes some refactoring of existing networking code. I have extracted the iproute2 helpers from proxmox-network-api into their own microcrate proxmox-iproute2. This avoids having to pull in the full proxmox-network-api crate when only the iproute2 helpers are required. This was the case for several projects (firewall, pdm) and would have been the case for the status reporting here as well. ## 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 endpoints. Initially, public keys were used - but they are potentially not unique. Relying on endpoints instead should be more reliable. 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 awhile or has gone down. Utilizing persistent keepalive can fix this, but this is currently optional so we have to find a solution for both cases. The general state of the interface is determined by looking at the flags of the virtual wireguard interface. If the flags of the interface contain the 'UP' flag, then the interface is considered 'up'. If it does not contain the 'UP' flag, then it is considered 'down'. If the interface does not exist at all, or has the wrong interface type, then it has state 'error'. State for neighbors has been omitted since there is no surefire way of always determining the state of a Wireguard peer, but a potential solution of tackling this has been proposed below in the 'Open questions' section. ## Open questions The neighbor status endpoint has some non-optional strings in the return schema. 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. For the neighbor status two fields were omitted: * uptime The main reason here being that there's no way of obtaining the uptime of an interface, since 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. * status WireGuard is a non-chatty protocol by default, which poses some problems for status reporting: As long as traffic is being sent to a peer, handshakes are exchanged every 180 seconds. If there is no traffic being sent over an interface (and persistent keepalive is inactive), then the latest handshake cannot be reliably used to gauge the status of the peer. One idea to handle this, which I didn't implement yet, would be to have three states (names are subject to change): 'active', 'idle', 'inactive'. A neighbor is active if the last handshake occurred in that 180 second window (potentially including some buffer). Otherwise, if the last handshake is more than 180 seconds in the past, then the neighbor is marked as 'idle'. If a handshake never occurred, then the neighbor would be 'inactive'. The time window would not change with persistent keepalive, since that doesn't affect the interval of handshakes. We could however infer that the connection to a peer has been lost if persistent keepalive is set. In that case we could potentially introduce a fourth state, 'failed', if no handshake occured within the last (180 + keepalive_interval) seconds. My worry with this approach mainly is that users would configure the fabric, check the status of the interfaces, see that the peer is 'inactive' and then falsely assume that something must have went wrong with configuring the fabric, even though the state only exists because no traffic has been sent yet. ## Dependencies Quite a few, due to extracting the iproute2-related stuff: New proxmox-network-api version breaks old proxmox-firewall, proxmox-datacenter-manager, proxmox-backup, proxmox-network-interface-pinning and therefore would need a major version bump. proxmox-firewall, proxmox-datacenter-manager, proxmox-backup, proxmox-network-interface-pinning, proxmox-network-api all depend on the new proxmox-iproute2 crate. libpve-rs-perl depends on librust-proxmox-ve-config libpve-rs-perl depends on proxmox-iproute2 pve-network depends on libpve-rs-perl pve-manager depends on libpve-network-api-perl proxmox: Stefan Hanreich (4): iproute2: schema: move iproute2 helpers to new create / schema iproute2: add missing getters iproute2: add support for parsing interface flags wireguard: derive additional traits for public key Cargo.toml | 3 + proxmox-iproute2/Cargo.toml | 18 + proxmox-iproute2/debian/changelog | 5 + proxmox-iproute2/debian/control | 42 +++ proxmox-iproute2/debian/debcargo.toml | 7 + proxmox-iproute2/src/lib.rs | 416 +++++++++++++++++++++++ proxmox-network-api/Cargo.toml | 1 + proxmox-network-api/debian/control | 2 + proxmox-network-api/src/config/helper.rs | 367 +------------------- proxmox-network-api/src/config/mod.rs | 8 +- proxmox-network-api/src/config/parser.rs | 5 +- proxmox-schema/src/api_types.rs | 5 + proxmox-wireguard/src/lib.rs | 5 +- 13 files changed, 510 insertions(+), 374 deletions(-) create mode 100644 proxmox-iproute2/Cargo.toml create mode 100644 proxmox-iproute2/debian/changelog create mode 100644 proxmox-iproute2/debian/control create mode 100644 proxmox-iproute2/debian/debcargo.toml create mode 100644 proxmox-iproute2/src/lib.rs proxmox-backup: Stefan Hanreich (1): metric_collection: switch to proxmox-iproute2 crate Cargo.toml | 2 ++ src/server/metric_collection/mod.rs | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) proxmox-datacenter-manager: Stefan Hanreich (1): metric_collection: switch to proxmox-iproute2 crate Cargo.toml | 1 + server/Cargo.toml | 1 + server/src/metric_collection/local_collection_task.rs | 6 +++--- 3 files changed, 5 insertions(+), 3 deletions(-) proxmox-firewall: Stefan Hanreich (1): firewall config: switch to proxmox-iproute2 crate Cargo.toml | 2 +- proxmox-firewall/Cargo.toml | 2 +- proxmox-firewall/src/config.rs | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) proxmox-network-interface-pinning: Stefan Hanreich (1): network-interface-pinning: switch to proxmox-iproute2 crate Cargo.toml | 1 + src/main.rs | 19 ++++++++----------- 2 files changed, 9 insertions(+), 11 deletions(-) proxmox-ve-rs: Stefan Hanreich (1): fabric: wireguard: add helper for findings peer based on endpoint proxmox-ve-config/src/sdn/fabric/mod.rs | 115 +++++++++++++++++- .../section_config/protocol/wireguard.rs | 8 ++ 2 files changed, 121 insertions(+), 2 deletions(-) proxmox-perl-rs: Stefan Hanreich (1): sdn status: fabrics: add status reporting for wireguard pve-rs/Cargo.toml | 1 + pve-rs/src/bindings/sdn/fabrics.rs | 41 ++- pve-rs/src/sdn/status.rs | 529 ++++++++++++++++++++++++++++- 3 files changed, 562 insertions(+), 9 deletions(-) pve-network: Stefan Hanreich (1): api: fabric status: add schema for wireguard properties src/PVE/API2/Network/SDN/Nodes/Fabric.pm | 71 +++++++++++++++++++++++- 1 file changed, 68 insertions(+), 3 deletions(-) pve-manager: Stefan Hanreich (1): ui: fabric content: add wireguard protocol www/manager6/sdn/FabricsContentView.js | 173 +++++++++++++++++++------ www/manager6/sdn/NetworkBrowser.js | 40 +++--- 2 files changed, 154 insertions(+), 59 deletions(-) pve-docs: Stefan Hanreich (1): sdn: add documentation for wireguard status reporting pve-gui.adoc | 1 + pvesdn.adoc | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+) Summary over all repositories: 33 files changed, 1500 insertions(+), 465 deletions(-) -- Generated by murpp 0.12.0