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

[Stefan Hanreich <s.hanreich@proxmox.com>]

## 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.

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

-- 
Generated by murpp 0.12.0