From: Stefan Hanreich <s.hanreich@proxmox.com>
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 [thread overview]
Message-ID: <20261117183500.750636-1-s.hanreich@proxmox.com> (raw)
## 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
next reply other threads:[~2026-11-17 18:36 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-17 18:34 Stefan Hanreich [this message]
2026-11-17 18:34 ` [PATCH proxmox v2 01/11] network-api: add missing getters Stefan Hanreich
2026-11-17 18:34 ` [PATCH proxmox v2 02/11] network-api: add support for parsing interface flags Stefan Hanreich
2026-11-17 18:34 ` [PATCH proxmox v2 03/11] wireguard: derive additional traits for public key Stefan Hanreich
2026-11-17 18:34 ` [PATCH proxmox-ve-rs v2 04/11] ve-config: sdn: wireguard: add getters for interface listen port and " Stefan Hanreich
2026-11-17 18:34 ` [PATCH proxmox-ve-rs v2 05/11] ve-config: sdn: wireguard: add helper for resolving the peers of an interface Stefan Hanreich
2026-11-17 18:34 ` [PATCH proxmox-perl-rs v2 06/11] sdn status: fabrics: add status reporting for wireguard Stefan Hanreich
2026-11-17 18:34 ` [PATCH proxmox-perl-rs v2 07/11] sdn status: fabrics: check interfaces and peers for wireguard status Stefan Hanreich
2026-11-17 18:34 ` [PATCH proxmox-perl-rs v2 08/11] sdn status: fabrics: report status of wireguard neighbors Stefan Hanreich
2026-11-17 18:34 ` [PATCH pve-network v2 09/11] api: fabric status: add schema for wireguard properties Stefan Hanreich
2026-11-17 18:34 ` [PATCH pve-manager v2 10/11] ui: fabric content: add wireguard protocol Stefan Hanreich
2026-11-17 18:34 ` [PATCH pve-docs v2 11/11] sdn: add documentation for wireguard status reporting Stefan Hanreich
2026-11-18 15:20 ` [PATCH docs/manager/network/proxmox{,-ve-rs,-perl-rs} v2 00/11] Status reporting for WireGuard fabrics Arthur Bied-Charreton
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20261117183500.750636-1-s.hanreich@proxmox.com \
--to=s.hanreich@proxmox.com \
--cc=pve-devel@lists.proxmox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox