Re: [PATCH docs/manager/network/proxmox{,-backup,-datacenter-manager,-firewall,-network-interface-pinning,-ve-rs,-perl-rs} 00/13] Status reporting for wireguard fabrics

[Hannes Laimer <h.laimer@proxmox.com>]

nit: the iproute2 change with the moves could probably a separate small
series, with this depending on it

this has to be rebased, ran into minor conflicts

On 2026-06-17 13:11, Stefan Hanreich wrote:
> ## 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.

together with the interface they should be. the endpoint in the dump can
change, also shouldn't match for hostnames or when behind a nat. using
the public key would avoid these, but we'd have to check for uniqueness
in the config?

> 
> 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(-)
>