public inbox for pve-devel@lists.proxmox.com
 help / color / mirror / Atom feed
From: Stefan Hanreich <s.hanreich@proxmox.com>
To: pve-devel@lists.proxmox.com
Subject: [PATCH proxmox-perl-rs v2 08/11] sdn status: fabrics: report status of wireguard neighbors
Date: Tue, 17 Nov 2026 19:34:55 +0100	[thread overview]
Message-ID: <20261117183500.750636-9-s.hanreich@proxmox.com> (raw)
In-Reply-To: <20261117183500.750636-1-s.hanreich@proxmox.com>

WireGuard has no notion of a peer being up or down, so derive the
status of a neighbor from its latest handshake instead:

* 'active': the latest handshake is less than 180 seconds old
* 'idle': there was no handshake within the last 180 seconds and
  persistent keepalive is disabled
* 'down': persistent keepalive is enabled, but there was no handshake
  within the last 180 seconds plus the keepalive interval plus 90
  seconds

WireGuard does not use session keys that are older than 180 seconds
(REJECT_AFTER_TIME in the kernel), neither for sending nor for
receiving. A handshake within that time therefore means that the peer
has a working session. While traffic is sent, a new handshake happens
after 120 seconds (REKEY_AFTER_TIME), so the latest handshake of an
active peer stays below 180 seconds.

Without persistent keepalive, peers only exchange handshakes if traffic
is sent. A peer without a recent handshake can then not be
distinguished from an unreachable one, so it is reported as 'idle'
rather than 'down', which would be misleading for a working but unused
peer. With persistent keepalive, keepalive packets are sent regularly,
so a reachable peer exchanges a new handshake before its session
expires. The keepalive interval and the 90 seconds for which WireGuard
retries a handshake (90 / REKEY_TIMEOUT attempts) serve as margin
before reporting a peer as 'down'.

Signed-off-by: Stefan Hanreich <s.hanreich@proxmox.com>
---
 pve-rs/src/bindings/sdn/fabrics.rs |   1 +
 pve-rs/src/sdn/status.rs           | 132 +++++++++++++++++++++++++++--
 2 files changed, 127 insertions(+), 6 deletions(-)

diff --git a/pve-rs/src/bindings/sdn/fabrics.rs b/pve-rs/src/bindings/sdn/fabrics.rs
index 6726045..0fd756d 100644
--- a/pve-rs/src/bindings/sdn/fabrics.rs
+++ b/pve-rs/src/bindings/sdn/fabrics.rs
@@ -975,6 +975,7 @@ pub mod pve_rs_sdn_fabrics {
                     &wg_dump,
                     fabric_entry.node_section(&current_node_id)?,
                     fabric_entry,
+                    proxmox_time::epoch_i64(),
                 )
                 .map(Into::into)
             }
diff --git a/pve-rs/src/sdn/status.rs b/pve-rs/src/sdn/status.rs
index 64ffb98..4fe8397 100644
--- a/pve-rs/src/sdn/status.rs
+++ b/pve-rs/src/sdn/status.rs
@@ -97,6 +97,60 @@ pub mod wireguard {
     use proxmox_wireguard::PublicKey;
     use serde::Serialize;
 
+    /// WireGuard does not use session keys that are older than this (`REJECT_AFTER_TIME`), so a peer
+    /// with a more recent handshake has a working session.
+    const REJECT_AFTER_TIME: u64 = 180;
+
+    /// WireGuard retries a handshake for this long before giving up.
+    const REKEY_ATTEMPT_TIME: u64 = 90;
+
+    /// The status of a WireGuard peer, derived from its latest handshake.
+    #[derive(Debug, Serialize, PartialEq, Eq, PartialOrd, Ord)]
+    #[serde(rename_all = "lowercase")]
+    pub enum PeerStatus {
+        /// The peer had a working session recently.
+        Active,
+        /// The peer is not reachable, which can only be determined with persistent keepalive.
+        Down,
+        /// The peer has no recent session, since no traffic was sent and persistent keepalive is
+        /// disabled.
+        Idle,
+    }
+
+    impl PeerStatus {
+        /// Determines the status of a peer at the time `now` (UNIX epoch).
+        ///
+        /// Without persistent keepalive, peers only exchange handshakes if traffic is sent, so a
+        /// peer without a recent handshake cannot be distinguished from an unreachable one. With
+        /// persistent keepalive, a reachable peer exchanges a new handshake before its session
+        /// expires after `REJECT_AFTER_TIME`, delayed by at most the keepalive interval and
+        /// `REKEY_ATTEMPT_TIME` of retries.
+        pub fn from_handshake(
+            latest_handshake: Option<u64>,
+            persistent_keepalive: Option<u16>,
+            now: i64,
+        ) -> Self {
+            let age = latest_handshake.map(|latest_handshake| {
+                u64::try_from(now)
+                    .unwrap_or(0)
+                    .saturating_sub(latest_handshake)
+            });
+
+            match persistent_keepalive {
+                None if age.is_some_and(|age| age < REJECT_AFTER_TIME) => PeerStatus::Active,
+                None => PeerStatus::Idle,
+                Some(interval)
+                    if age.is_some_and(|age| {
+                        age < REJECT_AFTER_TIME + u64::from(interval) + REKEY_ATTEMPT_TIME
+                    }) =>
+                {
+                    PeerStatus::Active
+                }
+                Some(_) => PeerStatus::Down,
+            }
+        }
+    }
+
     #[derive(Debug, Serialize, PartialEq, Eq, PartialOrd, Ord)]
     #[serde(rename_all = "kebab-case")]
     pub struct NeighborStatus {
@@ -104,6 +158,7 @@ pub mod wireguard {
         pub neighbor: Option<String>,
         #[serde(skip_serializing_if = "Option::is_none")]
         pub name: Option<String>,
+        pub status: PeerStatus,
         pub interface: String,
         pub public_key: PublicKey,
         #[serde(skip_serializing_if = "Option::is_none")]
@@ -286,10 +341,15 @@ pub mod wireguard {
         (value != "(none)").then_some(value)
     }
 
+    /// Parses the peers of the fabric interfaces in the `wg show all dump` output.
+    ///
+    /// `now` is the current time (UNIX epoch), which is used for determining the status of the
+    /// peers.
     pub fn parse_wireguard_neighbors(
         wg_dump_output: &str,
         node_section: &NodeSection<WireGuardNode>,
         fabric: &Entry<WireGuardProperties, WireGuardNode>,
+        now: i64,
     ) -> Result<Vec<NeighborStatus>, anyhow::Error> {
         let WireGuardNode::Internal(wireguard_node) = node_section.properties() else {
             anyhow::bail!("is not an internal node");
@@ -409,6 +469,7 @@ pub mod wireguard {
             neighbors.push(NeighborStatus {
                 neighbor,
                 name,
+                status: PeerStatus::from_handshake(latest_handshake, persistent_keepalive, now),
                 interface: interface.to_string(),
                 public_key,
                 allowed_ips,
@@ -472,7 +533,10 @@ pub mod wireguard {
 
         let mut running_peers: HashMap<String, HashSet<PublicKey>> = HashMap::new();
 
-        for neighbor in parse_wireguard_neighbors(wg_dump_output, node_section, fabric)? {
+        // the status of the peers does not matter here, only whether they are present
+        let now = proxmox_time::epoch_i64();
+
+        for neighbor in parse_wireguard_neighbors(wg_dump_output, node_section, fabric, now)? {
             running_peers
                 .entry(neighbor.interface)
                 .or_default()
@@ -3251,7 +3315,7 @@ mod tests {
         };
 
         use super::super::wireguard::{
-            InterfaceStatus, NeighborStatus, WireGuardInterfaceState, is_node_ok,
+            InterfaceStatus, NeighborStatus, PeerStatus, WireGuardInterfaceState, is_node_ok,
             parse_wireguard_interfaces, parse_wireguard_neighbors,
         };
         use super::super::*;
@@ -3577,6 +3641,7 @@ wg0	8ybxvVfiWqpBG160nMgH14acR3z31ZeceW7ita0zonA=	(none)	172.31.1.4:51820	198.51.
                 NeighborStatus {
                     neighbor: Some("172.31.1.10:51820".to_string()),
                     name: Some("stormweaver".to_string()),
+                    status: PeerStatus::Idle,
                     interface: "wg1".to_string(),
                     public_key: "aHnKVQ4yTtTdfwsk+r4Z12FrRlUnXXksjRcV7x41+G0="
                         .parse()
@@ -3590,6 +3655,7 @@ wg0	8ybxvVfiWqpBG160nMgH14acR3z31ZeceW7ita0zonA=	(none)	172.31.1.4:51820	198.51.
                 NeighborStatus {
                     neighbor: Some("172.31.1.2:51820".to_string()),
                     name: Some("occultist (wg0)".to_string()),
+                    status: PeerStatus::Idle,
                     interface: "wg0".to_string(),
                     public_key: "+PA/xNCZ3G+Wy1DeqF251Us5mcZhBTGc9CT3AaJ89HI="
                         .parse()
@@ -3603,6 +3669,7 @@ wg0	8ybxvVfiWqpBG160nMgH14acR3z31ZeceW7ita0zonA=	(none)	172.31.1.4:51820	198.51.
                 NeighborStatus {
                     neighbor: Some("172.31.1.4:51820".to_string()),
                     name: Some("chronomancer (wg0)".to_string()),
+                    status: PeerStatus::Idle,
                     interface: "wg0".to_string(),
                     public_key: "8ybxvVfiWqpBG160nMgH14acR3z31ZeceW7ita0zonA="
                         .parse()
@@ -3617,7 +3684,7 @@ wg0	8ybxvVfiWqpBG160nMgH14acR3z31ZeceW7ita0zonA=	(none)	172.31.1.4:51820	198.51.
 
             assert_eq!(
                 expected,
-                parse_wireguard_neighbors(wg_dump, elementalist(fabric), fabric)
+                parse_wireguard_neighbors(wg_dump, elementalist(fabric), fabric, 1781234627)
                     .expect("can parse wireguard output")
             );
         }
@@ -3634,6 +3701,7 @@ wg0	+PA/xNCZ3G+Wy1DeqF251Us5mcZhBTGc9CT3AaJ89HI=	(none)	203.0.113.50:40123	198.5
             let expected = vec![NeighborStatus {
                 neighbor: Some("203.0.113.50:40123".to_string()),
                 name: Some("occultist (wg0)".to_string()),
+                status: PeerStatus::Active,
                 interface: "wg0".to_string(),
                 public_key: "+PA/xNCZ3G+Wy1DeqF251Us5mcZhBTGc9CT3AaJ89HI="
                     .parse()
@@ -3647,7 +3715,7 @@ wg0	+PA/xNCZ3G+Wy1DeqF251Us5mcZhBTGc9CT3AaJ89HI=	(none)	203.0.113.50:40123	198.5
 
             assert_eq!(
                 expected,
-                parse_wireguard_neighbors(wg_dump, elementalist(fabric), fabric)
+                parse_wireguard_neighbors(wg_dump, elementalist(fabric), fabric, 1781234627)
                     .expect("can parse wireguard output")
             );
         }
@@ -3664,6 +3732,7 @@ wg0	8ybxvVfiWqpBG160nMgH14acR3z31ZeceW7ita0zonA=	(none)	(none)	198.51.100.4/32	0
             let expected = vec![NeighborStatus {
                 neighbor: None,
                 name: Some("chronomancer (wg0)".to_string()),
+                status: PeerStatus::Idle,
                 interface: "wg0".to_string(),
                 public_key: "8ybxvVfiWqpBG160nMgH14acR3z31ZeceW7ita0zonA="
                     .parse()
@@ -3677,7 +3746,7 @@ wg0	8ybxvVfiWqpBG160nMgH14acR3z31ZeceW7ita0zonA=	(none)	(none)	198.51.100.4/32	0
 
             assert_eq!(
                 expected,
-                parse_wireguard_neighbors(wg_dump, elementalist(fabric), fabric)
+                parse_wireguard_neighbors(wg_dump, elementalist(fabric), fabric, 1781234627)
                     .expect("can parse wireguard output")
             );
         }
@@ -3694,6 +3763,7 @@ wg0	AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=	(none)	(none)	(none)	0	0	0	off"
             let expected = vec![NeighborStatus {
                 neighbor: None,
                 name: None,
+                status: PeerStatus::Idle,
                 interface: "wg0".to_string(),
                 public_key: "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
                     .parse()
@@ -3707,7 +3777,7 @@ wg0	AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=	(none)	(none)	(none)	0	0	0	off"
 
             assert_eq!(
                 expected,
-                parse_wireguard_neighbors(wg_dump, elementalist(fabric), fabric)
+                parse_wireguard_neighbors(wg_dump, elementalist(fabric), fabric, 1781234627)
                     .expect("can parse wireguard output")
             );
         }
@@ -3952,5 +4022,55 @@ wg0	8ybxvVfiWqpBG160nMgH14acR3z31ZeceW7ita0zonA=	(none)	172.31.1.4:51820	198.51.
             let fabric_id = FabricId::from_str("test").expect("valid fabric id");
             assert_eq!(FabricStatus::NotOk, status[&fabric_id].status);
         }
+
+        #[test]
+        fn peer_status_without_keepalive() {
+            // without persistent keepalive, only a handshake within the last 180 seconds counts
+            let now = 1781234567;
+
+            assert_eq!(
+                PeerStatus::from_handshake(Some(now as u64 - 179), None, now),
+                PeerStatus::Active
+            );
+            assert_eq!(
+                PeerStatus::from_handshake(Some(now as u64 - 180), None, now),
+                PeerStatus::Idle
+            );
+            assert_eq!(
+                PeerStatus::from_handshake(None, None, now),
+                PeerStatus::Idle
+            );
+        }
+
+        #[test]
+        fn peer_status_with_keepalive() {
+            // with a keepalive interval of 25 seconds, a reachable peer exchanges a handshake
+            // within 180 + 25 + 90 seconds
+            let now = 1781234567;
+
+            assert_eq!(
+                PeerStatus::from_handshake(Some(now as u64 - 294), Some(25), now),
+                PeerStatus::Active
+            );
+            assert_eq!(
+                PeerStatus::from_handshake(Some(now as u64 - 295), Some(25), now),
+                PeerStatus::Down
+            );
+            assert_eq!(
+                PeerStatus::from_handshake(None, Some(25), now),
+                PeerStatus::Down
+            );
+        }
+
+        #[test]
+        fn peer_status_handshake_in_future() {
+            // a handshake in the future, e.g. due to clock adjustments, counts as recent
+            let now = 1781234567;
+
+            assert_eq!(
+                PeerStatus::from_handshake(Some(now as u64 + 10), None, now),
+                PeerStatus::Active
+            );
+        }
     }
 }
-- 
2.47.3





  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 ` Stefan Hanreich [this message]
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

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-9-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
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal