From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [IPv6:2a0f:8001:1:32::40]) by lore.proxmox.com (Postfix) with ESMTPS id C720C1FF0AA for ; Tue, 17 Nov 2026 19:36:15 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 3467A21745; Tue, 17 Nov 2026 19:35:35 +0100 (CET) From: Stefan Hanreich 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 Message-ID: <20261117183500.750636-12-s.hanreich@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261117183500.750636-1-s.hanreich@proxmox.com> References: <20261117183500.750636-1-s.hanreich@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1794940507794 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.253 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: NN3QXHZEYXEELJS2TACGSE3YXA5DFBPF X-Message-ID-Hash: NN3QXHZEYXEELJS2TACGSE3YXA5DFBPF X-MailFrom: s.hanreich@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: 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 --- 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