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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.