From: Stefan Hanreich <s.hanreich@proxmox.com>
To: pve-devel@lists.proxmox.com
Subject: [PATCH pve-docs v2 11/11] sdn: add documentation for wireguard status reporting
Date: Tue, 17 Nov 2026 19:34:58 +0100 [thread overview]
Message-ID: <20261117183500.750636-12-s.hanreich@proxmox.com> (raw)
In-Reply-To: <20261117183500.750636-1-s.hanreich@proxmox.com>
Explains the content of the returned fields and how to interpret them,
particularly how the status of an interface is determined.
Signed-off-by: Stefan Hanreich <s.hanreich@proxmox.com>
---
pve-gui.adoc | 1 +
pvesdn.adoc | 99 ++++++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 100 insertions(+)
diff --git a/pve-gui.adoc b/pve-gui.adoc
index 3a99eaf..dce5e26 100644
--- a/pve-gui.adoc
+++ b/pve-gui.adoc
@@ -149,6 +149,7 @@ Line Height :: Specify the absolute height of a line.
+[[gui_resource_tree]]
Resource Tree
~~~~~~~~~~~~~
diff --git a/pvesdn.adoc b/pvesdn.adoc
index b701636..f97fc7c 100644
--- a/pvesdn.adoc
+++ b/pvesdn.adoc
@@ -958,6 +958,105 @@ Skip Route Generation:: The fabric will autogenerate routes in the kernel
routing table for all allowed IPs of a peer. By setting this option, no routes
will be inserted into the kernel routing table.
+
+[[pvesdn_fabric_status]]
+Status Reporting
+~~~~~~~~~~~~~~~~
+
+Fabrics report their current status for informational and debugging purposes. It
+can be accessed by clicking on the respective entry for the fabric in the
+xref:gui_resource_tree[Resource Tree]. Depending on the protocol, different
+metrics are reported.
+
+
+[[pvesdn_fabric_status_wireguard]]
+WireGuard
+^^^^^^^^^
+
+A WireGuard fabric is shown as 'ok' in the resource tree if all of its
+interfaces on the node are in the 'up' state, use their configured public key
+and listen port, and have exactly the peers of the applied fabric
+configuration. Otherwise, for example if an interface is missing or applying
+the configuration failed on the node, it is shown as 'not ok'. Pending changes
+are not taken into account. Neither are handshakes, since peers do not exchange
+handshakes if no traffic is sent and persistent keepalive is disabled.
+
+.Interfaces
+
+Provides information about the WireGuard interfaces of a specific node. The
+following properties are available:
+
+Name:: The name of the network interface on the host.
+
+Type:: Interfaces are always of type 'wireguard'.
+
+State:: The SDN stack performs several checks to determine the state of the
+interface. Possible states are:
++
+* 'up': The interface exists and has the `UP` flag set.
+* 'down': The interface exists, but does not have the `UP` flag set.
+* 'missing': The interface does not exist on the node, for example because
+ applying the configuration failed on the node.
+* 'unknown': The interface exists, but its WireGuard state could not be read.
+* 'error': The interface exists, but is not a WireGuard interface.
++
+If WireGuard does not report the public key or listen port of an interface,
+the values from the fabric configuration are shown.
+
+Public Key:: The public key that can be used for communicating with the
+WireGuard instance on this interface.
+
+Listen Port:: The port that can be used to reach this WireGuard instance.
+
+.Neighbors
+
+Provides information about the peers of all WireGuard interfaces on a specific
+node. The following properties are available:
+
+Name:: The name of the node in the fabric configuration. Additionally contains
+the name of the referenced interface in parentheses, if the node is an internal
+node. Peers are matched to the fabric configuration by their public key. Peers
+that are not part of the fabric configuration have no name.
+
+Neighbor:: The endpoint that is currently used to reach this peer (e.g.
+192.0.2.1:51820). WireGuard updates the endpoint to the address it last
+received traffic from, so this can differ from the configured endpoint, for
+example if the peer is behind NAT. Empty if the endpoint is not known yet.
+
+Interface:: The interface that has this neighbor configured.
+
+Status:: The status of the neighbor, derived from its latest handshake.
+WireGuard does not use session keys that are older than 180 seconds, so a
+handshake within that time means that the neighbor has a working session.
+Possible states are:
++
+* 'active': The latest handshake is less than 180 seconds old. With persistent
+ keepalive, the keepalive interval and another 90 seconds, for which WireGuard
+ retries a handshake, are added as margin.
+* 'down': Persistent keepalive is enabled, but there was no handshake in that
+ time. Since keepalive packets are sent regularly, a reachable neighbor would
+ have exchanged a new handshake.
+* 'idle': Persistent keepalive is disabled and there was no recent handshake.
+ Without traffic, WireGuard does not exchange handshakes, so an unused but
+ working neighbor cannot be distinguished from an unreachable one. Enable
+ persistent keepalive on the fabric for a reliable status.
+
+Public Key:: The public key of the neighbor.
+
+Allowed IPs:: A comma separated list of CIDRs. Those indicate the destination
+IPs that are allowed when sending traffic to this neighbor.
+
+Latest Handshake:: When the latest handshake with this neighbor occurred.
+Handshakes are exchanged every 120 seconds, *if* traffic is sent via this
+WireGuard interface. If no traffic is sent, then also no handshake is exchanged.
+Empty if no handshake happened yet.
+
+Bytes transmitted:: The amount of traffic that has been sent to this neighbor.
+
+Bytes received:: The amount of traffic that has been received from this
+neighbor.
+
+
[[pvesdn_config_route_filtering]]
Prefix Lists and Route Maps
---------------------------
--
2.47.3
next prev parent 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 [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 ` Stefan Hanreich [this message]
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-12-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