public inbox for pve-devel@lists.proxmox.com
 help / color / mirror / Atom feed
* [PATCH docs/manager/network/proxmox{,-ve-rs,-perl-rs} v2 00/11] Status reporting for WireGuard fabrics
@ 2026-11-17 18:34 Stefan Hanreich
  2026-11-17 18:34 ` [PATCH proxmox v2 01/11] network-api: add missing getters Stefan Hanreich
                   ` (11 more replies)
  0 siblings, 12 replies; 13+ messages in thread
From: Stefan Hanreich @ 2026-11-17 18:34 UTC (permalink / raw)
  To: pve-devel

## 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




^ permalink raw reply	[flat|nested] 13+ messages in thread

end of thread, other threads:[~2026-11-18 15:20 UTC | newest]

Thread overview: 13+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-17 18:34 [PATCH docs/manager/network/proxmox{,-ve-rs,-perl-rs} v2 00/11] Status reporting for WireGuard fabrics Stefan Hanreich
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

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal