[PATCH pve-docs 1/1] sdn: fabrics: wireguard: add simple example

[PATCH pve-docs 1/1] sdn: fabrics: wireguard: add simple example

[Stefan Hanreich]

Initial feedback has shown that the UI currently is a bit confusing as
to which field expects which value. Provide a step-by-step setup guide
for a concrete example setup that should cover most basic uses cases.
This should help users with setting up WireGuard. In the future, we
should provide some kind of wizard or auto-full-meshify feature in
order to automate this procedure.

Signed-off-by: Stefan Hanreich <s.hanreich@proxmox.com>
---

Notes:
    The referenced screenshots are available in my staff repo (including
    this commit) on the branch 'wireguard-example'. The commit containing
    the screenshots has the hash 259e951.

 pvesdn.adoc | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)

diff --git a/pvesdn.adoc b/pvesdn.adoc
index f584526..a09a443 100644
--- a/pvesdn.adoc
+++ b/pvesdn.adoc
@@ -1867,6 +1867,135 @@ If you have configured an external BGP router, the BGP-EVPN routes (10.0.1.0/24
 and 10.0.2.0/24 in this example), will be announced dynamically.
 
 
+[[pvesdn_setup_example_wireguard]]
+WireGuard Setup Example
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The examples assumes a 3-node Proxmox cluster ('sdn1', 'sdn2' and 'sdn3') with
+the IP addresses `192.0.2.1`, `192.0.2.2` and `192.0.2.3`, as well as an
+external WireGuard peer ('sdn-router') with IP address `192.0.2.10`.
+
+In this example the Proxmox nodes as well as the external peer will be connected
+full-mesh via WireGuard in the `198.51.100.0/24` subnet and additionally the
+`203.0.113.0/24` subnet will allowed to be sent via the external WireGuard peer,
+`198.51.100.10`.
+
+Setup WireGuard Fabric
+^^^^^^^^^^^^^^^^^^^^^^
+
+[thumbnail="screenshot/gui-datacenter-create-fabric-wireguard.png"]
+
+Click on 'Datacenter' in the left-hand resource tree then navigate to 'SDN' >
+'Fabrics' and create new WireGuard fabric by clicking 'Create' and selecting
+'WireGuard'.
+
+Choose a name for the fabric, in this case 'example' has been chosen.
+
+Setup WireGuard Interfaces
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+[thumbnail="screenshot/gui-datacenter-create-internal-node-wireguard.png"]
+
+Each participating node requires a WireGuard interface. This can be configured
+by adding a new node with type 'Internal' to the WireGuard fabric, selecting the
+respective node and then creating a new WireGuard interface.
+
+On the node itself, two properties can be configured: 'Endpoint' and 'Allowed
+IPs'. 'Endpoint' refers to the IP / hostname that will be used for connecting to
+this node, `192.0.2.1` in the case of sdn1. Since we do not want to route
+additional subnets via this node in our example, leave the 'Allowed IPs' field
+empty.
+
+Create a new WireGuard interface, `wg0`, and configure the IP address that
+should be configured on the WireGuard interface, `198.51.100.1/24` in the case
+of sdn1. The default listen port is `51820`, but can be manually changed via the
+'Listen Port' field. A public / private key pair will be automatically created
+for every new WireGuard interface.
+
+Setup External Node
+^^^^^^^^^^^^^^^^^^^
+
+[thumbnail="screenshot/gui-datacenter-create-external-node-wireguard.png"]
+
+In order to add an external node, add another node to the WireGuard fabric, but
+select type 'External' in the Node creation dialogue. Enter the public key of
+the interface of the external node, as well as the IP / hostname + port that can
+be used to reach this external peer (`192.0.2.10:51820` in this example). Add
+the IP of the node, `198.51.100.10/32`, as well as the `203.0.113.0/24` subnet
+to the allowed IPs field.
+
+Setup WireGuard Peerings
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+[thumbnail="screenshot/gui-datacenter-select-peers-wireguard.png"]
+
+Now that all interfaces and external peers have been set up, they can be
+selected as peers in the WireGuard interface configuration. Add the nodes 'sdn2'
+and 'sdn3', as well as 'sdn-router' to the peers of the interface `wg0` on node
+'sdn1':
+
+This will generate the following `wg0.conf` file in `/etc/wireguard/proxmox`:
+
+----
+root@sdn1:~# cat /etc/wireguard/proxmox/wg0.conf
+[Interface]
+PrivateKey = EpP9R0kqNA1UjGGeDL0/y9Ok66G44dqa2ALYJ0jTWwQ=
+ListenPort = 51820
+
+[Peer]
+PublicKey = xIlHE6ZA25Qnpa+HYT1un3fbjO5/0A9YUbbRmTyLWW4=
+AllowedIPs = 198.51.100.10/32, 203.0.113.0/24
+Endpoint = 192.0.2.10:51820
+
+[Peer]
+PublicKey = CKClJbQ42U1pQM8MqMGCa1IpZbNcqb+OJBxVWJHIrx4=
+AllowedIPs = 198.51.100.2/32
+Endpoint = 192.0.2.2:51820
+
+[Peer]
+PublicKey = gCXBt+n2VNBR6RiUmUxG3+15G0qnXUzsSxEQvmwGMkw=
+AllowedIPs = 198.51.100.3/32
+Endpoint = 192.0.2.3:51820
+----
+
+There is a `[Peer]` section for each selected peer. The IP configured on the
+WireGuard interfaces will be added to the 'Allowed IPs' of a peer as well.
+
+Verifying the Setup
+^^^^^^^^^^^^^^^^^^^
+
+Verify connectivity to the other participants in the WireGuard fabric by
+pinging:
+
+----
+root@sdn1:~# ping -c1 198.51.100.2
+PING 198.51.100.2 (198.51.100.2) 56(84) bytes of data.
+64 bytes from 198.51.100.2: icmp_seq=1 ttl=64 time=2.08 ms
+
+--- 198.51.100.2 ping statistics ---
+1 packets transmitted, 1 received, 0% packet loss, time 0ms
+rtt min/avg/max/mdev = 2.083/2.083/2.083/0.000 ms
+
+
+root@sdn1:~# ping -c1 198.51.100.3
+PING 198.51.100.3 (198.51.100.3) 56(84) bytes of data.
+64 bytes from 198.51.100.3: icmp_seq=1 ttl=64 time=2.26 ms
+
+--- 198.51.100.3 ping statistics ---
+1 packets transmitted, 1 received, 0% packet loss, time 0ms
+rtt min/avg/max/mdev = 2.255/2.255/2.255/0.000 ms
+
+
+root@sdn1:~# ping -c1 198.51.100.10
+PING 198.51.100.10 (198.51.100.10) 56(84) bytes of data.
+64 bytes from 198.51.100.10: icmp_seq=1 ttl=64 time=1.29 ms
+
+--- 198.51.100.10 ping statistics ---
+1 packets transmitted, 1 received, 0% packet loss, time 0ms
+rtt min/avg/max/mdev = 1.286/1.286/1.286/0.000 ms
+----
+
+
 [[pvesdn_notes]]
 Notes
 -----
-- 
2.47.3

applied: [PATCH pve-docs 1/1] sdn: fabrics: wireguard: add simple example

[Thomas Lamprecht]

On Tue, 26 May 2026 16:22:35 +0200, Stefan Hanreich wrote:
> Initial feedback has shown that the UI currently is a bit confusing as
> to which field expects which value. Provide a step-by-step setup guide
> for a concrete example setup that should cover most basic uses cases.
> This should help users with setting up WireGuard. In the future, we
> should provide some kind of wizard or auto-full-meshify feature in
> order to automate this procedure.
> 
> [...]

Applied, thanks!

Pulled the screenshots from the staff repo but missed re-ordering the commits.

[1/1] sdn: fabrics: wireguard: add simple example
      commit: ea70b507a1964f178718a82de72f5ae435ee76d9